colcon-common-extensions: ROS 2 Build Tool Bundle

Common errors

• colcon: command not found

  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.
  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.

• ModuleNotFoundError: No module named 'colcon_core'

  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.
  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.

• [ERROR] [colcon build]: No packages found in the workspace

  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.
  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.

• [WARNING] [colcon build]: The CMAKE_PREFIX_PATH environment variable is set and will be ignored

  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.
  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`).

Warnings

• gotcha 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.
  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.
• gotcha 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.
  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.
• gotcha 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.
  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.
• breaking `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.
  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.

Install

• pip install colcon-common-extensions Install colcon-common-extensions

Imports

• main

  from colcon_core.cli import main

  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.

Quickstart

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.

import subprocess
import sys

# colcon-common-extensions itself is a meta-package and doesn't expose
# direct Python APIs for user applications. Its primary utility is installing
# the 'colcon' command-line tool and its extensions.
# This quickstart verifies the 'colcon' command is available and functional.

try:
    # Using '-m colcon_core.cli' to run colcon as a module is generally more robust
    # than 'colcon' directly, especially in isolated Python environments.
    result = subprocess.run(
        [sys.executable, "-m", "colcon_core.cli", "--version"],
        capture_output=True,
        text=True,
        check=True
    )
    print(f"colcon command is available. Version:\n{result.stdout.strip()}")
    print("colcon command is functional.")
except FileNotFoundError:
    print("Error: 'colcon' executable not found. Ensure colcon-common-extensions is installed and in PATH.")
    sys.exit(1)
except subprocess.CalledProcessError as e:
    print(f"Error running colcon: {e}")
    print(f"Stdout: {e.stdout}")
    print(f"Stderr: {e.stderr}")
    sys.exit(1)