{"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":"python","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":[{"wrong":"from colcon_library_path import PackageIdentificationExtension","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,"search_vec":"'0.2.1':52 '2':21 'add':25 'appear':54 'automat':24 'build':15,27,71 'build-tool':70 'built':32 'colcon':2,6,14,36,69 'colcon-library-path':1,5 'common':17 'current':49 'depend':46 'directori':30 'downstream':43 'environ':39,76 'environment-vari':75 'extens':11,73 'featur':64 'help':42 'infrequ':67 'instal':29 'librari':3,7,33,37 'locat':45 'mainten':59 'packag':44 'path':4,8,38 'phase':60 'project':22 'ros':20,74 'set':65 'stabl':63 'system':16 'tool':72 'updat':68 'use':18 'variabl':40,77 'version':51","created_at":"2026-04-17T01:19:45.263163+00:00","updated_at":"2026-04-17T01:19:45.263163+00:00","problems":{"verify_error":"Traceback (most recent call last):\n  File \"<string>\", line 1, in <module>\nModuleNotFoundError: No module named 'colcon_library_path.package_identification'"},"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.2.1","cli_name":"","cli_version":null,"type":"library","homepage":"https://colcon.readthedocs.io","github":"https://github.com/colcon/colcon-library-path","docs":null,"changelog":"https://github.com/colcon/colcon-library-path/milestones?direction=desc&sort=due_date&state=closed","pypi":"https://pypi.org/project/colcon-library-path/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["devops","workflow"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"import_fail","verified_at":"2026-07-03","last_verified":"2026-07-03","next_check":"2026-07-10","install_tag":null}}