colcon-recursive-crawl

Common errors

• colcon: error: unrecognized arguments: --recursive-crawl

  cause The `colcon-recursive-crawl` extension is not installed, or colcon cannot discover it in your Python environment.
  fix Install the extension using `pip install colcon-recursive-crawl`. Ensure the Python environment where `colcon-core` is installed is active.

• No packages found in the path '<your/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.
  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.

• command not found: colcon

  cause The `colcon-core` package, which provides the `colcon` command-line tool, is not installed or is not in your system's 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.

Warnings

• gotcha 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.
  Fix: Ensure `pip install colcon-core` has been run before using `colcon-recursive-crawl`.
• gotcha 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.
  Fix: Correct usage: `colcon build --recursive-crawl src`. Incorrect: `colcon --recursive-crawl build src`.
• breaking 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.
  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.

Install

• pip install colcon-recursive-crawl Install colcon-recursive-crawl

Quickstart

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.

# Assuming you have colcon-core installed and a 'src' directory with ROS packages
# Create some dummy package structure for demonstration
import os
import shutil

# Clean up previous run if any
if os.path.exists('src'):
    shutil.rmtree('src')
if os.path.exists('build'):
    shutil.rmtree('build')
if os.path.exists('install'):
    shutil.rmtree('install')
if os.path.exists('log'):
    shutil.rmtree('log')

# Create dummy package directories and package.xml files
os.makedirs('src/my_pkg_a', exist_ok=True)
os.makedirs('src/my_pkg_b/src', exist_ok=True)

with open('src/my_pkg_a/package.xml', 'w') as f:
    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>')

with open('src/my_pkg_b/package.xml', 'w') as f:
    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>')

print("Dummy package structure created in 'src/'")
print("Now, run colcon build with recursive crawl:")
print("colcon build --recursive-crawl src")

# To actually run the colcon command, you would execute this in a shell:
# import subprocess
# try:
#     subprocess.run(['colcon', 'build', '--recursive-crawl', 'src'], check=True)
#     print("colcon build --recursive-crawl src completed successfully.")
# except subprocess.CalledProcessError as e:
#     print(f"colcon command failed: {e}")
# except FileNotFoundError:
#     print("Error: 'colcon' command not found. Please ensure colcon-core is installed and in your PATH.")