Extracted CMake API reference

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

mrt_add_executable

mrt_add_executable(execname)

[function defined in mrt_cmake_modules-macros.cmake]

Adds an executable.

This command ensures the executable is compiled with all necessary dependencies.

Note

Make sure to call this after all messages and parameter generation CMAKE-Commands so that all dependencies are visible.

The files are automatically added to the list of installable targets so that mrt_install can mark them for installation.

Parameters:
  • execname (string) – name of the executable
  • FOLDER (string) – Folder containing the .cpp/.cc-files and .h/.hh/.hpp files for the executable, relative to ${PROJECT_SOURCE_DIR}.
  • FILES (list of strings) – List of extra source files to add. This or the FOLDER parameter is mandatory.
  • DEPENDS (list of strings) – List of extra (non-catkin, non-mrt) dependencies. This should only be required for including external projects.
  • LIBRARIES (list of strings) – Extra (non-catkin, non-mrt) libraries to link to. This should only be required for external projects

Example:

mrt_add_executable( example_package
    FOLDER src/example_package
    )

mrt_add_library

mrt_add_library(libname)

[function defined in mrt_cmake_modules-macros.cmake]

Adds a library.

This command ensures the library is compiled with all necessary dependencies. If no files are passed, the command will return silently.

Note

Make sure to call this after all messages and parameter generation CMAKE-Commands so that all dependencies are visible.

The files are automatically added to the list of installable targets so that mrt_install can mark them for installation.

Parameters:
  • libname (string) – Name of the library to generate as first argument (without lib or .so)
  • INCLUDES (list of strings) – Public include files needed to use the library, absolute or relative to ${PROJECT_SOURCE_DIR}
  • SOURCES (list of strings) – Source files and private headers to be added. If no source files are passed, a header-only library is assumed
  • DEPENDS (list of strings) – List of extra (non-catkin, non-mrt) dependencies. This should only be required for including external projects.
  • LIBRARIES (list of strings) – Extra (non-catkin, non-mrt) libraries to link to. This should only be required for external projects

Example:

mrt_add_library( example_package
    INCLUDES include/example_package/myclass.h include/example_package/myclass2.h
    SOURCES src/myclass.cpp src/myclass.cpp
    )

mrt_add_node_and_nodelet

mrt_add_node_and_nodelet(basename)

[function defined in mrt_cmake_modules-macros.cmake]

Adds a node and a corresponding nodelet.

This command ensures the node/nodelet are compiled with all necessary dependencies. Make sure to add lib<package_name>-<basename>-nodelet to the nodelet_plugins.xml file.

Note

Make sure to call this after all messages and parameter generation CMAKE-Commands so that all dependencies are visible.

The files are automatically added to the list of installable targets so that mrt_install can mark them for installation.

It requires a *_nodelet.cpp file and a *_node.cpp file to be present in this folder. It will then compile a nodelet-library, create an executable from the *_node.cpp file and link the executable with the nodelet library.

Unless the variable ${MRT_NO_FAIL_ON_TESTS} is set, failing unittests will result in a failed build.

Parameters:
  • basename (string) – base name of the node/nodelet (_nodelet will be appended for the nodelet name to avoid conflicts with library packages)
  • FOLDER (string) – Folder with cpp files for the executable, relative to ${PROJECT_SOURCE_DIR}
  • DEPENDS (list of strings) – List of extra (non-catkin, non-mrt) CMAKE dependencies. This should only be required for including external projects.
  • LIBRARIES (list of strings) – Extra (non-catkin, non-mrt) libraries to link to. This should only be required for external projects

Example:

mrt_add_node_and_nodelet( example_package
    FOLDER src/example_package
    )

The resulting entry in the nodelet_plugins.xml is thus (for a package named example_package): <library path=”lib/libexample_package-example_package-nodelet”>

mrt_add_nodelet

mrt_add_nodelet(nodeletname)

[function defined in mrt_cmake_modules-macros.cmake]

Adds a nodelet.

This command ensures the nodelet is compiled with all necessary dependencies. Make sure to add lib{PROJECT_NAME}-{NAME}-nodelet to the nodelet_plugins.xml file.

Note

Make sure to call this after all messages and parameter generation CMAKE-Commands so that all dependencies are visible.

The files are automatically added to the list of installable targets so that mrt_install can mark them for installation.

It requires a *_nodelet.cpp-File to be present in this folder. The command will look for a *_node.cpp-file and remove it from the list of files to avoid main()-functions to be compiled into the library.

Parameters:
  • nodeletname (string) – base name of the nodelet (_nodelet will be appended to the base name to avoid conflicts with library packages)
  • FOLDER (string) – Folder with cpp files for the executable, relative to ${PROJECT_SOURCE_DIR}
  • DEPENDS (list of strings) – List of extra (non-catkin, non-mrt) CMAKE dependencies. This should only be required for including external projects.
  • LIBRARIES (list of strings) – Extra (non-catkin, non-mrt) libraries to link to. This should only be required for external projects
  • TARGETNAME (string) – Choose the name of the internal CMAKE target. Will be autogenerated if not specified.

Example:

