doc/develop/tools/clion.rst - third_party/github/zephyrproject-rtos/zephyr - Git at Google

 .. _clion_ide:

 CLion
 #####

 CLion_ is a cross-platform C/C++ IDE that supports multi-threaded RTOS debugging.

 This guide describes the process of setting up, building, and debugging Zephyr's
 :zephyr:code-sample:`multi-thread-blinky` sample in CLion.

 The instructions have been tested on Windows. In terms of the CLion workflow, the steps would be the
 same for macOS and Linux, but make sure to select the correct environment file and to adjust the
 paths.

 Get CLion
 *********

 `Download CLion`_ and install it.

 Initialize a new workspace
 **************************

 This guide gives details on how to build and debug the :zephyr:code-sample:`multi-thread-blinky`
 sample application, but the instructions would be similar for any Zephyr project and :ref:`workspace
 layout <west-workspaces>`.

 Before you start, make sure you have a working Zephyr development environment, as per the
 instructions in the :ref:`getting_started`.

 Open the project in CLion
 **************************

 #. In CLion, click :guilabel:`Open` on the Welcome screen or select :menuselection:`File --> Open`
    from the main menu.

 #. Navigate to your Zephyr workspace (i.e.the :file:`zephyrproject` folder in your HOME directory if
    you have followed the Getting Started instructions), then select
    :file:`zephyr/samples/basic/threads` or another sample project folder.

    Click :guilabel:`OK`.

 #. If prompted, click :guilabel:`Trust Project`.

    See the `Project security`_ section in CLion web help for more information on project security.

 Configure the toolchain and CMake profile
 *****************************************

 CLion will open the :guilabel:`Open Project Wizard` with the CMake profile settings. If that does
 not happen, go to :menuselection:`Settings --> Build, Execution, Deployment --> CMake`.

 #. Click :guilabel:`Manage Toolchains` next to the :guilabel:`Toolchain` field. This will open the
    :guilabel:`Toolchain` settings dialog.

 #. We recommend that you use the :guilabel:`Bundled MinGW` toolchain with default settings on
    Windows, or the :guilabel:`System` (default) toolchain on Unix machines.

 #. Click :menuselection:`Add environment --> From file` and select
    ``..\.venv\Scripts\activate.bat``.

    .. figure:: img/clion_toolchain_mingw.webp
       :width: 600px
       :align: center
       :alt: MinGW toolchain with environment script

    Click :guilabel:`Apply` to save the changes.

 #. Back in the CMake profile settings dialog, specify your board in the :guilabel:`CMake options`
    field. For example:

    .. code-block::

       -DBOARD=nrf52840dk/nrf52840

    .. figure:: img/clion_cmakeprofile.webp
       :width: 600px
       :align: center
       :alt: CMake profile

 #. Click :guilabel:`Apply` to save the changes.

    CMake load should finish successfully.

 Configure Zephyr parameters for debug
 *************************************

 #. In the configuration switcher on the top right, select :guilabel:`guiconfig` and click the hammer
    icon.

 #. Use the GUI application to set the following flags:

    .. code-block::

       DEBUG_THREAD_INFO
       THREAD_RUNTIME_STATS
       DEBUG_OPTIMIZATIONS

 Build the project
 *****************

 In the configuration switcher, select **zephyr_final** and click the hammer icon.

 Note that other CMake targets like ``puncover`` or ``hardenconfig`` can also be called at this
 point.


 Enable RTOS integration
 ***********************

 #. Go to :menuselection:`Settings --> Build, Execution, Deployment --> Embedded Development --> RTOS
    Integration`.

 #. Set the :guilabel:`Enable RTOS Integration` checkbox.

    This option enables Zephyr tasks view during debugging. See `Multi-threaded RTOS debug`_ in CLion
    web help for more information.

    You can leave the option set to :guilabel:`Auto`. CLion will detect Zephyr automatically.

 Create an Embedded GDB Server configuration
 *******************************************

 In order to debug a Zephyr application in CLion, you need to create a run/debug configuration out of
 the Embedded GDB Server template.

 Instructions below show the case of a Nordic Semiconductor board and a Segger J-Link debug probe. If
 your setup is different, make sure to adjust the configuration settings accordingly.

 #. Select :menuselection:`Run --> New Embedded Configuration` from the main menu.

 #. Configure the settings:

     .. list-table::
         :header-rows: 1

         * - Option
           - Value

         * - :guilabel:`Name` (optional)
           - Zephyr-threads

         * - :guilabel:`GDB Server Type`
           - Segger JLink

         * - :guilabel:`Location`
           - The path to ``JLinkGDBServerCL.exe`` on Windows or the ``JLinkGDBServer`` binary on
             macOS/Linux.

         * - :guilabel:`Debugger`
           - Bundled GDB

             .. note:: For non-ARM and non-x86 architectures, use a GDB executable
                from Zephyr SDK. Make sure to pick a version with Python support
                (for example, **riscv64-zephyr-elf-gdb-py**) and check that Python
                is present in the system ``PATH``.

         * - :guilabel:`Target`
           - zephyr-final

         * - :guilabel:`Executable binary`
           - zephyr-final

         * - :guilabel:`Download binary`
           - Always

         * - :guilabel:`TCP/IP port`
           - Auto

     .. figure:: img/clion_gdbserverconfig.webp
        :width: 500px
        :align: center
        :alt: Embedded GDB server configuration

 #. Click :guilabel:`Next` to set the Segger J-Link parameters.

     .. figure:: img/clion_segger_settings.webp
        :width: 500px
        :align: center
        :alt: Segger J-Link parameters

 #. Click :guilabel:`Create` when ready.

 Start debugging
 ***************

 #. Place breakpoints by clicking in the left gutter next to the code lines.

 #. Make sure that **Zephyr-threads** is selected in the configuration switcher and click the bug
    icon or press :kbd:`Ctrl+D`.

 #. When a breakpoint is hit, CLion opens the Debug tool window.

    Zephyr tasks are listed in the :guilabel:`Threads & Variables` pane. You can switch between them
    and inspect the variables for each task.

     .. figure:: img/clion_debug_threads.webp
        :width: 800px
        :align: center
        :alt: Viewing Zephyr tasks during a debug session

    Refer to `CLion web help`_ for detailed description of the IDE debug capabilities.

 .. _CLion: https://www.jetbrains.com/clion/
 .. _Download CLion: https://www.jetbrains.com/clion/download
 .. _Project security: https://www.jetbrains.com/help/clion/project-security.html#projects_security
 .. _Multi-threaded RTOS debug: https://www.jetbrains.com/help/clion/rtos-debug.html
 .. _CLion web help: https://www.jetbrains.com/help/clion/debugging-code.html
	.. _clion_ide:

	CLion
	#####

	CLion_ is a cross-platform C/C++ IDE that supports multi-threaded RTOS debugging.

	This guide describes the process of setting up, building, and debugging Zephyr's
	:zephyr:code-sample:`multi-thread-blinky` sample in CLion.

	The instructions have been tested on Windows. In terms of the CLion workflow, the steps would be the
	same for macOS and Linux, but make sure to select the correct environment file and to adjust the
	paths.

	Get CLion
	*********

	`Download CLion`_ and install it.

	Initialize a new workspace
	**************************

	This guide gives details on how to build and debug the :zephyr:code-sample:`multi-thread-blinky`
	sample application, but the instructions would be similar for any Zephyr project and :ref:`workspace
	layout <west-workspaces>`.

	Before you start, make sure you have a working Zephyr development environment, as per the
	instructions in the :ref:`getting_started`.

	Open the project in CLion
	**************************

	#. In CLion, click :guilabel:`Open` on the Welcome screen or select :menuselection:`File --> Open`
	from the main menu.

	#. Navigate to your Zephyr workspace (i.e.the :file:`zephyrproject` folder in your HOME directory if
	you have followed the Getting Started instructions), then select
	:file:`zephyr/samples/basic/threads` or another sample project folder.

	Click :guilabel:`OK`.

	#. If prompted, click :guilabel:`Trust Project`.

	See the `Project security`_ section in CLion web help for more information on project security.

	Configure the toolchain and CMake profile
	*****************************************

	CLion will open the :guilabel:`Open Project Wizard` with the CMake profile settings. If that does
	not happen, go to :menuselection:`Settings --> Build, Execution, Deployment --> CMake`.

	#. Click :guilabel:`Manage Toolchains` next to the :guilabel:`Toolchain` field. This will open the
	:guilabel:`Toolchain` settings dialog.

	#. We recommend that you use the :guilabel:`Bundled MinGW` toolchain with default settings on
	Windows, or the :guilabel:`System` (default) toolchain on Unix machines.

	#. Click :menuselection:`Add environment --> From file` and select
	``..\.venv\Scripts\activate.bat``.

	.. figure:: img/clion_toolchain_mingw.webp
	:width: 600px
	:align: center
	:alt: MinGW toolchain with environment script

	Click :guilabel:`Apply` to save the changes.

	#. Back in the CMake profile settings dialog, specify your board in the :guilabel:`CMake options`
	field. For example:

	.. code-block::

	-DBOARD=nrf52840dk/nrf52840

	.. figure:: img/clion_cmakeprofile.webp
	:width: 600px
	:align: center
	:alt: CMake profile

	#. Click :guilabel:`Apply` to save the changes.

	CMake load should finish successfully.

	Configure Zephyr parameters for debug
	*************************************

	#. In the configuration switcher on the top right, select :guilabel:`guiconfig` and click the hammer
	icon.

	#. Use the GUI application to set the following flags:

	.. code-block::

	DEBUG_THREAD_INFO
	THREAD_RUNTIME_STATS
	DEBUG_OPTIMIZATIONS

	Build the project
	*****************

	In the configuration switcher, select zephyr_final and click the hammer icon.

	Note that other CMake targets like ``puncover`` or ``hardenconfig`` can also be called at this
	point.


	Enable RTOS integration
	***********************

	#. Go to :menuselection:`Settings --> Build, Execution, Deployment --> Embedded Development --> RTOS
	Integration`.

	#. Set the :guilabel:`Enable RTOS Integration` checkbox.

	This option enables Zephyr tasks view during debugging. See `Multi-threaded RTOS debug`_ in CLion
	web help for more information.

	You can leave the option set to :guilabel:`Auto`. CLion will detect Zephyr automatically.

	Create an Embedded GDB Server configuration
	*******************************************

	In order to debug a Zephyr application in CLion, you need to create a run/debug configuration out of
	the Embedded GDB Server template.

	Instructions below show the case of a Nordic Semiconductor board and a Segger J-Link debug probe. If
	your setup is different, make sure to adjust the configuration settings accordingly.

	#. Select :menuselection:`Run --> New Embedded Configuration` from the main menu.

	#. Configure the settings:

	.. list-table::
	:header-rows: 1

	* - Option
	- Value

	* - :guilabel:`Name` (optional)
	- Zephyr-threads

	* - :guilabel:`GDB Server Type`
	- Segger JLink

	* - :guilabel:`Location`
	- The path to ``JLinkGDBServerCL.exe`` on Windows or the ``JLinkGDBServer`` binary on
	macOS/Linux.

	* - :guilabel:`Debugger`
	- Bundled GDB

	.. note:: For non-ARM and non-x86 architectures, use a GDB executable
	from Zephyr SDK. Make sure to pick a version with Python support
	(for example, riscv64-zephyr-elf-gdb-py) and check that Python
	is present in the system ``PATH``.

	* - :guilabel:`Target`
	- zephyr-final

	* - :guilabel:`Executable binary`
	- zephyr-final

	* - :guilabel:`Download binary`
	- Always

	* - :guilabel:`TCP/IP port`
	- Auto

	.. figure:: img/clion_gdbserverconfig.webp
	:width: 500px
	:align: center
	:alt: Embedded GDB server configuration

	#. Click :guilabel:`Next` to set the Segger J-Link parameters.

	.. figure:: img/clion_segger_settings.webp
	:width: 500px
	:align: center
	:alt: Segger J-Link parameters

	#. Click :guilabel:`Create` when ready.

	Start debugging
	***************

	#. Place breakpoints by clicking in the left gutter next to the code lines.

	#. Make sure that Zephyr-threads is selected in the configuration switcher and click the bug
	icon or press :kbd:`Ctrl+D`.

	#. When a breakpoint is hit, CLion opens the Debug tool window.

	Zephyr tasks are listed in the :guilabel:`Threads & Variables` pane. You can switch between them
	and inspect the variables for each task.

	.. figure:: img/clion_debug_threads.webp
	:width: 800px
	:align: center
	:alt: Viewing Zephyr tasks during a debug session

	Refer to `CLion web help`_ for detailed description of the IDE debug capabilities.

	.. _CLion: https://www.jetbrains.com/clion/
	.. _Download CLion: https://www.jetbrains.com/clion/download
	.. _Project security: https://www.jetbrains.com/help/clion/project-security.html#projects_security
	.. _Multi-threaded RTOS debug: https://www.jetbrains.com/help/clion/rtos-debug.html
	.. _CLion web help: https://www.jetbrains.com/help/clion/debugging-code.html