acassis commented on code in PR #17162: URL: https://github.com/apache/nuttx/pull/17162#discussion_r2406611406
########## 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. Review Comment: I suggest to start explaining that Makefiles are the original build system used by NuttX, but currently it supports CMake as an alternative to Makefiles. The goal of supporting CMake was to improve the build system speed and to make (no pun intended) the integration with foreign libraries and application easy to do. ########## 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 Review Comment: Please include the Windows Build Setup before talking about The Build Process -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
