{"id":9602,"library":"colcon-metadata","title":"colcon-metadata","description":"colcon-metadata is an extension for the `colcon` build tool, providing the ability to read package metadata from various file formats beyond `package.xml`. It helps `colcon` discover and process packages in a more flexible way, especially useful for mixed workspaces. It is currently at version 0.2.5 and has an infrequent release cadence, often aligning with `colcon-core` updates.","status":"active","version":"0.2.5","language":"en","source_language":"en","source_url":"https://github.com/colcon/colcon-metadata/","tags":["colcon","build system","ROS","package management","metadata","extension","plugin"],"install":[{"cmd":"pip install colcon-metadata","lang":"bash","label":"Install colcon-metadata"}],"dependencies":[{"reason":"Provides the core `colcon` build system, which `colcon-metadata` extends. Essential for `colcon` commands.","package":"colcon-core","optional":false},{"reason":"Used internally by `colcon-metadata` for package information handling.","package":"colcon-package-information","optional":false}],"imports":[{"note":"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.","symbol":"colcon_metadata","correct":"colcon CLI commands (e.g., colcon build)"}],"quickstart":{"code":"import os\nimport subprocess\nimport shutil\n\n# Define workspace and package paths\nworkspace_dir = \"temp_colcon_metadata_workspace\"\npackage_dir = os.path.join(workspace_dir, \"my_python_package\")\ncolcon_pkg_path = os.path.join(package_dir, \"colcon.pkg\")\n\n# Clean up previous runs if any\nif os.path.exists(workspace_dir):\n    shutil.rmtree(workspace_dir)\n\n# Create directory structure\nos.makedirs(package_dir, exist_ok=True)\n\n# Create a dummy colcon.pkg file for metadata\ncolcon_pkg_content = \"\"\"\ntype: python\nname: my_python_package\nversion: 0.1.0\nmaintainers:\n  - Example User <user@example.com>\n\"\"\"\n\nwith open(colcon_pkg_path, \"w\") as f:\n    f.write(colcon_pkg_content)\n\n# Optional: Create a minimal setup.py and __init__.py for a buildable Python package\nsetup_py_content = \"\"\"\nfrom setuptools import setup\n\nsetup(\n    name='my_python_package',\n    version='0.1.0',\n    packages=['my_python_package'],\n    install_requires=[],\n)\n\"\"\"\n\nos.makedirs(os.path.join(package_dir, \"my_python_package\"), exist_ok=True)\nwith open(os.path.join(package_dir, \"setup.py\"), \"w\") as f:\n    f.write(setup_py_content)\nwith open(os.path.join(package_dir, \"my_python_package\", \"__init__.py\"), \"w\") as f:\n    f.write(\"\")\n\nprint(f\"Created dummy package at: {package_dir}\")\nprint(f\"Created colcon.pkg at: {colcon_pkg_path}\")\n\n# Attempt to run 'colcon build' to demonstrate discovery\nprint(\"\\nAttempting to run 'colcon build' in the workspace...\")\ntry:\n    # Check if colcon is installed\n    subprocess.run([\"colcon\", \"--version\"], check=True, capture_output=True)\n    \n    # Run colcon build for the specific package\n    result = subprocess.run(\n        [\"colcon\", \"build\", \"--packages-select\", \"my_python_package\"],\n        cwd=workspace_dir,\n        check=True,\n        capture_output=True,\n        text=True\n    )\n    print(\"colcon build successful! Output:\\n\")\n    print(result.stdout)\n    if result.stderr:\n        print(\"colcon build stderr:\\n\", result.stderr)\nexcept FileNotFoundError:\n    print(\"Error: 'colcon' command not found. Please install colcon-core: pip install colcon-core\")\nexcept subprocess.CalledProcessError as e:\n    print(f\"colcon build failed: {e}\")\n    print(\"stdout:\\n\", e.stdout)\n    print(\"stderr:\\n\", e.stderr)\nfinally:\n    # Clean up the workspace\n    if os.path.exists(workspace_dir):\n        print(f\"\\nCleaning up {workspace_dir}\")\n        shutil.rmtree(workspace_dir)","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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`.","message":"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`.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","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-core`: `pip install colcon-core`.","cause":"The core `colcon` build tool, which `colcon-metadata` extends, is not installed or not in your system's PATH.","error":"colcon: command not found"},{"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.","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.","error":"Failed to find package 'my_package' with any supported build type."},{"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.","cause":"The `colcon.pkg` file contains syntax errors, likely incorrect YAML formatting (e.g., indentation, missing colons, invalid character sequences).","error":"While parsing config file '.../colcon.pkg': expected <document start>, but found <scalar>"}]}