> For the complete documentation index, see [llms.txt](https://wiki.hanzheteng.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wiki.hanzheteng.com/development/cmake/catkin-tools.md).

# Catkin Tools

### Introduction

* Installation: `sudo apt install python-catkin-tools`
* [documentation](https://catkin-tools.readthedocs.io/en/latest/index.html), [cheat sheet](https://catkin-tools.readthedocs.io/en/latest/cheat_sheet.html)
* It's time to migrate from `catkin_make` to `catkin build` !

### `catkin build` command

* `rosbuild` was the very first build tool developed by ROS community
* Then comes `catkin_make` to help automate the merged build process at the top level
* To address the numerous drawbacks of the merged build process,`catkin_make_isolated` was introduced to isolated build process for each package
* Finally, `catkin build` is the most recent method to build packages, with improved performance
* See [catkin history](https://catkin-tools.readthedocs.io/en/latest/history.html) for more information

### catkin devel space

* In addition to the `merged` and `isolated` devel space layouts provided by `catkin_make` and `catkin_make_isolated`, respectively, `catkin_tools` provides a default [`linked`](https://catkin-tools.readthedocs.io/en/latest/advanced/linked_develspace.html) layout which enables robust cleaning of individual packages from a workspace.
* Specifically, catkin packages are built in the `.private` hidden directory at the root of the devel space. Files in devel space are symbolic links to files in `.private`folder. 
* Additionally, to avoid race condition on setup files (e.g., `setup.bash`) and other problems in parallelize building, in `linked` layout only one package generates these files. A package named `catkin_tools_prebuild` may be built first (before all other packages) for this purpose. 
* To use `merged` layout, run command `catkin config --merge-devel`.

### example catkin commands

```bash
#mkdir -p ~/catkin_ws/src
#cd ~/catkin_ws
catkin init  # cf. catkin_init_workspace

catkin config --extend /opt/ros/melodic  # extend explicitly
catkin config --merge-devel              # linked --> merged
catkin config --cmake-args -DCMAKE_BUILD_TYPE=Release

#cd src
catkin create pkg example
# cf. catkin_create_pkg example

catkin create pkg example --catkin-deps std_msgs
# cf. catkin_create_pkg example std_msgs
# deps will be added to catkin COMPONENTS

catkin create pkg example --system-deps PCL
# no corresponding command in old style (catkin_make system)
# will generate a new line: find_package(PCL REQUIRED)

catkin list  # List the packages in the workspace

catkin build  # can run at all levels (~/catkin_ws, ~/catkin_ws/src, within pkg)
catkin build example_pkg  # build only this package
cd ~/catkin_ws/src/example_pkg && catkin build --this
#echo 'source ~/catkin_ws/devel/setup.bash' >> ~/.bashrc

catkin clean
catkin clean example_pkg  # clean only this package
```

### FAQ & Troubleshooting

```
WARNING: Your current environment's CMAKE_PREFIX_PATH is different from the
cached CMAKE_PREFIX_PATH used the last time this workspace was built.

If you want to use a different CMAKE_PREFIX_PATH you should call `catkin clean`
to remove all references to the previous CMAKE_PREFIX_PATH.
```

* This warning can be ignored and it will continue to use the cached path. It often happens after new workspaces are established and setup files are sourced. 
* Alternatively, it can be resolved by explicitly extending other workspaces. 
  * `catkin config --extend /opt/ros/melodic` 
  * to revert, `catkin config --no-extend`