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

[Tom Rini]

On Fri, Feb 16, 2024 at 12:20:14AM +0100, Heinrich Schuchardt wrote:
> 
> 
> Am 15. Februar 2024 23:00:32 MEZ schrieb Tom Rini <trini at konsulko.com>:
> >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.
> >
> 
> On which operating systems will CROSS_COMPILE=aarch64-linux- work for the distro tools?
> 
> On which will CROSS_COMPILE=aarch64-linux-gnu- work?

Should we document what we test? We don't test distribution tools
because then we would have to test some number of distributions. And
distro tools can be too old. I guess the biggest problem is that I see
distro tools as a fall back option and you see kernel.org prebuilt
toolchains as a fallback option.

-- 
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/20240216/521a1e7d/attachment.sig>