Extracted CMake API reference

This page was auto-generated from cmake source files using generate_cmake_rst.py

Public CMake functions / macros

• catkin_add_env_hooks()
• catkin_add_executable_with_gtest()
• catkin_add_gtest()
• catkin_add_nosetests()
• catkin_download()
• catkin_download_test_data()
• catkin_filter_libraries_for_build_configuration()
• catkin_install_python()
• catkin_metapackage()
• catkin_pack_libraries_with_build_configuration()
• catkin_package()
• catkin_package_xml()
• catkin_python_setup()
• catkin_replace_imported_library_targets()
• catkin_unpack_libraries_with_build_configuration()

catkin_add_env_hooks

catkin_add_env_hooks(file_prefix)

[function defined in catkin_add_env_hooks.cmake]

Register environment hooks which are executed by the setup script.

For each shell in SHELLS, the macro searches for one of the following files in the directory DIRECTORY: <file_prefix>.<shell>, <file_prefix>.<shell>.<develspace|installspace>.em, <file_prefix>.<shell>.em, <file_prefix>.<shell>.<develspace|installspace>.in or <file_prefix>.<shell>.in.

Plain shells, will be copied to, templates are expanded to etc/catkin/profile.d/, where it will be read by global generated setup.<shell>.

The templates can also distinguish between devel- and installspace using the boolean variables DEVELSPACE and INSTALLSPACE which are either true or false. E.g. @[if DEVELSPACE]@ ... @[end if]@ for .em

Note

Note that the extra extensions must appear in the filename but must not appear in the argument.

Note

These files will share a single directory with other packages that choose to install env hooks. Be careful to give the file a unique name. Typically NN.name.<shell> is used, where NN can define when something should be run (the files are read in alphanumeric order) and the name serves to disambiguate in the event of collisions.

Example:

catkin_add_env_hooks(my_prefix SHELLS bash tcsh zsh DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/env-hooks)

looks for files env-hooks/my_prefix.[bash|tcsh|zsh]((.(devel|install)space)?.[em|in])?

Parameters:

• file_prefix (string) – the filename prefix
• SHELLS (list of strings) – the shell extensions (e.g.: sh bat bash zsh tcsh)
• DIRECTORY (string) – the directory (default: ${CMAKE_CURRENT_SOURCE_DIR})
• SKIP_INSTALL (option) – if specified the env hooks are only generated in the devel space but not installed

catkin_add_executable_with_gtest

catkin_add_executable_with_gtest(target)

[function defined in test/gtest.cmake]

Add a GTest executable target.

An executable target is created with the source files, it is linked against GTest. If you also want to register the executable as a test use catkin_add_gtest() instead.

Parameters:

• target (string) – the target name
• source_files (list of strings) – a list of source files used to build the test executable

Additionally, the option EXCLUDE_FROM_ALL can be specified.

catkin_add_gtest

catkin_add_gtest(target)

[function defined in test/gtest.cmake]

Add a GTest based test target.

An executable target is created with the source files, it is linked against GTest and added to the set of unit tests.

Note

The test can be executed by calling the binary directly or using: make run_tests_${PROJECT_NAME}_gtest_${target}

Parameters:

• target (string) – the target name
• source_files (list of strings) – a list of source files used to build the test executable
• TIMEOUT (integer) – currently not supported
• WORKING_DIRECTORY (string) – the working directory when executing the executable

catkin_add_nosetests

catkin_add_nosetests(path)

[function defined in test/nosetests.cmake]

Add Python nose tests.

Nose collects tests from the directory dir automatically.

Note

The test can be executed by calling nosetests directly or using: `` make run_tests_${PROJECT_NAME}_nosetests_${dir}`` (where slashes in the dir are replaced with periods)

Parameters:

• path (string) – a relative or absolute directory to search for nosetests in or a relative or absolute file containing tests
• DEPENDENCIES (list of strings) – the targets which must be built before executing the test
• TIMEOUT (integer) – the timeout for individual tests in seconds (default: 60)
• WORKING_DIRECTORY (string) – the working directory when executing the tests (this option can only be used when the path argument is a file but not when it is a directory)

catkin_download

catkin_download(target, url)

[function defined in catkin_download.cmake]

Download a file containing data from a URL.

It is commonly used to download larger data files which should not be stored in the repository.

Note

It is not recommended to rely on downloaded data during a configure / make cycle since this prevents building the package when no network connectivity is available.

Note

The target will be registered as a dependency of the “download_extra_data” target.

Parameters:

