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

[Tom Rini]

On Thu, Feb 15, 2024 at 10:53:59PM +0100, Heinrich Schuchardt wrote:
> 
> 
> 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.

We need to be consistent within our docs, and we aren't today. And
"-gnu" isn't a required suffix for aarch64 linux toolchains as not all
distributions do that. I'd be open to wording suggesting that users
install tools recommended by their vendors, but that still won't give us
consistent names due to "aarch64-poky-linux-" being what other vendor
tools will be.

-- 
Tom
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 659 bytes
Desc: not available
URL: <https://lists.denx.de/pipermail/u-boot/attachments/20240215/7a69d1af/attachment.sig>