Catkin cmake macro reference

catkin_project(projectname [parameters])

It creates the cmake stuff necessary for find_package to work (i.e. to be found by others that call find_package) and provide information about include directories, libraries, further dependencies and cmake variables for dependent projects.

Best practice is to call this macro early in your CMakeLists.txt, immediately after calling project().

Parameters:

• projectname – requires the same value as passed to cmake’s project() (may be vestigial)
• INCLUDE_DIRS – CMAKE_CURRENT_SOURCE_DIR-relative path to C/C++ includes
• LIBRARIES – names of library targets that will appear in the ROS_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.
• DEPENDS – The argument DEPENDS is used when client code finds us via find_package(). Each project listed will in turn be find_package-ed and their INCLUDE_DIRS and LIBRARIES will be appended to ours. Only catkin projects should be used where we can ensure that they are find_packagable and package_configurable.
• CFG_EXTRAS – Any extra cmake stuff that should be accessible to users of the project. This file should live in subdirectory cmake and have extension .in. It will be expanded by cmake’s configure_file() and made available to clients in both the install and build spaces: be sure it works both ways (by checking proj_SOURCE_DIR, which is not set in the install case)

Output Variables:  

PROJECT_SHARE_INSTALL_PREFIX – set to CMAKE_INSTALL_PREFIX/share/${PROJECT_NAME} by default. For use with cmake install() macro.

Example

catkin_project(proj
  INCLUDE_DIRS include
  LIBRARIES proj-one proj-two
  DEPENDS roscpp
  CFG_EXTRAS proj-extras.cmake
  )

catkin_export_python([dir1 dir2 ...])

Parameters:dirs – list of directories given relative to CMAKE_CURRENT_SOURCE_DIR containing python code

Creates forwarding python pkgutil infrastructure that “points” from the part of the build directory that holds generated code (python) back to the specified source directories that hold static code.

In addition, this will provoke that the python distutils’ file setup.py is interrogated by catkin and used during installation. See Handling of setup.py.

catkin_stack()

Required for all stacks. No parameters.

Reads the stack.xml from the current source dir and makes the version number available to cmake via stackname_VERSION; does the same for other fields in the stack.xml. Also sets CATKIN_CURRENT_STACK. You must call catkin_stack() once in each stack’s CMakeLists.txt, before any calls to catkin_project(), to ensure that auto-generated pkg-config and CMake files get correct version information.

catkin_workspace()

No parameters.

Called only in catkin’s toplevel.cmake, normally symlinked to from the workspace level directory (which contains multiple stacks). This provokes the traversal of the stack directories based on the dependencies specified in the build_depends field of their respective stack.xml files.

Documentation Macros

catkin_sphinx(SOURCEDIR BUILDDIR)

Parameters:

• SOURCEDIR – Directory containing sphinx .rst documentation source code
• BUILDDIR – Directory to contain generated html

Targets Created:  

<PROJECT_NAME>-sphinx – Builds html documentation. Dependee: toplevel target doc

Optionally creates -deploy targets, see CATKIN_DOCS_DEPLOY_DESTINATION.

find_sphinx()

Output Variables:  SPHINX_BUILD – Path to sphinx-build binary.

Finds sphinx binary. You don’t need this... called automatically by catkin_sphinx()

CATKIN_DOCS_DEPLOY_DESTINATION

Default :OFF

If this is set, the *-sphinx targets above will also have *-sphinx-deploy targets which rsync the documentation to the provided location (value may contain user@: it is passed directly to cmake)

Testing macros

initialize_tests()

Initialize. Tests.

append_test_to_cache(CACHENAME [args])

Internal use.

Parameters:

• CACHENAME – Name of cache.
• [args] – Command to be appended to cache file.

Use this when you want to append to a file that is recreated at each cmake run. CACHENAME need not be globally unique. File will be located in the PROJECT_BINARY_DIR cmake files directory (CMakeFiles) as ${PROJECT_NAME}.${CACHENAME}.

add_pyunit(FILE)

Parameters:FILE – name of pyunit test file

Add file to test list and run under rosunit at testing time.

add_gtest(EXE FILES [parameters])

Parameters:

• EXE – executable name
• FILES – list of gtest .cpp files
• TIMEOUT – The timeout in seconds (defaults to 60s)
• WORKING_DIRECTORY – The working directory

Add an executable EXE build from FILES and link to gtest. Run under rosunit when test target is built.

Convenience macros

install_matching_to_share(globexpr)

Parameters:globexpr – Glob expression (shell style)

For each file F in subdirectories of CMAKE_CURRENT_SOURCE_DIR that (recursively) match globbing expression globexpr, install F to share/P/F, where P is the name of the parent directory of F

Example

For a directory containing:

src/
  CMakeLists.txt
  foo/
    bar.txt
  shimmy/
    baz/
      bam.txt

A call to install_matching_to_share(b??.txt) in src/CMakeLists.txt will create an installation of:

<CMAKE_INSTALL_PREFIX>/
  share/
    foo/
      bar.txt
    baz/
      bam.txt

catkin_add_env_hooks(fileprefix SHELLS shell1 shell2...)

Parameters:

• fileprefix – prefix of environment file to be expanded and added to build environment
• SHELLS – list of shells

For each shell in SHELLS, find file <fileprefix>.buildspace.<shell>.in in the current directory and expand to CMAKE_BINARY_DIR/etc/catkin/profile.d/, where it will be read by generated setup.<shell>.

Similarly, install expanded <fileprefix>.<shell>.in to CMAKE_INSTALL_PREFIX/etc/catkin/profile.d, where it will be read by the installed setup.<shell> and friends.

Note

Note the extra ”.in” that must appear in the filename that does not appear in the argument.

You my also specify all as a shell; this will be read by all shells, before the shell-specific files are read. Note that your syntax had better be portable across all shells.

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 NNprojectname.sh is used, where NN can define when something should be run (the files are read in alphanumeric order) and projectname serves to disambiguate in the event of collision.

stamp(filepath)

Parameters:filepath – file name

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