{"id":9599,"library":"colcon-common-extensions","title":"colcon-common-extensions: ROS 2 Build Tool Bundle","description":"colcon-common-extensions is a meta-package that aggregates `colcon-core` and several common `colcon` extensions, providing a comprehensive build system for ROS 2 and other robotics projects. It does not provide functionality itself, but ensures a consistent set of `colcon` features are installed. The current version is 0.3.0, and it follows the release cadence of its underlying `colcon-*` dependencies, often aligning with ROS 2 distribution releases.","status":"active","version":"0.3.0","language":"en","source_language":"en","source_url":"https://github.com/colcon/colcon-common-extensions/","tags":["ROS","ROS 2","build-system","meta-package","CLI","robotics"],"install":[{"cmd":"pip install colcon-common-extensions","lang":"bash","label":"Install colcon-common-extensions"}],"dependencies":[{"reason":"This meta-package directly pulls in colcon-core and numerous other colcon-* extensions (e.g., colcon-ros, colcon-cmake, colcon-bash, etc.) as its primary function to provide a complete colcon environment.","package":"colcon-core","optional":false}],"imports":[{"note":"colcon-common-extensions is a meta-package and does not offer direct Python APIs for user import. Users typically interact with the 'colcon' command-line tool, which is provided by 'colcon-core'. If programmatic interaction is needed, symbols from 'colcon_core' or specific extensions are imported.","symbol":"main","correct":"from colcon_core.cli import main"}],"quickstart":{"code":"import subprocess\nimport sys\n\n# colcon-common-extensions itself is a meta-package and doesn't expose\n# direct Python APIs for user applications. Its primary utility is installing\n# the 'colcon' command-line tool and its extensions.\n# This quickstart verifies the 'colcon' command is available and functional.\n\ntry:\n    # Using '-m colcon_core.cli' to run colcon as a module is generally more robust\n    # than 'colcon' directly, especially in isolated Python environments.\n    result = subprocess.run(\n        [sys.executable, \"-m\", \"colcon_core.cli\", \"--version\"],\n        capture_output=True,\n        text=True,\n        check=True\n    )\n    print(f\"colcon command is available. Version:\\n{result.stdout.strip()}\")\n    print(\"colcon command is functional.\")\nexcept FileNotFoundError:\n    print(\"Error: 'colcon' executable not found. Ensure colcon-common-extensions is installed and in PATH.\")\n    sys.exit(1)\nexcept subprocess.CalledProcessError as e:\n    print(f\"Error running colcon: {e}\")\n    print(f\"Stdout: {e.stdout}\")\n    print(f\"Stderr: {e.stderr}\")\n    sys.exit(1)\n","lang":"python","description":"This quickstart demonstrates how to verify the installation of the 'colcon' command-line tool, which is enabled by `colcon-common-extensions`. It executes `colcon --version` using `subprocess` to confirm that the tool is accessible and functional within a Python environment."},"warnings":[{"fix":"Do not attempt to import symbols directly from `colcon_common_extensions`. Instead, import from specific `colcon_*` packages (e.g., `colcon_core`) or use the `colcon` CLI.","message":"colcon-common-extensions is a meta-package and does not provide direct Python APIs for user code. Its primary purpose is to bundle 'colcon-core' and other 'colcon-*' extension packages, enabling the 'colcon' command-line interface with a full set of features.","severity":"gotcha","affected_versions":"All versions"},{"fix":"When using `colcon` outside of ROS 2, review the documentation for `colcon-core` and its extensions carefully, particularly regarding package discovery, build types, and environment setup.","message":"The `colcon` build system is primarily designed for ROS 2 development workflows. While it can be used for other C++/Python projects, its default behaviors and assumptions (e.g., package discovery, environment hooks) are heavily optimized for the ROS 2 ecosystem. Using it outside of ROS 2 might require significant custom configuration.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always `source` the appropriate ROS 2 `setup.bash`/`setup.zsh`/`setup.ps1` before running `colcon` commands. For custom workspaces, remember to source the workspace's `install/setup.bash` after building.","message":"Proper functioning of `colcon` (especially for finding ROS 2 packages and dependencies) often depends on sourcing ROS 2 environment setup scripts (e.g., `source /opt/ros/humble/setup.bash`). Forgetting to do so will result in `colcon` not finding ROS 2 packages or build dependencies.","severity":"gotcha","affected_versions":"All versions (when used with ROS 2)"},{"fix":"Ensure you are using Python 3 (preferably Python 3.8+ as per ROS 2 recommendations). Use `python3 -m pip install ...` or a virtual environment configured for Python 3.","message":"`colcon` and its extensions (including those pulled by `colcon-common-extensions`) are strictly Python 3 compatible. Attempts to install or run `colcon` in a Python 2 environment will result in errors.","severity":"breaking","affected_versions":"< 0.1.0"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Verify installation with `pip show colcon-common-extensions`. Ensure pip's bin directory (e.g., `~/.local/bin` or a virtual environment's `bin`) is in your PATH. On Linux, `export PATH=$HOME/.local/bin:$PATH` might resolve it. In a virtual environment, activate it.","cause":"The `colcon` executable is not in your system's PATH, or `colcon-common-extensions` (and thus `colcon-core`) was not installed correctly into an accessible location.","error":"colcon: command not found"},{"fix":"Reinstall `colcon-common-extensions` in a clean virtual environment: `python3 -m venv venv && source venv/bin/activate && pip install colcon-common-extensions`. This ensures all dependencies are correctly installed and isolated.","cause":"While `colcon-common-extensions` might be installed, its dependencies, specifically `colcon-core`, failed to install or are not accessible in the current Python environment.","error":"ModuleNotFoundError: No module named 'colcon_core'"},{"fix":"Ensure you are running `colcon build` from the root of a `colcon` workspace (the directory containing your source repositories). Verify packages have valid manifest files. Check for `.ignore` files (e.g., `COLCON_IGNORE`) that might be preventing discovery.","cause":"`colcon` could not find any recognizable package manifests (e.g., `package.xml`, `setup.py`, `CMakeLists.txt`) in the current directory or its subdirectories, or the workspace is incorrectly structured.","error":"[ERROR] [colcon build]: No packages found in the workspace"},{"fix":"This is often just a warning. If you intend `colcon` to use specific ROS 2 installations, ensure you've sourced the correct `setup.bash` for *your* target ROS 2 distro. If this causes build failures, try unsetting `CMAKE_PREFIX_PATH` before running `colcon build` (e.g., `unset CMAKE_PREFIX_PATH`).","cause":"This warning commonly occurs in ROS 2 setups where `CMAKE_PREFIX_PATH` is set by a prior environment (e.g., ROS 1 or another ROS 2 distro), but `colcon` manages its own environment for the build process, potentially leading to confusion if users expect specific paths to be propagated automatically.","error":"[WARNING] [colcon build]: The CMAKE_PREFIX_PATH environment variable is set and will be ignored"}]}