Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/xXThanatosXx/MobileRobot/llms.txt

Use this file to discover all available pages before exploring further.

The ros2_install.sh script does more than install the ROS2 Humble binaries — it also creates a fully initialized colcon workspace at ~/colcon_ws/src and runs an initial colcon build to verify everything is working. This page covers the workspace directory layout, how to build packages incrementally, how to install dependencies with rosdep, and the overlay sourcing that ties everything together in your shell. For details on the environment variables and aliases that ros2_install.sh adds to your ~/.bashrc, see ROS2 Environment.

​
Workspace Directory Layout

After ros2_install.sh completes, your home directory contains the following workspace structure: 
~/colcon_ws/
├── src/           # Place your ROS2 packages here
├── build/         # Generated by colcon build (do not edit)
├── install/       # Installed packages overlay (sourced in .bashrc)
└── log/           # Build logs

src/

The only directory you work in directly. Clone or create ROS2 packages here. colcon build discovers packages by scanning this tree.

build/

Intermediate build artifacts generated automatically. Never edit files here — they are overwritten on every build.

install/

The workspace overlay that is sourced in ~/.bashrc. Contains the executables, libraries, and resource index for every built package.

log/

Detailed per-package build logs. Useful for diagnosing compile errors without re-running the full build.
The workspace source line (source ~/colcon_ws/install/setup.bash) is appended to ~/.bashrc by ros2_install.sh, so every new terminal session automatically activates the workspace overlay — you do not need to source it manually.

​
Building the Workspace

1

Navigate to the workspace root

Always run colcon build from ~/colcon_ws, not from inside src/:
cd ~/colcon_ws
2

Run the build

Build all packages in the workspace with symlink install enabled:
colcon build --symlink-install
The --symlink-install flag creates symbolic links to your source files instead of copying them into install/. This means changes to Python scripts are reflected immediately without requiring a rebuild — only C++ or CMake changes require a new colcon build.
3

Verify the build succeeded

A successful build ends with a summary line like:
# Look for:
Summary: X packages finished [Xs]
If any package reports failed or aborted, check ~/colcon_ws/log/latest_build/ for the detailed output of the failing package.
4

Reload your shell

After any build, source your ~/.bashrc (or open a new terminal) before running ROS2 nodes so the updated overlay is active:
source ~/.bashrc
# or use the alias added by ros2_install.sh
sb
Always run source ~/.bashrc (or open a new terminal) after building before launching ROS2 nodes. Running nodes against a stale overlay is the most common cause of “package not found” errors even when the build succeeded.

​
Rebuilding a Single Package

Rebuilding the entire workspace every time is unnecessary when you are iterating on a single package. Use the --packages-select flag to target only the package you changed: 
cd ~/colcon_ws
colcon build --symlink-install --packages-select <package_name>
Use colcon build --packages-select <package_name> to rebuild a single package instead of the entire workspace. This dramatically reduces build times during active development.

​
Sourcing the Workspace Overlay

The workspace overlay is the install/ directory. It must be sourced so that ros2 run, ros2 launch, and other tools can find your locally built packages: 
source ~/colcon_ws/install/setup.bash
# this is done automatically in .bashrc after running ros2_install.sh
Because ros2_install.sh appended this line to ~/.bashrc, every new terminal session sources it automatically. You only need to run it manually if you are in a session that pre-dates the installation or if you have customized your shell startup files.

​
Managing Dependencies with rosdep

rosdep resolves and installs system-level and ROS-level dependencies declared in your packages’ package.xml files. Run the following commands to keep dependencies up to date before building: 
rosdep update
rosdep install --from-paths src --ignore-src -r -y
FlagMeaning
--from-paths srcScan ~/colcon_ws/src for package.xml files to discover all declared dependencies.
--ignore-srcSkip packages whose source is already present in src/ — only install external deps.
-rContinue installing even if a dependency resolution fails for one package.
-yAnswer yes automatically to all apt prompts.
ros2_install.sh calls rosdep update once during installation to populate the local package index. Re-run rosdep update periodically to pull in the latest index before installing new packages.

​
Adding a New Package

1

Clone or create the package inside src/

cd ~/colcon_ws/src
# Clone an existing package:
git clone <package-url>
# or create a new one:
ros2 pkg create --build-type ament_python my_package
2

Install its dependencies

cd ~/colcon_ws
rosdep install --from-paths src --ignore-src -r -y
3

Build

colcon build --symlink-install
4

Reload the shell

source ~/.bashrc
# or
sb

​
Next Steps

For details on every environment variable and alias that ros2_install.sh writes to your shell — including ROS_DOMAIN_ID and colcon tab completion — see the ROS2 Environment page.

Build docs developers (and LLMs) love

Get started for freeTalk to us