Install & Compatibility
Where this runs
tested against v0.2.9 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.000s · 39.6MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 5.3s · import 0.000s · 41MB
43MB installed
● package 43MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
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.
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')
colcon --version
Upgrade
Version history
0.2.9latest on PyPI · released Dec 18, 2024
Audit
Dependencies
colcon-corerequiredcolcon-defaults is an extension for colcon and requires the core colcon functionality.
PyYAMLrequiredUsed for parsing the YAML default configuration files.