colcon-metadata

Common errors

• colcon: command not found

  cause The core `colcon` build tool, which `colcon-metadata` extends, is not installed or not in your system's PATH.
  fix Install `colcon-core`: `pip install colcon-core`.

• Failed to find package 'my_package' with any supported build type.

  cause While `colcon-metadata` might have read your `colcon.pkg`, `colcon` requires a build extension (e.g., `colcon-ros-python-setup-py`) to know how to build the package type declared. This error also occurs if `colcon.pkg` is not in the package root.
  fix Verify `colcon.pkg` is in the package root. Install the relevant `colcon` build extension for the `type` specified in your `colcon.pkg` (e.g., `pip install colcon-ros-python-setup-py` for `type: python`). Use `colcon build --log-level debug` for detailed discovery logs.

• While parsing config file '.../colcon.pkg': expected <document start>, but found <scalar>

  cause The `colcon.pkg` file contains syntax errors, likely incorrect YAML formatting (e.g., indentation, missing colons, invalid character sequences).
  fix Carefully review the `colcon.pkg` file for correct YAML syntax. Pay close attention to indentation and key-value pair formatting. Use a YAML linter to validate the file.

Warnings

• gotcha colcon.pkg files are written in YAML. Any indentation errors or incorrect syntax will lead to parsing failures, which might present as generic package discovery errors if not debugged with verbose `colcon` output.
  Fix: Strictly adhere to YAML syntax. Use a YAML linter during development of `colcon.pkg` files. Run `colcon build --log-level debug` for detailed parsing feedback.
• gotcha colcon-metadata only provides the ability to *read* a `colcon.pkg` file. For `colcon` to actually *build* the package, a separate build extension (e.g., for Python, CMake, etc.) must also be installed and capable of handling the package `type` specified in `colcon.pkg`.
  Fix: Ensure that the necessary `colcon` build extensions (e.g., `colcon-ros-python-setup-py` for Python packages, `colcon-ament-cmake` for CMake) are installed and compatible with the package type declared in your `colcon.pkg`.
• gotcha If multiple `colcon` extensions provide metadata for the same package or source file, the behavior might be undefined or depend on the internal loading order of extensions. This can lead to unexpected package discovery or configuration.
  Fix: Be mindful of other `colcon` extensions installed in your environment, especially if you encounter conflicts in package discovery. Explicitly list packages to build using `--packages-select` if ambiguity arises. Consult `colcon` documentation for extension priority.

Install

• pip install colcon-metadata Install colcon-metadata

Imports

• colcon_metadata

  colcon CLI commands (e.g., colcon build)

  colcon-metadata is a colcon extension that registers entry points; it is not typically imported directly into user Python code. Its functionality is exposed via the `colcon` command-line interface.

Quickstart

This quickstart demonstrates `colcon-metadata` by creating a temporary `colcon` workspace with a Python package defined solely by a `colcon.pkg` file. It then attempts to run `colcon build` to show how `colcon`, with the `colcon-metadata` extension, can discover and process packages based on this metadata file. Ensure `colcon-core` is installed in your environment for the `colcon` command to be available.

import os
import subprocess
import shutil

# Define workspace and package paths
workspace_dir = "temp_colcon_metadata_workspace"
package_dir = os.path.join(workspace_dir, "my_python_package")
colcon_pkg_path = os.path.join(package_dir, "colcon.pkg")

# Clean up previous runs if any
if os.path.exists(workspace_dir):
    shutil.rmtree(workspace_dir)

# Create directory structure
os.makedirs(package_dir, exist_ok=True)

# Create a dummy colcon.pkg file for metadata
colcon_pkg_content = """
type: python
name: my_python_package
version: 0.1.0
maintainers:
  - Example User <user@example.com>
"""

with open(colcon_pkg_path, "w") as f:
    f.write(colcon_pkg_content)

# Optional: Create a minimal setup.py and __init__.py for a buildable Python package
setup_py_content = """
from setuptools import setup

setup(
    name='my_python_package',
    version='0.1.0',
    packages=['my_python_package'],
    install_requires=[],
)
"""

os.makedirs(os.path.join(package_dir, "my_python_package"), exist_ok=True)
with open(os.path.join(package_dir, "setup.py"), "w") as f:
    f.write(setup_py_content)
with open(os.path.join(package_dir, "my_python_package", "__init__.py"), "w") as f:
    f.write("")

print(f"Created dummy package at: {package_dir}")
print(f"Created colcon.pkg at: {colcon_pkg_path}")

# Attempt to run 'colcon build' to demonstrate discovery
print("\nAttempting to run 'colcon build' in the workspace...")
try:
    # Check if colcon is installed
    subprocess.run(["colcon", "--version"], check=True, capture_output=True)
    
    # Run colcon build for the specific package
    result = subprocess.run(
        ["colcon", "build", "--packages-select", "my_python_package"],
        cwd=workspace_dir,
        check=True,
        capture_output=True,
        text=True
    )
    print("colcon build successful! Output:\n")
    print(result.stdout)
    if result.stderr:
        print("colcon build stderr:\n", result.stderr)
except FileNotFoundError:
    print("Error: 'colcon' command not found. Please install colcon-core: pip install colcon-core")
except subprocess.CalledProcessError as e:
    print(f"colcon build failed: {e}")
    print("stdout:\n", e.stdout)
    print("stderr:\n", e.stderr)
finally:
    # Clean up the workspace
    if os.path.exists(workspace_dir):
        print(f"\nCleaning up {workspace_dir}")
        shutil.rmtree(workspace_dir)