# 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`


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://wiki.hanzheteng.com/development/cmake/catkin-tools.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.