gz-build
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.
git clone --depth 1 https://github.com/harunkurtdev/ros2-claude-code-template /tmp/gz-build && cp -r /tmp/gz-build/.claude/skills/gz-build ~/.claude/skills/gz-buildSKILL.md
# Building gz-sim `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. ## 1. Direct CMake (single repo) Assumes every Gazebo dependency (`gz-cmake`, `gz-common`, `gz-physics`, …) is already installed system-wide. ```sh 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): ```sh cmake --install build ``` ## 2. colcon workspace (Gazebo source build) When the user is building the full Gazebo stack: ```sh # 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: ```sh colcon build --merge-install \ --packages-up-to gz-sim \ --cmake-args -DCMAKE_BUILD_TYPE=RelWithDebInfo ``` ## Bazel (alternative) ```sh bazel build //... --config=linux bazel test //... --config=linux ``` `MODULE.bazel` pins the dependencies; the matrix is exercised by `.github/workflows/bazel.yml`. ## After building * Run the smoke test: `gz sim -v 4 shapes.sdf` (needs `source install/setup.bash` when built via colcon). * For headless CI, prefix with `xvfb-run -s '-screen 0 1280x800x24'`. * For sanitizers, configure with `-DCMAKE_CXX_FLAGS="-fsanitize=address,undefined"` and `-DCMAKE_EXE_LINKER_FLAGS="-fsanitize=address,undefined"`. ## Common failures * `find_package(gz-cmake REQUIRED)` failing → user hasn't installed gz-cmake. * Linker errors about Qt6 → ensure `qt6-base-dev` + `qt6-declarative-dev` + `qt6-5compat-dev` are present. * Missing `sdformat` → install the matching `libsdformat<NN>-dev` for the current Gazebo distribution (`Rotary` → check `package.xml`). * Out-of-date `gz-msgs` headers → rebuild `gz-msgs` before `gz-sim`. Always cd into the repo root (`/home/rdadmin/gz-sim`) before running these.
Use proactively before opening a PR that adds or changes BehaviorTree.CPP nodes or BehaviorTree.ROS2 wrappers (RosActionNode/RosServiceNode/RosTopicPub/SubNode, TreeExecutionServer). Reviews a diff against BT.CPP v4 conventions — node base-class choice, non-blocking ticks, ports/blackboard typing, factory/plugin registration, XML v4, and the ROS 2 wrapper contract. Returns a punch list with file:line anchors, not a rewrite.
Use when a design decision touches Clean Architecture boundaries in a ROS 2 project — which layer a new behaviour belongs to, whether a port belongs in domain or application, whether a new node should be lifecycle-managed, whether to compose nodes or split packages. Returns an architectural recommendation with trade-offs, not implementation.
Use when a design decision touches the gz-sim ECS — where new state should live, which system phase should write it, how to avoid coupling, whether to add a component vs. a member variable, whether a new system should be split or merged with an existing one. Returns an architectural recommendation with trade-offs, not implementation.
Use proactively before opening any gz-sim PR. Reviews a diff against the project's C++17 style, ECS conventions, plugin registration patterns, CMake structure, test placement, Migration.md / Changelog.md expectations, and pre-commit configuration. Returns a punch list, not a rewrite.
Use proactively before opening a PR that adds or changes a ros2_control controller, broadcaster, or hardware component (incl. URDF <ros2_control> bringup). Reviews a diff against ros2_controllers / ros2_control_demos conventions — controller & hardware lifecycle, command/state interface configuration, real-time safety of update()/read()/write(), generate_parameter_library usage, pluginlib registration, chainable-controller correctness, URDF wiring, and tests. Returns a punch list with file:line anchors, not a rewrite.
Use proactively before opening any ROS 2 / Nav 2 PR. Reviews a diff against this template's Clean Architecture, ROS 2 communication, lifecycle, testing, and Nav 2 plugin conventions. Returns a punch list with file:line anchors, not a rewrite.
Use proactively before opening a PR that touches a VDA 5050 connector / fleet bridge. Reviews a diff against VDA 5050 v3.0.0 protocol compliance (topics, QoS, header rules, base/horizon, action state machine, schema validation) and the template's Clean Architecture for the MQTT↔Nav 2 bridge. Returns a punch list with file:line anchors, not a rewrite.
Build the colcon workspace (optionally a single package) and report the outcome.