doc: config_and_build: regroup and rework pages

Moved sections about CMake and Kconfig from modifying.rst
to separate pages and removed modifying.rst.
Split Building and programming into two separate sections.
Grouped guides for configuring under Configuring and building the app.
NCSDK-22324 and NCSDK-21617.

Signed-off-by: Grzegorz Ferenc <[email protected]>

Author: greg-fer

applications/asset_tracker_v2/doc/asset_tracker_v2_description.rst

@@ -167,7 +167,7 @@ Building and running
 ********************
 
 This application can be found under :file:`applications/asset_tracker_v2` in the |NCS| folder structure.
-See :ref:`programming` for information about how to build and program the application.
+See :ref:`building` for information about how to build the application and :ref:`programming` for information about how to program it.
 
 Testing
 =======

applications/nrf5340_audio/broadcast_sink/README.rst

@@ -63,7 +63,7 @@ Configuration
 
 See :ref:`nrf53_audio_app_configuration` and :ref:`nrf53_audio_app_fota` for configuration options common to all nRF5340 Audio applications.
 
-For information about how to configure applications in the |NCS|, see :ref:`modifying`.
+For information about how to configure applications in the |NCS|, see :ref:`configure_application`.
 
 .. _nrf53_audio_broadcast_sink_app_building:
 

applications/nrf5340_audio/broadcast_source/README.rst

@@ -51,7 +51,7 @@ Configuration
 
 See :ref:`nrf53_audio_app_configuration` and :ref:`nrf53_audio_app_fota` for configuration options common to all nRF5340 Audio applications.
 
-For information about how to configure applications in the |NCS|, see :ref:`modifying`.
+For information about how to configure applications in the |NCS|, see :ref:`configure_application`.
 
 .. _nrf53_audio_broadcast_source_app_building:
 

applications/nrf5340_audio/unicast_client/README.rst

@@ -58,7 +58,7 @@ Configuration
 
 See :ref:`nrf53_audio_app_configuration` and :ref:`nrf53_audio_app_fota` for configuration options common to all nRF5340 Audio applications.
 
-For information about how to configure applications in the |NCS|, see :ref:`modifying`.
+For information about how to configure applications in the |NCS|, see :ref:`configure_application`.
 
 .. _nrf53_audio_unicast_client_app_building:
 

applications/nrf5340_audio/unicast_server/README.rst

@@ -63,7 +63,7 @@ Configuration
 
 See :ref:`nrf53_audio_app_configuration` and :ref:`nrf53_audio_app_fota` for configuration options common to all nRF5340 Audio applications.
 
-For information about how to configure applications in the |NCS|, see :ref:`modifying`.
+For information about how to configure applications in the |NCS|, see :ref:`configure_application`.
 
 .. _nrf53_audio_unicast_server_app_building:
 

doc/_utils/redirects.py

@@ -21,6 +21,7 @@
     ("app_boards", "config_and_build/board_support"),
     ("app_dev/board_support/index", "config_and_build/board_support"),
     ("config_and_build/board_support", "config_and_build/board_support/index"),
+    ("config_and_build/output_build_files", "config_and_build/configuring_app/output_build_files"),
     ("config_and_build/pin_control", "config_and_build/configure_app/hardware/pin_control"),
     ("config_and_build/use_gpio_pin_directly", "config_and_build/configure_app/hardware/use_gpio_pin_directly"),
     ("ug_bootloader", "config_and_build/bootloaders_and_dfu/bootloader"),
@@ -98,6 +99,7 @@
     ("installation/installing", "installation/install_ncs"),
     ("gs_modifying", "config_and_build/modifying"),
     ("getting_started/modifying", "config_and_build/modifying"),
+    ("config_and_build/modifying", "config_and_build/configuring_app/index"),
     ("gs_programming", "config_and_build/programming"),
     ("getting_started/programming", "config_and_build/programming"),
     ("gs_recommended_versions", "installation/recommended_versions"),

doc/nrf/config_and_build.rst

@@ -4,24 +4,27 @@
 Configuration and building
 ##########################
 
-The |NCS| build and configuration system is based on the one from :ref:`Zephyr project <zephyr:getting_started>`, with some additions.
+After you have :ref:`created an application <create_application>`, you need to configure and build it in order to be able to run it.
 
-The figure below visualizes the tools and configuration methods in the |NCS|.
+The |NCS| configuration and build system is based on the one from :ref:`Zephyr <zephyr:getting_started>`, with some additions.
+
+The following figure lists the main tools and configuration methods in the |NCS|.
 All of them have a role in the creation of an application, from configuring the libraries or applications to building them.
 
 .. figure:: images/ncs-toolchain.svg
    :alt: nRF Connect SDK tools and configuration
 
    |NCS| tools and configuration methods
 
