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

Tom Rini trini at konsulko.com
Thu Feb 15 22:10:25 CET 2024


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
 
 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)
 
 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.
-- 
2.34.1



More information about the U-Boot mailing list