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