Documentation/Makefile: add make_build_system.rst

Author: tinnedkarma

Documentation/guides/index.rst

@@ -52,6 +52,7 @@ Guides
   fully_linked_elf.rst
   building_nuttx_with_app_out_of_src_tree.rst
   building_uclibcpp.rst
+  make_build_system.rst
   custom_app_directories.rst
   multiple_nsh_sessions.rst
   nsh_network_link_management.rst

Documentation/guides/make_build_system.rst

@@ -0,0 +1,192 @@
+.. Licensed to the Apache Software Foundation (ASF) under one or more
+.. contributor license agreements.  See the NOTICE file distributed with
+.. this work for additional information regarding copyright ownership.  The
+.. ASF licenses this file to you under the Apache License, Version 2.0 (the
+.. "License"); you may not use this file except in compliance with the
+.. License.  You may obtain a copy of the License at
+..
+..   http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the
+.. License for the specific language governing permissions and limitations
+.. under the License.
+
+.. _make_build_system:
+
+Make Build System
+=================
+
+This guide explains the NuttX `make`-based build system.
+
+Overview
+--------
+
+The build system uses a series of Makefiles to compile the NuttX kernel and
+your applications.
+
+Key components:
+
+- **Root `Makefile`:** The main entry point for any build. It's located in the
+  NuttX root directory. It checks for a ``.config`` file and then pulls in the
+  correct host-specific Makefile (``tools/Unix.mk`` or ``tools/Win.mk``).
+
+- **Host-specific Makefiles:** ``tools/Unix.mk`` and ``tools/Win.mk`` contain
+  the core build logic. They set up the environment, create symlinks, build
+  libraries, and link the final executable.
+
+- **LibTargets.mk:** ``tools/LibTargets.mk`` is included by the host-specific
+  Makefiles. It handles compiling source files and creating libraries
+  (``.a`` files) for both the kernel and applications.
+
+- **Config.mk:** ``tools/Config.mk`` defines configuration variables based
+  on ``.config`` file. It sets compiler flags, paths, and other build
+  options.
+
+Verbosity
+~~~~~~~~~
+
+You can control the build verbosity with the ``V`` variable:
+
+*   **Quiet (Default):** By default, the build output is minimal.
+
+    .. code-block:: console
+
+       make
+
+*   **Verbose (`V=0` or `V=1`):** Shows the full compiler commands. There is no
+    difference between ``V=0`` and ``V=1``.
+
+    .. code-block:: console
+
+       make V=1
+
+*   **Debug (`V=2`):** Enables verbose output and adds extra debug flags to
+    certain build tools, such as the ``mkexport.sh`` script.
+
+    .. code-block:: console
+
+       make V=2
+
+Common Build Setup
+------------------
+
+Entrypoint: **Root `Makefile`**
+
+The build starts in the root ``Makefile``. Its main job is to check for a
+``.config`` file and then include the appropriate (either Unix or Windows)
+**host-specific Makefile**.
+
+Unix Build Setup
+----------------
+
+Entrypoint: **``tools/Unix.mk``**
+
+The build system, driven by ``tools/Unix.mk``, uses symlinks to create a source
+tree view that matches your ``.config``. This lets the core NuttX code stay
+generic while pointing to the specific board and architecture files needed for
+your build.
+
+1.  **Initial Setup:**
+    *   The build starts by setting the ``TOPDIR`` and ``WSDIR`` variables.
+    *   The main ``Make.defs`` file gets included, set while running
+    ``tools/configure.sh``.
+    *   If GIT is available, the build system will impact versioning.
+    See :ref:`versioning`.
+
+2.  **Directory Setup:** Key directories variables are defined:
+    *   ``ARCH_DIR``: Points to the architecture directory, determined by
+    ``CONFIG_ARCH``.
+    *   ``APPDIR``: Points to the applications directory, determined by
+    ``CONFIG_APPS_DIR``.
+    *   ``EXTERNALDIR``: Points to the ``external/`` directory if it contains a
+    ``Kconfig`` file.
+    *   ``tools/Directories.mk`` gets included. See :ref:`directories_mk`.
+    *   ``CONTEXTDIRS``: Directories needing a one-time setup.
+    *   ``CLEANDIRS``: All directories the ``clean`` target needs to hit.
+
+3.  **Symbolic Linking:** The ``context`` target creates symlinks to map generic
+    paths to your configured source files. This is the core of the configuration
+    process. For example:
+    *   ``include/arch`` links to the correct ``arch/$(CONFIG_ARCH)/include`` directory.
+    *   ``drivers/platform`` links to the board-specific driver directory.
+
+4.  **Final Context:** The build touches ``.context`` files in the subdirectories
+    (``CONTEXTDIRS``) to mark the context setup as complete for those locations.
+
+The Build Process
+-----------------
+
+Running ``make`` kicks off a sequence of steps to build the final executable.
+
+1.  **Configure:** First, you need a ``.config`` file. You typically create
+    this by running ``make menuconfig``, selecting your board and options, and
+    saving the configuration.
+
+2.  **Set Up Context:** The ``context`` target runs automatically. It creates
+    symlinks and generates ``config.h`` and ``version.h`` based on your
+    ``.config`` file.
+
+3.  **Build Libraries:** The build system compiles the source code and creates
+    a set of libraries (``.a`` files) in the ``staging/`` directory.
+
+4.  **Link Executable:** Finally, the build system links all the libraries from
+    ``staging/`` to create the ``nuttx`` executable in the root directory.
+
+The build is modular, so it only recompiles files that have changed, making
+development faster.
+
+Cleaning the Build
+------------------
+
+There are two targets for cleaning the build:
+
+**``make clean``**
+
+This removes most build artifacts like object files (``.o``), libraries (``.a``),
+and the final ``nuttx`` executable.
+
+It intentionally **leaves** your ``.config`` file, the ``staging/`` directory,
+and the symlinks created by the build. This is useful when you want to do a
+fresh build without losing your configuration.
+
+**``make distclean``**
+
+This is a complete reset. It does everything ``clean`` does, but **also deletes**:
+
+*   Your ``.config`` file
+*   The ``staging/`` directory
+*   All symlinks
+
+Use this to return your source tree to a pristine state.
+
+.. _directories_mk:
+
+Directories.mk
+--------------
+
+``tools/Directories.mk`` defines groups of directories used throughout the
+
+.. _libtargets_mk:
+
+LibTargets.mk
+-------------
+
+The ``tools/LibTargets.mk`` file is the engine for building all the libraries
+(archives) for the kernel and apps. It's included by ``tools/Unix.mk`` and
+handles compiling source files and installing the resulting libraries into the
+``staging/`` directory.
+
+A key job for ``LibTargets.mk`` is handling NuttX's build modes:
+
+*   **Flat Build (``CONFIG_BUILD_FLAT``):** The simplest mode. Kernel and
+    user-space code are built into a single binary.
+*   **Protected Build (``CONFIG_BUILD_PROTECTED``):** Kernel and user-space
+    code are built separately, with the kernel in a privileged mode.
+*   **Kernel Build (``CONFIG_BUILD_KERNEL``):** Similar to the protected build,
+    but with support for kernel modules.
+
+The Makefile contains different logic for kernel-mode builds (Protected/Kernel)
+versus user-mode builds (Flat) to ensure libraries are compiled with the
+correct flags for each scenario.

Documentation/guides/versioning_and_task_names.rst

@@ -33,6 +33,8 @@ Answer
 
 This is probably normal behavior. There are two separate, unrelated issues here.
 
+.. _versioning:
+
 Versioning
 ----------