# ROS2 setup tutorial

[ROS2](https://docs.ros.org/en/lyrical/index.html) is the newest version of ROS, Robot Operating System,  which is a set of libraries and tools designed for robot applications.

This tutorial describes how to use CLion as an IDE for developing ROS2 applications built with [colcon](https://colcon.readthedocs.io/en/released/). If you are working with an older ROS distribution, which uses catkin build tools, please refer to the [previous tutorial](ros-setup-tutorial.html).

Instructions below show the following procedures on Windows: creating a ROS2 workspace, opening it as a compilation database project in CLion, building, running/debugging a package, adding another package, and rebuilding the workspace.

Procedure: Prepare the ROS2 environment

1. [Install](https://docs.ros.org/en/foxy/Installation.html) ROS2 on your system.

2. Make sure that [sourcing](https://docs.ros.org/en/foxy/Tutorials/Configuring-ROS2-Environment.html#source-the-setup-files) the ROS2 installation succeeds. Follow the tips in the same guide in case of issues.

Procedure: Create a workspace

> **Note:**
> If you already have a workspace, jump to [Build the workspace and generate a compilation database](#build-ws).

We will take the official [Simple publisher and subscriber (C++)](https://docs.ros.org/en/foxy/Tutorials/Writing-A-Simple-Cpp-Publisher-And-Subscriber.html) guide as an example.

1. Open a terminal in Administrator mode.

2. [Source](https://docs.ros.org/en/foxy/Tutorials/Configuring-ROS2-Environment.html#source-the-setup-files) the ROS2 installation. In our case the command is

```CONSOLE
call C:\dev\ros2\ros2-windows\local_setup.bat
```

> **Tip:**
> If you get an RTI Connext DDS environment script not found warning, you can safely ignore it in the scope of this tutorial.

3. Create a directory for a new workspace and navigate into it

```CONSOLE
md \dev_ws\src
cd \dev_ws\src
```

4. Create a publisher-subscriber package

```CONSOLE
ros2 pkg create --build-type ament_cmake cpp_pubsub
```

Follow the next [steps](https://docs.ros.org/en/foxy/Tutorials/Writing-A-Simple-Cpp-Publisher-And-Subscriber.html#tasks) to get the source files, `CMakeLists.txt`, and `package.xml`, up until building.

At this point, we have the following folder structure:

```CONSOLE
|_dev_ws
   |_src
      |_cpp_pubsub
         |_include
         |_src
               subscriber_member_function.cpp
               publisher_member_function.cpp
           CMakeLists.txt
           package.xml
```

Procedure: Build a workspace in terminal and generate a compilation database

In order to be able to open a ROS2 workspace in CLion, we will generate a [JSON compilation database](https://www.jetbrains.com/help/clion/compilation-database.html) using the [CMAKE_EXPORT_COMPILE_COMMANDS](https://cmake.org/cmake/help/latest/variable/CMAKE_EXPORT_COMPILE_COMMANDS.html) CMake flag.

This option is supported in CMake only for the Makefile and Ninja generators, so we also need to switch between the generators using `-G`.

1. In the same terminal where you initially sourced the ROS2 installation, navigate to the workspace-level folder (`dev_ws` in our case) and run

```CONSOLE
colcon build --cmake-args -DCMAKE_EXPORT_COMPILE_COMMANDS=ON -G Ninja
```

> **Tip:**
> If you get the Generator: execution of make failed error, try initializing the Visual C++ environment before building. Customize the path in the following command as required:
>
> `call "C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Auxiliary\Build\vcvarsall.bat" x86_amd64`
>
> Then run the build command again.

2. When build is finished, make sure that `dev_ws\build` contains a `compile_commands.json` file. In case it is not there, make sure your colcon version supports generating workspace-level compilation databases (see this [issue](https://github.com/colcon/colcon-cmake/issues/61)).

Procedure: Launch CLion in the sourced environment

1. In the same terminal, source the workspace setup files:

```CONSOLE
call install/setup.bat
```

2. Next, launch CLion from the same shell. For more information, refer to [Command-line interface](working-with-the-ide-features-from-command-line.html).

For example, in the case of using Toolbox, you can create a [script for launching the IDE](https://www.jetbrains.com/help/clion/working-with-the-ide-features-from-command-line.html#generate-shell-scripts). In our case, it is located in `C:\IDE_shell_scripts`.

```CONSOLE
cd C:\IDE_shell_scripts\
clion
```

3. As the result, CLion will be launched with the ROS2 environment already prepared.

Procedure: Open a workspace in CLion

1. In CLion, call `File | Open` from the main menu and select the `compile_commands.json` file in the top-level `build` directory:

![Opening a ROS2 workspace as a compilation database project](https://resources.jetbrains.com/help/img/idea/2026.2/cl_ros2_compdb_open.png)

2. Click Open as project:

![Open compDB as project](https://resources.jetbrains.com/help/img/idea/2026.2/cl_ros2_compdb_open_as_prj.png)

3. Check that the project is loaded successfully:

![Initial loading of a ROS2 workspace](https://resources.jetbrains.com/help/img/idea/2026.2/cl_ros2_load_initial.png)

Procedure: Change the project root

By default, CLions considers the directory containing the `compile_commands.json` file as project root. In our case, it is the `build` directory. In the Project tree, the actual source files are marked as external:

![Source files marked external](https://resources.jetbrains.com/help/img/idea/2026.2/cl_ros2_external_sources.png)

To get the correct project structure, we need to set the project root to the actual workspace directory.

1. Call `Tools | Compilation Database | Change Project Root` from the main menu and select the workspace directory (`dev_ws` in our case).

2. Check the changes in Project view:

![Workspace project root](https://resources.jetbrains.com/help/img/idea/2026.2/cl_ros2_change_prj_dir.png)

At this point, all the CLion [editing features](working-with-source-code.html) are fully available for the workspace sources.

> **Tip:**
> By default, CLion doesn't reload projects automatically on changes in `compile_command.json` except for the cases of external events like VCS update. You can change this behavior in `Settings | Build, Execution, Deployment | Build Tools`.
>
>
>
> See [Compilation database: configure auto-reload](compilation-database.html#compdb_reload).

## How to build a package

In order to build and then launch a package inside CLion, we will create a [custom build target](custom-build-targets.html#customtarget-compdb) for CMake commands actually performed during `colcon build`, and then create a [custom application configuration](custom-build-targets.html#custom-rundebug) for that target.

Procedure: 1. Create a script for the 'colcon build' commands

1. Navigate to the build logs directory. In our case, it's `C:\dev_ws\log\latest_build\cpp_pubsub`. Open the `command.txt` file from the latest build.

2. Copy the commands into another file and modify them to the following:

```BASH
"C:\Program Files\CMake\bin\cmake.EXE" C:\dev_ws\src\cpp_pubsub -DCMAKE_EXPORT_COMPILE_COMMANDS=ON -G Ninja -DCMAKE_INSTALL_PREFIX=C:\dev_ws\install\cpp_pubsub
"C:\Program Files\CMake\bin\cmake.EXE" --build C:\dev_ws\build\cpp_pubsub -- -j8 -l8
"C:\Program Files\CMake\bin\cmake.EXE" --install C:\dev_ws\build\cpp_pubsub
```

> **Tip:**
> This script will be called from the package build directory, `build/cpp_pubsub`, and the compilation database file will be generated there. For consistency, you can copy that file up to the workspace `build` level by adding the following command at the end:
>
>
>
>
> ```BASH
> copy  C:\dev_ws\build\cpp_pubsub\compile_commands.json  C:\dev_ws\build
> ```

3. Save the file as a `.bat` script. In our example, it is called `cmake_commands.bat` and placed into `c:\dev_ws\src\cpp_pubsub\`.

Procedure: 2. Create a custom build target

1. In CLion, go to `Settings | Build, Execution, Deployment | Custom Build Targets` and click ![](https://resources.jetbrains.com/help/img/idea/2026.2/app.expui.general.add.svg) to add a new target.

2. * Set the Toolchain to Visual Studio. For more information about configuring a Visual Studio toolchain in CLion, refer to [Windows tutorial](https://www.jetbrains.com/help/clion/quick-tutorial-on-configuring-clion-on-windows.html#MSVC).

* Click the three dots icon next to the Build field. Then click ![](https://resources.jetbrains.com/help/img/idea/2026.2/app.expui.general.add.svg) to add an external. In the Program field, select the newly created script. Set the Working directory to the package build directory.

![Creating a custom build target for CMake commands](https://resources.jetbrains.com/help/img/idea/2026.2/cl_ros2_customtool.png)

3. Save the custom target.

Procedure: 3. Create a run/debug configuration for the custom build target

To be able to build and then launch the target we have for the package, we need to create a corresponding [configuration](run-debug-configuration.html).

1. In the main menu, go to `Run | Edit Configurations`, click ![](https://resources.jetbrains.com/help/img/idea/2026.2/app.expui.general.add.svg) and select Custom Build Application.

2. In the configuration settings, select the Target and make sure to remove Build from the Before launch area.

![Custom configuration](https://resources.jetbrains.com/help/img/idea/2026.2/cl_ros2_custom_config.png)

Procedure: 4. Build a package

1. Select the configuration in the toolbar switcher:

![Configuration for build](https://resources.jetbrains.com/help/img/idea/2026.2/cl_ros2_config_switcher.png)

2. Click the hammer icon or press `Ctrl + F9`. Alternatively, call Build | Build 'Build cpp_pubsub' from the main menu.

3. Check the result in the Run tool window.

> **Tip:**
> If you have added or removed files in the package, the compilation database will be regenerated accordingly. Make sure to reload it or [configure auto-reload](compilation-database.html#compdb_reload).

Procedure: Run/debug a package

1. Open the Edit Configurations dialog again.

2. Modify the [configuration for build](#custom-apps) to the following:

* Set the Executable to the actual package binary.

* Select the Run with Administrator privileges checkbox. See [Debug as root](debug-as-root.html) for more information.

![Run/debug configuration for a package](https://resources.jetbrains.com/help/img/idea/2026.2/cl_ros2_run_talker_config.png)

3. After saving the configuration, it is ready to be Run![](https://resources.jetbrains.com/help/img/idea/2026.2/app.actions.execute.svg) or Debugged![](https://resources.jetbrains.com/help/img/idea/2026.2/app.actions.startDebugger.svg). All the CLion [debugging](debugging-code.html) and [dynamic analysis](profiling-tools.html) features will be available for the workspace code.

CLion will take the debugger from target's toolchain. In our case, it is [MSVC LLDB](quick-tutorial-on-configuring-clion-on-windows.html#msvc-debugger).

> **Tip:**
> Another alternative for debugging is to launch a package outside CLion and then [attach the debugger](attach-to-process.html) to a running process.

## How to build a workspace

Now let’s take a look at how we can add a new package and rebuild the entire workspace in CLion. To illustrate this, we’ll take an example of adding a [Simple service and client](https://docs.ros.org/en/foxy/Tutorials/Writing-A-Simple-Cpp-Service-And-Client.html) package to our `dev_ws` workspace.

Procedure: Prepare new package files

1. In a terminal, [source](https://docs.ros.org/en/foxy/Tutorials/Configuring-ROS2-Environment.html#source-the-setup-files) the ROS2 installation and navigate to `dev_ws\src`

2. Create a new package

```CONSOLE
ros2 pkg create --build-type ament_cmake cpp_srvcli --dependencies rclcpp example_interfaces
```

3. Follow the [steps](https://docs.ros.org/en/foxy/Tutorials/Writing-A-Simple-Cpp-Service-And-Client.html#tasks) to get the source files, `CMakeLists.txt`, and `package.xml`, up until building.

Procedure: Build the whole workspace

To (re)build the entire workspace, we will configure an [external tool](configuring-third-party-tools.html) for `colcon build` and call it without leaving CLion.

1. Go to `Settings | Tools | External Tools` and click ![](https://resources.jetbrains.com/help/img/idea/2026.2/app.expui.general.add.svg) to add a new tool.

2. Configure the tool to perform the same `colcon build` command as we used when building from the command line:

![External tool for colcon build](https://resources.jetbrains.com/help/img/idea/2026.2/cl_ros2_colcon_build_external_tool.png)

> **Note:**
> Make sure to set the Working directory.

3. After saving the tool, call it via `Tools | External Tools` in the main menu.

4. Check the results in the Run tool window:

![Results of colcon build using an external tool](https://resources.jetbrains.com/help/img/idea/2026.2/cl_ros2_colcon_build_results.png)

> **Tip:**
> Next time use the ![](https://resources.jetbrains.com/help/img/idea/2026.2/app.actions.execute.svg) button in the Run tool window to rebuild the workspace again.

5. Check that `compile_commands.json` has been regenerated and now includes the entities for both packages:

![Compilation database regenerated after workspace rebuild](https://resources.jetbrains.com/help/img/idea/2026.2/cl_ros2_compdb_regenerated.png)

6. Make sure to reload the compilation database (press `Ctrl+Shift+O` (Windows), `⌘ ⇧ I` (macOS), `⌘ ⇧ O` (IntelliJ IDEA Classic (macOS)), `⌘ ⇧ I` (macOS System Shortcuts), `Ctrl+Shift+O` (XWin), `Ctrl+Shift+O` (GNOME), `Ctrl+Shift+O` (KDE), `Ctrl+Shift+O` (Emacs), `Ctrl+Shift+O` (Sublime Text), `⌘ ⇧ I` (Sublime Text (macOS)), `⌘ ⇧ I` (Xcode), `Ctrl+Shift+O` (Visual Studio), `⌘ ⇧ I` (Visual Studio (macOS)), `Ctrl+Shift+O` (ReSharper), `⌘ ⇧ I` (ReSharper (macOS)), `Ctrl+Shift+O` (QtCreator), `Ctrl+Shift+O` (QtCreator (macOS)), `Ctrl+Shift+O` (NetBeans), `Ctrl+Shift+O` (Eclipse), `Ctrl+Shift+O` (Eclipse (macOS)) or call `Tools | Compilation Database | Reload Compilation Database Project` form the main menu). To avoid reloading the project manually, [configure auto-reload](compilation-database.html#compdb_reload).

At this point, both of the packages are included in CLion project model and you can work with them as usual. To build and run the second package, follow the steps described [above](#build-pkg).

## See also

### Getting Started

[Tutorial: Configure CLion on Windows](quick-tutorial-on-configuring-clion-on-windows.html) [Custom build targets and applications](custom-build-targets.html) [Compilation database](compilation-database.html)

### External Links

[ROS wiki](https://wiki.ros.org/)