Add CLion to "Tools and IDEs"

doc/develop/tools/clion.rst

@@ -0,0 +1,207 @@
+.. _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

doc/develop/tools/index.rst

@@ -6,4 +6,5 @@ Tools and IDEs
 .. toctree::
    :maxdepth: 1
 
+   clion.rst
    coccinelle.rst