Overview

The core build tool ROS uses is CMake. CMake is a powerful cross-platform build tool that provides both configure and make functionality.

The core problem solved by rosbuild is gathering appropriate build flags from and track dependencies in the ROS package tree. For example, by using the macros provided by rosbuild, you automatically inherit the union of build flags exported by packages on which your package depends. rosbuild also provides extensive support for declaring tests.

To build packages, use rosmake.

Every ROS package should have the following three files in its top-level directory:

• CMakeLists.txt : a CMake build file, possibly using ROS macros

• manifest.xml : the package manifest.xml. This file include the license, author, and description information. It also includes packages on which this package depends, and provides compiler and linker flags for other packages that depend on this one.

• Makefile : a standard Makefile. For backward compatibility, we still invoke make to build a package. For all new packages, the Makefile should contain just one line, which will properly invoke CMake:

  • include $(shell rospack find mk)/cmake.mk

API (writing a CMakeLists.txt file)

Most of rosbuild is an API for writing CMakeLists.txt files that are used to control the build and test of packages. See API documentation. Also see examples.

Cross-Compiling

ROS does not yet have strong support for cross compiling, though there has been some success building ROS for non-x86 platforms. You can see our notes on cross-compiling to find out more.

Customizing the build (debug, optimizations, default build flags)

There are a number of things that you might want to change about how the build occurs, such as debug vs. optimization, and shared vs. static libraries. The system defaults for ROS are specified in $ROS_ROOT/core/rosbuild/rosconfig.cmake; do not edit this file.

The following variables are defined in $ROS_ROOT/core/rosbuild/rosconfig.cmake:

• ROS_BUILD_TYPE: Set the build type. Options are (default: RelWithDebInfo):

  • Debug : w/ debug symbols, w/o optimization

  • Release : w/o debug symbols, w/ optimization

  • RelWithDebInfo : w/ debug symbols, w/ optimization

  • RelWithAsserts : w/o debug symbols, w/ optimization, w/ assertions (i.e., w/o -DNDEBUG). New in ros 1.1.

  • MinSizeRel : w/o debug symbols, w/ optimization, stripped binaries

• ROS_BUILD_STATIC_EXES: Build static-only executables (e.g., for copying over to another machine)? true or false; default: false

• ROS_BUILD_SHARED_LIBS: Build shared libs? true or false; default: true

• ROS_BUILD_STATIC_LIBS: Build static libs? true or false; default: false

• ROS_COMPILE_FLAGS: Default compile flags for all source files; default: "-W -Wall -Wno-unused-parameter -fno-strict-aliasing"

• ROS_LINK_FLAGS: Default link flags for all executables and libraries; default: ""

You can override the system defaults by set()ting different values in three places, listed here in increasing priority (i.e., later settings overwrite earlier ones):

1. The current package's CMakeLists.txt (i.e., the content *preceding* the rosbuild_init() invocation), e.g.:

   • Turn on static libs, but turn off shared libs:

     cmake_minimum_required(VERSION 2.4.6)
     include($ENV{ROS_ROOT}/core/rosbuild/rosbuild.cmake)
     # Turn off shared libs and turn on static libs, just for this package
     set(ROS_BUILD_STATIC_LIBS true)
     set(ROS_BUILD_SHARED_LIBS false)
     rosbuild_init()
     rosbuild_add_library(mylib mysrc.cpp)

   • Another example, changing the warnings:

     cmake_minimum_required(VERSION 2.4.6)
     include($ENV{ROS_ROOT}/core/rosbuild/rosbuild.cmake)
     # Turn on higher warnings, because I'm hard-core
     set(ROS_COMPILE_FLAGS "-W -Wall -Wextra -pedantic")
     rosbuild_init()
     rosbuild_add_library(mylib mysrc.cpp)

   • Another example, changing from Debug to Release build:

     cmake_minimum_required(VERSION 2.4.6)
     include($ENV{ROS_ROOT}/core/rosbuild/rosbuild.cmake)
     # Go to a release build, because I'm done debugging and I want compiler optimizations
     set(ROS_BUILD_TYPE Release)
     rosbuild_init()
     rosbuild_add_library(mylib mysrc.cpp)

2. If present, $(ROS_ROOT)/rosconfig.cmake, e.g.:

   • # I want both static and shared libs for all ROS packages (shared are enabled by default)
     set(ROS_BUILD_STATIC_LIBS true)

3. If present, rosconfig.cmake in the current package's top-level directory, e.g.:

   • # I want just static libs, just for this package
     set(ROS_BUILD_STATIC_LIBS true)
     set(ROS_BUILD_SHARED_LIBS false)

NOTE: this ordering is a little non-intuitive, in that the setting in the package's CMakeLists.txt is overridden by the settings in the rosconfig.cmake files.

ROS #defines

The build system defines the following pre-processor macros on the command line of every compilation step:

• ROS_PACKAGE_NAME='"foo"', where foo is the name of the package being built.

Miscellaneous configurations

Using the Intel Compilers

To compile ROS with Intel C/C++ compiler, first install Intel compilers as instructed on the Intel website. Next, modify your CMakeLists.txt in the ROS package to contain the following lines:

set (CMAKE_C_COMPILER $(INTEL_DIR)/bin/icc)
set (CMAKE_CXX_COMPILER $(INTEL_DIR)/bin/icpc)

set (CMAKE_C_EXECUTABLE $(INTEL_DIR)/bin/xild)
set (CMAKE_CXX_EXECUTABLE $(INTEL_DIR)/bin/xild)

set (CMAKE_C_FLAGS   "-msse3 -ip  -no-prec-div         -parallel -O3 -fPIC" )
set (CMAKE_CXX_FLAGS "-msse3 -ip  -no-prec-div         -parallel -O3 -fPIC" )

set (CMAKE_EXE_LINKER_FLAGS  "-Wl,-rpath,$(INTEL_DIR)/lib -L$(INTEL_DIR)/lib -lguide -lcxaguard -limf -lsvml -lirc -lpthread -lintlc" )

Where $(INTEL_DIR) is the Intel compiler install directory (e.g. /opt/intel/cc/10.1.008), optimization flags used here are optional.

If the package you want to compile is a third-party package (e.g. ODE), you will need to customize the Makefiles and pass in the correct flags.

Using ccache and distcc

The ROS build system can take advantage of ccache and distcc. Just configure them as you normally would.

E.g., to enable ccache:

export PATH=/usr/lib/ccache:$PATH

Make sure that

which gcc

points to ccache's wrapper (e.g., /usr/lib/ccache/gcc).

E.g., to enable distcc, in concert with ccache, assuming that you have four machines, named pre1 through pre4:

export DISTCC_HOSTS='@pre1/1 @pre2/1 @pre3/1 @pre4/1'
export CCACHE_PREFIX=distcc

Parallel jobs

If you have a multi-core machine, you can set ROS_PARALLEL_JOBS to take advantage of it during the build.