colcon-package-selection

0.2.10 · active · verified Fri Apr 17

colcon-package-selection is an extension for colcon, a build tool primarily used in the Robot Operating System (ROS) ecosystem, to allow users to precisely select which packages should be processed during build, test, or install operations. It enhances colcon's core functionality by providing command-line arguments for including or excluding packages based on names or dependencies. The current version is 0.2.10. It follows the colcon core release cadence, typically tied to ROS releases or when new features/fixes are required.

Common errors

```
colcon: error: argument --packages-select: unrecognized arguments: my_package
```
cause The `colcon-package-selection` extension is not installed or not discoverable by `colcon`.

fix Install the extension using `pip install colcon-package-selection`.
```
--- stderr: my_package_name` (followed by build failure due to missing dependencies)
```
cause The user used `--packages-select` expecting recursive dependencies to be built, but only the specified package was processed.

fix If dependencies need to be built, use `colcon build --packages-up-to my_package_name` instead of `--packages-select`.
```
[WARN] Some packages were not found in the workspace: 'non_existent_package'
```
cause The specified package either doesn't exist, is misspelled, or is not correctly discovered by colcon in the current workspace (e.g., missing a `package.xml` or not sourced correctly).

fix Verify the package name is correct and the package's `package.xml` is valid. Ensure you are running `colcon` in a valid workspace root or have sourced the workspace's `install/setup.bash` (or similar) if necessary.

Warnings

gotcha Using `--packages-select` only builds the specified packages, *not* their recursive dependencies. To build a package and all its dependencies, use `--packages-up-to`.
Fix: Switch from `colcon build --packages-select PKG` to `colcon build --packages-up-to PKG` when a full dependency chain build is desired.
gotcha Arguments like `--packages-skip` take precedence over `--packages-select`. If a package is both selected and skipped, it will be skipped.
Fix: Review your `colcon` command line for conflicting package selection arguments. Ensure `--packages-skip` is not unintentionally overriding a desired `--packages-select` target.
gotcha When using shell globs (e.g., `colcon build --packages-select 'my_pkg_*'`), be aware that your shell might expand the glob before `colcon` processes it, potentially leading to incorrect selection or command-line length issues.
Fix: Always quote your package patterns (e.g., `colcon build --packages-select 'my_pkg*'` or use colcon's `--regex` option if available for more complex patterns. Consult `colcon`'s documentation for specific pattern matching capabilities.

Install

pip install colcon-package-selection Install colcon-package-selection

Imports

colcon-package-selection CLI
wrong:
```
from colcon_package_selection import some_internal_class
```
correct:
```
colcon build --packages-select PACKAGE_NAME
```
This library is primarily an extension to the `colcon` command-line interface. Users interact with its functionality via `colcon` arguments (e.g., `--packages-select`), not through direct Python imports into user code. Attempting to import internal classes is generally incorrect for typical usage.

Quickstart

Demonstrates building a single package (`my_robot_pkg`) and its direct dependencies using `--packages-select`. This is the primary way to interact with `colcon-package-selection`. Ensure `colcon-package-selection` is installed and your `my_robot_pkg` is discoverable in the current workspace.

colcon build --packages-select my_robot_pkg

view raw JSON →