{"id":9609,"library":"colcon-recursive-crawl","title":"colcon-recursive-crawl","description":"colcon-recursive-crawl is an extension for colcon, the build tool for ROS and other package-based systems, enabling it to recursively discover packages within a specified directory structure. As of version 0.2.3, it enhances colcon's package discovery capabilities without requiring manual listing. Releases are infrequent, tied to specific feature additions or compatibility updates with `colcon-core`.","status":"active","version":"0.2.3","language":"en","source_language":"en","source_url":"https://github.com/colcon/colcon-recursive-crawl/","tags":["colcon","build-system","ros","package-management","extension"],"install":[{"cmd":"pip install colcon-recursive-crawl","lang":"bash","label":"Install colcon-recursive-crawl"}],"dependencies":[{"reason":"This is a colcon extension and requires the core colcon package to function.","package":"colcon-core","optional":false}],"imports":[],"quickstart":{"code":"# Assuming you have colcon-core installed and a 'src' directory with ROS packages\n# Create some dummy package structure for demonstration\nimport os\nimport shutil\n\n# Clean up previous run if any\nif os.path.exists('src'):\n    shutil.rmtree('src')\nif os.path.exists('build'):\n    shutil.rmtree('build')\nif os.path.exists('install'):\n    shutil.rmtree('install')\nif os.path.exists('log'):\n    shutil.rmtree('log')\n\n# Create dummy package directories and package.xml files\nos.makedirs('src/my_pkg_a', exist_ok=True)\nos.makedirs('src/my_pkg_b/src', exist_ok=True)\n\nwith open('src/my_pkg_a/package.xml', 'w') as f:\n    f.write('<package><name>my_pkg_a</name><version>0.0.0</version><description>Test A</description><maintainer email=\"a@example.com\">a</maintainer><license>Apache 2.0</license></package>')\n\nwith open('src/my_pkg_b/package.xml', 'w') as f:\n    f.write('<package><name>my_pkg_b</name><version>0.0.0</version><description>Test B</description><maintainer email=\"b@example.com\">b</maintainer><license>Apache 2.0</license><depend>my_pkg_a</depend></package>')\n\nprint(\"Dummy package structure created in 'src/'\")\nprint(\"Now, run colcon build with recursive crawl:\")\nprint(\"colcon build --recursive-crawl src\")\n\n# To actually run the colcon command, you would execute this in a shell:\n# import subprocess\n# try:\n#     subprocess.run(['colcon', 'build', '--recursive-crawl', 'src'], check=True)\n#     print(\"colcon build --recursive-crawl src completed successfully.\")\n# except subprocess.CalledProcessError as e:\n#     print(f\"colcon command failed: {e}\")\n# except FileNotFoundError:\n#     print(\"Error: 'colcon' command not found. Please ensure colcon-core is installed and in your PATH.\")\n","lang":"python","description":"This quickstart demonstrates how to use `colcon-recursive-crawl` to build packages found in a nested directory structure. The extension adds the `--recursive-crawl` argument to standard colcon verbs like `build`, `test`, or `install`. This example sets up a simple `src` directory with two dummy packages for testing."},"warnings":[{"fix":"Ensure `pip install colcon-core` has been run before using `colcon-recursive-crawl`.","message":"colcon-recursive-crawl is an extension for colcon-core. You must have `colcon-core` installed and accessible in your environment for this extension to function.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Correct usage: `colcon build --recursive-crawl src`. Incorrect: `colcon --recursive-crawl build src`.","message":"The `--recursive-crawl` argument must be placed after the colcon verb (e.g., `build`, `test`, `install`) and before any specific package arguments or workspace directories. Incorrect placement can lead to the argument being ignored or an error.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Update `colcon-recursive-crawl` to its latest version (`pip install --upgrade colcon-recursive-crawl`) after upgrading `colcon-core`. Consult `colcon-recursive-crawl`'s GitHub for specific compatibility notes.","message":"Due to its dependency on `colcon-core`, major updates to `colcon-core` might introduce breaking changes that require updates to `colcon-recursive-crawl`. While the extension aims for backward compatibility, always check the release notes if upgrading `colcon-core` to a new major version.","severity":"breaking","affected_versions":"<0.2.0 (potentially with future colcon-core versions)"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Install the extension using `pip install colcon-recursive-crawl`. Ensure the Python environment where `colcon-core` is installed is active.","cause":"The `colcon-recursive-crawl` extension is not installed, or colcon cannot discover it in your Python environment.","error":"colcon: error: unrecognized arguments: --recursive-crawl"},{"fix":"Verify that `package.xml` files exist in the expected package directories within `<your/path>` and that they are correctly formatted according to ROS package standards. Check for typos in the path.","cause":"The specified path does not contain any valid `package.xml` files at its root or recursively, or the XML files are malformed/incomplete.","error":"No packages found in the path '<your/path>'"},{"fix":"Install `colcon-core` using `pip install colcon-core`. If already installed, ensure your shell environment is correctly configured to include the Python script path in your system's PATH variable.","cause":"The `colcon-core` package, which provides the `colcon` command-line tool, is not installed or is not in your system's PATH.","error":"command not found: colcon"}]}