Package CarlaUE4

Paths. scripts/… and references/… below are relative to the directory holding this SKILL.md. Your working directory is the user's project, not that directory, so prefix them with its absolute path or the command is not found.

make package produces two different artifacts depending on --packages:

Mode	Command	Output	Cook driven by
Release	bash scripts/package.sh	Dist/CARLA_<tag>.tar.gz	Config/DefaultGame.ini
Asset package	PACKAGES=<Name> bash scripts/package.sh	Dist/<Name>_<tag>.tar.gz	<Name>.Package.json

Instructions

Copy this checklist and track progress — the run is long and gated, so a skipped step usually surfaces an hour in:

Package Progress:
- [ ] Step 1: Activate the client Python env, run check_env.sh, clear FAILs
- [ ] Step 2: Cook — 2a full release, or 2b a named asset package
- [ ] Step 3: Verify the artifact exists, is the right size, and is in Dist/
- [ ] (opt-in) Run or import the build — only if asked to run/load it

Step 1: Activate your Python env, then check prerequisites

The wheel stage runs python3 -m build, so have your CARLA client environment active first — the one whose python3 imports build and carla. Any manager works (venv, conda, system); the skill assumes none and pins no version. If you drive this non-interactively, either activate the env in the same shell, or point CARLA_ENV_ACTIVATE at its activate script — the only hook the skill looks at. Only set CARLA_PY_VERSION if you deliberately need a version-suffixed interpreter — and it must resolve inside that env, or the wheel escapes to the wrong Python.

bash scripts/check_env.sh

Fix warnings about the wheel python and missing content before starting — both cost most of the build time before they surface.

Step 2a: Full release

bash scripts/package.sh 2>&1 | tee /tmp/carla_package.log

30-90 min cold, not resumable.

Step 2b: Standalone asset package

For distributing maps and props, or for a cheap sensor-capable build containing one town instead of thirteen.

A package is defined by a JSON found anywhere under Content/ — the package name is the filename minus .Package.json. It needs no matching directory, so stock maps can be exported as-is:

# define it (writes Content/Carla/Config/OneTown.Package.json)
python3 scripts/package_json.py OneTown --map Town02 --carla-materials

# cook it
PACKAGES=OneTown bash scripts/package.sh

Each map needs <MapName>.xodr under an OpenDrive/ directory somewhere in Content/. package_json.py --check verifies this; a missing .xodr yields a package that imports but has no road network.

Step 3: Verify

scripts/package.sh already checks the expected artifact by name, size and location, and fails loudly if it is missing — make can exit 0 having produced nothing. Confirm independently:

ls -la "${CARLA_UE4_ROOT:?}"/Dist/

A release is several GB; low megabytes means the cook ran without content.

This is where the skill stops by default. The deliverable is the verified artifact in Dist/ (or in PACKAGE_DEST, below). Booting or importing it is a separate, opt-in step — do it only when the request explicitly asks to run or load the result.

Placing artifacts outside Dist/

Set PACKAGE_DEST to a directory to land the artifact elsewhere. It is applied after verification: PACKAGE_DEST_MODE=move (the default) relocates the verified artifact and leaves no multi-GB duplicate in Dist/; PACKAGE_DEST_MODE=copy keeps Dist/ intact. So "package CARLA into <dir>" is a move, "package CARLA and copy it to <dir>" is a copy.

# move the release into ~/dev/Carla/packages/ (nothing left in Dist/)
PACKAGE_DEST=~/dev/Carla/packages bash scripts/package.sh
# copy instead, keeping Dist/
PACKAGE_DEST=~/dev/Carla/packages PACKAGE_DEST_MODE=copy bash scripts/package.sh

ROS 2 packages (ROS2=1)

ROS2=1 bash scripts/package.sh          # release WITH the native ROS 2 interface

Package.sh has no ROS 2 option — support is inherited from the editor build. But make package depends on CarlaUE4Editor, so every cook re-runs BuildCarlaUE4.sh, which rewrites Unreal/CarlaUE4/Config/OptionalModules.ini. Cook without ROS2=1 and that rewrite says Ros2 OFF: the package loses ROS 2 even though the checkout was built with it, with nothing in the log to say so. Hence:

• ROS2=1 appends --ros2 to the forwarded ARGS (Package.sh and BuildPythonAPI.sh print a harmless unrecognized option '--ros2'; only Setup.sh/BuildLibCarla.sh/BuildCarlaUE4.sh act on it).
• Cooking without ROS2=1 from a ROS-2-built checkout warns and pauses 5 s.
• After the cook, package.sh re-reads the ini and fails if ROS2=1 did not end up as Ros2 ON — the staged binaries would have no ROS 2.
• If the middleware deps (Build/{fast-dds,cyclone-dds,zenoh}-install) are not built yet, this cook builds them first — add that to the 30-90 min.

