colcon-defaults

Common errors

• colcon: error: unrecognized arguments: --defaults-file

  cause The `colcon-defaults` package is not installed or not discoverable by your `colcon` installation.
  fix Ensure `colcon-defaults` is correctly installed in the Python environment that `colcon` is using: `pip install colcon-defaults`. If using a virtual environment, ensure both `colcon-core` and `colcon-defaults` are installed within it.

• yaml.scanner.ScannerError: while scanning a simple key

  cause There is a syntax error in your `defaults.yaml` file. This often means incorrect indentation, a missing colon, or an unquoted string that YAML interprets as a special character.
  fix Review your `defaults.yaml` file carefully, paying attention to indentation and YAML syntax. Ensure keys are followed by colons (`:`), lists are properly indented, and strings containing special characters are quoted. Use a YAML linter to identify the exact line and column of the error.

• colcon build --packages-select foo bar ... --defaults-file defaults.yaml

  cause Attempting to specify both `--packages-select` (or similar package selection arguments) on the command line and `packages` within the `defaults.yaml` for the same colcon command can lead to confusion or unintended behavior due to argument precedence.
  fix Command-line arguments always override defaults. If you specify packages in `defaults.yaml` for `build: packages: [pkg_a]`, and also use `--packages-select pkg_b` on the command line, only `pkg_b` will be considered. For dynamic package selection, prefer using a single source of truth (either the command line or the defaults file, but not both for the same argument type).

Warnings

• gotcha colcon-defaults is a colcon extension, not a standalone library to be imported in Python code. Its functionality is accessed through the `colcon` command-line interface, specifically via the `--defaults-file` argument.
  Fix: Do not attempt to `import colcon_defaults` in your Python scripts for user-facing functionality. Simply install it via `pip install colcon-defaults`, and colcon will automatically discover and use it. Configure its behavior using a `defaults.yaml` file.
• gotcha Command-line arguments always take precedence over values defined in `defaults.yaml`. If an argument is provided on the command line, it will override any corresponding default in the configuration file.
  Fix: Be aware of the precedence. Use `defaults.yaml` for common, baseline configurations, and use command-line arguments for one-off or temporary overrides.
• gotcha Incorrect YAML syntax in `defaults.yaml` can lead to parsing errors and prevent colcon from applying your desired configurations. Common mistakes include incorrect indentation, missing colons, or invalid key structures.
  Fix: Always validate your `defaults.yaml` file for correct YAML syntax. Use a YAML linter or validator, or carefully check for common issues. Ensure the structure (e.g., `build: args: [...]`) matches the expected format for colcon commands.

Install

• pip install colcon-defaults Install colcon-defaults

Imports

• colcon-defaults

  This is a colcon extension and is typically not imported directly by end-user Python code. colcon discovers and loads it automatically upon installation.

  As an extension, colcon-defaults integrates directly into the colcon command-line interface. Users interact with its functionality via colcon commands (e.g., `colcon build --defaults-file`), not by writing Python code that imports it.

Quickstart

This quickstart demonstrates how to use `colcon-defaults` by creating a `defaults.yaml` file that specifies build arguments and target packages. It then executes a `colcon build` command, explicitly passing the `--defaults-file` option. The `colcon` tool, with `colcon-defaults` installed, will automatically parse this file and apply the specified defaults to the build process.

# 1. Create a dummy colcon package (e.g., 'my_package/package.xml')
# This minimal package.xml makes 'my_package' discoverable by colcon
# <package format="3">
#   <name>my_package</name>
#   <version>0.0.0</version>
#   <description>A minimal dummy package</description>
#   <maintainer email="user@example.com">Your Name</maintainer>
#   <license>Apache-2.0</license>
#   <buildtool_depend>ament_cmake</buildtool_depend>
#   <buildtool_depend>ament_cmake_auto</buildtool_depend>
# </package>

# 2. Create a defaults.yaml file in your workspace root
# This file applies custom arguments and selects packages for 'build' command.
with open('defaults.yaml', 'w') as f:
    f.write('''
build:
  args: [ --cmake-args -DCMAKE_BUILD_TYPE=Release ]
  packages: [ my_package ]
''')

# 3. Create a dummy package directory and package.xml for 'my_package'
import os
os.makedirs('my_package', exist_ok=True)
with open('my_package/package.xml', 'w') as f:
    f.write('''
<package format="3">
  <name>my_package</name>
  <version>0.0.0</version>
  <description>A minimal dummy package</description>
  <maintainer email="user@example.com">Your Name</maintainer>
  <license>Apache-2.0</license>
  <buildtool_depend>ament_cmake</buildtool_depend>
  <buildtool_depend>ament_cmake_auto</buildtool_depend>
</package>
''')

# 4. Run colcon build with the defaults file
# This command will build 'my_package' with CMAKE_BUILD_TYPE=Release
# If colcon-defaults is installed, this will apply the defaults.
import subprocess
try:
    print("\n--- Running colcon build with defaults.yaml ---")
    subprocess.run(['colcon', 'build', '--defaults-file', 'defaults.yaml'], check=True)
    print("\n--- colcon build completed. Check build arguments in logs. ---")
except FileNotFoundError:
    print("Error: 'colcon' command not found. Please ensure colcon-core is installed and in your PATH.")
except subprocess.CalledProcessError as e:
    print(f"Error during colcon build: {e}")

# Cleanup (optional)
os.remove('defaults.yaml')
os.remove('my_package/package.xml')
os.rmdir('my_package')