-* CMake generates build files based on the provided :file:`CMakeLists.txt` files, which use information from Kconfig and devicetree.
-  See the `CMake documentation`_.
-* :ref:`Devicetree <zephyr:dt-guide>` describes the hardware.
-* :ref:`zephyr:kconfig` generates definitions that configure the software.
-* Ninja (comparable to Make) uses the build files to build the program, see the `Ninja documentation`_.
-* The compiler (for example, `GCC compiler`_) creates the executables.
+* Devicetree describes the hardware.
+* Kconfig generates definitions that configure the software.
+* Partition Manager describes the memory layout.
+* CMake generates build files based on the provided :file:`CMakeLists.txt` files, which use information from devicetree files, Kconfig, and Partition Manager.
+* Ninja (comparable to Make) uses the build files to build the program.
+* The compiler (for example, GCC) creates the executables.
+
+For a more detailed overview, see :ref:`app_build_system`.
 
-Read the guides in this section to learn how to use these tools and configuration methods in areas valid for :ref:`all supported boards <app_boards>`.
 Depending on the board you are working with, check also its :ref:`hardware guide <device_guides>`, as some nRF Series families have specific exceptions and rules to be applied on top of the general configuration procedures.
 
 Make sure to consider :ref:`app_bootloaders` and :ref:`app_dfu` already at this stage of the application development.
@@ -32,10 +35,8 @@ Make sure to consider :ref:`app_bootloaders` and :ref:`app_dfu` already at this
 
    config_and_build/config_and_build_system
    config_and_build/board_support/index
-   config_and_build/configuring_app/hardware/index
+   config_and_build/configuring_app/index
    config_and_build/programming
-   config_and_build/output_build_files
-   config_and_build/modifying
    config_and_build/multi_image
    config_and_build/bootloaders/index
    config_and_build/dfu/index

doc/nrf/config_and_build/config_and_build_system.rst

@@ -38,7 +38,8 @@ The build and configuration system in Zephyr and the |NCS| uses the following bu
      - :file:`Kconfig`, :file:`prj.conf`, :file:`.config`
      - Software configuration system also used in the Linux kernel.
      - `Kconfig GUI <Configuring with nRF Kconfig_>`_, :ref:`menuconfig and guiconfig <zephyr:menuconfig>`
-     - Kconfig GUI is part of the |nRFVSC|.
+     - | Kconfig GUI is part of the |nRFVSC|.
+       | The :ref:`Kconfig Reference <configuration_options>` provides the documentation for each configuration option.
    * - :ref:`partition_manager`
      - :file:`pm.yml`, :file:`pm_static.yml`
      - Memory layout configuration system.
@@ -49,11 +50,16 @@ Each of these systems comes with a specialized syntax and purpose.
 See the following sections for more information.
 To read more about Zephyr's configuration system and its role in the application development, see :ref:`zephyr:build_overview` and :ref:`zephyr:application` in the Zephyr documentation.
 
-When you :ref:`create_application`, the configuration files for each of these systems are created in the :ref:`application directory <create_application_structure>`: :file:`CMakeLists.txt` for CMake, :file:`app.overlay` for Devicetree, :file:`prj.conf` for Kconfig, and :file:`partitions.yml` for Partition Manager (if enabled).
-You can then edit them according to your needs (see :ref:`modifying`).
+When you :ref:`create_application`, the configuration files for each of these systems are created in the :ref:`application directory <create_application_structure>`: :file:`CMakeLists.txt` for CMake, :file:`app.overlay` for devicetree, :file:`prj.conf` for Kconfig, and :file:`partitions.yml` for Partition Manager (if enabled).
+You can then edit them according to your needs (see :ref:`building`).
 
 When you start building, a CMake build is executed in two stages: configuration phase and building phase.
 
+.. figure:: ../images/ncs-toolchain.svg
+   :alt: nRF Connect SDK tools and configuration
+
+   |NCS| tools and configuration methods
+
 .. _configuration_system_overview_config:
 
 Configuration phase
@@ -114,6 +120,7 @@ The :file:`.config` file in the :file:`<build_dir>/zephyr/` directory describes
 Some subsystems can use their own configuration files.
 
 For more information, see :ref:`configure_application` and Zephyr's :ref:`zephyr:application-kconfig`.
+The :ref:`Kconfig Reference <configuration_options>` provides the documentation for each configuration option in the |NCS|.
 
 Memory layout configuration
 ---------------------------
@@ -149,8 +156,9 @@ Building phase
 ==============
 
 During this phase, the final build scripts are executed.
