doc: config_and_build: reorganize additions in NCS

Moved and expanded information in "Additions in the NCS" section of the build and config overview page. Replaced includes with links in some application readme files. NCSDK-22324. Signed-off-by: Grzegorz Ferenc <[email protected]>
D-Triveni · Jan 3, 2024 · 0b4dbc4 · 0b4dbc4
1 parent 2a1b3f5
commit 0b4dbc4
Show file tree

Hide file tree

Showing 12 changed files with 293 additions and 312 deletions.
diff --git a/applications/machine_learning/README.rst b/applications/machine_learning/README.rst
@@ -180,37 +180,6 @@ Check the sample Requirements section for the list of supported development kits
 The sample is used to receive data over NUS and forward it to the host computer over UART.
 See `Testing with Thingy:53`_ for how to test this solution.
 
-.. _nrf_machine_learning_app_requirements_build_types:
-
-nRF Machine Learning build types
-================================
-
-The nRF Machine Learning application does not use a single :file:`prj.conf` file.
-Configuration files are provided for different build types for each supported board.
-
-Each board has its own :file:`prj.conf` file, which represents a ``debug`` build type.
-Other build types are covered by dedicated files with the build type added as a suffix to the ``prj`` part, as per the following list.
-For example, the ``release`` build type file name is :file:`prj_release.conf`.
-If a board has other configuration files, for example associated with partition layout or child image configuration, these follow the same pattern.
-
-.. include:: /config_and_build/modifying.rst
-   :start-after: build_types_overview_start
-   :end-before: build_types_overview_end
-
-Before you start testing the application, you can select one of the build types supported by nRF Machine Learning application, depending on your development kit and the building method.
-The application supports the following build types:
-
-* ``debug`` -- Debug version of the application - can be used to verify if the application works correctly.
-* ``release`` -- Release version of the application - can be used to achieve better performance and reduce memory consumption.
-
-Not every board supports both mentioned build types.
-The given board can also support some additional configurations of the nRF Machine Learning application.
-For example, the nRF52840 Development Kit supports ``nus`` configuration that uses :ref:`nus_service_readme` instead of :ref:`zephyr:uart_api` for data forwarding.
-
-.. note::
-    `Selecting a build type`_ is optional.
-    The ``debug`` build type is used by default if no build type is explicitly selected.
-
 User interface
 **************
 
@@ -318,8 +287,7 @@ The following configuration files can be defined for any supported board:
 
 * :file:`prj_build_type.conf` - Kconfig configuration file for a build type.
   To support a given build type for the selected board, you must define the configuration file with a proper name.
-  For example, the :file:`prj_release.conf` defines configuration for ``release`` build type.
-  The :file:`prj.conf` without any suffix defines the ``debug`` build type.
+  See :ref:`nrf_machine_learning_app_configuration_build_types` for more information.
 * :file:`app.overlay` - DTS overlay file specific for the board.
   Defining the DTS overlay file for a given board is optional.
 * :file:`_def` files - These files are defined separately for modules used by the application.
