Catkin

Catkin is a collection of cmake macros and associated code used to build some parts of ROS as of the Fuerte release.

Code & tickets

See ‘issues’ links for tickets.

Catkin	http://github.com/ros/catkin
Catkinized ROS Stacks	http://github.com/ros

Contents

• How to build
• How to build the docs
• Sketch of directory structure
• Stack manifest XML tags reference
• Pre- and Post-installation Disk Layout reference
• Catkin cmake macro reference
• Environment files
• Variables
• Code Generation
• Glossary
• Migrating from rosbuild to catkin

Evolving Documentation Snippets

• Internals of the generated find_package() infrastructure
• Finding ROS by component (recommended method)
• Handling of setup.py
• CMake coding standards

Design sketch

• There is only one invocation of cmake (and make) to build a source directory containing N stacks.
• There is no search of ROS_PACKAGE_PATH: the stacks/packages to be built are the subdirectories (not recursive) of the CMAKE_SOURCE_DIR.
• Catkin does not differentiate between stacks or packages: it simply examines the subdirectories of CMAKE_SOURCE_DIR for buildable projects (indicated by the presence of a file stack.xml). It determines the dependency ordering of stacks by examining these files.
• The ability to build only specific targets or sets of targets are provided through cmake’s “natural” mechanisms.
• The build does not modify the source directories in any way.
• The build does not depend on any compiled code (i.e. rospack) for ease of compiling on windows, cross-compiling for ARM, etc.
• Packages use standard cmake macros, modulo a few that are provided by catkin.
• The build system depends only only on python and cmake.
• Downloading, untarring, patching and especially the wanton use of sed and/or handcoded Makefiles is considered to be in the very poorest taste. Exception: for now, Sphinx-generated Makefiles used to generate documentation are okay.

Build Parameters

• The standard set of cmake variables, especially CMAKE_INSTALL_PREFIX, CMAKE_BUILD_TYPE, CMAKE_TOOLCHAIN_FILE etc.
• The language projects that are found in the buildspace.
• Assorted others as needed by individual stacks/packages, i.e. to enable/disable certain features or dependencies.

Installation

The buildspace has one install target, which creates an FHS compliant (or as close as we can get) filesystem under CMAKE_INSTALL_PREFIX via make install. This install target obeys DESTDIR for ease of packaging. Projects specify what should be installed and where in the usual cmake fashion, via the install() macro. Resources, assets, launchfiles, etc get installed to share/PKGNAME/.

Main trickery

Dependency ordering of stacks

During the cmake run the main source directory is scanned for stacks to build. Actually cmake does not care if it is a stack or a package; it cares that the directory has something there that indicates that it is buildable, and what its dependencies are... that, is stack.xml. Catkin topologically sorts this and reads the files in order.

Generation of find_package infrastructure

Each project calls catkin_project() which generates find_package files; this is for other packages to use. Each project does a find_package of each other; in this way, packages can build with their dependencies in the same buildspace, or already installed on the system. Different versions of these files are created for use in the buildspace, and in the installation. The stress-test for this scheme is message generation; different language generators must implement a specific cmake interface which is used by genmsg. See also Internals of the generated find_package() infrastructure.

Python path forwarding

A special thunk (via the standard python package pkgutil is generated and put in CMAKE_BINARY_DIR/gen/py/PACKAGENAME/__init__.py, which extends the PYTHONPATH to include CMAKE_SOURCE_DIR/path/to/PACKAGENAME/src. This way the buildspace PYTHONPATH need only contain CMAKE_BINARY_DIR/gen/py. Caveat: it will also need to contain CMAKE_BINARY_DIR/lib (for compiled python bindings). At installation time, this thunk-__init__.py disappears and the static python library source is installed alongside the generated message code in the same directory.

Environment generation

When cmake runs, it knows the locations of the CMAKE_BINARY_DIR and so forth, it generates an environment file (in CMAKE_BINARY_DIR). Projects may extend this environment via catkin_add_env_hooks().