colcon-library-path

Common errors

• colcon command not found

  cause The `colcon` build tool, which `colcon-library-path` extends, is not installed or not in your system's PATH.
  fix Install `colcon` and its common extensions: `pip install colcon-common-extensions`

• ImportError: No module named 'colcon_library_path'

  cause You are attempting to `import colcon_library_path` directly in a Python script. This library is an extension for the `colcon` CLI and is not designed for direct programmatic import by end-users.
  fix This library's functionality is accessed via the `colcon` command-line interface (e.g., `colcon build --add-build-paths`). You typically don't import it in your Python code.

• Libraries are not found by downstream packages after building with colcon.

  cause The `colcon-library-path` extension was either not activated during the build, or the `colcon` environment setup file was not sourced.
  fix 1. Ensure you used `--add-build-paths` (or `--library-path`) in your `colcon build` command. 2. After building, open a new terminal or run `source install/setup.bash` (or `setup.ps1`/`setup.bat`) to set the environment variables, including `COLCON_LIBRARY_PATH`.

Warnings

• gotcha The `COLCON_LIBRARY_PATH` environment variable, managed by this extension, is primarily used by colcon's internal environment setup (e.g., in `setup.bash`/`setup.ps1`). It does not directly modify system-wide library search paths like `LD_LIBRARY_PATH` on Linux or `PATH` on Windows. You must source the `install/setup.*` file to activate it in your current shell.
  Fix: Always source the `install/setup.bash` (or equivalent for your shell) file in your terminal after a `colcon build` to make the library paths available for subsequent commands or packages.
• gotcha The `colcon-library-path` extension is only active when specific `colcon build` options are used, primarily `--add-build-paths` or `--library-path`. Without these options, the extension will not modify `COLCON_LIBRARY_PATH`.
  Fix: Ensure you explicitly add `--add-build-paths` to your `colcon build` command to enable this extension's functionality. For specific path additions, use `--library-path 'PKG_NAME:PATH'`.
• gotcha If you are migrating from older build systems or have complex environment setups, ensure that `COLCON_LIBRARY_PATH` is not being inadvertently overridden or cleared by other environment scripts. The ordering of environment file sourcing matters.
  Fix: Inspect your shell's startup files (e.g., `.bashrc`, `.profile`) and any other `setup.*` files you source to ensure that `colcon`'s environment setup (and thus `COLCON_LIBRARY_PATH`) is applied correctly and not undone by subsequent commands.

Install

• pip install colcon-library-path Install latest version

Imports

• PackageIdentificationExtension

  from colcon_library_path.package_identification import PackageIdentificationExtension

  This library is primarily a colcon CLI extension and not intended for direct programmatic import by user applications. This symbol is an internal component of its plugin system.

Quickstart

This quickstart demonstrates the effect of `colcon-library-path` by programmatically (via `subprocess`) running a `colcon build` command with the `--add-build-paths` option. It then simulates sourcing the generated `setup.bash` file and prints the `COLCON_LIBRARY_PATH` environment variable, showing how the extension contributes library paths. Note that `colcon-library-path` is primarily a CLI extension for `colcon` and is not typically used for direct programmatic Python imports.

import subprocess
import os
import shutil

# --- Setup: Create a dummy colcon workspace and package ---
# This part simulates typical shell commands for setting up a colcon project.
workspace_path = "my_colcon_workspace"
os.makedirs(f"{workspace_path}/src/my_library", exist_ok=True)
with open(f"{workspace_path}/src/my_library/CMakeLists.txt", "w") as f:
    f.write("project(my_library NONE)\n")
    f.write("add_library(my_library SHARED my_library.cpp)\n")
with open(f"{workspace_path}/src/my_library/my_library.cpp", "w") as f:
    f.write("// dummy C++ file\nint main() { return 0; }")

print(f"Created dummy package in {workspace_path}/src/my_library")

# --- Step 1: Run colcon build with --add-build-paths ---
# This activates the colcon-library-path extension.
try:
    print("\nRunning colcon build with --add-build-paths...")
    # Ensure colcon is in PATH, otherwise specify full path to colcon executable
    result = subprocess.run(
        ['colcon', 'build', '--cmake-args', '-DBUILD_SHARED_LIBS=ON',
         '--packages-select', 'my_library', '--add-build-paths'],
        cwd=workspace_path,
        check=True,
        capture_output=True,
        text=True
    )
    print("colcon build stdout:\n" + result.stdout)
    if result.stderr:
        print("colcon build stderr:\n" + result.stderr)

except FileNotFoundError:
    print("Error: 'colcon' command not found. Please install colcon (pip install colcon-common-extensions).")
    # Cleanup before exiting
    shutil.rmtree(workspace_path)
    exit(1)
except subprocess.CalledProcessError as e:
    print(f"Error during colcon build:\n{e.stderr}")
    # Cleanup before exiting
    shutil.rmtree(workspace_path)
    exit(1)

# --- Step 2: Source the generated setup file and check COLCON_LIBRARY_PATH ---
# This demonstrates the effect of colcon-library-path on the environment.
setup_file_path = os.path.join(workspace_path, "install", "setup.bash")
if os.path.exists(setup_file_path):
    print(f"\nSourcing {setup_file_path} and checking COLCON_LIBRARY_PATH...")
    # Simulate sourcing in a new shell to get the environment variable
    command = f"source {setup_file_path} && echo $COLCON_LIBRARY_PATH"
    result_env = subprocess.run(
        ['bash', '-c', command],
        check=True,
        capture_output=True,
        text=True
    )
    colcon_lib_path = result_env.stdout.strip()
    print(f"COLCON_LIBRARY_PATH after setup: {colcon_lib_path}")
    if f"{workspace_path}/install/my_library/lib" in colcon_lib_path or \
       f"{workspace_path}/build/my_library" in colcon_lib_path:
        print("\u2705 colcon-library-path successfully contributed to COLCON_LIBRARY_PATH.")
    else:
        print("\u274c COLCON_LIBRARY_PATH does not contain expected library paths.")
else:
    print(f"\u274c Error: {setup_file_path} not found. Build might have failed or not produced a setup file.")

# --- Cleanup ---
print(f"\nCleaning up workspace: {workspace_path}")
shutil.rmtree(workspace_path)