Principle:CARLA simulator Carla Simulator Packaging
| Knowledge Sources | |
|---|---|
| Domains | Build_System, Development |
| Last Updated | 2026-02-15 00:00 GMT |
Overview
Build artifact packaging for CARLA provides two modes of operation: launching the Unreal Engine editor for interactive development, or creating a standalone distributable package for deployment.
Description
The final step in the CARLA build-from-source pipeline produces runnable artifacts. CARLA supports two distinct packaging modes through CMake build targets:
- Launch (
launchtarget): Opens the CARLA project in the Unreal Engine editor. This mode is used during development for iterating on maps, assets, sensor configurations, and plugin code. The editor provides visual debugging, real-time preview, and the full Unreal Engine toolset.
- Package (
packagetarget): Creates a standalone distributable build that does not require the Unreal Engine editor or source code. The package includes the compiled simulator binary, all content assets (cooked for the target platform), the CARLA plugin, and runtime dependencies. This is the mode used for creating release builds, CI/CD artifacts, and deployments to machines that do not have the development environment.
Both targets are defined in Unreal/CMakeLists.txt and internally invoke Unreal Engine's build and packaging tools (Unreal Build Tool and Unreal Automation Tool).
Usage
This principle applies when:
- A developer wants to open the CARLA project in the UE editor for visual development and testing
- Creating a distributable CARLA build for deployment to simulation clusters
- Producing release artifacts for CI/CD pipelines
- Packaging CARLA for distribution to users who do not have the UE development environment
Theoretical Basis
Editor launch mode: The launch target invokes the Unreal Engine editor with the CARLA project loaded. This mode:
- Does not cook or package assets (uses raw source assets directly)
- Supports hot-reloading of C++ plugin code
- Provides full editor UI for map editing, blueprint debugging, and material authoring
- Runs the simulator in Play-In-Editor (PIE) mode for testing
- Requires the full Unreal Engine installation and CARLA source tree
This mode is essential during development because it provides the fastest iteration cycle: make a change, recompile the plugin, and immediately test in the editor without a full packaging step.
Package mode and the BuildCookRun pipeline: The package target invokes Unreal Engine's BuildCookRun pipeline, which is a multi-stage process:
- Build: Compiles the CARLA Unreal project and all plugin code in the Shipping configuration (fully optimized, no editor features).
- Cook: Converts all referenced content assets from their editor format (UASSET/UMAP) to platform-optimized runtime formats. Cooking performs:
- Texture compression to platform-appropriate formats (e.g., ASTC, DXT)
- Mesh optimization and LOD generation
- Shader compilation for the target rendering API (Vulkan)
- Asset dependency analysis to include only referenced assets
- Localization data processing
- Stage: Collects all cooked assets, compiled binaries, and runtime dependencies into a staging directory with the correct directory structure for the target platform.
- Package: Creates the final distributable package, typically as a directory tree that can be archived (tar/zip) for distribution.
Shipping vs Development builds: The package target uses the Shipping build configuration, which differs from Development (used in editor mode) in several ways:
- All logging and debugging features are stripped
- Assertions are disabled
- Performance-critical code paths use maximum optimization
- Console commands and developer tools are removed
- The resulting binary is smaller and faster
Content cooking rationale: Raw Unreal Engine assets are not suitable for runtime distribution because they contain editor-only metadata, uncompressed textures, and platform-independent shader source. Cooking transforms these into compact, platform-specific formats that load quickly at runtime. This is why packaged builds are significantly smaller and faster to start than running from the editor.
CMake integration: Both the launch and package targets are defined as CMake custom commands in Unreal/CMakeLists.txt. They act as wrappers around Unreal Engine's native build tools (UnrealBuildTool for compilation and UnrealAutomationTool for cooking/packaging), providing a consistent CMake-based interface for the entire CARLA build pipeline.
Practical Guide
Option A: Launch the editor for development
cd CarlaUE5
cmake --build Build --target launch
This opens the CARLA project in the Unreal Engine editor. Use the editor to:
- Browse and edit maps
- Test the simulator in Play-In-Editor mode
- Debug blueprints and C++ plugin code
- Preview sensor outputs
Option B: Create a standalone package
cd CarlaUE5
cmake --build Build --target package
This produces a distributable CARLA build. The process takes considerable time (30-90 minutes) as it compiles, cooks all assets, and stages the final package.
The output is typically placed in a directory such as Build/Package/ or Unreal/CarlaUnreal/Saved/StagedBuilds/.
Step 3: Verify the package
# Check that the packaged binary exists
ls Build/Package/LinuxNoEditor/CarlaUE5.sh
# Or check the staged builds directory
ls Unreal/CarlaUnreal/Saved/StagedBuilds/Linux/
Step 4: Run the packaged simulator
# Run the standalone simulator
./CarlaUE5.sh -RenderOffScreen # headless mode
# Or with rendering
./CarlaUE5.sh