colcon-cmake

Common errors

• colcon: command not found

  cause `colcon-core` (which `colcon-cmake` depends on) is either not installed or its executable script directory is not in your system's PATH.
  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.

• Could not find a build type for package 'my_cmake_pkg'

  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"`.
  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>`.

• CMake Error at CMakeLists.txt:X (find_package): By not providing a "FindSomeDependency.cmake" in CMAKE_MODULE_PATH...

  cause The underlying CMake project itself has a missing dependency. This is a CMake-specific error, not directly related to `colcon-cmake`.
  fix Install the required system dependency (e.g., `sudo apt install libsomedependency-dev`) or ensure your `CMakeLists.txt` correctly locates the dependency.

• error: unrecognized arguments: --build-type Release

  cause CMake-specific arguments were passed directly to `colcon build` without the `--cmake-args` and `--` delimiter.
  fix Use `colcon build --cmake-args -- -DCMAKE_BUILD_TYPE=Release` to correctly pass arguments to CMake.

Warnings

• gotcha 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.
  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>`.
• gotcha 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.
  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.
• breaking 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.
  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`).

Install

• pip install colcon-cmake Install latest version

Quickstart

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`.

mkdir -p my_colcon_workspace/src/my_cmake_pkg
cd my_colcon_workspace/src/my_cmake_pkg

# Create a minimal CMakeLists.txt
echo 'cmake_minimum_required(VERSION 3.1)' > CMakeLists.txt
echo 'project(my_cmake_pkg CXX)' >> CMakeLists.txt
echo 'add_executable(my_node src/main.cpp)' >> CMakeLists.txt
echo 'install(TARGETS my_node DESTINATION bin)' >> CMakeLists.txt

# Create a simple C++ source file
mkdir src
echo '#include <iostream>\nint main() { std::cout << "Hello from colcon-cmake!" << std::endl; return 0; }' > src/main.cpp

# Go back to the workspace root and build
cd ../..
colcon build

# To run the built executable
./install/my_cmake_pkg/bin/my_node