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

Fri Feb 16 16:45:54 CET 2024

On Fri, Feb 16, 2024 at 04:00:27PM +0100, Heinrich Schuchardt wrote:
> On 16.02.24 2:18 PM, Tom Rini wrote:
> > 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
> 
> 
> Referring to Debian the CROSS_COMPILE value was correct.
> 
> After the change we have some value that is wrong for many or even most
> distros.
> 
> Please, drop this change.

One of the reasons for this series is to lay the groundwork to make
everything consistent, which we are not today:
$ git grep -l CROSS_COMPILE=aarch64-poky-linux- doc/ | wc -l
7
$ git grep -l CROSS_COMPILE=aarch64-linux-gnu doc/ | wc -l
34
$ git grep -l CROSS_COMPILE=aarch64-none-elf doc/ | wc -l
39

So yes, I dropped "Debian" from the text in order to be
distribution-agnostic and then changed to the prefix used by the
toolchain we test, which very annoyingly, is the one that doesn't put
"gnu" in the suffix as it's not required (if it was OpenEmbedded
wouldn't be ignoring it).

Since I'm not sure we even can build the world on a distribution
toolchain due to age of the toolchain (for the cases where there is a
toolchain, but that is the most common case at least), I don't want to
encourage that as the first choice.

-- 
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/9dc98494/attachment.sig>