mrt_add_nodelet( example_package
    FOLDER src/example_package
    )

The resulting entry in the nodelet_plugins.xml is thus: <library path=”lib/libexample_package-example_package-nodelet”>

mrt_add_nosetests

mrt_add_nosetests(folder)

[function defined in mrt_cmake_modules-macros.cmake]

Adds python nosetest contained in a folder. Wraps the function catkin_add_nosetests.

Parameters:
  • folder (string) – folder containing the tests (relative to ${PROJECT_SOURCE_DIR}) as first argument
  • DEPENDS (list of strings) – Additional (non-catkin, non-mrt) dependencies (e.g. with catkin_download_test_data)
  • DEPENDENCIES (list of strings) – Alias for DEPENDS

Example:

mrt_add_nosetests(test)

mrt_add_python_api

mrt_add_python_api(modulename)

[function defined in mrt_cmake_modules-macros.cmake]

Generates a python module from boost-python cpp files.

Each <file>.cpp will become a seperate <file>.py submodule within <modulename>. After building and sourcing you can use the modules simply with “import <modulename>.<file>”.

The files are automatically linked with boost-python libraries and a python module is generated and installed from the resulting library. If this project declares any libraries with mrt_add_library(), they will automatically be linked with this library.

This function will define the compiler variable PYTHON_API_MODULE_NAME with the name of the generated library. This can be used in the BOOST_PYTHON_MODULE C++ Macro.

Note

This function can only be called once per package.

Parameters:
  • modulename (string) – Name of the module needs to be passed as first parameter.
  • FILES (list of strings) – list of C++ files defining the BOOST-Python API.

Example:

mrt_add_python_api( example_package
    FILES python_api/python.cpp
    )

mrt_add_ros_tests

mrt_add_ros_tests(folder)

[function defined in mrt_cmake_modules-macros.cmake]

Adds all rostests (identified by a .test file) contained in a folder as unittests.

If a .cpp file exists with the same name, it will be added and comiled as a gtest test. Unittests can be run with “catkin run_tests” or similar. “-test” will be appended to the name of the test node to avoid conflicts (i.e. the type argument should then be <test … type=”mytest-test”/> in a mytest.test file).

Unittests will always be executed with the folder as cwd. E.g. if the test folder contains a sub-folder “test_data”, it can simply be accessed as “test_data”.

If coverage information is enabled (by setting MRT_ENABLE_COVARAGE to true), coverage analysis will be performed after unittests have run. The results can be found in the package’s build folder in the folder “coverage”.

Unless the variable ${MRT_NO_FAIL_ON_TESTS} is set, failing unittests will result in a failed build.

Parameters:
  • folder (string) – folder containing the tests (relative to ${PROJECT_SOURCE_DIR}) as first argument
  • LIBRARIES (list of strings) – Additional (non-catkin, non-mrt) libraries to link to
  • DEPENDS (list of strings) – Additional (non-catkin, non-mrt) dependencies (e.g. with catkin_download_test_data)

Example:

mrt_add_ros_tests( test
    )

mrt_add_tests

mrt_add_tests(folder)

[function defined in mrt_cmake_modules-macros.cmake]

Adds all gtests (without a corresponding .test file) contained in a folder as unittests.

Parameters:
  • folder (string) – folder containing the tests (relative to ${PROJECT_SOURCE_DIR}) as first argument
  • LIBRARIES (list of strings) – Additional (non-catkin, non-mrt) libraries to link to
  • DEPENDS (list of strings) – Additional (non-catkin, non-mrt) dependencies (e.g. with catkin_download_test_data)

Unittests will be executed with the folder as cwd if ctest or the run_test target is used. E.g. if the test folder contains a sub-folder “test_data”, it can simply be accessed as “test_data”. Another way of getting the location of the project root folder path is to #include "test/test_utility.hpp" and use the variable <project_name>::test::projectRootDir.

Unless the variable ${MRT_NO_FAIL_ON_TESTS} is set, failing unittests will result in a failed build.

If coverage information is enabled (by setting MRT_ENABLE_COVARAGE to true), coverage analysis will be performed after unittests have run. The results can be found in the package’s build folder in the folder “coverage”.

Example:

mrt_add_tests( test
    )

mrt_add_to_ide

mrt_add_to_ide(files)

[function defined in mrt_cmake_modules-macros.cmake]

Once upon a time this used to make non-code files known to IDEs that parse Cmake output. But as this messes up with the target determination mechanism used by most ides and garbages up the target view.

Therefore this function is no longer used and only here for backwards compability.

mrt_install

mrt_install()

[function defined in mrt_cmake_modules-macros.cmake]

Installs all relevant project files.

All targets added by the mrt_add_<library/executable/nodelet/…> commands will be installed automatically when using this command. Other files/folders (launchfiles, scripts) need to be specified explicitly. Non existing files and folders will be silently ignored.

If the project contains a file cmake/<project-name>-extras.cmake[.in], it will be automatically included by all depending projects. This allows to export cmake functions, etc. If the file ends with [.in], it will be configured by cmake and the variables “@DEVELSPACE@” “@INSTALLSPACE@” will be replaced by true or files depending on the build type, @PROJECT_SPACE_DIR@ to the devel/install folder and @PKT_CMAKE_DIR@ to the cmake folder

