colcon-bash

Common errors

• colcon: command not found

  cause The `colcon` command-line tool is not installed or not in your system's PATH.
  fix Install `colcon` and its common extensions: `pip install colcon-common-extensions`.

• No such file or directory: install/setup.bash

  cause The `colcon build` command either failed, was not run, or did not produce the expected `setup.bash` file in the `install` directory. This can happen if the build failed or if `colcon-bash` was not active.
  fix Ensure `colcon build` completes successfully. Check the build output for errors. Verify that `colcon-bash` is installed (`pip show colcon-bash`) and that `colcon` is configured to use bash extensions (which it typically is by default).

• my_executable: command not found (after building)

  cause You have built your package, but you have not sourced the `colcon` workspace's `setup.bash` file, which adds your executable's path to your shell's PATH variable.
  fix Run `source install/setup.bash` from your workspace root directory (`my_colcon_ws` in the quickstart example) to update your environment.

Warnings

• gotcha colcon-bash only generates Bash-compatible setup scripts (`setup.bash`). Users of other shells (like Zsh or Fish) will need to install corresponding colcon extensions (e.g., `colcon-zsh`, `colcon-fish`) to get native setup scripts for their shell.
  Fix: Install `colcon-zsh` for Zsh or `colcon-fish` for Fish, and use `source install/setup.zsh` or `source install/setup.fish` respectively.
• gotcha Sourcing multiple `setup.bash` files (e.g., from different `colcon` workspaces or ROS distributions) can lead to environment variable conflicts or unexpected behavior. The order of sourcing matters, and the last sourced environment typically takes precedence.
  Fix: Always start with a clean shell or carefully manage your environment. Use `source /opt/ros/{DISTRO}/setup.bash` first (for ROS 2), then your workspace's `source install/setup.bash`. Unset ROS environment variables before switching workspaces if conflicts occur.
• gotcha After running `colcon build`, the new packages, executables, or libraries will not be immediately available in your shell. You must explicitly `source install/setup.bash` in your terminal to update the environment variables (like PATH, LD_LIBRARY_PATH).
  Fix: Run `source install/setup.bash` from your workspace root directory (`my_colcon_ws` in the quickstart example) to update your environment. Consider adding it to your shell's startup script (`.bashrc`) if it's your primary workspace.

Install

• pip install colcon-bash Install colcon-bash directly
• pip install colcon-common-extensions Recommended: Install common colcon extensions (includes colcon-bash)

Imports

• PackageBashExtension

  from colcon_bash.bash.package import PackageBashExtension

  While this symbol exists, colcon-bash is primarily an extension loaded by colcon. End-users typically interact with its functionality via the `colcon` command-line tool, not direct Python imports.

Quickstart

This quickstart demonstrates how `colcon-bash` integrates with `colcon`. After building a package, `colcon-bash` ensures that `install/setup.bash` is generated. Sourcing this script adds package-specific environment variables and PATH entries, allowing executables like `my_executable` to be run directly.

# Create a colcon workspace
mkdir -p my_colcon_ws/src
cd my_colcon_ws/src

# Create a minimal C++ package (CMake)
mkdir my_pkg
cd my_pkg
cat << EOF > CMakeLists.txt
cmake_minimum_required(VERSION 3.5)
project(my_pkg NONE)
add_executable(my_executable my_executable.cpp)
EOF
cat << EOF > my_executable.cpp
#include <iostream>

int main() {
    std::cout << "Hello from my_pkg!" << std::endl;
    return 0;
}
EOF
cd .. # back to src

# Build the workspace using colcon (colcon-bash will generate setup.bash)
cd .. # back to my_colcon_ws
# Note: ensure colcon-bash is installed (e.g., pip install colcon-common-extensions)
colcon build --packages-select my_pkg

# Source the generated setup script to make the package discoverable
source install/setup.bash

# Run the executable from the environment
my_executable