Principle:CARLA simulator Carla CMake Build Configuration

Knowledge Sources	CARLA Simulator CARLA Documentation
Domains	Build_System, Development
Last Updated	2026-02-15 00:00 GMT

Overview

Cross-platform build system configuration using CMake with the Ninja generator and a custom toolchain file provides ABI-compatible compilation of CARLA's native libraries against Unreal Engine 5.

Description

CARLA uses CMake as its meta-build system, configured through a top-level CMakeLists.txt and supporting files in the CMake/ directory. The build configuration integrates several critical components:

• Ninja generator: Selected via -G Ninja, Ninja provides faster incremental builds compared to Make due to its minimal overhead and optimized dependency tracking.
• Custom toolchain: The CMake/Toolchain.cmake file configures the compiler, linker, and standard library to match those bundled with Unreal Engine's SDK. This ensures ABI (Application Binary Interface) compatibility between CARLA's native code and the Unreal Engine runtime.
• Build type: Release mode enables compiler optimizations (-O2/-O3) and strips debug symbols, producing binaries suitable for performance-sensitive simulation workloads.
• Engine path: The CARLA_UNREAL_ENGINE_PATH variable tells the build system where to find the compiled Unreal Engine installation, enabling it to locate engine headers, libraries, and the toolchain.

The CMake configuration step generates the Ninja build files in the Build/ directory, which are then consumed by subsequent cmake --build invocations.

Usage

This principle applies when:

• Performing the initial CARLA build configuration after all prerequisites are in place
• Changing build options (Debug vs Release, enabling/disabling optional features)
• Troubleshooting build failures related to compiler settings, missing libraries, or path resolution
• Understanding how CARLA integrates with Unreal Engine at the build system level

Theoretical Basis

CMake as meta-build system: CMake does not compile code directly. Instead, it generates build files for a native build tool (in this case, Ninja). This two-phase approach allows CARLA to maintain a single set of build definitions (CMakeLists.txt files) that work across platforms and build tools. The CMakeLists.txt files declaratively specify targets, dependencies, compiler flags, and link libraries; CMake translates these into Ninja's low-level build graph.

Toolchain file purpose: When building native code that will be loaded as a plugin into Unreal Engine, it is essential that the code is compiled with the same compiler version, standard library, and ABI settings as the engine itself. Unreal Engine 5 on Linux ships with its own Clang toolchain (typically a specific version of clang/lld from the engine's Engine/Extras/ThirdPartyNotUE/SDKs/HostLinux/ directory). The CMake/Toolchain.cmake file:

• Sets CMAKE_C_COMPILER and CMAKE_CXX_COMPILER to the Clang from the UE SDK
• Configures CMAKE_LINKER to use lld from the UE SDK
• Sets the C++ standard library to libc++ (matching UE5's usage)
• Configures platform-specific flags for Linux x86_64

Ninja vs Make: Ninja was designed as a faster alternative to Make, specifically optimized for the case where build files are generated by a higher-level system (like CMake). Key advantages:

• Minimal overhead for parsing build rules (simple, non-recursive format)
• Optimal parallelism with built-in job scheduling
• Fast incremental builds through accurate dependency tracking
• Typically 10-20% faster than Make on large projects like CARLA

CMake presets: CARLA provides CMakePresets.json for convenient preconfigured build settings. Presets encapsulate common configurations (generator, toolchain, build type, cache variables) into named profiles, reducing the complexity of the manual cmake command line.

Build directory separation: The -B Build flag creates an out-of-source build, keeping generated files separate from the source tree. This enables clean rebuilds (by simply deleting the Build/ directory), supports multiple build configurations simultaneously, and prevents build artifacts from polluting version-controlled source files.

Practical Guide

Step 1: Set the Unreal Engine path

export UE5_ROOT=~/UnrealEngine5.3

Step 2: Run the CMake configuration

From the CARLA repository root:

cmake -G Ninja -S . -B Build \
  --toolchain=$PWD/CMake/Toolchain.cmake \
  -DCMAKE_BUILD_TYPE=Release \
  -DCARLA_UNREAL_ENGINE_PATH=$UE5_ROOT

Key flags explained:

• -G Ninja: Use the Ninja build generator
• -S .: Source directory is the current directory
• -B Build: Place build artifacts in the Build/ subdirectory
• --toolchain: Use CARLA's custom toolchain for ABI compatibility
• -DCMAKE_BUILD_TYPE=Release: Optimize for performance
• -DCARLA_UNREAL_ENGINE_PATH: Path to the compiled Unreal Engine

Step 3: Verify configuration output

CMake will output a configuration summary. Check for:

• Compiler detected (should be Clang from UE SDK)
• Unreal Engine path found and validated
• All required dependencies located

Step 4: Proceed to build targets

After successful configuration, use cmake --build Build --target <target> to build specific components (Python API, launch, package).

Related Pages

Implemented By

• Implementation:CARLA_simulator_Carla_CMake_Configure_Build