From a502619ca551658d19bb8126c704ce775ae4c2e6 Mon Sep 17 00:00:00 2001 From: Grzegorz Ferenc Date: Mon, 27 Nov 2023 17:46:19 +0100 Subject: [PATCH] doc: config_and_build: gather concepts on one page Edited the overview page to gather conceptual information on one page. This removes some duplication and allows to expand procedures with more content in a future PR. Added the term entry for build configuration to the glossary. NCSDK-22324. Signed-off-by: Grzegorz Ferenc --- .../config_and_build_system.rst | 173 +++++++++++++++--- doc/nrf/config_and_build/modifying.rst | 122 +----------- doc/nrf/config_and_build/multi_image.rst | 2 +- .../working_with_nrf/nrf53/nrf5340.rst | 2 +- .../working_with_nrf/nrf91/nrf9160.rst | 2 +- doc/nrf/documentation/glossary.rst | 7 + doc/nrf/installation/recommended_versions.rst | 6 + .../getting_started/transmission_power.rst | 2 +- .../releases/release-notes-changelog.rst | 6 +- 9 files changed, 175 insertions(+), 147 deletions(-) diff --git a/doc/nrf/config_and_build/config_and_build_system.rst b/doc/nrf/config_and_build/config_and_build_system.rst index 48b80b726b14..f9c7ae91ce01 100644 --- a/doc/nrf/config_and_build/config_and_build_system.rst +++ b/doc/nrf/config_and_build/config_and_build_system.rst @@ -9,28 +9,160 @@ Build and configuration system The |NCS| build and configuration system is based on the one from Zephyr, with some additions. -Zephyr's build and configuration system -*************************************** +.. _configuration_system_overview: -Zephyr's build and configuration system uses the following building blocks as a foundation: +Overview of build and configuration system +****************************************** -* CMake, the cross-platform build system generator. -* Kconfig, a powerful configuration system also used in the Linux kernel. -* Devicetree, a hardware description language that is used to describe the hardware that the |NCS| is meant to run on. +The build and configuration system in Zephyr and the |NCS| uses the following building blocks as a foundation: -Since the build and configuration system used by the |NCS| comes from Zephyr, references to the original Zephyr documentation are provided here in order to avoid duplication. -See the following links for information about the different building blocks mentioned above: +.. list-table:: Configuration system overview + :header-rows: 1 -* :ref:`zephyr:application` is a complete guide to application development with Zephyr, including the build and configuration system. -* :ref:`zephyr:cmake-details` describes in-depth the usage of CMake for Zephyr-based applications. -* :ref:`zephyr:application-kconfig` contains a guide for Kconfig usage in applications. -* :ref:`zephyr:set-devicetree-overlays` explains how to use devicetree and its overlays to customize an application's devicetree. -* :ref:`board_porting_guide` is a complete guide to porting Zephyr to your own board. + * - Source + - File types + - Usage + - Available dedicated editing tools + - Additional information + * - :ref:`CMake ` + - :file:`CMakeLists.txt`, :file:`.cmake` + - Build system generator. + - n/a + - CMake is used to build your application together with the Zephyr kernel. + * - :ref:`Devicetree ` + - :file:`.dts`, :file:`.dtsi`, :file:`.overlay` + - Hardware description language. + - `Devicetree Visual Editor `_ + - Devicetree Visual Editor is part of the |nRFVSC|. You still need to be familiar with the devicetree language to use it. + * - :ref:`Kconfig ` + - :file:`Kconfig`, :file:`prj.conf`, :file:`.config` + - Software configuration system also used in the Linux kernel. + - `Kconfig GUI `_, :ref:`menuconfig and guiconfig ` + - Kconfig GUI is part of the |nRFVSC|. + * - :ref:`partition_manager` + - :file:`pm.yml`, :file:`pm_static.yml` + - Memory layout configuration system. + - :ref:`partition_manager` script + - Partition Manager is an |NCS| configuration system that is not available in Zephyr. + +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 `: :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 start building, a CMake build is executed in two stages: configuration phase and building phase. + +.. _configuration_system_overview_config: + +Configuration phase +=================== + +During this phase, CMake executes build scripts from :file:`CMakeLists.txt` and gathers configuration from different sources to generate the final build scripts and create a model of the build for the specified build target. +The result of this process is a :term:`build configuration`, a set of files that will drive the build process. + +For more information about this phase, see the respective sections on Zephyr's :ref:`zephyr:cmake-details` page, which describes in-depth the usage of CMake for Zephyr-based applications. + +Role of CMakeLists.txt +---------------------- + +In Zephyr and the |NCS|, the application is a CMake project. +As such, the application controls the configuration and build process of itself, Zephyr, and sourced libraries. +The application's :file:`CMakeLists.txt` file is the main CMake project file and the source of the build process configuration. + +Zephyr provides a CMake package that must be loaded by the application into its :file:`CMakeLists.txt` file. +When loaded, the application can reference items provided by both Zephyr and the |NCS|. + +Loading Zephyr's `CMake `_ package creates the ``app`` CMake target. +You can add application source files to this target from the application :file:`CMakeLists.txt` file. +See :ref:`modifying_files_compiler` for detailed information. + +.. _configure_application_hw: + +Hardware-related configuration +------------------------------ + +.. ncs-include:: build/cmake/index.rst + :docset: zephyr + :dedent: 3 + :start-after: Devicetree + :end-before: The preprocessed devicetree sources + +The preprocessed devicetree sources are parsed by the :file:`zephyr/scripts/dts/gen_defines.py` script to generate a :file:`devicetree_unfixed.h` header file with preprocessor macros. + +The :file:`zephyr.dts` file contains the entire hardware-related configuration of the system in the devicetree format. +The header file contains the same kind of information, but with defines usable by source code. + +For more information, see :ref:`configure_application` and Zephyr's :ref:`zephyr:dt-guide`. +In particular, :ref:`zephyr:set-devicetree-overlays` explains how to use devicetree and its overlays to customize an application's devicetree. + +.. _configure_application_sw: + +Software-related configuration +------------------------------ + +.. ncs-include:: build/cmake/index.rst + :docset: zephyr + :dedent: 3 + :start-after: Kconfig + :end-before: Information from devicetree is available to Kconfig, + +Information from devicetree is available to Kconfig, through the functions defined in :file:`zephyr/scripts/kconfig/kconfigfunctions.py`. + +The :file:`.config` file in the :file:`/zephyr/` directory describes most of the software configuration of the constructed binary. +Some subsystems can use their own configuration files. + +For more information, see :ref:`configure_application` and Zephyr's :ref:`zephyr:application-kconfig`. + +Memory layout configuration +--------------------------- + +The Partition Manager is specific to the |NCS|. +If enabled, it provides the memory layout configuration. +The layout is impacted by various elements, such as Kconfig configuration options or the presence of child images. +Partition Manager ensures that all required partitions are in the correct place and have the correct size. + +If enabled, the memory layout can be controlled in the following ways: + +* Dynamically (default) - In this scenario, the layout is impacted by various elements, such as Kconfig configuration options or the presence of child images. + Partition Manager ensures that all required partitions are in the correct place and have the correct size. +* Statically - In this scenario, you need to provide the static configuration. + See :ref:`ug_pm_static` for information about how to do this. + +After CMake has run, a :file:`partitions.yml` file with the memory layout will have been created in the :file:`build` directory. +This process also creates a set of header files that provides defines, which can be used to refer to memory layout elements. + +For more information, see :ref:`partition_manager`. + +Child images +------------ + +The |NCS| build system allows the application project to become a root for the sub-applications known in the |NCS| as child images. +Examples of child images are bootloader images, network core images, or security-related images. +Each child image is a separate application. + +For more information, see :ref:`ug_multi_image`. + +.. _configuration_system_overview_build: + +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 result of this process is a complete application in a format suitable for flashing on the desired target board. +See :ref:`output build files ` for details. + +The build phase can be broken down, conceptually, into four stages: the pre-build, first-pass binary, final binary, and post-processing. +To read about each of these stages, see :ref:`zephyr:cmake-details` in the Zephyr documentation. .. _app_build_additions: -|NCS| additions -*************** +Additions specific to the |NCS| +******************************* The |NCS| adds some functionality on top of the Zephyr build and configuration system. Those additions are automatically included into the Zephyr build system using a :ref:`cmake_build_config_package`. @@ -56,14 +188,3 @@ You must be aware of these additions when you start writing your own application You can find out more about these in the :ref:`ug_multi_image` section. * The |NCS| adds a :ref:`partition_manager`, responsible for partitioning the available flash memory. * The |NCS| build system generates zip files containing binary images and a manifest for use with nRF Cloud FOTA. - -.. _app_build_additions_tools: - -|NCS| configuration tools -========================= - -The |nRFVSC| provides the following configuration tools for the build system components: - -* For CMake, the `build configuration management `_. -* For Devicetree, the `Devicetree Visual Editor `_. -* For Kconfig, the `Kconfig GUI `_. diff --git a/doc/nrf/config_and_build/modifying.rst b/doc/nrf/config_and_build/modifying.rst index 26c3ffba75c4..3c85c00e595b 100644 --- a/doc/nrf/config_and_build/modifying.rst +++ b/doc/nrf/config_and_build/modifying.rst @@ -12,24 +12,14 @@ Modifying an application After programming and testing an application, you probably want to make some modifications to the application, for example, add your own files with additional functionality, change compilation options, or update the default configuration. +.. _modifying_files_compiler: + Adding files and changing compiler settings ******************************************* The |NCS| build system is based on Zephyr, whose build system is based on `CMake `_. -For more information about how the build system works in Zephyr, see :ref:`zephyr:build_overview` and :ref:`zephyr:application` in the Zephyr documentation. - -Role of CMakeLists.txt -====================== - -In the |NCS|, the application is a CMake project. -As such, the application controls the configuration and build process of itself, Zephyr, and sourced libraries. -The application's :file:`CMakeLists.txt` file is the main CMake project file and the source of the build process configuration. - -Zephyr provides a CMake package that must be loaded by the application into its :file:`CMakeLists.txt` file. -When loaded, the application can reference items provided by both Zephyr and the |NCS|. - -Loading Zephyr's `CMake `_ package creates the ``app`` CMake target. -You can add application source files to this target from the application :file:`CMakeLists.txt` file. +For an overview of the build system in the |NCS|, see :ref:`app_build_system`. +For information about how the build system works in Zephyr, see :ref:`zephyr:build_overview` and :ref:`zephyr:application` in the Zephyr documentation. Updating CMakeLists.txt ======================= @@ -72,109 +62,9 @@ Compiler options not controlled by the Zephyr build system can be controlled thr Configuring your application **************************** -You might want to change the default options of the application. +You might want to change the default options of the application for each of its :ref:`configuration systems `. There are different ways of doing this, but not all will store your configuration permanently. -.. _configuration_system_overview: - -Configuration system overview -============================= - -Zephyr and the |NCS| use several configuration systems, each system with a specialized syntax and purpose. - -The following tables summarizes information about the configuration sources in the |NCS|. - -.. list-table:: Configuration source overview - :header-rows: 1 - - * - Source - - File types - - Usage - - Available editing tools - - Additional information - * - :ref:`Devicetree ` - - :file:`.dts`, :file:`.dtsi`, :file:`.overlay` - - Hardware-related options - - `Devicetree Visual Editor `_ - - Devicetree Visual Editor is part of the |nRFVSC|. You still need to be familiar with the devicetree language to use it. - * - :ref:`Kconfig ` - - :file:`Kconfig`, :file:`prj.conf`, :file:`.config` - - Software-related options - - `Kconfig GUI `_, :ref:`menuconfig and guiconfig ` - - Kconfig GUI is part of the |nRFVSC|. - * - :ref:`partition_manager` - - :file:`pm.yml` - - Memory layout configuration - - :ref:`partition_manager` script - - Partition Manager is an |NCS| configuration system that is not available in Zephyr. - -See the following sections for more information. -To read more about Zephyr's configuration system, see :ref:`zephyr:build_overview` in the Zephyr documentation. - -.. _configure_application_hw: - -Hardware-related configuration ------------------------------- - -.. ncs-include:: build/cmake/index.rst - :docset: zephyr - :dedent: 3 - :start-after: Devicetree - :end-before: The preprocessed devicetree sources - -The preprocessed devicetree sources are parsed by the :file:`zephyr/scripts/dts/gen_defines.py` script to generate a :file:`devicetree_unfixed.h` header file with preprocessor macros. - -The :file:`zephyr.dts` file contains the entire hardware-related configuration of the system in the devicetree format. -The header file contains the same kind of information, but with defines usable by source code. - -For more information, see Zephyr's :ref:`zephyr:dt-guide`. - -.. _configure_application_sw: - -Software-related configuration ------------------------------- - -.. ncs-include:: build/cmake/index.rst - :docset: zephyr - :dedent: 3 - :start-after: Kconfig - :end-before: Information from devicetree is available to Kconfig, - -Information from devicetree is available to Kconfig, through the functions defined in :file:`zephyr/scripts/kconfig/kconfigfunctions.py`. - -The single :file:`.config` file in the :file:`/zephyr/` directory describes the entire software configuration of the constructed binary. - -For more information, see Zephyr's :ref:`zephyr:application-kconfig`. - -Memory layout configuration ---------------------------- - -The Partition Manager is specific to the |NCS|. -If enabled, it provides the memory layout configuration. -The layout is impacted by various elements, such as Kconfig configuration options or the presence of child images. -Partition Manager ensures that all required partitions are in the correct place and have the correct size. - -If enabled, the memory layout can be controlled in the following ways: - -* Dynamically (default) - In this scenario, the layout is impacted by various elements, such as Kconfig configuration options or the presence of child images. - Partition Manager ensures that all required partitions are in the correct place and have the correct size. -* Statically - In this scenario, you need to provide the static configuration. - See :ref:`ug_pm_static` for information about how to do this. - -After CMake has run, a single :file:`partitions.yml` file with the complete memory layout will have been created in the :file:`build` directory. -This process also creates a set of header files that provides defines, which can be used to refer to memory layout elements. - -For more information, see :ref:`partition_manager`. - -Child images ------------- - -The |NCS| build system allows the application project to become a root for the sub-applications known in the |NCS| as child images. -Examples of child images are bootloader images, network core images, or security-related images. -Each child image is a separate application. - -For more information, see :ref:`ug_multi_image`. - Changing the hardware configuration =================================== @@ -292,7 +182,7 @@ For information about what variables can be set and how to add these variables i .. group-tab:: nRF Connect for VS Code - If you work with the |nRFVSC|, you can specify project-specific CMake options when you add the build configuration for a new |NCS| project. + 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 diff --git a/doc/nrf/config_and_build/multi_image.rst b/doc/nrf/config_and_build/multi_image.rst index 74105ae50ebe..a58bbe826134 100644 --- a/doc/nrf/config_and_build/multi_image.rst +++ b/doc/nrf/config_and_build/multi_image.rst @@ -19,7 +19,7 @@ Using multiple images has the following advantages: This partitioning is often useful for bootloaders. * Since there is a symbol table for each image, the same symbol names can exist multiple times in the final firmware. This is useful for bootloader images, which can require their own copy of a library that the application uses, but in a different version or configuration. -* In multi-core builds, the build configuration of a child image in a separate core can be made known to the parent image. +* In multi-core builds, the :term:`build configuration` of a child image in a separate core can be made known to the parent image. For the list of image files output by the build system for the multi-image builds, refer to :ref:`app_build_output_files` page. diff --git a/doc/nrf/device_guides/working_with_nrf/nrf53/nrf5340.rst b/doc/nrf/device_guides/working_with_nrf/nrf53/nrf5340.rst index 69d38f6ed829..435a5f96a7e8 100644 --- a/doc/nrf/device_guides/working_with_nrf/nrf53/nrf5340.rst +++ b/doc/nrf/device_guides/working_with_nrf/nrf53/nrf5340.rst @@ -339,7 +339,7 @@ By default, the two images are built together for all Bluetooth LE, Thread, Zigb Samples that are designed to run only on the network core include the :ref:`nrf5340_empty_app_core` sample as a child image. For other samples, the images are built separately. -The build configuration depends on the following Kconfig options that must be set in the configuration of the parent image: +The :term:`build configuration` depends on the following Kconfig options that must be set in the configuration of the parent image: * :kconfig:option:`CONFIG_BT_RPMSG` - set to ``y`` in all Bluetooth LE samples for the application core * :kconfig:option:`CONFIG_NRF_802154_SER_HOST` - set to ``y`` in all Thread, Zigbee, and Matter samples for the application core diff --git a/doc/nrf/device_guides/working_with_nrf/nrf91/nrf9160.rst b/doc/nrf/device_guides/working_with_nrf/nrf91/nrf9160.rst index c622cf8e1cad..ad45788408f3 100644 --- a/doc/nrf/device_guides/working_with_nrf/nrf91/nrf9160.rst +++ b/doc/nrf/device_guides/working_with_nrf/nrf91/nrf9160.rst @@ -417,7 +417,7 @@ nRF91 modem tracing with UART backend using snippets It enables the :kconfig:option:`CONFIG_NRF_MODEM_LIB_TRACE` Kconfig option and chooses the Zephyr UART driver for the backend, with the necessary Kconfig options. The snippet also enables the UART1 peripheral with a baud rate of 1 Mbd and hardware flow control enabled. If this configuration does not match your requirements, you can add a snippet or Kconfig and devicetree overlays to your application with the desired setup. -To enable modem tracing with the UART trace backend on a nRF91 device, add the ``nrf91-modem-trace-uart`` snippet to the build configuration. +To enable modem tracing with the UART trace backend on a nRF91 device, add the ``nrf91-modem-trace-uart`` snippet to the :term:`build configuration`. This can be done in one of the following ways: With west diff --git a/doc/nrf/documentation/glossary.rst b/doc/nrf/documentation/glossary.rst index d789e1a9b02f..956586258136 100644 --- a/doc/nrf/documentation/glossary.rst +++ b/doc/nrf/documentation/glossary.rst @@ -84,6 +84,13 @@ Glossary Carries the information on the amount of data available for each Logical Channel Group (LCG) from UE to eNB. From Wi-Fi perspective, BSR indicates the amount of queued uplink data buffered in the respective STA and access categories to which the queued data belong. + Build configuration + A set of build scripts. + The build configuration is created by :ref:`CMake ` by executing the build scripts from :file:`CMakeLists.txt` during the :ref:`configuration_system_overview_config` of the build process. + At this stage, CMake gathers configuration from different sources to produce a set of output files that will drive the build process. + The different sources can include source files such as :file:`main.c` and configuration input files such as :ref:`Devicetree ` and :ref:`Kconfig ` files. + The build scripts are then used during the :ref:`configuration_system_overview_build` to create the application firmware. + Carrier-sense Multiple Access with Collision Avoidance (CSMA/CA) A network multiple access method in which carrier sensing is used, but nodes attempt to avoid collisions by beginning transmission only after the channel is sensed to be idle. diff --git a/doc/nrf/installation/recommended_versions.rst b/doc/nrf/installation/recommended_versions.rst index 87555637fa9a..72f0c51c567d 100644 --- a/doc/nrf/installation/recommended_versions.rst +++ b/doc/nrf/installation/recommended_versions.rst @@ -330,6 +330,12 @@ Nordic Semiconductor provides proprietary |NCS| toolchain management tools that |vsc_extension_description| +In addition, the |nRFVSC| provides the following configuration tools for the :ref:`build system components `: + +* For CMake, the `build configuration management `_. +* For Devicetree, the `Devicetree Visual Editor `_. +* For Kconfig, the `Kconfig GUI `_. + The extension follows its own `release cycle `_. Use the latest available release for development. diff --git a/doc/nrf/protocols/matter/getting_started/transmission_power.rst b/doc/nrf/protocols/matter/getting_started/transmission_power.rst index f44f963c20c9..d2d00cc57098 100644 --- a/doc/nrf/protocols/matter/getting_started/transmission_power.rst +++ b/doc/nrf/protocols/matter/getting_started/transmission_power.rst @@ -91,7 +91,7 @@ You can provide the desired value also as a CMake argument when building the sam .. group-tab:: nRF Connect for VS Code - To build a Matter sample with a custom Thread TX power in the nRF Connect for VS Code IDE, add the :kconfig:option:`CONFIG_OPENTHREAD_DEFAULT_TX_POWER` Kconfig option variable and the dBm value to the build configuration's :guilabel:`Extra CMake arguments` and rebuild the build configuration. + To build a Matter sample with a custom Thread TX power in the nRF Connect for VS Code IDE, add the :kconfig:option:`CONFIG_OPENTHREAD_DEFAULT_TX_POWER` Kconfig option variable and the dBm value to the :term:`build configuration`'s :guilabel:`Extra CMake arguments` and rebuild the build configuration. For example, if you want to build for the ``nrf52840dk_nrf52840`` build target with the default Thread TX power equal to 2 dBm, add ``-DCONFIG_OPENTHREAD_DEFAULT_TX_POWER=2``. See `nRF Connect for VS Code extension pack `_ documentation for more information. diff --git a/doc/nrf/releases_and_maturity/releases/release-notes-changelog.rst b/doc/nrf/releases_and_maturity/releases/release-notes-changelog.rst index 4e44d79e6d12..fa94f2caaf9b 100644 --- a/doc/nrf/releases_and_maturity/releases/release-notes-changelog.rst +++ b/doc/nrf/releases_and_maturity/releases/release-notes-changelog.rst @@ -663,7 +663,11 @@ Documentation * The :ref:`installation` section by replacing two separate pages about installing the |NCS| with just one (:ref:`install_ncs`). * The :ref:`requirements` page with new sections about :ref:`requirements_clt` and :ref:`toolchain_management_tools`. - * The :ref:`configuration_and_build` section with the new reference page :ref:`app_build_output_files`, which gathers information previously listed on several other pages. + * The :ref:`configuration_and_build` section: + + * :ref:`app_build_system` gathers conceptual information about the build and configuration system previously listed on several other pages. + * New reference page :ref:`app_build_output_files` gathers information previously listed on several other pages. + * The :ref:`ug_nrf9160_gs` and :ref:`ug_thingy91_gsg` pages so that instructions in the :ref:`nrf9160_gs_connecting_dk_to_cloud` and :ref:`thingy91_connect_to_cloud` sections, respectively, match the updated nRF Cloud workflow. * The :ref:`ug_nrf9160_gs` by replacing the Updating the DK firmware section with a new :ref:`nrf9160_gs_installing_software` section. This new section includes steps for using Quick Start, a new application in `nRF Connect for Desktop`_ that streamlines the getting started process with the nRF91 Series DKs.