Serve the result with [[run-carla-server]] PACKAGED=1 ROS2=1 (the runtime --ros2 flag is separate); build-time detail in [[build-carla-ue4]] references/ros2.md.

Optional: run the packaged build

Only when the request asks to run or load the result (e.g. "package the engine and Town15, then run the server and load it"). Packaging on its own boots nothing.

# release: boot the packaged server, then load a town from a client
PACKAGED=1 bash ../run-carla-server/scripts/run_server.sh >/tmp/carla_pkg.log 2>&1 &
until nc -z 127.0.0.1 2000; do sleep 1; done
python -c "import carla; c=carla.Client('127.0.0.1',2000); c.set_timeout(60); \
           print('loaded', c.load_world('Town15').get_map().name)"
pkill -x CarlaUE4-Linux-        # NOT ...-Shipping: comm is truncated to 15 chars

# asset package: install into an extracted release first, from its ROOT
cp Dist/OneTown_TAG.tar.gz RELEASE/Import/
cd RELEASE && ./ImportAssets.sh

The packaged server process is CarlaUE4-Linux-Shipping, not UE4Editor. Asset packages import only into a packaged release, never a source build, and are platform-specific.

Flags (PACKAGE_CONFIG, PACKAGE_ZIP, CLEAN_INTERMEDIATE, ARCHIVE_SUFIX, TARGET_ARCHIVE, PACKAGE_DEST, PACKAGE_DEST_MODE) and the JSON schema: references/packaging.md.

Examples

Example 1: full release (build only)

User says: "package CARLA"

Check prerequisites, bash scripts/package.sh, verify size and location. Deliverable: Dist/CARLA_<tag>.tar.gz, several GB. The skill stops here — nothing is booted.

Example 2: export one town

User says: "export Town02 as a package I can drop into a release"

python3 scripts/package_json.py OneTown --map Town02 --carla-materials, then PACKAGES=OneTown bash scripts/package.sh. Result Dist/OneTown_<tag>.tar.gz for ImportAssets.sh.

Example 3: package, then run and load (opt-in)

User says: "package the CARLA engine and Town15, then run the server and load the packaged town"

Build the release (it contains the towns) and verify, then — because the request asked for it — boot with PACKAGED=1 and load the town from a client, per "Optional: run the packaged build" above.

Example 4: fast iteration

User says: "I just need the staged build, skip the tarball"

PACKAGE_ZIP=0 bash scripts/package.sh leaves Dist/CARLA_Shipping_<tag>/LinuxNoEditor runnable in place, skipping compression.

Troubleshooting

Error: No module named build.__main__ Cause: the PythonAPI.wheel prerequisite runs python3 -m build, and the active python3 has no build module. It runs after the editor compile, before the cook, so the compile is not wasted. Solution: activate the env whose python3 has build (or pip install build into it) and re-run; compiled artifacts survive. scripts/package.sh verifies this up front and forwards no version, so the active env's python3 is used — a hand-run make package uses whatever python3 is on PATH.

Error: Package json file not found Cause: no <Name>.Package.json anywhere under Content/. Solution: python3 scripts/package_json.py <Name> --map .... The name must match the filename exactly, minus the suffix.

Error: asset package imports but the map has no roads Cause: no <MapName>.xodr found under an OpenDrive/ directory. Solution: place it beside the .umap, named exactly like the map. Check with python3 scripts/package_json.py <Name> --check.

Error: package tarball absurdly large or corrupt Cause: content packages are built with tar -rf, which appends. A stale Dist/<Name>_*.tar from an interrupted run is added to, not replaced. Solution: rm Dist/<Name>_*.tar and re-run. scripts/package.sh refuses to start when one is present.

Error: release tarball is only a few MB Cause: cooked with no content. Solution: build the carla content first, then re-package.

Error: killed mid-cook, or the machine freezes Cause: OOM — the cook parallelises and each worker is memory-hungry. Solution: free RAM or add swap; there is no parallelism knob (packaging.md P3). Re-running is cheap — the cook is iterative, so cooked assets are reused.

Outputs

• Dist/CARLA_<tag>.tar.gz — full release (Shipping; other configs carry the config in the name).
• Dist/<Name>_<tag>.tar.gz — standalone asset package.
• Dist/CARLA_<config>_<tag>/LinuxNoEditor — staged tree, runnable in place.

<tag> is the git short SHA, suffixed -dirty when tracked files are modified.