Add directions in using STM32CubeIDE

doc/develop/tools/index.rst

@@ -8,4 +8,5 @@ Tools and IDEs
 
    clion.rst
    coccinelle.rst
+   stm32cubeide.rst
    vscode.rst

doc/develop/tools/stm32cubeide.rst

@@ -0,0 +1,110 @@
+.. _stm32cube_ide:
+
+STM32CubeIDE
+############
+
+STM32CubeIDE_ is an Eclipse-based integrated development environment from STMicroelectronics designed for the STM32 series of MCUs and MPUs.
+
+This guide describes the process of setting up, building, and debugging Zephyr
+applications using the IDE.
+
+A project must have already been created with Zephyr and west.
+
+These directions have been validated to work with version 1.16.0 of the IDE
+on Linux.
+
+Project Setup
+*************
+
+#. Before you start, make sure you have a working Zephyr development environment, as per the
+   instructions in the :ref:`getting_started`.
+
+#. Run STM32CubeIDE from your Zephyr environment.  Example:
+
+   .. code-block::
+
+      $ /opt/st/stm32cubeide_1.16.0/stm32cubeide
+
+#. Open your already existing project by going to
+   :menuselection:`File --> New --> STM32 CMake Project`:
+
+   .. figure:: img/stm32cube_new_cmake.webp
+      :align: center
+      :alt: Create new CMake project
+
+#. Select :guilabel:`Project with existing CMake sources`, then click :guilabel:`Next`.
+
+#. Select :menuselection:`Next` and browse to the location of your sources.  The
+   folder that is opened should have the ``CMakeLists.txt`` and ``prj.conf`` files.
+
+#. Select :menuselection:`Next` and select the appropriate MCU.
+   Press :guilabel:`Finish` and your project should now be available.
+   However, more actions must still be done in order to configure it properly.
+
+#. Right-click on the newly created project in the workspace, and select
+   :guilabel:`Properties`.
+
+#. Go to the :guilabel:`C/C++ Build` page and set the Generator
+   to ``Ninja``.  In :guilabel:`Other Options`, specify the target ``BOARD`` in
+   CMake argument format. If an out-of-tree board is targeted, the ``BOARD_ROOT``
+   option must also be set. The resulting settings page should look similar to this:
+
+   .. figure:: img/stm32cube_project_properties.webp
+      :align: center
+      :alt: Properties dialog for project
+
+   These options may or may not be needed depending on if you have an
+   out-of-tree project or not.
+
+#. Go to the :menuselection:`C/C++ General --> Preprocessor Include` page.
+   Select the :guilabel:`GNU C` language, and click on the
+   :menuselection:`CDT User Settings Entries` option.
+
+   .. figure:: img/stm32cube_preprocessor_include.webp
+      :align: center
+      :alt: Properties dialog for preprocessor options
+
+   Click :guilabel:`Add` to add an :guilabel:`Include File`
+   that points to Zephyr's ``autoconf.h``, which is located in
+   ``<build dir>/zephyr/include/generated/autoconf.h``. This will ensure
+   that STM32CubeIDE picks up Zephyr configuration options.
+   The following dialog will be shown.  Fill it in as follows:
+
+   .. figure:: img/stm32cube_add_include.webp
+      :align: center
+      :alt: Add include file dialog
+
+   Once the include file has been added, your properties page should look
+   similar to the following:
+
+   .. figure:: img/stm32cube_autoconf_h.webp
+      :align: center
+      :alt: Properties page after adding autoconf.h file
+
+#. Click :guilabel:`Apply and Close`
+
+#. You may now build the project using the :guilabel:`Build` button on the toolbar.
+   The project can be run using the :guilabel:`Run` button, as well as debugged
+   using the :guilabel:`Debug` button.
+
+Troubleshooting
+***************
+
+When configuring your project you see an error that looks similar to:
+
+.. code-block::
+
+  Error message: Traceback (most recent call last):
+
+    File "/path/to/zephyr/scripts/list_boards.py", line 11, in <module>
+      import pykwalify.core
+
+  ModuleNotFoundError: No module named 'pykwalify'
+
+
+This means that you did not start the IDE in a Zephyr environment.  You must
+delete the ``config_default`` build directory and start STM32CubeIDE again,
+making sure that you can run ``west`` in the shell that you start STM32CubeIDE
+from.
+
+.. _STM32CubeIDE: https://www.st.com/en/development-tools/stm32cubeide.html