-The build phase begins when the user invokes ``make`` or ``ninja``.
-You can customize this stage by :ref:`cmake_options`.
+The build phase begins when the user invokes ``make`` or `ninja <Ninja documentation_>`_.
+The compiler (for example, `GCC compiler`_) then creates object files used to create the final executables.
+You can customize this stage by :ref:`cmake_options` and using :ref:`compiler_settings`.
 
 The result of this process is a complete application in a format suitable for flashing on the desired target board.
 See :ref:`output build files <app_build_output_files>` for details.

doc/nrf/config_and_build/configuring_app/advanced_building.rst

@@ -0,0 +1,107 @@
+.. _building_advanced:
+
+Advanced building procedures
+############################
+
+.. contents::
+   :local:
+   :depth: 2
+
+You can customize the basic :ref:`building <building>` procedures in a variety of ways, depending on the configuration of your project.
+
+.. _compiler_settings:
+
+Advanced compiler settings
+**************************
+
+The application has full control over the build process.
+
+Using Zephyr's configuration options is the standard way of controlling how the system is built.
+These options can be found under Zephyr's menuconfig **Build and Link Features** > **Compiler Options**.
+For example, to turn off optimizations, select :kconfig:option:`CONFIG_NO_OPTIMIZATIONS`.
+
+Compiler options not controlled by the Zephyr build system can be controlled through the :kconfig:option:`CONFIG_COMPILER_OPT` Kconfig option.
+
+.. _gs_modifying_build_types:
+.. _modifying_build_types:
+
+Configuring build types
+***********************
+
+When the ``CONF_FILE`` variable contains a single file and this file name follows the naming pattern :file:`prj_<buildtype>.conf`, then the build type will be inferred to be *<buildtype>*.
+The build type cannot be set explicitly.
+The *<buildtype>* can be any string, but it is common to use ``release`` and ``debug``.
+
+For information about how to set variables, see :ref:`zephyr:important-build-vars` in the Zephyr documentation.
+
+The following software components can be made dependent on the build type:
+
+* The Partition Manager's :ref:`static configuration <ug_pm_static>`.
+  When the build type has been inferred, the file :file:`pm_static_<buildtype>.yml` will have precedence over :file:`pm_static.yml`.
+* The :ref:`child image Kconfig configuration <ug_multi_image_permanent_changes>`.
+  Certain child image configuration files located in the :file:`child_image/` directory can be defined per build type.
+
+The devicetree configuration is not affected by the build type.
+
+.. note::
+    For an example of an application that uses build types, see the :ref:`nrf_desktop` application (:ref:`nrf_desktop_requirements_build_types`) or the :ref:`nrf_machine_learning_app` application (:ref:`nrf_machine_learning_app_requirements_build_types`).
+
+.. tabs::
+
+   .. group-tab:: nRF Connect for VS Code
+
+      To select the build type in the |nRFVSC|:
+
+      1. When `building an application <How to build an application_>`_ as described in the |nRFVSC| documentation, follow the steps for setting up the build configuration.
+      #. In the **Add Build Configuration** screen, select the desired :file:`.conf` file from the :guilabel:`Configuration` drop-down menu.
+      #. Fill in other configuration options, if applicable, and click :guilabel:`Build Configuration`.
+
+   .. group-tab:: Command line
+
+      To select the build type when building the application from command line, specify the build type by adding the following parameter to the ``west build`` command:
+
+      .. parsed-literal::
+         :class: highlight
+
+         -- -DCONF_FILE=prj_\ *selected_build_type*\.conf
+
+      For example, you can replace the *selected_build_type* variable to build the ``release`` firmware for ``nrf52840dk_nrf52840`` by running the following command in the project directory:
+
+      .. parsed-literal::
+         :class: highlight
+
+         west build -b nrf52840dk_nrf52840 -d build_nrf52840dk_nrf52840 -- -DCONF_FILE=prj_release.conf
+
+      The ``build_nrf52840dk_nrf52840`` parameter specifies the output directory for the build files.
+
+If the selected board does not support the selected build type, the build is interrupted.
+For example, for the :ref:`nrf_machine_learning_app` application, 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.
+
+Optional build parameters
+*************************
+
+Here are some of the possible options you can use:
+
+* Some applications contain configuration overlay files that enable specific features.
+  These can be added to the ``west build`` command as follows:
+
+  .. parsed-literal::
+     :class: highlight
+
+     west build -b *build_target* -- -DOVERLAY_CONFIG="overlay-feature1.conf;overlay-feature2.conf"
+
+  See :ref:`configuration_permanent_change` and Zephyr's :ref:`zephyr:west-building-cmake-args` for more information.
+* You can include the *directory_name* parameter to build from a directory other than the current directory.
+* You can use the *build_target@board_revision* parameter to get extra devicetree overlays with new features available for a board version.
+  The *board_revision* is printed on the label of your DK, just below the PCA number.
+  For example, if you run the west build command with an additional parameter ``@1.0.0`` for nRF9160 build target, it adds the external flash on the nRF9160 DK that was available since :ref:`board version v0.14.0 <nrf9160_board_revisions>`.
+* You can :ref:`start menuconfig with the west command <configuration_temporary_change>` to configure your application.
+* You can :ref:`reuse an existing build directory <zephyr:west-building-pristine>` for building another application for another board or build target by passing ``-p=auto`` to ``west build``.
+
+For more information on other optional build parameters, run the ``west build -h`` help text command.
+
+.. |output_files_note| replace:: For more information about files generated as output of the build process, see :ref:`app_build_output_files`.