Parameters:
  • PROGRAMS (list of strings) – List of all folders and files that are programs (python scripts will be indentified and treated separately). Files will be made executable.
  • FILES (list of strings) – List of non-executable files and folders. Subfolders will be installed recursively.
  • EXPORT_LIBS (list of (interface) library targets) – List of non-mrt-created libraries that should be installed and exported

Example:

mrt_install(
    PROGRAMS scripts
    FILES launch nodelet_plugins.xml
    )

mrt_parse_package_xml

mrt_parse_package_xml()

[macro defined in mrt_cmake_modules-macros.cmake]

Parses the package.xml and sets its information in form of cmake variables as ${PACKAGE_NAME}_<info>, where info is one of version, VERSION, MAINTAINER, PACKAGE_FORMAT, <BUILD/BUILD_EXPORT/TEST/EXEC/…>_DEPENDS, URL_<WEBSITE/BUGTRACKER/REPOSITORY>

This function must be called before any other of the mrt_* functions can be called.

mrt_python_module_setup

mrt_python_module_setup()

[function defined in mrt_cmake_modules-macros.cmake]

Automatically sets up and installs python modules located under src/${PROJECT_NAME}. Modules can afterwards simply be included using “import <project_name>” in python.

The python folder (under src/${PROJECT_NAME}) is required to have an __init__.py file.

The command will automatically generate a setup.py in your project folder. This file should not be commited, as it will be regenerated at every new CMAKE run. Due to restrictions imposed by catkin (searches hardcoded for this setup.py), the file cannot be placed elsewhere.

Example:

mrt_python_module_setup()

_mrt_run_test

_mrt_run_test(target_name, working_dir, result_xml_path)

[function defined in Modules/MrtTesting.cmake]

All paths have to be absolute

generate_ros_parameter_files

generate_ros_parameter_files()

[macro defined in mrt_cmake_modules-macros.cmake]

define rosparam/rosinterface_handler macro for compability. Macros will be overriden by the actual macros defined by the packages, if existing.

glob_folders

glob_folders()

[macro defined in mrt_cmake_modules-macros.cmake]

Deprecated function. Use ‘mrt_glob_folders’ instead.

glob_ros_files

glob_ros_files(excecutable_name, extension_name)

[macro defined in mrt_cmake_modules-macros.cmake]

Deprecated function. Use one of ‘mrt_add_message_files’, ‘mrt_add_service_files’ or ‘mrt_add_action_files’.

mrt_add_action_files

mrt_add_action_files(folder_name)

[macro defined in mrt_cmake_modules-macros.cmake]

Globs for action files and calls add_action_files

mrt_add_message_files

mrt_add_message_files(folder_name)

[macro defined in mrt_cmake_modules-macros.cmake]

Globs for message files and calls add_message_files

mrt_add_service_files

mrt_add_service_files(folder_name)

[macro defined in mrt_cmake_modules-macros.cmake]

Globs for service files and calls add_service_files

mrt_glob_files

mrt_glob_files(varname)

[function defined in mrt_cmake_modules-macros.cmake]

Globs files in the currect project dir.

mrt_glob_files_recurse

mrt_glob_files_recurse(varname)

[function defined in mrt_cmake_modules-macros.cmake]

Globs files recursivly in the currect project dir.

mrt_glob_folders

mrt_glob_folders(DIRECTORY_LIST, SEARCH_DIRECTORY)

[function defined in mrt_cmake_modules-macros.cmake]

Glob for folders in the search directory.

_mrt_add_nosetests_impl

_mrt_add_nosetests_impl(folder)

[function defined in Modules/MrtTesting.cmake]

_mrt_create_executable_gtest

_mrt_create_executable_gtest(target, file)

[function defined in Modules/MrtTesting.cmake]

_mrt_export_package

_mrt_export_package()

[function defined in Modules/ExportPackage.cmake]

_mrt_get_python_destination

_mrt_get_python_destination(output_var)

[function defined in mrt_cmake_modules-macros.cmake]

_setup_coverage_info

_setup_coverage_info()

[macro defined in mrt_cmake_modules-macros.cmake]

catkin_install_python

catkin_install_python(programs)

[function defined in Modules/CatkinMockForConan.cmake]

catkin_package

catkin_package()

[function defined in Modules/CatkinMockForConan.cmake]

catkin_package_xml

catkin_package_xml()

[function defined in Modules/CatkinMockForConan.cmake]

generate_ros_interface_files

generate_ros_interface_files()

[macro defined in mrt_cmake_modules-macros.cmake]

mrt_add_gtest

mrt_add_gtest(target, file)

[function defined in Modules/MrtTesting.cmake]

mrt_add_rostest

mrt_add_rostest(target, launch_file)

[function defined in Modules/MrtTesting.cmake]

mrt_add_rostest_gtest

mrt_add_rostest_gtest(target, launch_file, cpp_file)

[function defined in Modules/MrtTesting.cmake]

mrt_init_testing

mrt_init_testing()

[function defined in Modules/MrtTesting.cmake]