// Configure and build gz-sim from source using either CMake/Ninja directly or a colcon workspace. Trigger when the user asks to build, recompile, configure, or set up the gz-sim binary tree.
Concise reference for the gz-sim Entity-Component-System architecture — how Entities, Components, Systems, the ECM, the Server, and SimulationRunner fit together. Trigger when the user asks how gz-sim is organized, where to add code, or how the simulation loop runs.
Run unit, integration, performance, and benchmark tests for gz-sim, filter by name, and debug a single failing case. Trigger when the user asks to test, rerun a test, debug a flaky test, or check that a change didn't regress something.
Scaffold a new ECS component header under include/gz/sim/components/, wire its CMake listing, and (if needed) register it with ComponentFactory for serialization. Trigger when the user asks to add a new component or a per-entity data field.
Scaffold a new Nav 2 plugin (controller, planner, behavior, smoother, goal-checker, progress-checker, costmap layer, or BT node). Wires pluginlib registration, parameter declaration on the lifecycle node, and a minimal integration test. Trigger when the user asks to write or extend a Nav 2 plugin.
Scaffold a new ROS 2 package (ament_python or ament_cmake) inside a colcon workspace, restructured to follow this template's Clean Architecture layout. Trigger when the user asks to create a new ROS 2 package or to bootstrap a Clean-Architecture-compliant codebase.
Scaffold a new gz-sim system plugin under src/systems/<name>/ — header, source, CMake glue, plugin registration, and an integration test stub. Trigger when the user asks to create a new system, controller, or plugin that hooks into the simulation loop.
| name | gz-build |
| description | Configure and build gz-sim from source using either CMake/Ninja directly or a colcon workspace. Trigger when the user asks to build, recompile, configure, or set up the gz-sim binary tree. |
gz-sim follows the Gazebo project's standard build process. Two equally
valid front-ends exist; pick based on what the user already has set up.
Assumes every Gazebo dependency (gz-cmake, gz-common, gz-physics, …)
is already installed system-wide.
cmake -S . -B build -G Ninja \
-DCMAKE_BUILD_TYPE=RelWithDebInfo \
-DBUILD_TESTING=ON
cmake --build build -j"$(nproc)"
Useful flags:
| Flag | Effect |
|---|---|
-DCMAKE_BUILD_TYPE=Debug | Asserts on, no optimization, full symbols. |
-DENABLE_PROFILER=ON | Compiles in GZ_PROFILER hooks. |
-DBUILD_TESTING=OFF | Skip test targets (faster, smaller). |
-DCMAKE_INSTALL_PREFIX=/opt/gz | Override install location. |
-DBUILD_DOCS=ON | Build Doxygen + tutorials (needs doxygen). |
Install (optional, into prefix):
cmake --install build
When the user is building the full Gazebo stack:
# from <workspace>/src/ that contains gz-sim and friends
colcon build --merge-install --cmake-args -DBUILD_TESTING=ON
source install/setup.bash
Limit to gz-sim and its deps:
colcon build --merge-install \
--packages-up-to gz-sim \
--cmake-args -DCMAKE_BUILD_TYPE=RelWithDebInfo
bazel build //... --config=linux
bazel test //... --config=linux
MODULE.bazel pins the dependencies; the matrix is exercised by
.github/workflows/bazel.yml.
gz sim -v 4 shapes.sdf (needs source install/setup.bash
when built via colcon).xvfb-run -s '-screen 0 1280x800x24'.-DCMAKE_CXX_FLAGS="-fsanitize=address,undefined"
and -DCMAKE_EXE_LINKER_FLAGS="-fsanitize=address,undefined".find_package(gz-cmake REQUIRED) failing → user hasn't installed gz-cmake.qt6-base-dev + qt6-declarative-dev
qt6-5compat-dev are present.sdformat → install the matching libsdformat<NN>-dev for the
current Gazebo distribution (Rotary → check package.xml).gz-msgs headers → rebuild gz-msgs before gz-sim.Always cd into the repo root (/home/rdadmin/gz-sim) before running these.