{"id":9605,"library":"colcon-package-selection","title":"colcon-package-selection","description":"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.","status":"active","version":"0.2.10","language":"en","source_language":"en","source_url":"https://github.com/colcon/colcon-package-selection/","tags":["colcon","ROS","build-system","package-selection","robotics"],"install":[{"cmd":"pip install colcon-package-selection","lang":"bash","label":"Install colcon-package-selection"}],"dependencies":[{"reason":"This library is an extension to colcon, requiring colcon-core for its functionality.","package":"colcon-core","optional":false}],"imports":[{"note":"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.","wrong":"from colcon_package_selection import some_internal_class","symbol":"colcon-package-selection CLI","correct":"colcon build --packages-select PACKAGE_NAME"}],"quickstart":{"code":"colcon build --packages-select my_robot_pkg","lang":"bash","description":"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."},"warnings":[{"fix":"Switch from `colcon build --packages-select PKG` to `colcon build --packages-up-to PKG` when a full dependency chain build is desired.","message":"Using `--packages-select` only builds the specified packages, *not* their recursive dependencies. To build a package and all its dependencies, use `--packages-up-to`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Review your `colcon` command line for conflicting package selection arguments. Ensure `--packages-skip` is not unintentionally overriding a desired `--packages-select` target.","message":"Arguments like `--packages-skip` take precedence over `--packages-select`. If a package is both selected and skipped, it will be skipped.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","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":"Install the extension using `pip install colcon-package-selection`.","cause":"The `colcon-package-selection` extension is not installed or not discoverable by `colcon`.","error":"colcon: error: argument --packages-select: unrecognized arguments: my_package"},{"fix":"If dependencies need to be built, use `colcon build --packages-up-to my_package_name` instead of `--packages-select`.","cause":"The user used `--packages-select` expecting recursive dependencies to be built, but only the specified package was processed.","error":"--- stderr: my_package_name` (followed by build failure due to missing dependencies)"},{"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.","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).","error":"[WARN] Some packages were not found in the workspace: 'non_existent_package'"}]}