build-workspace

name	build-workspace
description	Build the `geniesim_ros` colcon workspace inside the Genie Sim Docker container using the `geniesim ros build` CLI verb. Produces the `./devel` overlay that every `ros2 launch genie_sim_bringup …` step depends on. Trigger: When the user asks to "build ros workspace", "编译 ros 工作空间", "colcon build", "build genie_sim_bringup", "set up the ROS overlay", or after a fresh `geniesim docker into` shell where the workspace isn't sourced yet.
license	MPL-2.0
metadata	{"author":"genie-sim","version":"1.0"}
prerequisites	["geniesim_cli:fresh-machine-setup"]
inputs	[{"name":"build_type","desc":"`dev` (RelWithDebInfo + symlink-install) or `release`","required":false,"default":"dev"}]
outputs	[{"desc":"`./devel`, `./devel_build`, `./devel_log` overlays sourced; `ros2 pkg list | grep genie_sim` lists 10 packages"}]

When to Use

• First time entering the container in a fresh checkout.
• After pulling new commits that touched any package under source/geniesim_ros/src/ros_ws/src/.
• After running geniesim ros build cleanup and you want to rebuild from scratch.
• Before invoking the launch-scene skill (its ros2 launch … step needs the workspace sourced).

Do not use for:

• Installing the wheel layout that ships with pip install geniesim_ros — that's already built; just source the install tree.
• Building a Release wheel for deploy → use geniesim deploy geniesim_ros.

Critical Patterns

1. Run inside the container. The colcon toolchain and rosdep tree live in the Isaac Sim + Jazzy image; outside the container the build will pick up the wrong Python / Boost / Eigen.
2. Dev vs Release. geniesim ros build dev produces a RelWithDebInfo + --symlink-install overlay at ./devel, ./devel_build, ./devel_log (intentionally namespaced so they can't collide with a release build under ./install). geniesim ros build release is for deploy, not for iteration.
3. Always source devel/setup.bash after building. The shell environment doesn't carry the overlay automatically.
4. rosdep first if anything fails. Missing apt-side dependencies are the #1 source of "package not found" build errors — run geniesim ros doctor before re-trying the build.

Workflow

Step 1 — Confirm you're inside the container

geniesim status                       # should report all distributions OK
echo $ROS_DISTRO                      # should print "jazzy"

If $ROS_DISTRO is empty, you're on the host — geniesim docker into first.

Step 2 — (optional) Repair rosdep

geniesim ros doctor                   # check & fix rosdep deps

Step 3 — Build

cd /workspace                         # repo root (mounted by `geniesim docker up`)
geniesim ros build dev                # RelWithDebInfo + symlink-install -> ./devel

Iteration loop after editing C++ / xacro / launch files:

geniesim ros build dev                # re-runs incrementally thanks to symlink-install

Step 4 — Source the overlay

source devel/setup.bash

Verify:

ros2 pkg list | grep genie_sim         # should list the 10 genie_sim_* packages

Step 5 — Cleanup (only when something is wedged)

geniesim ros build cleanup             # interactive prompt before removing devel*/build/install/log

Commands (copy-paste summary for the user)

# Inside the container, from the repo root:
geniesim ros doctor                    # optional — fix rosdep first
geniesim ros build dev                 # build the overlay
source devel/setup.bash                # overlay the built workspace
ros2 pkg list | grep genie_sim         # sanity check

Notes

• geniesim ros build is a thin wrapper around colcon build — the same flags work if you call colcon directly, but the CLI sets the right CMAKE_BUILD_TYPE, picks up $GENIESIM_WORKSPACE, and routes output to the namespaced ./devel* dirs.
• geniesim ros graph writes colcon graph to geniesim_graph.png in the cwd — handy when you need to reason about which packages pull in which.
• The bundled workspace is also installed system-wide via pip install geniesim_ros; that path is fine for running but not for iterating — every edit needs a rebuild, and pip won't pick up a symlink-install layout.

Resources

• CLI dispatcher: source/geniesim_cli/src/geniesim_cli/commands/ros.py
• Workspace root: source/geniesim_ros/src/ros_ws/
• Package routing: source/geniesim_ros/AGENTS.md