• target (string) – the target name
• url (string) – the url to download
• DESTINATION (string) – the directory where the file is downloaded to (default: ${PROJECT_BINARY_DIR})
• FILENAME (string) – the filename of the downloaded file (default: the basename of the url)
• MD5 (string) – the expected md5 hash to compare against (default: empty, skipping the check)

Additionally, options EXCLUDE_FROM_ALL and REQUIRED can be specified.

catkin_download_test_data

catkin_download_test_data(target, url)

[function defined in test/catkin_download_test_data.cmake]

Parameters:

• DESTINATION (string) – the directory where the file is downloaded to (default: ${PROJECT_BINARY_DIR})
• FILENAME (string) – the filename of the downloaded file (default: the basename of the url)
• MD5 (string) – the expected md5 hash to compare against (default: empty, skipping the check)

Additionally, option REQUIRED can be specified.

catkin_filter_libraries_for_build_configuration

catkin_filter_libraries_for_build_configuration(VAR)

[macro defined in catkin_libraries.cmake]

Filter libraries based on optional build configuration keywords.

Parameters:

• VAR (string) – the output variable name
• ARGN (list of strings) – a list of libraries
• BUILD_TYPE (list of strings) – a keyword for the build type (default: CMAKE_BUILD_TYPE)

catkin_install_python

catkin_install_python(signature)

[function defined in catkin_install_python.cmake]

Install Python files and update their shebang lines to use a different Python executable.

The signature:

catkin_install_python(PROGRAMS files... DESTINATION <dir> [OPTIONAL])

See the documentation for CMake install() function for more information.

catkin_metapackage

catkin_metapackage()

[function defined in catkin_metapackage.cmake]

It installs the package.xml file of a metapackage.

Note

It must be called once for each metapackage. Best practice is to call this macro early in your root CMakeLists.txt, immediately after calling project() and find_package(catkin REQUIRED).

Parameters:DIRECTORY (string) – the path to the package.xml file if not in the same location as the CMakeLists.txt file

catkin_pack_libraries_with_build_configuration

catkin_pack_libraries_with_build_configuration(VAR)

[macro defined in catkin_libraries.cmake]

Pack a list of libraries with optional build configuration keywords. Each keyword is joined with its library using a separator. A packed library list can be deduplicated correctly.

Parameters:

• VAR (string) – the output variable name
• ARGN (list of strings) – a list of libraries

catkin_package

catkin_package()

[macro defined in catkin_package.cmake]

It installs the package.xml file, and it generates code for find_package and pkg-config so that other packages can get information about this package. For this purpose the information about include directories, libraries, further dependencies and CMake variables are used.

Note

It must be called once for each package. It is indirectly calling``catkin_destinations()`` which will provide additional output variables. Please make sure to call catkin_package() before using those variables.

Parameters:

• INCLUDE_DIRS (list of strings) – CMAKE_CURRENT_SOURCE_DIR-relative paths to C/C++ includes
• LIBRARIES (list of strings) – names of library targets that will appear in the catkin_LIBRARIES and ${PROJECT_NAME}_LIBRARIES of other projects that search for you via find_package. Currently this will break if the logical target names are not the same as the installed names.
• CATKIN_DEPENDS (list of strings) – a list of catkin projects which this project depends on. It is used when client code finds this project via find_package() or pkg-config. Each project listed will in turn be find_package-ed or is states as Requires in the .pc file. Therefore their INCLUDE_DIRS and LIBRARIES will be appended to ours. Only catkin projects should be used where it be guarantee that they are find_packagable and have pkg-config files.
• DEPENDS (list of strings) – a list of CMake projects which this project depends on. Since they might not be find_packagable or lack a pkg-config file their INCLUDE_DIRS and LIBRARIES are passed directly. This requires that it has been find_package-ed before.
• CFG_EXTRAS (string) – a CMake file containing extra stuff that should be accessible to users of this package after find_package-ing it. This file must live in the subdirectory cmake or be an absolute path. All passed extra files must have unique basenames since they are being installed into a single folder. Various additional file extension are possible: for a plain cmake file just .cmake, for files expanded using CMake’s configure_file() use .cmake.in or for files expanded by empy use .cmake.em. The templates can distinguish between devel- and installspace using the boolean variables DEVELSPACE and INSTALLSPACE. For templated files it is also possible to use the extensions .cmake.develspace.(in|em) or .cmake.installspace.(em|in) to generate the files only for a specific case. If the global variable ${PROJECT_NAME}_CFG_EXTRAS is set it will be prepended to the explicitly passed argument.
• EXPORTED_TARGETS (list of strings) – a list of target names which usually generate code. Downstream packages can depend on these targets to ensure that code is generated before it is being used. The generated CMake config file will ensure that the targets exists. If the global variable ${PROJECT_NAME}_EXPORTED_TARGETS is set it will be prepended to the explicitly passed argument.
• SKIP_CMAKE_CONFIG_GENERATION (bool) – the option to skip the generation of the CMake config files for the package
• SKIP_PKG_CONFIG_GENERATION (bool) – the option to skip the generation of the pkg-config file for the package

