`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 [[http://ros.org/reps/rep-0128.html|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 [[https://github.com/ros/catkin/blob/kinetic-devel/bin/catkin_make|catkin_make]].

More information about workspaces and catkin spaces: [[catkin/workspaces]]