1.. _clion_ide:
2
3CLion
4#####
5
6.. note::
7
8   This guide describes how to set up, build, and debug Zephyr's sample application in CLion, using
9   the IDE's CMake integration. This approach is no longer optimal.
10
11   CLion now features `native Zephyr West integration`_ which provides an easier and more intuitive
12   way to open, build, and run/debug Zephyr projects. This guide will be updated soon, but is still
13   valid if you prefer to use CMake.
14
15CLion_ is a cross-platform C/C++ IDE that supports multi-threaded RTOS debugging.
16
17This guide describes the process of setting up, building, and debugging Zephyr's
18:zephyr:code-sample:`multi-thread-blinky` sample in CLion.
19
20The instructions have been tested on Windows. In terms of the CLion workflow, the steps would be the
21same for macOS and Linux, but make sure to select the correct environment file and to adjust the
22paths.
23
24Get CLion
25*********
26
27`Download CLion`_ and install it.
28
29Initialize a new workspace
30**************************
31
32This guide gives details on how to build and debug the :zephyr:code-sample:`multi-thread-blinky`
33sample application, but the instructions would be similar for any Zephyr project and :ref:`workspace
34layout <west-workspaces>`.
35
36Before you start, make sure you have a working Zephyr development environment, as per the
37instructions in the :ref:`getting_started`.
38
39Open the project in CLion
40**************************
41
42#. In CLion, click :guilabel:`Open` on the Welcome screen or select :menuselection:`File --> Open`
43   from the main menu.
44
45#. Navigate to your Zephyr workspace (i.e.the :file:`zephyrproject` folder in your HOME directory if
46   you have followed the Getting Started instructions), then select
47   :file:`zephyr/samples/basic/threads` or another sample project folder.
48
49   Click :guilabel:`OK`.
50
51#. If prompted, click :guilabel:`Trust Project`.
52
53   See the `Project security`_ section in CLion web help for more information on project security.
54
55Configure the toolchain and CMake profile
56*****************************************
57
58CLion will open the :guilabel:`Open Project Wizard` with the CMake profile settings. If that does
59not happen, go to :menuselection:`Settings --> Build, Execution, Deployment --> CMake`.
60
61#. Click :guilabel:`Manage Toolchains` next to the :guilabel:`Toolchain` field. This will open the
62   :guilabel:`Toolchain` settings dialog.
63
64#. We recommend that you use the :guilabel:`Bundled MinGW` toolchain with default settings on
65   Windows, or the :guilabel:`System` (default) toolchain on Unix machines.
66
67#. Click :menuselection:`Add environment --> From file` and select
68   ``..\.venv\Scripts\activate.bat``.
69
70   .. figure:: img/clion_toolchain_mingw.webp
71      :width: 600px
72      :align: center
73      :alt: MinGW toolchain with environment script
74
75   Click :guilabel:`Apply` to save the changes.
76
77#. Back in the CMake profile settings dialog, specify your board in the :guilabel:`CMake options`
78   field. For example:
79
80   .. code-block::
81
82      -DBOARD=nrf52840dk/nrf52840
83
84   .. figure:: img/clion_cmakeprofile.webp
85      :width: 600px
86      :align: center
87      :alt: CMake profile
88
89#. Click :guilabel:`Apply` to save the changes.
90
91   CMake load should finish successfully.
92
93Configure Zephyr parameters for debug
94*************************************
95
96#. In the configuration switcher on the top right, select :guilabel:`guiconfig` and click the hammer
97   icon.
98
99#. Use the GUI application to set the following flags:
100
101   .. code-block::
102
103      DEBUG_THREAD_INFO
104      THREAD_RUNTIME_STATS
105      DEBUG_OPTIMIZATIONS
106
107Build the project
108*****************
109
110In the configuration switcher, select **zephyr_final** and click the hammer icon.
111
112Note that other CMake targets like ``puncover`` or ``hardenconfig`` can also be called at this
113point.
114
115
116Enable RTOS integration
117***********************
118
119#. Go to :menuselection:`Settings --> Build, Execution, Deployment --> Embedded Development --> RTOS
120   Integration`.
121
122#. Set the :guilabel:`Enable RTOS Integration` checkbox.
123
124   This option enables Zephyr tasks view during debugging. See `Multi-threaded RTOS debug`_ in CLion
125   web help for more information.
126
127   You can leave the option set to :guilabel:`Auto`. CLion will detect Zephyr automatically.
128
129Create an Embedded GDB Server configuration
130*******************************************
131
132In order to debug a Zephyr application in CLion, you need to create a run/debug configuration out of
133the Embedded GDB Server template.
134
135Instructions below show the case of a Nordic Semiconductor board and a Segger J-Link debug probe. If
136your setup is different, make sure to adjust the configuration settings accordingly.
137
138#. Select :menuselection:`Run --> New Embedded Configuration` from the main menu.
139
140#. Configure the settings:
141
142    .. list-table::
143        :header-rows: 1
144
145        * - Option
146          - Value
147
148        * - :guilabel:`Name` (optional)
149          - Zephyr-threads
150
151        * - :guilabel:`GDB Server Type`
152          - Segger JLink
153
154        * - :guilabel:`Location`
155          - The path to ``JLinkGDBServerCL.exe`` on Windows or the ``JLinkGDBServer`` binary on
156            macOS/Linux.
157
158        * - :guilabel:`Debugger`
159          - Bundled GDB
160
161            .. note:: For non-ARM and non-x86 architectures, use a GDB executable
162               from Zephyr SDK. Make sure to pick a version with Python support
163               (for example, **riscv64-zephyr-elf-gdb-py**) and check that Python
164               is present in the system ``PATH``.
165
166        * - :guilabel:`Target`
167          - zephyr-final
168
169        * - :guilabel:`Executable binary`
170          - zephyr-final
171
172        * - :guilabel:`Download binary`
173          - Always
174
175        * - :guilabel:`TCP/IP port`
176          - Auto
177
178    .. figure:: img/clion_gdbserverconfig.webp
179       :width: 500px
180       :align: center
181       :alt: Embedded GDB server configuration
182
183#. Click :guilabel:`Next` to set the Segger J-Link parameters.
184
185    .. figure:: img/clion_segger_settings.webp
186       :width: 500px
187       :align: center
188       :alt: Segger J-Link parameters
189
190#. Click :guilabel:`Create` when ready.
191
192Start debugging
193***************
194
195#. Place breakpoints by clicking in the left gutter next to the code lines.
196
197#. Make sure that **Zephyr-threads** is selected in the configuration switcher and click the bug
198   icon or press :kbd:`Ctrl+D`.
199
200#. When a breakpoint is hit, CLion opens the Debug tool window.
201
202   Zephyr tasks are listed in the :guilabel:`Threads & Variables` pane. You can switch between them
203   and inspect the variables for each task.
204
205    .. figure:: img/clion_debug_threads.webp
206       :width: 800px
207       :align: center
208       :alt: Viewing Zephyr tasks during a debug session
209
210   Refer to `CLion web help`_ for detailed description of the IDE debug capabilities.
211
212.. _native Zephyr West integration: https://www.jetbrains.com/help/clion/zephyr.html
213.. _CLion: https://www.jetbrains.com/clion/
214.. _Download CLion: https://www.jetbrains.com/clion/download
215.. _Project security: https://www.jetbrains.com/help/clion/project-security.html#projects_security
216.. _Multi-threaded RTOS debug: https://www.jetbrains.com/help/clion/rtos-debug.html
217.. _CLion web help: https://www.jetbrains.com/help/clion/debugging-code.html
218