acassis commented on code in PR #17162:
URL: https://github.com/apache/nuttx/pull/17162#discussion_r2486954980
##########
Documentation/implementation/make_build_system.rst:
##########
@@ -66,11 +66,136 @@ The ``V`` variable can be passed to ``make`` to control
the build verbosity.
# V=2: Enable bug/verbose options in tools and scripts
$ make V=2
-Build Flow
-----------
+Build Process
+-------------
+
+.. note::
+
+ Most of the configuration step documentation and adjacent tooling should be
+ documented separately. Most of what is presented here will be moved.
+
+The ``Make`` based build process starts with the NuttX tree configuration.
+This is done by running ``tools/configure.sh`` script.
+
+During configuration, some symlinks are created.
+
+- the "current" chip directory gets symlinked to ``nutt/include/arch/chip``.
+- the "current" board directory gets symlinked to ``nutt/include/arch/board``.
+- the "current" arch directory gets symlinked to ``nutt/include/arch``.
+
+Each board should also supply an ``scripts/Make.defs`` file.
+The board ``Make.defs`` file should:
+
+- include the complete .config file.
+- include the :ref:`config_mk`
+- include the arch-specific toolchain.
+- set the linker file used for linking. (``LDSCRIPT``)
+- set the compiler flags needed for the board.
+
+The board config is stored as ``defconfig`` file, which is a minimal config,
+storing only the configs that differs from default config values.
+Due to NuttX's particularity of strict dependance to the ``app``
+directory, the ``.config`` file is not generated by either ``kconfiglib`` or
+``kconfig-frontends``, but rather by the an in-tree ``tools/process_config.sh``
+script. This script take a "base" input file (the boards ``defconfig`` file),
+additional include paths (the most relevant being the ``apps`` top directory),
+and generate an output file (the ``$(TOPDIR)/.config`` file).
+
+.. code-block:: bash
Review Comment:
please change bash -> console
##########
Documentation/implementation/make_build_system.rst:
##########
@@ -66,11 +66,136 @@ The ``V`` variable can be passed to ``make`` to control
the build verbosity.
# V=2: Enable bug/verbose options in tools and scripts
$ make V=2
-Build Flow
-----------
+Build Process
+-------------
+
+.. note::
+
+ Most of the configuration step documentation and adjacent tooling should be
+ documented separately. Most of what is presented here will be moved.
+
+The ``Make`` based build process starts with the NuttX tree configuration.
+This is done by running ``tools/configure.sh`` script.
+
+During configuration, some symlinks are created.
+
+- the "current" chip directory gets symlinked to ``nutt/include/arch/chip``.
+- the "current" board directory gets symlinked to ``nutt/include/arch/board``.
+- the "current" arch directory gets symlinked to ``nutt/include/arch``.
+
+Each board should also supply an ``scripts/Make.defs`` file.
+The board ``Make.defs`` file should:
+
+- include the complete .config file.
+- include the :ref:`config_mk`
+- include the arch-specific toolchain.
+- set the linker file used for linking. (``LDSCRIPT``)
+- set the compiler flags needed for the board.
+
+The board config is stored as ``defconfig`` file, which is a minimal config,
+storing only the configs that differs from default config values.
+Due to NuttX's particularity of strict dependance to the ``app``
+directory, the ``.config`` file is not generated by either ``kconfiglib`` or
+``kconfig-frontends``, but rather by the an in-tree ``tools/process_config.sh``
+script. This script take a "base" input file (the boards ``defconfig`` file),
+additional include paths (the most relevant being the ``apps`` top directory),
+and generate an output file (the ``$(TOPDIR)/.config`` file).
+
+.. code-block:: bash
+
+ # part of configure.sh shell script, starting at line 240
+ #
+ # src_config=${configpath}/defconfig
+ # dest_config="${TOPDIR}/.config"
+ # original_config="${TOPDIR}/.config.orig"
+ # backup_config="${TOPDIR}/defconfig"
+
Review Comment:
Please run "make html" inside Documentation/ and check it everything was
created correctly. I suspect that because this empty line the following lines
will not be inside the code-block
##########
Documentation/implementation/make_build_system.rst:
##########
@@ -66,11 +66,136 @@ The ``V`` variable can be passed to ``make`` to control
the build verbosity.
# V=2: Enable bug/verbose options in tools and scripts
$ make V=2
-Build Flow
-----------
+Build Process
+-------------
+
+.. note::
+
+ Most of the configuration step documentation and adjacent tooling should be
+ documented separately. Most of what is presented here will be moved.
+
+The ``Make`` based build process starts with the NuttX tree configuration.
+This is done by running ``tools/configure.sh`` script.
+
+During configuration, some symlinks are created.
+
+- the "current" chip directory gets symlinked to ``nutt/include/arch/chip``.
+- the "current" board directory gets symlinked to ``nutt/include/arch/board``.
+- the "current" arch directory gets symlinked to ``nutt/include/arch``.
+
+Each board should also supply an ``scripts/Make.defs`` file.
+The board ``Make.defs`` file should:
+
+- include the complete .config file.
+- include the :ref:`config_mk`
+- include the arch-specific toolchain.
+- set the linker file used for linking. (``LDSCRIPT``)
+- set the compiler flags needed for the board.
+
+The board config is stored as ``defconfig`` file, which is a minimal config,
+storing only the configs that differs from default config values.
+Due to NuttX's particularity of strict dependance to the ``app``
+directory, the ``.config`` file is not generated by either ``kconfiglib`` or
+``kconfig-frontends``, but rather by the an in-tree ``tools/process_config.sh``
+script. This script take a "base" input file (the boards ``defconfig`` file),
+additional include paths (the most relevant being the ``apps`` top directory),
+and generate an output file (the ``$(TOPDIR)/.config`` file).
+
+.. code-block:: bash
+
+ # part of configure.sh shell script, starting at line 240
+ #
+ # src_config=${configpath}/defconfig
+ # dest_config="${TOPDIR}/.config"
+ # original_config="${TOPDIR}/.config.orig"
+ # backup_config="${TOPDIR}/defconfig"
+
+ $ ln -sf ${src_makedefs} ${dest_makedefs} || \
+ { echo "Failed to symlink ${src_makedefs}" ; exit 8 ; }
+ $ ${TOPDIR}/tools/process_config.sh -I ${configpath}/../../common/configs \
+ -I ${configpath}/../common \
+ -I ${configpath} -I ${TOPDIR}/../apps \
+ -I ${TOPDIR}/../nuttx-apps \
+ -o ${dest_config} ${src_config}
+
+Starting the Build
+^^^^^^^^^^^^^^^^^^
The root **Makefile** is the build process entrypoint. Its main job is
to check for a ``.config`` file and include the appropriate **host-specific
Makefile**.
+The "actual" first steps of the build process are handled by the host-specific
+**Makefile** (either ``Win.mk`` or ``Unix.mk``).
+
+Early on, during parsing, both host-specific **Makefile** will also include
+
+- board's ``Make.defs`` file mentioned above. this will include also
+ - the main ``.config`` file.
+ - the tools ``config.mk`` file.
+ - the arch ``toolchain.defs`` file.
+- based on the build mode, one of the following files:
+ - :ref:`flatlibs_mk`
+ - :ref:`protectedlibs_mk`
+ - :ref:`kernelibs_mk`
+- :ref:`directories_mk`
Review Comment:
Please align with above line
##########
Documentation/implementation/make_build_system.rst:
##########
@@ -66,11 +66,136 @@ The ``V`` variable can be passed to ``make`` to control
the build verbosity.
# V=2: Enable bug/verbose options in tools and scripts
$ make V=2
-Build Flow
-----------
+Build Process
+-------------
+
+.. note::
+
+ Most of the configuration step documentation and adjacent tooling should be
+ documented separately. Most of what is presented here will be moved.
+
+The ``Make`` based build process starts with the NuttX tree configuration.
+This is done by running ``tools/configure.sh`` script.
+
+During configuration, some symlinks are created.
+
+- the "current" chip directory gets symlinked to ``nutt/include/arch/chip``.
+- the "current" board directory gets symlinked to ``nutt/include/arch/board``.
+- the "current" arch directory gets symlinked to ``nutt/include/arch``.
+
+Each board should also supply an ``scripts/Make.defs`` file.
+The board ``Make.defs`` file should:
+
+- include the complete .config file.
+- include the :ref:`config_mk`
+- include the arch-specific toolchain.
+- set the linker file used for linking. (``LDSCRIPT``)
+- set the compiler flags needed for the board.
+
+The board config is stored as ``defconfig`` file, which is a minimal config,
+storing only the configs that differs from default config values.
+Due to NuttX's particularity of strict dependance to the ``app``
+directory, the ``.config`` file is not generated by either ``kconfiglib`` or
+``kconfig-frontends``, but rather by the an in-tree ``tools/process_config.sh``
+script. This script take a "base" input file (the boards ``defconfig`` file),
+additional include paths (the most relevant being the ``apps`` top directory),
+and generate an output file (the ``$(TOPDIR)/.config`` file).
+
+.. code-block:: bash
+
+ # part of configure.sh shell script, starting at line 240
+ #
+ # src_config=${configpath}/defconfig
+ # dest_config="${TOPDIR}/.config"
+ # original_config="${TOPDIR}/.config.orig"
+ # backup_config="${TOPDIR}/defconfig"
+
+ $ ln -sf ${src_makedefs} ${dest_makedefs} || \
+ { echo "Failed to symlink ${src_makedefs}" ; exit 8 ; }
+ $ ${TOPDIR}/tools/process_config.sh -I ${configpath}/../../common/configs \
+ -I ${configpath}/../common \
+ -I ${configpath} -I ${TOPDIR}/../apps \
+ -I ${TOPDIR}/../nuttx-apps \
+ -o ${dest_config} ${src_config}
+
+Starting the Build
+^^^^^^^^^^^^^^^^^^
The root **Makefile** is the build process entrypoint. Its main job is
to check for a ``.config`` file and include the appropriate **host-specific
Makefile**.
+The "actual" first steps of the build process are handled by the host-specific
+**Makefile** (either ``Win.mk`` or ``Unix.mk``).
+
+Early on, during parsing, both host-specific **Makefile** will also include
+
+- board's ``Make.defs`` file mentioned above. this will include also
Review Comment:
```suggestion
- board's ``Make.defs`` file mentioned above. This will include also
--
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]
