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

[Heinrich Schuchardt]

Am 15. Februar 2024 22:28:24 MEZ schrieb Tom Rini <trini at konsulko.com>:
>On Thu, Feb 15, 2024 at 10:24:40PM +0100, Heinrich Schuchardt wrote:
>> 
>> 
>> 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
>
>But this is what the kernel.org compiler is called, and for consistency
>we should reference the reference compiler in our docs. I'm wanting to
>follow up and change everyone to use consistent names.
>

Please, do not asume that Linux distros will change. 

Users will and should use the tools provided by their distros. Side loading foreign binaries is a secutity risc which should be avoided.

I cannot see what is inconsistent about sticking to triples.

Best regards

Heinrich