{"id":9598,"library":"colcon-defaults","title":"colcon-defaults","description":"colcon-defaults is an extension for the colcon build tool, primarily used in the ROS 2 ecosystem. It allows users to define default arguments and package sets for colcon commands (like `build`, `test`) in a YAML configuration file, such as `defaults.yaml`. This helps streamline complex build workflows and ensure consistent build parameters across projects or team members. The current stable version is 0.2.9, and it maintains a consistent release cadence aligned with colcon updates, focusing on stability and integration.","status":"active","version":"0.2.9","language":"en","source_language":"en","source_url":"https://github.com/colcon/colcon-defaults/","tags":["colcon","ROS","ROS2","build system","configuration","automation"],"install":[{"cmd":"pip install colcon-defaults","lang":"bash","label":"Install colcon-defaults"}],"dependencies":[{"reason":"colcon-defaults is an extension for colcon and requires the core colcon functionality.","package":"colcon-core","optional":false},{"reason":"Used for parsing the YAML default configuration files.","package":"PyYAML","optional":false}],"imports":[{"note":"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.","symbol":"colcon-defaults","correct":"This is a colcon extension and is typically not imported directly by end-user Python code. colcon discovers and loads it automatically upon installation."}],"quickstart":{"code":"# 1. Create a dummy colcon package (e.g., 'my_package/package.xml')\n# This minimal package.xml makes 'my_package' discoverable by colcon\n# <package format=\"3\">\n#   <name>my_package</name>\n#   <version>0.0.0</version>\n#   <description>A minimal dummy package</description>\n#   <maintainer email=\"user@example.com\">Your Name</maintainer>\n#   <license>Apache-2.0</license>\n#   <buildtool_depend>ament_cmake</buildtool_depend>\n#   <buildtool_depend>ament_cmake_auto</buildtool_depend>\n# </package>\n\n# 2. Create a defaults.yaml file in your workspace root\n# This file applies custom arguments and selects packages for 'build' command.\nwith open('defaults.yaml', 'w') as f:\n    f.write('''\nbuild:\n  args: [ --cmake-args -DCMAKE_BUILD_TYPE=Release ]\n  packages: [ my_package ]\n''')\n\n# 3. Create a dummy package directory and package.xml for 'my_package'\nimport os\nos.makedirs('my_package', exist_ok=True)\nwith open('my_package/package.xml', 'w') as f:\n    f.write('''\n<package format=\"3\">\n  <name>my_package</name>\n  <version>0.0.0</version>\n  <description>A minimal dummy package</description>\n  <maintainer email=\"user@example.com\">Your Name</maintainer>\n  <license>Apache-2.0</license>\n  <buildtool_depend>ament_cmake</buildtool_depend>\n  <buildtool_depend>ament_cmake_auto</buildtool_depend>\n</package>\n''')\n\n# 4. Run colcon build with the defaults file\n# This command will build 'my_package' with CMAKE_BUILD_TYPE=Release\n# If colcon-defaults is installed, this will apply the defaults.\nimport subprocess\ntry:\n    print(\"\\n--- Running colcon build with defaults.yaml ---\")\n    subprocess.run(['colcon', 'build', '--defaults-file', 'defaults.yaml'], check=True)\n    print(\"\\n--- colcon build completed. Check build arguments in logs. ---\")\nexcept FileNotFoundError:\n    print(\"Error: 'colcon' command not found. Please ensure colcon-core is installed and in your PATH.\")\nexcept subprocess.CalledProcessError as e:\n    print(f\"Error during colcon build: {e}\")\n\n# Cleanup (optional)\nos.remove('defaults.yaml')\nos.remove('my_package/package.xml')\nos.rmdir('my_package')\n","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Be aware of the precedence. Use `defaults.yaml` for common, baseline configurations, and use command-line arguments for one-off or temporary overrides.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","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":"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.","cause":"The `colcon-defaults` package is not installed or not discoverable by your `colcon` installation.","error":"colcon: error: unrecognized arguments: --defaults-file"},{"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.","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.","error":"yaml.scanner.ScannerError: while scanning a simple key"},{"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).","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.","error":"colcon build --packages-select foo bar ... --defaults-file defaults.yaml"}]}