@@ -347,8 +315,46 @@ The Kconfig configuration file should be located in subdirectory :file:`child_im
 For example, the :file:`applications/machine_learning/configuration/thingy53_nrf5340_cpuapp/child_image/hci_rpmsg/prj.conf` file defines configuration of Bluetooth HCI RPMsg for ``debug`` build type on ``thingy53_nrf5340_cpuapp`` board, while the :file:`applications/machine_learning/configuration/thingy53_nrf5340_cpuapp/child_image/hci_rpmsg/prj_release.conf` file defines configuration of Bluetooth HCI RPMsg for ``release`` build type.
 See :ref:`ug_multi_image` for detailed information about multi-image builds and child image configuration.
 
+.. _nrf_machine_learning_app_requirements_build_types:
 .. _nrf_machine_learning_app_configuration_build_types:
 
+nRF Machine Learning build types
+================================
+
+The nRF Machine Learning application does not use a single :file:`prj.conf` file.
+Before you start testing the application, you can select one of the build types supported by the application, depending on your development kit and the building method.
+Not every board supports both mentioned build types.
+
+See :ref:`app_build_additions_build_types` and :ref:`modifying_build_types` for more information about this feature of the |NCS|.
+
+The application supports the following build types:
+
+.. list-table:: nRF Machine Learning build types
+   :widths: auto
+   :header-rows: 1
+
+   * - Build type
+     - File name
+     - Supported board
+     - Description
+   * - Debug
+     - :file:`prj.conf`
+     - All from `Requirements`_
+     - | Debug version of the application; can be used to verify if the application works correctly.
+       | Used by default if no build type is explicitly selected.
+   * - Release
+     - :file:`prj_release.conf`
+     - ``nrf52840dk_nrf52840``
+     - Release version of the application; can be used to achieve better performance and reduce memory consumption.
+   * - NUS
+     - :file:`prj_nus.conf`
+     - ``nrf52840dk_nrf52840``
+     - Debug version of the application that uses :ref:`nus_service_readme` instead of :ref:`zephyr:uart_api` for data forwarding.
+   * - RTT
+     - :file:`prj_rtt.conf`
+     - ``thingy53_nrf5340_cpuapp`` and ``thingy53_nrf5340_cpuapp_ns``
+     - Debug version of the application that uses RTT for printing logs instead of USB CDC.
+
 Building and running
 ********************
 
@@ -363,28 +369,7 @@ Selecting a build type
 ======================
 
 Before you start testing the application, you can select one of the :ref:`nrf_machine_learning_app_requirements_build_types`, depending on your development kit and building method.
-
-Selecting a build type in |VSC|
--------------------------------
-
-.. include:: /config_and_build/modifying.rst
-   :start-after: build_types_selection_vsc_start
-   :end-before: build_types_selection_vsc_end
-
-Selecting a build type from command line
-----------------------------------------
-
-.. include:: /config_and_build/modifying.rst
-   :start-after: build_types_selection_cmd_start
-   :end-before: build_types_selection_cmd_end
-
-.. note::
-   If the selected board does not support the selected build type, the build is interrupted.
-   For example, if the ``nus`` build type is not supported by the selected board, the following notification appears:
-
-   .. code-block:: console
-
-      Configuration file for build type ``nus`` is missing.
+See :ref:`modifying_build_types` for detailed steps how to select a build type.
 
 Providing API key
 =================

diff --git a/applications/matter_bridge/doc/matter_bridge_description.rst b/applications/matter_bridge/doc/matter_bridge_description.rst
@@ -131,35 +131,6 @@ If the Bluetooth LE advertising times out, you can re-enable it manually by pres
 Additionally, the controller must get the `Onboarding information`_ from the Matter accessory device and provision the device into the network.
 For details, see the `Testing`_ section.
 
-.. _matter_bridge_app_build_types:
-
-Matter bridge build types
-=========================
-
-The bridge application uses different configuration files depending on the supported features.
-Configuration files are provided for different build types and they are located in the application root directory.
-
-The :file:`prj.conf` file represents a ``debug`` build type.
-Other build types are covered by dedicated files with the build type added as a suffix to the ``prj`` part, as per the following list.
-For example, the ``release`` build type file name is :file:`prj_release.conf`.
-If a board has other configuration files, for example associated with partition layout or child image configuration, these follow the same pattern.
-
-.. include:: /config_and_build/modifying.rst
-   :start-after: build_types_overview_start
-   :end-before: build_types_overview_end
-
-Before you start testing the application, you can select one of the build types supported by the sample.
-This sample supports the following build types:
-
-* ``debug`` -- Debug version of the application.
-  You can use this version to enable additional features for verifying the application behavior, such as logs.
-* ``release`` -- Release version of the application.
-  You can use this version to enable only the necessary application functionalities to optimize its performance.
-
-.. note::
-    `Selecting a build type`_ is optional.
-    The ``debug`` build type is used by default if no build type is explicitly selected.
-
 User interface
 **************
 
@@ -382,48 +353,49 @@ Build the target using the following command in the project directory to enable
 
 Replace *absolute_path* with the absolute path to the Matter bridge application on your local disk.
 
-Building and running
-********************
-
-.. |sample path| replace:: :file:`applications/matter_bridge`
-
-.. include:: /includes/build_and_run.txt
-
-Selecting a build type
-======================
-
-Before you start testing the application, you can select one of the :ref:`matter_bridge_app_build_types`, depending on your building method.
+.. _matter_bridge_app_build_types:
 
-Selecting a build type in |VSC|
--------------------------------
+Matter bridge build types
+=========================
 
-.. include:: /config_and_build/modifying.rst
-   :start-after: build_types_selection_vsc_start
-   :end-before: build_types_selection_vsc_end
+The Matter bridge application does not use a single :file:`prj.conf` file.
+Before you start testing the application, you can select one of the build types supported by the application, depending on your development kit and the building method.
+Not every board supports both mentioned build types.
 
-Selecting a build type from command line
-----------------------------------------
+See :ref:`app_build_additions_build_types` and :ref:`modifying_build_types` for more information about this feature of the |NCS|.
 
-.. include:: /config_and_build/modifying.rst
-   :start-after: build_types_selection_cmd_start
-   :end-before: For example, you can replace the
+The application supports the following build types:
 
-For example, you can replace the *selected_build_type* variable to build the ``release`` firmware for ``nrf7002dk_nrf5340_cpuapp`` by running the following command in the project directory:
+.. list-table:: Matter bridge build types
+   :widths: auto
+   :header-rows: 1
 
-.. parsed-literal::
-   :class: highlight
+   * - Build type
+     - File name
+     - Supported board
+     - Description
+   * - Debug
+     - :file:`prj.conf`
+     - All from `Requirements`_
+     - | Debug version of the application; can be used to enable additional features for verifying the application behavior, such as logs.
+       | Used by default if no build type is explicitly selected.
+   * - Release
+     - :file:`prj_release.conf`
+     - All from `Requirements`_
+     - Release version of the application; can be used to enable only the necessary application functionalities to optimize its performance.
 
-   west build -b nrf7002dk_nrf5340_cpuapp -d build_nrf7002dk_nrf5340_cpuapp -- -DCONF_FILE=prj_release.conf
+Building and running
+********************
 
-The ``build_nrf7002dk_nrf5340_cpuapp`` parameter specifies the output directory for the build files.
+.. |sample path| replace:: :file:`applications/matter_bridge`
 
-.. note::
-   If the selected board does not support the selected build type, the build is interrupted.
-   For example, if the ``shell`` build type is not supported by the selected board, the following notification appears:
+.. include:: /includes/build_and_run.txt
 
-   .. code-block:: console
+Selecting a build type
+======================
 
-      File not found: ./ncs/nrf/applications/matter_bridge/configuration/nrf7002dk_nrf5340_cpuapp/prj_shell.conf
+Before you start testing the application, you can select one of the :ref:`matter_bridge_app_build_types`, depending on your building method.
+See :ref:`modifying_build_types` for detailed steps how to select a build type.
 
 .. _matter_bridge_testing:
 

diff --git a/applications/matter_weather_station/README.rst b/applications/matter_weather_station/README.rst
@@ -127,37 +127,41 @@ Matter weather station build types
 ==================================
 
 The Matter weather station application does not use a single :file:`prj.conf` file.
-Configuration files are provided for different build types and they are located in the :file:`configuration/thingy53_nrf5340_cpuapp` directory.
-
-The :file:`prj.conf` file represents a ``debug`` build type.
-Other build types are covered by dedicated files with the build type added as a suffix to the ``prj`` part, as per the following list.
-For example, the ``release`` build type file name is :file:`prj_release.conf`.
-If a board has other configuration files, for example associated with partition layout or child image configuration, these follow the same pattern.
-
-.. include:: /config_and_build/modifying.rst
-   :start-after: build_types_overview_start
-   :end-before: build_types_overview_end
-
-Before you start testing the application, you can select one of the build types supported by Matter weather station application, depending on the building method.
-This application supports the following build types:
-
-* ``debug`` - Debug version of the application.
-  You can use this version to enable additional features for verifying the application behavior, such as logs or command-line shell.
-* ``release`` - Release version of the application.
-  You can use this version to enable only the necessary application functionalities to optimize its performance.
-
-.. note::
-    Currently, this application supports only the ``release`` build type when `Building for the nRF7002 Wi-Fi expansion board`_.
-
-.. note::
-    `Selecting a build type`_ is optional.
-    The ``debug`` build type is used by default if no build type is explicitly selected.
+Configuration files are provided for different build types, and they are located in the :file:`configuration/thingy53_nrf5340_cpuapp` directory.
+Before you start testing the application, you can select one of the build types supported by the application, depending on the building method.
+
+See :ref:`app_build_additions_build_types` and :ref:`modifying_build_types` for more information about this feature of the |NCS|.
+
+The application supports the following build types:
+
+.. list-table:: Matter weather station build types
+   :widths: auto
+   :header-rows: 1
+
+   * - Build type
+     - File name
+     - Supported board
+     - Description
+   * - Debug
+     - :file:`prj.conf`
+     - All from `Requirements`_
+     - | Debug version of the application; can be used to enable additional features for verifying the application behavior, such as logs or command-line shell.
+       | Used by default if no build type is explicitly selected.
+   * - Release
+     - :file:`prj_release.conf`
+     - All from `Requirements`_
+     - | Release version of the application; can be used to enable only the necessary application functionalities to optimize its performance.
+       |
+       | .. note::
+       |     Currently, this application supports only the ``release`` build type when `Building for the nRF7002 Wi-Fi expansion board`_.
 
 .. _matter_weather_station_app_build_configuration_overlays:
 
 Matter weather station build configuration overlays
 ===================================================
 
+The application comes with the following overlays:
+
 * ``overlay-factory_data`` - factory data storage support enabled.
   You can use this optional configuration overlay to enable reading necessary factory data from a separate partition in the device non-volatile memory.
   This way, you can read information such as product information, keys, and certificates, useful for example for Matter certification.
@@ -179,37 +183,7 @@ Selecting a build type
 ======================
 
 Before you start testing the application, you can select one of the :ref:`matter_weather_station_app_build_types`, depending on your building method.
-
-Selecting a build type in |VSC|
--------------------------------
-
-.. include:: /config_and_build/modifying.rst
-   :start-after: build_types_selection_vsc_start
-   :end-before: build_types_selection_vsc_end
-
-Selecting a build type from command line
-----------------------------------------
-
-.. include:: /config_and_build/modifying.rst
-   :start-after: build_types_selection_cmd_start
-   :end-before: For example, you can replace the
-
-For example, you can replace the *selected_build_type* variable to build the ``release`` firmware for ``thingy53_nrf5340_cpuapp`` by running the following command in the project directory:
-
-.. parsed-literal::
-   :class: highlight
-
-   west build -b thingy53_nrf5340_cpuapp -d build_thingy53_nrf5340_cpuapp -- -DCONF_FILE=prj_release.conf
-
-The ``build_thingy53_nrf5340_cpuapp`` parameter specifies the output directory for the build files.
-
-.. note::
-   If the selected board does not support the selected build type, the build is interrupted.
-   For example, if the ``shell`` build type is not supported by the selected board, the following notification appears:
-
-   .. code-block:: console
-
-      File not found: ./ncs/nrf/applications/matter_weather_station/configuration/thingy53_nrf5340_cpuapp/prj_shell.conf
+See :ref:`modifying_build_types` for detailed steps how to select a build type.
 
 Building for the nRF7002 Wi-Fi expansion board
 ==============================================