{"id":9597,"library":"colcon-cmake","title":"colcon-cmake","description":"colcon-cmake is an extension for the colcon build tool, providing robust support for building, testing, and installing packages that utilize CMake as their build system. It seamlessly integrates CMake projects into the colcon workspace management workflow, enabling consistent project orchestration across various build types. The current version is 0.2.29, with releases generally aligned with colcon's development or as required for improvements and bug fixes.","status":"active","version":"0.2.29","language":"en","source_language":"en","source_url":"https://github.com/colcon/colcon-cmake/","tags":["colcon","cmake","build-system","ros","ros2","development"],"install":[{"cmd":"pip install colcon-cmake","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Provides the core colcon framework which this package extends.","package":"colcon-core","optional":false},{"reason":"Used for package metadata discovery within the colcon ecosystem.","package":"colcon-package-information","optional":false}],"imports":[],"quickstart":{"code":"mkdir -p my_colcon_workspace/src/my_cmake_pkg\ncd my_colcon_workspace/src/my_cmake_pkg\n\n# Create a minimal CMakeLists.txt\necho 'cmake_minimum_required(VERSION 3.1)' > CMakeLists.txt\necho 'project(my_cmake_pkg CXX)' >> CMakeLists.txt\necho 'add_executable(my_node src/main.cpp)' >> CMakeLists.txt\necho 'install(TARGETS my_node DESTINATION bin)' >> CMakeLists.txt\n\n# Create a simple C++ source file\nmkdir src\necho '#include <iostream>\\nint main() { std::cout << \"Hello from colcon-cmake!\" << std::endl; return 0; }' > src/main.cpp\n\n# Go back to the workspace root and build\ncd ../..\ncolcon build\n\n# To run the built executable\n./install/my_cmake_pkg/bin/my_node","lang":"bash","description":"This quickstart demonstrates how to set up a simple CMake package and build it using colcon, leveraging the colcon-cmake extension. Ensure `colcon-cmake` is installed before running `colcon build`."},"warnings":[{"fix":"Ensure your CMake project has a `CMakeLists.txt` in the root of its source directory. For ROS-style packages, add a `package.xml` with `<build_type>cmake</build_type>`.","message":"colcon-cmake relies on `CMakeLists.txt` or `package.xml` for package discovery. If a source directory does not contain a `CMakeLists.txt` file at its root or, for ROS/ROS 2 packages, a `package.xml` specifying `<build_type>cmake</build_type>`, the package might not be identified correctly, leading to it being ignored or a 'Could not find a build type' error.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always use `colcon build --cmake-args -- <YOUR_CMAKE_ARGS>`. The `--` after `--cmake-args` is crucial to separate `colcon`'s own arguments from those intended for CMake.","message":"Passing custom CMake arguments (e.g., `-DCMAKE_BUILD_TYPE=Release`) directly to `colcon build` without proper delimiters will result in these arguments being ignored or causing a `colcon` error.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always ensure your `colcon-core` installation meets or exceeds the minimum version required by `colcon-cmake`. Upgrade `colcon-core` if facing unexplainable errors (`pip install --upgrade colcon-core`).","message":"While `colcon-cmake` generally maintains compatibility, using it with very old versions of `colcon-core` (prior to 0.7.0, which is the minimum required by `colcon-cmake`) can lead to unexpected errors due to API changes in the core framework. Although `pip` prevents this by design, users forcing installations might encounter issues.","severity":"breaking","affected_versions":"colcon-core < 0.7.0"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Install `colcon-core` or `colcon-cmake`: `pip install colcon-cmake`. Ensure your Python environment's script directory (e.g., `~/.local/bin` on Linux) is included in your system's PATH.","cause":"`colcon-core` (which `colcon-cmake` depends on) is either not installed or its executable script directory is not in your system's PATH.","error":"colcon: command not found"},{"fix":"Verify that `CMakeLists.txt` exists at the root of your package's source directory. If applicable, confirm your `package.xml` contains `<build_type>cmake</build_type>`.","cause":"`colcon` could not identify the package as a CMake project. This usually means `CMakeLists.txt` is missing from the package root or, for ROS/ROS 2 packages, `package.xml` doesn't specify `build_type=\"cmake\"`.","error":"Could not find a build type for package 'my_cmake_pkg'"},{"fix":"Install the required system dependency (e.g., `sudo apt install libsomedependency-dev`) or ensure your `CMakeLists.txt` correctly locates the dependency.","cause":"The underlying CMake project itself has a missing dependency. This is a CMake-specific error, not directly related to `colcon-cmake`.","error":"CMake Error at CMakeLists.txt:X (find_package): By not providing a \"FindSomeDependency.cmake\" in CMAKE_MODULE_PATH..."},{"fix":"Use `colcon build --cmake-args -- -DCMAKE_BUILD_TYPE=Release` to correctly pass arguments to CMake.","cause":"CMake-specific arguments were passed directly to `colcon build` without the `--cmake-args` and `--` delimiter.","error":"error: unrecognized arguments: --build-type Release"}]}