+Build System Internals
+=======================
+
+Build Scripts
+-------------
+
+The listfiles for the ESP-IDF build system reside in :idf:`/tools/cmake`. The modules which implement core build system functionality are as follows:
+
+ - build.cmake - Build related commands i.e. build initialization, retrieving/setting build properties, build processing.
+ - component.cmake - Component related commands i.e. adding components, retrieving/setting component properties, registering components.
+ - kconfig.cmake - Generation of configuration files (sdkconfig, sdkconfig.h, sdkconfig.cmake, etc.) from Kconfig files.
+ - ldgen.cmake - Generation of final linker script from linker fragment files.
+ - target.cmake - Setting build target and toolchain file.
+ - utilities.cmake - Miscellaneous helper commands.
+
+ Aside from these files, there are two other important CMake scripts in :idf:`/tools/cmake`:
+
+ - idf.cmake - Sets up the build and includes the core modules listed above. Included in CMake projects in order to access ESP-IDF build system functionality.
+ - project.cmake - Includes ``idf.cmake`` and provides a custom ``project()`` command that takes care of all the heavy lifting of building an executable. Included in the top-level CMakeLists.txt of standard ESP-IDF projects.
+
+The rest of the files in :idf:`/tools/cmake` are support or third-party scripts used in the build process.
+
+Build Process
+-------------
+
+This section describes the standard ESP-IDF application build process. The build process can be broken down roughly into four phases:
+
+.. blockdiag::
+ :scale: 100%
+ :caption: ESP-IDF Build System Process
+ :align: center
+
+ blockdiag idf-build-system-process {
+ Initialization -> Enumeration
+ Enumeration -> Processing
+ Processing -> Finalization
+ }
+
+Initialization
+^^^^^^^^^^^^^^
+ This phase sets up necessary parameters for the build.
+
+ - Upon inclusion of ``idf.cmake`` in ``project.cmake``, the following steps are performed:
+ - Set ``IDF_PATH`` from environment variable or inferred from path to ``project.cmake`` included in the top-level CMakeLists.txt.
+ - Add :idf:`/tools/cmake` to ``CMAKE_MODULE_PATH`` and include core modules plus the various helper/third-party scripts.
+ - Set build tools/executables such as default Python interpreter, mconf, etc.
+ - Get ESP-IDF git revision and store as ``IDF_VER``.
+ - Set global build specifications i.e. compile options, compile definitions, include directories for all components in the build.
+ - Add components in :idf:`components` to the build.
+ - The initial part of the custom ``project()`` command performs the following steps:
+ - Set ``IDF_TARGET`` from environment variable or CMake cache and the corresponding ``CMAKE_TOOLCHAIN_FILE`` to be used.
+ - Add components in ``EXTRA_COMPONENTS_DIRS`` to the build.
+ - Prepare arguments for calling command ``idf_build_process()`` from variables such as ``COMPONENTS``/``EXCLUDE_COMPONENTS``, ``SDKCONFIG``, ``SDKCONFIG_DEFAULTS``.
+
+ The call to ``idf_build_process()`` command marks the end of this phase.
+
+Enumeration
+^^^^^^^^^^^
+ This phase builds a final list of components to be processed in the build, and is performed in the first half of ``idf_build_process()``.
+
+ - Retrieve each component's public and private requirements. A child process is created which executes each component's CMakeLists.txt in script mode. The values of ``idf_component_register`` REQUIRES and PRIV_REQUIRES argument is returned to the parent build process. This is called early expansion. The variable ``CMAKE_BUILD_EARLY_EXPANSION`` is defined during this step.
+ - Recursively include components based on public and private requirements.
+
+Processing
+^^^^^^^^^^
+ This phase processes the components in the build, and is the second half of ``idf_build_process()``.
+
+ - Load project configuration from sdkconfig file and generate an sdkconfig.cmake and sdkconfig.h header. These define configuration variables/macros that are accessible from the build scripts and C/C++ source/header files, respectively.
+ - Include each component's ``project_include.cmake``.
+ - Add each component as a subdirectory, processing its CMakeLists.txt. The component CMakeLists.txt calls the registration command, ``idf_component_register`` which adds source files, include directories, creates component library, links dependencies, etc.
+
+Finalization
+^^^^^^^^^^^^
+ This phase is everything after ``idf_build_process()``.
+
+ - Create executable and link the component libraries to it.
+ - Generate project metadata files such as project_description.json and display relevant information about the project built.
+
+
+Browse :idf_file:`/tools/cmake/project.cmake` for more details.