Example:

catkin_package(
  INCLUDE_DIRS include
  LIBRARIES projlib1 projlib2
  CATKIN_DEPENDS roscpp
  DEPENDS Eigen
  CFG_EXTRAS proj-extras[.cmake|.cmake.in|.cmake(.develspace|.installspace)?.em]
)

catkin_package_xml

catkin_package_xml()

[macro defined in catkin_package_xml.cmake]

Parse package.xml from CMAKE_CURRENT_SOURCE_DIR and make several information available to CMake.

Note

It is called automatically by catkin_package() if not called manually before. It must be called once in each package, after calling project() where the project name must match the package name. The macro should only be called manually if the variables are use to parameterize catkin_package().

Parameters:

DIRECTORY (string) – the directory of the package.xml (default ${CMAKE_CURRENT_SOURCE_DIR}).

Output Variables:  

• <packagename>_VERSION – the version number
• <packagename>_MAINTAINER – the name and email of the maintainer(s)
• _CATKIN_CURRENT_PACKAGE – the name of the package from the manifest

Note

It is calling catkin_destinations() which will provide additional output variables.

catkin_python_setup

catkin_python_setup()

[function defined in catkin_python_setup.cmake]

This macro will interrogate the Python setup.py file in ${${PROJECT_NAME}_SOURCE_DIR}, and then creates forwarding Python pkgutil infrastructure in devel space accordingly for the scripts and packages declared in setup.py.

Doing so enables mixing generated code in devel space with static code from sourcespace within a single Python package.

In addition, it adds the install command of distutils/setuputils to the install target.

Note

If the project also uses genmsg message generation via generate_messages() this function must be called before.

catkin_replace_imported_library_targets

catkin_replace_imported_library_targets(VAR)

[macro defined in catkin_libraries.cmake]

Replace imported library target names with the library name.

Parameters:

• VAR (string) – the output variable name
• ARGN (list of strings) – a list of libraries

catkin_unpack_libraries_with_build_configuration

catkin_unpack_libraries_with_build_configuration(VAR)

[macro defined in catkin_libraries.cmake]

Unpack a list of libraries with optional build configuration keyword prefixes. Libraries prefixed with a keyword are split into the keyword and the library.

Parameters:

• VAR (string) – the output variable name
• ARGN (list of strings) – a list of libraries

Non-public CMake functions / macros

• _generate_function_if_testing_is_disabled()
• _set_cmake_policy_to_new_if_available()
• _warn_if_skip_testing()
• catkin_destinations()
• catkin_run_tests_target()
• catkin_workspace()
• list_append_deduplicate()
• list_append_unique()
• stamp()
• string_starts_with()

_generate_function_if_testing_is_disabled

_generate_function_if_testing_is_disabled(funcname)

[macro defined in test/tests.cmake]

creates a dummy function in case testing has been explicitly disabled (and not only skipping) which outputs an error message when being invoked

_set_cmake_policy_to_new_if_available

_set_cmake_policy_to_new_if_available(policy)

[macro defined in all.cmake]

enable all new policies (if available)

_warn_if_skip_testing

_warn_if_skip_testing(funcname)

[macro defined in test/tests.cmake]

checks if a function has been called while testing is skipped and outputs a warning message

catkin_destinations

catkin_destinations()

[macro defined in catkin_destinations.cmake]

Set several path suffixes for install destinations.

Output Variables:  

