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

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

[Heinrich Schuchardt]

Provide a newcomer friendly documentation how to obtain the U-Boot source
and how to build U-Boot with GCC.

Heinrich Schuchardt (2):
  doc: describe source repository
  doc: describe building with GCC

 doc/build/gcc.rst    | 119 +++++++++++++++++++++++++++++++++++++++++++
 doc/build/index.rst  |   2 +
 doc/build/source.rst |  30 +++++++++++
 3 files changed, 151 insertions(+)
 create mode 100644 doc/build/gcc.rst
 create mode 100644 doc/build/source.rst

--
2.28.0

[PATCH 1/2] doc: describe source repository

[Heinrich Schuchardt]

Add a chapter to the HTML documentation describing how to retrieve the
U-Boot sources.

Signed-off-by: Heinrich Schuchardt <xypron.glpk@gmx.de>
---
 doc/build/index.rst  |  1 +
 doc/build/source.rst | 30 ++++++++++++++++++++++++++++++
 2 files changed, 31 insertions(+)
 create mode 100644 doc/build/source.rst

diff --git a/doc/build/index.rst b/doc/build/index.rst
index e0072afb5e..5051a97e70 100644
--- a/doc/build/index.rst
+++ b/doc/build/index.rst
@@ -6,5 +6,6 @@ Build U-Boot
 .. toctree::
    :maxdepth: 2

+   source
    clang
    tools
diff --git a/doc/build/source.rst b/doc/build/source.rst
new file mode 100644
index 0000000000..4627c1f79e
--- /dev/null
+++ b/doc/build/source.rst
@@ -0,0 +1,30 @@
+Obtaining the source
+=====================
+
+The source of the U-Boot project is maintained in a Git repository.
+
+You can download the source via
+
+.. code-block:: bash
+
+    git clone https://gitlab.denx.de/u-boot/u-boot.git
+
+A mirror of the source is maintained on Github
+
+.. code-block:: bash
+
+    git clone https://github.com/u-boot/u-boot
+
+The released versions are available as tags which use the naming scheme::
+
+    v<year>.<month>
+
+Release candidates are named::
+
+    v<year>.<month>-rc<number>
+
+To checkout the October 2020 release you would use:
+
+.. code-block:: bash
+
+    git checkout v2020.10
--
2.28.0

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

[Heinrich Schuchardt]

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

diff --git a/doc/build/gcc.rst b/doc/build/gcc.rst
new file mode 100644
index 0000000000..fcb0b1ffb3
--- /dev/null
+++ b/doc/build/gcc.rst
@@ -0,0 +1,119 @@
+Building with GCC
+=================
+
+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.
+
+Debian based
+~~~~~~~~~~~~
+
+On Debian based systems the cross compiler packages are named
+gcc-<architecture>-linux-gnu.
+
+You could install GCC and the GCC cross compiler for the ARMv8 architecture with
+
+.. code-block:: bash
+
+    sudo apt-get gcc gcc-aarch64-linux-gnu
+
+Depending on the build targets further packages maybe needed
+
+.. code-block:: bash
+
+    sudo apt-get install bc bison build-essential coccinelle \
+      device-tree-compiler dfu-util efitools flex gdisk liblz4-tool \
+      libguestfs-tools libncurses-dev libpython3-dev libsdl2-dev libssl-dev \
+      lzma-alone openssl python3 python3-coverage python3-pyelftools \
+      python3-pytest python3-sphinxcontrib.apidoc python3-sphinx-rtd-theme swig
+
+Prerequisites
+-------------
+
+For some boards you have to build prerequisite files before you can build
+U-Boot, e.g. for the some boards you will need to build the ARM Trusted Firmware
+beforehand. Please, refer to the board specific documentation
+:doc:`../board/index`.
+
+Configuration
+-------------
+
+Directory configs/ contains the template configuration files for the maintained
+boards following the naming scheme::
+
+    <board name>_defconfig
+
+These files have been stripped of default settings. So you cannot use them
+directly. Instead their name serves as a make target to generate the actual
+configuration file .config. For instance the configuration template for the
+Odroid C2 board is called odroid-c2_defconfig. The corresponding .config file
+is generated by
+
+.. code-block:: bash
+
+    make odroid-c2_defconfig
+
+You can adjust the configuration using
+
+.. code-block:: bash
+
+    make menuconfig
+
+Building
+--------
+
+When cross compiling you will have to specify the prefix of the cross-compiler.
+You can either specify the value of the CROSS_COMPILE variable on the make
+command line or export it beforehand.
+
+.. code-block:: bash
+
+    CROSS_COMPILE=<compiler-prefix> make
+
+Assuming cross compiling on Debian for ARMv8 this would be
+
+.. code-block:: bash
+
+    CROSS_COMPILE=aarch64-linux-gnu- make
+
+Build parameters
+~~~~~~~~~~~~~~~~
+
+A list of available parameters for the make command can be obtained via
+
+.. code-block:: bash
+
+    make help
+
+You can speed up compilation by parallelization using the -j parameter, e.g.
+
+.. code-block:: bash
+
+    CROSS_COMPILE=aarch64-linux-gnu- make -j$(nproc)
+
+Further important build parameters are
+
+* O=<dir> - generate all output files in directory <dir>, including .config
+* V=1 - verbose build
+
+Other build targets
+~~~~~~~~~~~~~~~~~~~
+
+A list of all make targets can be obtained via
+
+.. code-block:: bash
+
+    make help
+
+Important ones are
+
+* clean - remove most generated files but keep the configuration
+* mrproper - remove all generated files + config + various backup files
+
+Installation
+------------
+
+The process for installing U-Boot on the target device is device specific.
+Please, refer to the board specific documentation :doc:`../board/index`.
diff --git a/doc/build/index.rst b/doc/build/index.rst
index 5051a97e70..5f90f95aca 100644
--- a/doc/build/index.rst
+++ b/doc/build/index.rst
@@ -7,5 +7,6 @@ Build U-Boot
    :maxdepth: 2

    source
+   gcc
    clang
    tools
--
2.28.0

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

[Tom Rini]

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!

-- 
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/20200905/787d9aa9/attachment.sig>

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

[Heinrich Schuchardt]

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

[PATCH 1/2] doc: describe source repository

[Tom Rini]

On Sat, Sep 05, 2020 at 10:58:52AM +0200, Heinrich Schuchardt wrote:

> Add a chapter to the HTML documentation describing how to retrieve the
> U-Boot sources.
> 
> Signed-off-by: Heinrich Schuchardt <xypron.glpk@gmx.de>

Applied to u-boot/master, thanks!

-- 
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/20200914/8d0b1d3b/attachment.sig>

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

[Tom Rini]

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>

Applied to u-boot/master, thanks!

-- 
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/20200914/d9d68186/attachment.sig>