Re: [PATCH 2/2] doc: Rework the gcc section to reflect general build instructions

Thu Feb 15 22:24:40 CET 2024

Am 15. Februar 2024 22:10:25 MEZ schrieb Tom Rini <trini at konsulko.com>:
>The first big issue is that the "gcc" file talked a lot about the
>general build requirements as well, but was titled in a gcc-centric
>manner. Solve this by renaming the file to compile.rst and more fully
>reflecting that it is general build instructions. Next, add a section
>about the prebuilt toolchains that are recommended (as they are the ones
>we use in CI), and update a few places to reference these vendor-neutral
>tools.
>
>Next, we can include the reproducible builds section directly in the
>compile instructions rather than as a small standalone file.
>
>Finally, we update the sandbox document to reflect both the name change
>as well as what is specifically required to build sandbox.
>
>Signed-off-by: Tom Rini <trini at konsulko.com>
>---
>Cc: Heinrich Schuchardt <xypron.glpk at gmx.de>
>---
> doc/arch/sandbox/sandbox.rst       |  5 ++-
> doc/build/{gcc.rst => compile.rst} | 64 ++++++++++++++++++++++++++----
> doc/build/index.rst                |  3 +-
> doc/build/reproducible.rst         | 27 -------------
> 4 files changed, 61 insertions(+), 38 deletions(-)
> rename doc/build/{gcc.rst => compile.rst} (73%)
> delete mode 100644 doc/build/reproducible.rst
>
>diff --git a/doc/arch/sandbox/sandbox.rst b/doc/arch/sandbox/sandbox.rst
>index 5f8db126657f..f2ed5a25c115 100644
>--- a/doc/arch/sandbox/sandbox.rst
>+++ b/doc/arch/sandbox/sandbox.rst
>@@ -39,11 +39,12 @@ integers can only be built on 64-bit hosts.
> 
> Note that standalone/API support is not available at present.
> 
>-
> Prerequisites
> -------------
> 
>-Install the dependencies noted in :doc:`../../build/gcc`.
>+In addition to the normal dependencies shows in the :doc:`general build
>+instructions <../../build/compile>` to enable display support SDL2 libraries
>+need to be available.
> 
> 
> Basic Operation
>diff --git a/doc/build/gcc.rst b/doc/build/compile.rst
>similarity index 73%
>rename from doc/build/gcc.rst
>rename to doc/build/compile.rst
>index 3c6465772729..ef9c8545835a 100644
>--- a/doc/build/gcc.rst
>+++ b/doc/build/compile.rst
>@@ -1,11 +1,19 @@
>-Building with GCC
>-=================
>+Building U-Boot
>+===============
> 
> Dependencies
> ------------
> 
>-For building U-Boot you need a GCC compiler for your host platform. If you
>-are not building on the target platform you further need  a GCC cross compiler.
>+For building U-Boot you need the general build tools such as `make` and a C
>+compiler for your host platform. Next, if you are not building on the same
>+architecture as the target platform you further need a C cross compiler.
>+Furthermore, some target platforms require additional host tools to be present
>+and their package names may vary slightly dependinng on the naming scheme used
>+by a particular host OS.
>+
>+In general, GCC should be used for both the host and target C compiler. Using
>+:doc:`clang <clang>` is supported but please see the documented issues for it as
>+well.
> 
> Debian based
> ~~~~~~~~~~~~
>@@ -69,6 +77,17 @@ Depending on the build target further packages may be needed:
> * riscv64 S-mode targets: opensbi
> * some arm64 targets: arm-trusted-firmware
> 
>+Prebuilt
>+~~~~~~~~
>+
>+Another option, which the project uses for CI for example, is to use a prebuilt
>+toolchain. For the most part, we use the latest `kernel.org`_ prebuit binaries,
>+but there are a few architectures that require their own specific toolchains
>+still.
>+
>+In general, examples found within the documentation here refer to the tools
>+found here and exceptions will be noted where relevant.
>+
> Prerequisites
> -------------
> 
>@@ -112,11 +131,11 @@ command line or export it beforehand.
> 
>     CROSS_COMPILE=<compiler-prefix> make
> 
>-Assuming cross compiling on Debian for ARMv8 this would be
>+Assuming cross compiling for ARMv8 this would be
> 
> .. code-block:: bash
> 
>-    CROSS_COMPILE=aarch64-linux-gnu- make
>+    CROSS_COMPILE=aarch64-linux- make

