[PATCH 2/2] doc: describe building with GCC

[Heinrich Schuchardt <xypron.glpk@gmx.de>]

On 9/5/20 2:40 PM, Tom Rini wrote:
> On Sat, Sep 05, 2020 at 10:58:53AM +0200, Heinrich Schuchardt wrote:
>
>> Provide a description of the U-Boot build process with GCC in the HTML
>> documentation.
>>
>> Signed-off-by: Heinrich Schuchardt <xypron.glpk@gmx.de>
>> ---
>>  doc/build/gcc.rst   | 119 ++++++++++++++++++++++++++++++++++++++++++++
>>  doc/build/index.rst |   1 +
>>  2 files changed, 120 insertions(+)
>>  create mode 100644 doc/build/gcc.rst
>
> It's good to have this.  Can we restructure things so that it's clear
> that the majority of this is toolchain independent and we can update the
> clang doc, or if this becomes a more generic "build U-Boot for target"
> doc, we just need to add a section about the Clang caveat about how gd
> works and then it's just noting that instead of
> CROSS_COMPILE=aarch64-linux-gnu- it's CROSS_COMPILE="clang -target
> aarch64-linux-gnu" ?  Thanks!

I think the documentation serves different readers:

1) Users who want to build U-Boot and understand how to use it. They
will be interested in:

* What is U-Boot?
* Building U-Boot
* Board specific installation information
* Booting
* Using the shell
* Firmware update

In this area we are lacking a lot. Between "Build U-Boot" and "Develop
U-Boot" I see a need for a main chapter "Using U-Boot".

2) Developers who want to modify U-Boot and contribute to upstream. They
will be interested in

* APIs
* Inner workings of U-Boot
* Contribution guidelines

In this area we should strive to move the existing documentation to
reStructured text.

The description about the clang implementation of gd should be moved to
the "Develop U-Boot" section as a non-developer would not care about it.
We can add a chapter "Global data" collecting all gd related information.

Best regards

Heinrich