{"id":9601,"library":"colcon-library-path","title":"colcon-library-path","description":"colcon-library-path is an extension for the colcon build system (commonly used in ROS 2 projects) that automatically adds the build and install directories of built libraries to the COLCON_LIBRARY_PATH environment variable. This helps downstream packages locate dependencies. It is currently at version 0.2.1 and appears to be in a maintenance phase, with a stable feature set and infrequent updates.","status":"maintenance","version":"0.2.1","language":"en","source_language":"en","source_url":"https://github.com/colcon/colcon-library-path/","tags":["colcon","build-tool","extension","ROS","environment-variables"],"install":[{"cmd":"pip install colcon-library-path","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"This package is a colcon extension and requires colcon-core to function.","package":"colcon-core","optional":false},{"reason":"Required for package information processing within colcon.","package":"colcon-package-information","optional":false}],"imports":[{"note":"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.","symbol":"PackageIdentificationExtension","correct":"from colcon_library_path.package_identification import PackageIdentificationExtension"}],"quickstart":{"code":"import subprocess\nimport os\nimport shutil\n\n# --- Setup: Create a dummy colcon workspace and package ---\n# This part simulates typical shell commands for setting up a colcon project.\nworkspace_path = \"my_colcon_workspace\"\nos.makedirs(f\"{workspace_path}/src/my_library\", exist_ok=True)\nwith open(f\"{workspace_path}/src/my_library/CMakeLists.txt\", \"w\") as f:\n    f.write(\"project(my_library NONE)\\n\")\n    f.write(\"add_library(my_library SHARED my_library.cpp)\\n\")\nwith open(f\"{workspace_path}/src/my_library/my_library.cpp\", \"w\") as f:\n    f.write(\"// dummy C++ file\\nint main() { return 0; }\")\n\nprint(f\"Created dummy package in {workspace_path}/src/my_library\")\n\n# --- Step 1: Run colcon build with --add-build-paths ---\n# This activates the colcon-library-path extension.\ntry:\n    print(\"\\nRunning colcon build with --add-build-paths...\")\n    # Ensure colcon is in PATH, otherwise specify full path to colcon executable\n    result = subprocess.run(\n        ['colcon', 'build', '--cmake-args', '-DBUILD_SHARED_LIBS=ON',\n         '--packages-select', 'my_library', '--add-build-paths'],\n        cwd=workspace_path,\n        check=True,\n        capture_output=True,\n        text=True\n    )\n    print(\"colcon build stdout:\\n\" + result.stdout)\n    if result.stderr:\n        print(\"colcon build stderr:\\n\" + result.stderr)\n\nexcept FileNotFoundError:\n    print(\"Error: 'colcon' command not found. Please install colcon (pip install colcon-common-extensions).\")\n    # Cleanup before exiting\n    shutil.rmtree(workspace_path)\n    exit(1)\nexcept subprocess.CalledProcessError as e:\n    print(f\"Error during colcon build:\\n{e.stderr}\")\n    # Cleanup before exiting\n    shutil.rmtree(workspace_path)\n    exit(1)\n\n# --- Step 2: Source the generated setup file and check COLCON_LIBRARY_PATH ---\n# This demonstrates the effect of colcon-library-path on the environment.\nsetup_file_path = os.path.join(workspace_path, \"install\", \"setup.bash\")\nif os.path.exists(setup_file_path):\n    print(f\"\\nSourcing {setup_file_path} and checking COLCON_LIBRARY_PATH...\")\n    # Simulate sourcing in a new shell to get the environment variable\n    command = f\"source {setup_file_path} && echo $COLCON_LIBRARY_PATH\"\n    result_env = subprocess.run(\n        ['bash', '-c', command],\n        check=True,\n        capture_output=True,\n        text=True\n    )\n    colcon_lib_path = result_env.stdout.strip()\n    print(f\"COLCON_LIBRARY_PATH after setup: {colcon_lib_path}\")\n    if f\"{workspace_path}/install/my_library/lib\" in colcon_lib_path or \\\n       f\"{workspace_path}/build/my_library\" in colcon_lib_path:\n        print(\"\\u2705 colcon-library-path successfully contributed to COLCON_LIBRARY_PATH.\")\n    else:\n        print(\"\\u274c COLCON_LIBRARY_PATH does not contain expected library paths.\")\nelse:\n    print(f\"\\u274c Error: {setup_file_path} not found. Build might have failed or not produced a setup file.\")\n\n# --- Cleanup ---\nprint(f\"\\nCleaning up workspace: {workspace_path}\")\nshutil.rmtree(workspace_path)\n","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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'`.","message":"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`.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"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` build tool, which `colcon-library-path` extends, is not installed or not in your system's PATH.","error":"colcon command not found"},{"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.","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.","error":"ImportError: No module named 'colcon_library_path'"},{"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`.","cause":"The `colcon-library-path` extension was either not activated during the build, or the `colcon` environment setup file was not sourced.","error":"Libraries are not found by downstream packages after building with colcon."}]}