{"id":9594,"library":"colcon-bash","title":"colcon-bash","description":"colcon-bash is an extension for the colcon build system, primarily used in robotics development (e.g., ROS 2). It provides the functionality to generate Bash shell scripts (e.g., `setup.bash`) within colcon workspaces. These scripts are crucial for setting up the environment, allowing users to easily source packages and make their executables and libraries discoverable. The current version is 0.5.0, and it follows the colcon project's release cadence, often coinciding with ROS 2 releases or colcon-core updates.","status":"active","version":"0.5.0","language":"en","source_language":"en","source_url":"https://github.com/colcon/colcon-bash/","tags":["colcon","build system","bash","shell","robotics","ros2"],"install":[{"cmd":"pip install colcon-bash","lang":"bash","label":"Install colcon-bash directly"},{"cmd":"pip install colcon-common-extensions","lang":"bash","label":"Recommended: Install common colcon extensions (includes colcon-bash)"}],"dependencies":[{"reason":"colcon-bash is an extension to colcon-core and requires it to function. It is a direct install_requires dependency.","package":"colcon-core","optional":false}],"imports":[{"note":"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.","symbol":"PackageBashExtension","correct":"from colcon_bash.bash.package import PackageBashExtension"}],"quickstart":{"code":"# Create a colcon workspace\nmkdir -p my_colcon_ws/src\ncd my_colcon_ws/src\n\n# Create a minimal C++ package (CMake)\nmkdir my_pkg\ncd my_pkg\ncat << EOF > CMakeLists.txt\ncmake_minimum_required(VERSION 3.5)\nproject(my_pkg NONE)\nadd_executable(my_executable my_executable.cpp)\nEOF\ncat << EOF > my_executable.cpp\n#include <iostream>\n\nint main() {\n    std::cout << \"Hello from my_pkg!\" << std::endl;\n    return 0;\n}\nEOF\ncd .. # back to src\n\n# Build the workspace using colcon (colcon-bash will generate setup.bash)\ncd .. # back to my_colcon_ws\n# Note: ensure colcon-bash is installed (e.g., pip install colcon-common-extensions)\ncolcon build --packages-select my_pkg\n\n# Source the generated setup script to make the package discoverable\nsource install/setup.bash\n\n# Run the executable from the environment\nmy_executable\n","lang":"bash","description":"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."},"warnings":[{"fix":"Install `colcon-zsh` for Zsh or `colcon-fish` for Fish, and use `source install/setup.zsh` or `source install/setup.fish` respectively.","message":"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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"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).","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Install `colcon` and its common extensions: `pip install colcon-common-extensions`.","cause":"The `colcon` command-line tool is not installed or not in your system's PATH.","error":"colcon: command not found"},{"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).","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.","error":"No such file or directory: install/setup.bash"},{"fix":"Run `source install/setup.bash` from your workspace root directory (`my_colcon_ws` in the quickstart example) to update your environment.","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.","error":"my_executable: command not found (after building)"}]}