Principle:CARLA simulator Carla Source Repository Setup
| Knowledge Sources | |
|---|---|
| Domains | Build_System, Development |
| Last Updated | 2026-02-15 00:00 GMT |
Overview
Version-controlled source acquisition with branch selection ensures developers obtain the correct CARLA codebase revision for building from source.
Description
The CARLA simulator is maintained as a Git repository hosted on GitHub at carla-simulator/carla. Building from source begins with cloning this repository, specifically targeting the ue5-dev branch which contains the Unreal Engine 5 development codebase. The repository uses a branching model where the ue5-dev branch serves as the primary integration branch for UE5-based development, distinct from legacy UE4 branches.
The clone operation creates a local working copy named CarlaUE5 by convention. This naming convention is referenced throughout CARLA's build scripts and documentation, and deviating from it may require adjusting environment variables or script paths.
Source acquisition is the foundational first step in the build pipeline. All subsequent build steps -- prerequisite installation, Unreal Engine compilation, content download, CMake configuration, Python API build, and packaging -- depend on having a properly cloned and branch-checked-out repository.
Usage
This principle applies whenever a developer needs to:
- Set up a new CARLA development environment from scratch
- Reproduce a specific build on a clean machine
- Contribute to CARLA development by forking and cloning
- Verify build integrity by starting from a known repository state
Theoretical Basis
Version-controlled source acquisition is a fundamental practice in software engineering that provides several guarantees critical to complex build pipelines:
Reproducibility: By specifying a branch (or tag or commit hash), developers can reproduce the exact same source state across different machines and at different points in time. The -b ue5-dev flag ensures that the working tree is checked out to the correct development branch immediately after cloning, avoiding accidental builds against the wrong branch.
Integrity: Git's content-addressable storage model ensures that every file, directory, and commit is cryptographically hashed (SHA-1/SHA-256). This means that any corruption or tampering in the source tree is detectable, providing a chain of trust from the upstream repository to the local build environment.
Isolation: Cloning into a dedicated directory (CarlaUE5) isolates the CARLA source from other projects and system files. This is particularly important because CARLA's build system generates substantial build artifacts (the Build/ directory) and expects specific relative paths to content assets and Unreal Engine installations.
Branch Model: CARLA uses a branch-per-engine-version strategy. The ue5-dev branch is specifically maintained for Unreal Engine 5 compatibility, while older branches target UE4. Selecting the correct branch at clone time prevents build failures caused by engine version mismatches.
Practical Guide
Step 1: Verify Git is installed
Ensure Git is available on the system. CARLA requires a relatively recent version of Git (2.x or later) for proper LFS and submodule support.
git --version
Step 2: Clone the repository with branch selection
Clone the CARLA repository targeting the ue5-dev branch into a directory named CarlaUE5:
git clone -b ue5-dev https://github.com/carla-simulator/carla.git CarlaUE5
Step 3: Verify the clone
Navigate into the cloned directory and confirm the active branch:
cd CarlaUE5
git branch --show-current
# Expected output: ue5-dev
Step 4: Review repository structure
Familiarize yourself with the key directories that will be referenced in subsequent build steps:
Util/SetupUtils/-- Prerequisite installation scriptsCMakeLists.txt-- Top-level CMake build configurationCMake/-- CMake toolchain and module filesPythonAPI/-- Python API source and build definitionsUnreal/-- Unreal Engine project files and CMake targetsDocs/-- Build documentation includingbuild_linux_ue5.md