doc/nrf/config_and_build/configuring_app/cmake/index.rst

@@ -0,0 +1,67 @@
+.. _configuring_cmake:
+
+Adding files and configuring CMake
+##################################
+
+.. contents::
+   :local:
+   :depth: 2
+
+As described in more detail in :ref:`app_build_system`, the Zephyr and |NCS| build systems are based on `CMake <CMake documentation_>`_.
+For this reason, every application in Zephyr and the |NCS| must have a :file:`CMakeLists.txt` file.
+This file is the entry point of the build system as it specifies the application source files for the compiler to include in the :ref:`configuration phase <app_build_system>`.
+
+Maintaining CMakeLists.txt
+**************************
+
+The recommended method to maintain and update the :file:`CMakeLists.txt` file is to use the |nRFVSC|.
+The extension provides support for the `source control with west`_ and `CMake build system`_, including `build configuration management <How to work with build configurations_>`_ and `source and config files overview <Details View_>`_.
+
+.. _modifying_files_compiler:
+
+Adding source files to CMakeLists.txt
+*************************************
+
+You can add source files to the ``app`` CMake target with the :c:func:`target_sources` function provided by CMake.
+
+Pay attention to the following configuration options:
+
+* If your application is complex, you can split it into subdirectories.
+  These subdirectories can provide their own :file:`CMakeLists.txt` files.
+  (The main :file:`CMakeLists.txt` file needs to include those.)
+* The build system searches for header files in include directories.
+  Add additional include directories for your application with the :c:func:`target_include_directories` function provided by CMake.
+  For example, if you want to include an :file:`inc` directory, the code would look like the following:
+
+  .. code-block:: c
+
+     target_include_directories(app PRIVATE inc)
+
+See :ref:`zephyr:zephyr-app-cmakelists` in the Zephyr documentation for more information about how to edit :file:`CMakeLists.txt`.
+
+.. note::
+    You can also read the `CMake Tutorial`_ in the CMake documentation for a better understanding of how :file:`CMakeLists.txt` are used in a CMake project.
+    This tutorial however differs from Zephyr and |NCS| project configurations, so use it only as reference.
+
+.. _cmake_options:
+
+Providing CMake options
+***********************
+
+You can provide additional options for building your application to the CMake process, which can be useful, for example, to switch between different build scenarios.
+These options are specified when CMake is run, thus not during the actual build, but when configuring the build.
+
+For information about what variables can be set and how to add these variables in your project, see :ref:`zephyr:important-build-vars` in the Zephyr documentation.
+
+.. tabs::
+
+   .. group-tab:: nRF Connect for VS Code
+
+      If you work with the |nRFVSC|, you can specify project-specific CMake options when you add the :term:`build configuration` for a new |NCS| project.
+      See `How to build an application`_ in the |nRFVSC| documentation.
+
+   .. group-tab:: Command line
+
+      If you work on the command line, pass the additional options to the ``west build`` command when :ref:`building`.
+      The options must be added after a ``--`` at the end of the command.
+      See :ref:`zephyr:west-building-cmake-args` for more information.

doc/nrf/config_and_build/configuring_app/hardware/index.rst

@@ -11,7 +11,7 @@ Follow the steps in `How to create devicetree files`_ and use one of the followi
 * `Devicetree language support`_
 
 The following guides provide information about configuring specific aspects of hardware support related to devicetree.
-Read them together with Zephyr's :ref:`zephyr:hardware_support` and :ref:`zephyr:dt-guide` guides.
+Read them together with Zephyr's :ref:`zephyr:hardware_support` and :ref:`zephyr:dt-guide` guides, and the official `Devicetree Specification`_.
 
 .. toctree::
    :maxdepth: 1