GCC uses triples to specify the architecture. With the suggested change building will fail on many distros, e.g. in our CI image.

cf. https://gcc.gnu.org/install/specific.html#aarch64-x-x

> 
> Build parameters
> ~~~~~~~~~~~~~~~~
>@@ -131,13 +150,40 @@ You can speed up compilation by parallelization using the -j parameter, e.g.
> 
> .. code-block:: bash
> 
>-    CROSS_COMPILE=aarch64-linux-gnu- make -j$(nproc)
>+    CROSS_COMPILE=aarch64-linux- make -j$(nproc)

ditto

Best regards

Heinrich

> 
> Further important build parameters are
> 
> * O=<dir> - generate all output files in directory <dir>, including .config
> * V=1 - verbose build
> 
>+
>+Reproducible builds
>+~~~~~~~~~~~~~~~~~~~
>+
>+In order to achieve reproducible builds, timestamps used in the U-Boot build
>+process have to be set to a fixed value.
>+
>+This is done using the SOURCE_DATE_EPOCH environment variable which specifies
>+the number of seconds since 1970-01-01T00:00:00Z.
>+
>+
>+To build the sandbox with 2023-01-01T00:00:00Z as timestamp we can use:
>+
>+.. code-block:: bash
>+
>+    make sandbox_defconfig
>+    SOURCE_DATE_EPOCH=1672531200 make
>+
>+This date is shown when we launch U-Boot:
>+
>+.. code-block:: console
>+
>+    ./u-boot -T
>+    U-Boot 2023.01 (Jan 01 2023 - 00:00:00 +0000)
>+
>+The same effect can be obtained with buildman using the `-r` flag.
>+
> Devicetree compiler
> ~~~~~~~~~~~~~~~~~~~
> 
>@@ -176,6 +222,8 @@ builds during development, you can disable it by setting `NO_LTO` to `1`.
> 
>     NO_LTO=1 make
> 
>+Note that not all platforms which enable LTO support disabling it however.
>+
> Other build targets
> ~~~~~~~~~~~~~~~~~~~
> 
>@@ -195,3 +243,5 @@ Installation
> 
> The process for installing U-Boot on the target device is device specific.
> Please, refer to the board specific documentation :doc:`../board/index`.
>+
>+.. _`kernel.org`: https://mirrors.edge.kernel.org/pub/tools/crosstool/files/bin/
>diff --git a/doc/build/index.rst b/doc/build/index.rst
>index 7a4507b57461..5262b4f3c1b9 100644
>--- a/doc/build/index.rst
>+++ b/doc/build/index.rst
>@@ -7,9 +7,8 @@ Build U-Boot
>    :maxdepth: 2
> 
>    source
>-   gcc
>+   compile
>    clang
>-   reproducible
>    docker
>    tools
>    buildman
>diff --git a/doc/build/reproducible.rst b/doc/build/reproducible.rst
>deleted file mode 100644
>index 8b030f469d7c..000000000000
>--- a/doc/build/reproducible.rst
>+++ /dev/null
>@@ -1,27 +0,0 @@
>-Reproducible builds
>-===================
>-
>-In order to achieve reproducible builds, timestamps used in the U-Boot build
>-process have to be set to a fixed value.
>-
>-This is done using the SOURCE_DATE_EPOCH environment variable which specifies
>-the number of seconds since 1970-01-01T00:00:00Z.
>-
>-Example
>--------
>-
>-To build the sandbox with 2023-01-01T00:00:00Z as timestamp we can use:
>-
>-.. code-block:: bash
>-
>-    make sandbox_defconfig
>-    SOURCE_DATE_EPOCH=1672531200 make
>-
>-This date is shown when we launch U-Boot:
>-
>-.. code-block:: console
>-
>-    ./u-boot -T
>-    U-Boot 2023.01 (Jan 01 2023 - 00:00:00 +0000)
>-
>-The same effect can be obtained with buildman using the `-r` flag.