## repository: https://code.ros.org/svn/ros
<<PackageHeader(rosbuild)>>

{{{#!wiki blue/solid
[[catkin]] is the recommended build system for packages starting with ROS [[groovy]]. Up to ROS [[fuerte]], ROS was build using a cmake wrapper script called ``rosmake`` which is part of rosbuild.

Please select the EOL-distro above to see the old documentation.
}}}

{{{{#!wiki version fuerte_and_older
<<TableOfContents(3)>>

== Overview ==
The core build tool ROS uses is [[http://www.cmake.org|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 [[/CMakeLists#Test_macros|declaring tests]].

To build [[Packages|packages]], use [[rosmake]].

Every ROS [[Packages|package]] should have the following three files in its top-level directory:
 * [[/CMakeLists|CMakeLists.txt]] : a CMake build file, possibly using ROS macros
 * [[rosbuild/Manifest|manifest.xml]] : the package [[rosbuild/Manifest|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 [[/CMakeLists|API documentation]].  Also see [[/CMakeLists/Examples|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 [[ROS/CrossCompiling|notes on cross-compiling]] to find out more.

<<Anchor(Customizing)>>
== 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)
}}}
 1. 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)
}}}
 1. 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 [[http://ccache.samba.org/|ccache]] and [[http://distcc.samba.org/|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/EnvironmentVariables#ROS_PARALLEL_JOBS|ROS_PARALLEL_JOBS]] to take advantage of it during the build.

}}}}

##Please create this page with template "PackageReviewIndex"
## CategoryPackage
## M3Package