catkin_make is a convenience tool for building code in a catkin workspace. catkin_make follows the standard layout of a catkin workspace, as described in REP-128.

Usage

You should always call catkin_make in the root of your catkin workspace, assuming your catkin workspace is in ~/catkin_ws:

• $ cd ~/catkin_ws
  $ catkin_make

The above command will build any packages located in ~/catkin_ws/src. The equivalent commands to do this manually would be:

• $ cd ~/catkin_ws
  $ cd src
  $ catkin_init_workspace
  $ cd ..
  $ mkdir build
  $ cd build
  $ cmake ../src -DCMAKE_INSTALL_PREFIX=../install -DCATKIN_DEVEL_PREFIX=../devel
  $ make

If you would like to build specific packages in the workspace, invoke the following in the root of your workspace:

• $ catkin_make -DCATKIN_WHITELIST_PACKAGES="package1;package2"

If you want to revert back to building all packages, do the following:

• $ catkin_make -DCATKIN_WHITELIST_PACKAGES=""

After running catkin_make, you should notice two new folders in the root of your catkin workspace: the build and devel folders. The build folder is where cmake and make are invoked, and the devel folder contains any generated files and targets, plus setup.*sh files so that you can use it like it is installed.

You can pass any arguments to catkin_make that you would normally pass to make and cmake. For example, you can invoke the install target like this:

• $ cd ~/catkin_ws
  $ catkin_make install

Which would be equivalent to calling make like this:

• $ cd ~/catkin_ws/build
  # If cmake hasn't already been called
  $ cmake ../src -DCMAKE_INSTALL_PREFIX=../install -DCATKIN_DEVEL_PREFIX=../devel
  $ make
  $ make install

Now there should be a third folder in the root of your workspace: install. This is a FHS compliant installation of all of the packages in your catkin workspace. It contains setup.*sh files which can be sourced, allowing you to utilize the packages your built.

You can change the location to which packages are installed by passing -DCMAKE_INSTALL_PREFIX=... to catkin_make:

• $ cd ~/catkin_ws
  $ catkin_make -DCMAKE_INSTALL_PREFIX=/opt/ros/<distro> install

Important note: When installing to /opt/ros/<distro> (where <distro> refers to the version ROS you have, e.g indigo, kinetic...) you will probably face an issue with the permissions. Usually as a normal user you don't have permissions to write to /opt hence you need superuser privileges. There are three possible ways of solving this:

• Install ROS (at least the minimal installation) for root (not recommended!)

• Install the packages by changing to root

• Install the packages to a location where you have the required permissions (read and write)

The first option is not recommended since ROS doesn't usually require superuser privileges when you do development. Also working as a superuser is often something that people generally avoid to do (security reasons). So under normal circumstances we have only the second and third option from the list above. The third option might pose some issues for new ROS users who are not used to handling multiple workspaces, which require combining several setup.bash files. That is why option two seems the most straight forward way to go. All you have to do is change the current user (marked as <user> indicating a user with not superuser privileges and the one you normally use for developing ROS software):

• $ sudo su
  $[sudo] password for <user>:

Now that you have superuser privileges all you have to do is source the setup.bash located in your non-super user's catkin workspace or the one located in /opt/ros/<distro>/setup.bash:

• $ source /home/<user>/<user_catkin_workspace>/devel/setup.bash
  
  OR
  
  $ source /opt/ros/<distro>/setup.bash

This will make catkin_make visible to the superuser. You don't need anything else since the way catkin_make install works is to simply copy the files from your source location to the location where you want to install your ROS packages. The final step is to call catkin_make with the arguments from above. The installation should proceed without any further issues. Note that this applies for all cases where you need to install your packages to a location where you normally don't have read and write permissions.

References

The source for catkin_make is located at catkin_make.

More information about workspaces and catkin spaces: catkin/workspaces