colcon-output

0.2.14 · active · verified Fri Apr 17

colcon-output is an extension for the colcon build tool, primarily used in the ROS ecosystem, to customize and enhance the terminal output in various ways. It provides alternative output formats like 'log' for more detailed logs and 'json' for machine-readable output. The current version is 0.2.14, and it follows an infrequent, feature-driven release cadence, typically aligning with `colcon-core` updates.

Common errors

```
colcon: error: unrecognized arguments: --output-format
```
cause `colcon-output` is not installed or not correctly recognized by `colcon`.

fix Ensure `colcon-output` is installed in the same Python environment as `colcon-core` using `pip install colcon-output`. Verify installation with `pip list | grep colcon-output`.
```
Unknown output format 'my_custom_format'. Valid formats are: ['standard', 'log', 'json', 'json_verbose']
```
cause An invalid or misspelled output format was provided to the `--output-format` argument.

fix Use one of the officially supported output formats listed in the error message. Refer to the `colcon-output` documentation or its `--help` output for a current list of available formats.
```
Error: Failed to load entry point 'some_entry_point' for 'colcon_core.plugin.some_type'
```
cause Plugin loading issue, often due to corrupted installation or environment path problems.

fix Try reinstalling `colcon-output` and `colcon-core` (`pip uninstall colcon-output colcon-core && pip install colcon-output colcon-core`). Ensure your Python environment is clean and correctly activated.

Warnings

gotcha colcon-output is an extension, not a standalone library. Trying to `import colcon_output` directly in user scripts for its functionality will not work as expected, as its features are exposed through the `colcon` CLI.
Fix: Access `colcon-output` features through `colcon` command-line arguments (e.g., `--output-format`) or `colcon` configuration files, not via direct Python imports in user code.
gotcha Color output may appear inconsistent or be disabled in certain terminal environments or CI/CD pipelines. This can be influenced by terminal capabilities or specific environment variables.
Fix: For fine-tuning color darkening, set the `COLCON_COLOR_DARKEN_THRESHOLD` environment variable (e.g., `export COLCON_COLOR_DARKEN_THRESHOLD=10`). Ensure your terminal supports 256-color output. In CI environments, you might need to force color output if it's automatically disabled.
gotcha Compatibility with `colcon-core` versions is crucial. Using an outdated `colcon-output` with a very new `colcon-core` (or vice-versa) might lead to unexpected behavior or missing features.
Fix: Always ensure your `colcon-output` version is compatible with your `colcon-core` version. Check the `colcon-output` release notes and `colcon-core` documentation for specific compatibility matrices. Update both packages regularly (`pip install --upgrade colcon-core colcon-output`).

Install

pip install colcon-output Install colcon-output

Imports

colcon-output functionality
wrong:
```
from colcon_output import SomeClass
```
correct:
```
Functionality is enabled via colcon CLI arguments or configuration, not direct Python imports.
```
colcon-output is a colcon extension, not a library meant for direct programmatic import by end-user applications. Its features are accessed through the `colcon` command-line interface.

Quickstart

This quickstart demonstrates how to use the `colcon-output` extension by specifying different output formats during a `colcon build` command. The `--output-format` argument allows you to switch between available formats like `standard`, `log`, `json`, or `json_verbose`.

# Assuming you have a colcon workspace with a package (e.g., 'my_package')
# Build with the 'log' output format for detailed messages
# (Often used in CI/CD or when debugging verbose output)
colcon build --packages-select my_package --output-format log

# Build with the 'json' output format for machine-readable results
# (Useful for parsing build status in scripts)
colcon build --packages-select my_package --output-format json

view raw JSON →