Migrating from catkin_make¶
Important Distinctions between catkin_make
and catkin build
¶
Unlike catkin_make
, the catkin
command-line tool is not just a thin wrapper around a the cmake
and make
commands.
The catkin build
command builds each package in a workspace’s source space in isolation in order to prevent build-time cross-talk.
As such, in its simplest use, catkin build
behaves similarly to a parallelized version of catkin_make_isolated
.
While there are many more features in catkin_tools
described in the rest of the documentation, this chapter provides details on how to switch from using catkin_make
and catkin_make_isolated
.
This chapter does not describe advanced features that catkin_tools
provides over catkin_make
and catkin_make_isolated
.
For a quick overview of what you can do with catkin build
, see the Cheat Sheet.
Implications of Isolation¶
Build isolation has the following implications for both catkin_make_isolated
and catkin build
:
- There is no “top-level”
CMakeLists.txt
file in the source space. - Each package in a
catkin_tools
workspace has its own isolated build space. - Packages built with
catkin build
can not access variables defined in other Catkin packages in the same workspace. - All targets in each of a package’s dependencies are guaranteed to have been built before the current package.
- Packages do not need to define target dependencies on ROS messages built in other packages.
- It passes the same CMake command line arguments to multiple packages.
- Plain CMake packages can be built if they each have a
package.xml
file with the appropriate <build_type> tag.
Additional Differences with catkin build
¶
In addition to the differences due to isolation, catkin build
is also different from catkin_make_isolated
in the following ways:
- It builds packages in parallel, using an internal job server to distribute load.
- It puts products into hidden directories, and then symbolically links them into the devel space (by default).
- It stores persistent configuration options in a
.catkin_tools
directory at the root of your workspace. - It passes
--no-warn-unused-cli
to thecmake
command since not all packages accept the same CMake arguments. - It generates
.catkin
files where each source package is listed, individually, instead of just listing the source space for the workspace. This leads to similarROS_PACKAGE_PATH
variables which list each package source space.
Step-by-Step Migration¶
Most problems users will encounter when migrating from catkin_make
to catkin build
are due to hidden bugs in packages which previously relied on side-effects from their dependencies to build.
The best way to debug these problems before switching to the entirely new tool, is to use catkin_make_isolated
first.
Note that all three of these tools can share source spaces, but they must use their own build, devel, and install spaces.
1. Verify that your packages already build with catkin_make
:¶
To make iterating easier, use catkin_make
with build and devel spaces with the suffix _cm
so that they do not collide with the other build tools:
cd /path/to/ws
catkin_make --build build_cm --cmake-args -DCATKIN_DEVEL_PREFIX=devel_cm -DCMAKE_INSTALL_PREFIX=install_cm [CMAKE_ARGS...] --make-args [MAKE_ARGS...]
If your packages build and other appropriate tests pass, continue to the next step.
2. Verify that your packages build in isolation:¶
Use catkin_make_isolated
with build and devel spaces with the suffix _cmi
, and make sure your packages build in isolation.
This is where you are most likely to discover bugs in your packages’ CMakeLists.txt
files.
Fix each problem, using the troubleshooting advice later in this chapter.
cd /path/to/ws
catkin_make_isolated --build build_cmi --devel devel_cmi --merge --cmake-args [CMAKE_ARGS...] --make-args [MAKE_ARGS...]
Once your packages build (and other appropriate tests pass), continue to the next step.
3. Build with catkin build
:¶
Finally, you can verify that your packages build with catkin build
, using build and devel spaces with the suffix _cb
.
Since catkin build
stores build configuration, you only need to set your CMake and Make args once:
cd /path/to/ws
catkin config --space-suffix _cb --cmake-args [CMAKE_ARGS...] --make-args [MAKE_ARGS...]
Then you can build with catkin build
.
If issues arise, try to use the troubleshooting advice later in this chapter and in the main Troubleshooting chapter.
cd /path/to/ws
catkin build
Once the build succeeds and your appropriate tests pass, you can go on to continue using catkin build
!
Migration Troubleshooting¶
When migrating from catkin_make
to catkin build, the most common problems come from Catkin packages taking advantage of package cross-talk in the CMake configuration stage.
Many Catkin packages implicitly rely on other packages in a workspace to declare and find dependencies.
When switching from catkin_make
, users will often discover these bugs.
Common Issues¶
Unknown CMake command “catkin_package”¶
If find_package(catkin REQUIRED ...)
isn’t called, then the catkin_package()
macro will not be available.
If such a package builds with catkin_make
, it’s because it’s relying on another package in the same workspace to do this work.
Compilation Errors (Missing Headers)¶
Compilation errors can occur if required headers are not found.
If your package includes headers from ${catkin_INCLUDE_DIRS}
, make sure that package is finding the right Catkin packages in find_package(catkin COMPONENTS ...)
.
If your package includes headers from other libraries, make sure those libraries are found and those CMake variables are defined.
Linker Errors (Undefined References)¶
Linker errors are due to targets not being linked to required libraries.
If your target links against ${catkin_LIBRARIES}
, make sure that package is finding the right Catkin packages in find_package(catkin COMPONENTS ...)
.
If your target links against other libraries, make sure those libraries are found and those CMake variables are defined.
Targets Not Being Built¶
It is critical for Catkin-based packages to call catkin_package()
before any targets are defined.
Otherwise your targets will not be built into the devel space.
Previously with catkin_make
, as long as some package called catkin_package()
before your package was configured, the appropriate target destinations were defined.
Compiler Options Aren’t Correct¶
Your program might fail to build or fail to run due to incorrect compiler options. Sometimes these compiler options are needed to use a dependency, but aren’t made available to the dependent package.
With catkin_make
, if a package sets certain compiler options, such as:
set(CMAKE_CXX_FLAGS "-std=c++ ${CMAKE_CXX_FLAGS}")
These options will be set for every package in the topological sort which is built after it, even packages which don’t depend on it.
With catkin build
, however, these effects are isolated, so even the packages that need these options will not get them.
The catkin_package()
macro already provides options for exporting libraries and include directories, but it does not have an option for CMake variables.
To export such settings (or even execute code), the CFG_EXTRAS
option must be used with an accompanying CMake file.
For more information on this option, see the catkin_package() documentation.
Uncommon Issues¶
Exporting Build Utilities¶
Some Catkin packages provide build tools at configuration time, like scripts for generating code or downloading resources from the internet. These packages need to export absolute paths to such tools both when used in a workspace and when installed.
For example, when using in a source space, the build tools from package my_build_util
would be found at ${CMAKE_CURRENT_SOURCE_DIR}/cmake
, but when installed, they would be found in ${my_build_util_DIR}
.
With catkin_make
, the path to these tools could be set to either the source or install space in the provider package just by setting a CMake variable, which would be “leaked” to all subsequently built packages.
With catkin build
, these paths need to be properly exported with CFG_EXTRAS
.
A way to do this that works both out of a workspace and install is shown below:
# generated from stdr_common/cmake/stdr_common-extras.cmake.em
@[if DEVELSPACE]@
# set path to source space
set(my_build_util_EXTRAS_DIR "@(CMAKE_CURRENT_SOURCE_DIR)/cmake")
@[else]@
# set path to installspace
set(my_build_util_EXTRAS_DIR "${my_build_util_DIR}")
@[end if]@
Exporting Non-Standard Library Output Locations or Prefixes¶
Some users may choose to build library targets with non-standard output locations or prefixes.
However, the normal catkin_package()
macro cannot export libraries with such paths across packages.
Again, we can use the CFG_EXTRAS
option to append the special library to the ${PROJECT_NAME}_LIBRARIES
variable that catkin_package()
exports to other packages.
catkin_package(
...
LIBRARIES # NOTE: Not specified here, but in extras file
CFG_EXTRAS my-extras.cmake
)
set_target_properties(
${PROJECT_NAME} PROPERTIES
PREFIX ""
LIBRARY_OUTPUT_DIRECTORY ${CATKIN_DEVEL_PREFIX}/${CATKIN_PACKAGE_PYTHON_DESTINATION}
)
find_library(@PROJECT_NAME@_LIBRARY
NAMES @PROJECT_NAME@
PATHS "${@PROJECT_NAME@_DIR}/../../../@CATKIN_GLOBAL_LIB_DESTINATION@/"
NO_DEFAULT_PATH)
if(@PROJECT_NAME@_LIBRARY)
# Multiple CMake projects case (i.e. 'catkin build'):
# - The target has already been built when its dependencies require it
# - Specify full path to found library
list(APPEND @PROJECT_NAME@_LIBRARIES ${@PROJECT_NAME@_LIBRARY})
else()
# Single CMake project case (i.e. 'catkin_make'):
# - The target has not been built when its dependencies require it
# - Specify target name only
list(APPEND @PROJECT_NAME@_LIBRARIES @PROJECT_NAME@)
endif()
Controlling Python Version¶
On some platforms, there are multiple versions of Python, and Catkin’s internal setup file generation might pick the wrong one.
For catkin_make
, this is sometimes solved on a given platform by creating a shell alias which sets the PYTHON_EXECUTABLE
CMake variable.
For catkin build
, however, you can create a verb alias like the one below, which overrides the default behavior of catkin build
even in new workspaces.
build: build -DPYTHON_EXECUTABLE=/usr/bin/python2.7
See Verb Aliasing for more details.
IDE Integration¶
Since all packages are built in isolation with catkin build
, you can’t rely on CMake’s IDE integration to generate a single project for your entire workspace.
CLI Comparison with catkin_make
and catkin_make_isolated
¶
Below are tables mapping catkin_make
and catkin_make_isolated
arguments into catkin
arguments.
Note that some catkin_make
options can only be achieved with the catkin config
verb.
catkin_make … | catkin … |
---|---|
-C PATH |
-w PATH [build | config | ...] |
--source PATH |
config --source-space PATH [1] |
--build PATH |
config --build-space PATH [1] |
--use-ninja |
not yet available |
--force-cmake |
build --force-cmake |
--pkg PKG [PKG ...] |
build --no-deps PKG [PKG ...] |
--only-pkg-with-deps PKG [PKG ...] |
build PKG [PKG ...] |
--cmake-args ARG [ARG ...] |
build --cmake-args ARG [ARG ...] [2] |
--make-args ARG [ARG ...] |
build --make-args ARG [ARG ...] [2] |
--override-build-tool-check |
build --override-build-tool-check |
ARG [ARG ...] |
build --make-args ARG [ARG ...] |
install |
config --install [1] |
-DCATKIN_DEVEL_PREFIX=PATH |
config --devel-space PATH [1] |
-DCATKIN_INSTALL_PREFIX=PATH |
config --install-space PATH [1] |
-DCATKIN_BUILDLIST_PACKAGES="PKG[;PKG ...]" |
config --buildlist PKG [PKG ...] [1] |
catkin_make_isolated … | catkin … |
---|---|
-C PATH |
-w PATH [build | config | ...] |
--source PATH |
config --source-space PATH [1] |
--build PATH |
config --build-space PATH [1] |
--devel PATH |
config --devel-space PATH [1] |
--merge |
config --devel-layout merged [1] |
--install-space PATH |
config --install-space PATH [1] |
--use-ninja |
not yet available |
--install |
config --install [1] |
--force-cmake |
build --force-cmake |
--no-color |
build --no-color |
--pkg PKG [PKG ...] |
build --no-deps PKG [PKG ...] |
--from-pkg PKG |
build --start-with PKG |
--only-pkg-with-deps PKG [PKG ...] |
build PKG [PKG ...] |
--cmake-args ARG [ARG ...] |
build --cmake-args ARG [ARG ...] [2] |
--make-args ARG [ARG ...] |
build --make-args ARG [ARG ...] [2] |
--catkin-make-args ARG [ARG ...] |
build --catkin-make-args ARG [ARG ...] [2] |
--override-build-tool-check |
build --override-build-tool-check |
[1] | (1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12) These options require a subsequent call to catkin build , and the options
will continue to persist until changed. |
[2] | (1, 2, 3, 4, 5) These options, if passed to catkin build only affect that
invocation. If passed to catkin config , they will persist to
subsequent calls to catkin build . |