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

Fri Feb 16 16:00:27 CET 2024

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.

Best regards

Heinrich

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