• CATKIN_PACKAGE_BIN_DESTINATION – See CATKIN_PACKAGE_BIN_DESTINATION.
• CATKIN_PACKAGE_ETC_DESTINATION – See CATKIN_PACKAGE_ETC_DESTINATION.
• CATKIN_PACKAGE_INCLUDE_DESTINATION – See CATKIN_PACKAGE_INCLUDE_DESTINATION.
• CATKIN_PACKAGE_LIB_DESTINATION – See CATKIN_PACKAGE_LIB_DESTINATION.
• CATKIN_PACKAGE_PYTHON_DESTINATION – See CATKIN_PACKAGE_PYTHON_DESTINATION.
• CATKIN_PACKAGE_SHARE_DESTINATION – See CATKIN_PACKAGE_SHARE_DESTINATION.
• CATKIN_GLOBAL_BIN_DESTINATION – See CATKIN_GLOBAL_BIN_DESTINATION.
• CATKIN_GLOBAL_ETC_DESTINATION – See CATKIN_GLOBAL_ETC_DESTINATION.
• CATKIN_GLOBAL_INCLUDE_DESTINATION – See CATKIN_GLOBAL_INCLUDE_DESTINATION.
• CATKIN_GLOBAL_LIB_DESTINATION – See CATKIN_GLOBAL_LIB_DESTINATION.
• CATKIN_GLOBAL_LIBEXEC_DESTINATION – See CATKIN_GLOBAL_LIBEXEC_DESTINATION.
• CATKIN_GLOBAL_PYTHON_DESTINATION – See CATKIN_GLOBAL_PYTHON_DESTINATION.
• CATKIN_GLOBAL_SHARE_DESTINATION – See CATKIN_GLOBAL_SHARE_DESTINATION.

catkin_run_tests_target

catkin_run_tests_target(type, name, xunit_filename)

[function defined in test/tests.cmake]

Create a test target, integrate it with the run_tests infrastructure and post-process the junit result.

All test results go under ${CATKIN_TEST_RESULTS_DIR}/${PROJECT_NAME}

This function is only used internally by the various catkin_add_*test() functions.

catkin_workspace

catkin_workspace()

[function defined in catkin_workspace.cmake]

Search all subfolders in the workspace for package.xml files. Based on the dependencies specified in the build_depends, buildtool_depends and (as of package format version 2) test_depends tags it performs a topological sort and calls add_subdirectory() for each directory.

The functions is only called in catkin’s toplevel.cmake, which is usually symlinked to the workspace root directory (which contains multiple packages).

list_append_deduplicate

list_append_deduplicate(listname)

[macro defined in list_append_deduplicate.cmake]

Append elements to a list and remove existing duplicates from the list.

Note

Using CMake’s list(APPEND ..) and list(REMOVE_DUPLICATES ..) is not sufficient since its implementation uses a set internally which makes the operation unstable.

list_append_unique

list_append_unique(listname)

[macro defined in list_append_unique.cmake]

Append elements to a list if they are not already in the list.

Note

Using CMake’s list(APPEND ..) and list(REMOVE_DUPLICATES ..) is not sufficient since its implementation uses a set internally which makes the operation unstable.

stamp

stamp(path)

[function defined in stamp.cmake]

param path:file name

Uses configure_file to generate a file filepath.stamp hidden somewhere in the build tree. This will cause cmake to rebuild its cache when filepath is modified.

string_starts_with

string_starts_with(str, prefix, var)

[function defined in string_starts_with.cmake]

Check if a string starts with a prefix.

Parameters:

• str (string) – the string
• prefix (string) – the prefix
• var (bool) – the output variable name

Not documented CMake functions / macros

_catkin_package

_catkin_package()

[function defined in catkin_package.cmake]

_catkin_package_xml

_catkin_package_xml(dest_dir)

[macro defined in catkin_package_xml.cmake]

_strip_path_prefix

_strip_path_prefix(var, value, prefix)

[macro defined in test/nosetests.cmake]

assert

assert(VAR)

[function defined in assert.cmake]

assert_file_exists

assert_file_exists(FILENAME, MESSAGE)

[function defined in assert.cmake]

assert_unset

assert_unset(VAR)

[function defined in assert.cmake]

atomic_configure_file

atomic_configure_file(input, output)

[function defined in atomic_configure_file.cmake]

catkin_doxygen

catkin_doxygen(TARGET_NAME, SEARCH_DIRS)

[macro defined in tools/doxygen.cmake]

catkin_generate_environment

catkin_generate_environment()

[function defined in catkin_generate_environment.cmake]

catkin_stack

catkin_stack()

[function defined in legacy.cmake]

configure_shared_library_build_settings

configure_shared_library_build_settings()

[function defined in tools/libraries.cmake]

debug_message

debug_message(level)

[macro defined in debug_message.cmake]

em_expand

em_expand(context_in, context_out, em_file_in, file_out)

[macro defined in em_expand.cmake]

find_program_required

find_program_required(ARG_VAR, ARG_PROGRAM_NAME)

[function defined in find_program_required.cmake]

find_python_module

find_python_module(module)

[function defined in empy.cmake]

list_insert_in_workspace_order

list_insert_in_workspace_order(listname)

[macro defined in list_insert_in_workspace_order.cmake]

safe_execute_process

safe_execute_process(cmd_keyword, arg1)

[macro defined in safe_execute_process.cmake]

shell

shell(arg1)

[function defined in shell.cmake]