doc: describe building with GCC

Provide a description of the U-Boot build process with GCC in the HTML
documentation.

Signed-off-by: Heinrich Schuchardt <xypron.glpk@gmx.de>

2 files changed, 120 insertions, 0 deletions

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