[PATCH 1/2] doc: Update our clang documentation to reflect current status
First, since this document was written the biggest challenges at the time are simply not applicable anymore. Second, we need to list the challenges which are preventing more platforms from being able to be built with Clang today. Next, we update the general wording to be host distribution agnostic. Finally, the section about xenguest_arm64 issues is not present anymore.
Signed-off-by: Tom Rini trini@konsulko.com --- Cc: Mark Kettenis kettenis@openbsd.org This does leave the FreeBSD section unchanged and should likely be looked at again by someone with a BSD build machine available. --- doc/build/clang.rst | 85 +++++++++++---------------------------------- 1 file changed, 21 insertions(+), 64 deletions(-)
diff --git a/doc/build/clang.rst b/doc/build/clang.rst index 09bb988e9236..d8c554982567 100644 --- a/doc/build/clang.rst +++ b/doc/build/clang.rst @@ -1,34 +1,27 @@ Building with Clang ===================
-The biggest problem when trying to compile U-Boot with Clang is that almost all -archs rely on storing gd in a global register and the Clang 3.5 user manual -states: "Clang does not support global register variables; this is unlikely to -be implemented soon because it requires additional LLVM backend support." - -The ARM backend can be instructed not to use the r9 and x18 registers using --ffixed-r9 or -ffixed-x18 respectively. As global registers themselves are not -supported inline assembly is needed to get and set the r9 or x18 value. This -leads to larger code then strictly necessary, but at least works. - -Debian based ------------- - -Required packages can be installed via apt, e.g. - -.. code-block:: bash - - sudo apt-get install clang - -We make use of the CROSS_COMPILE variable to derive the build target which is -passed as the --target parameter to clang. - -The CROSS_COMPILE variable further determines the paths to other build -tools. As assembler we use the binary pointed to by '$(CROSS_COMPILE)as' -instead of the LLVM integrated assembler (IAS). - -Here is an example demonstrating building U-Boot for the Raspberry Pi 2 -using clang: +In general terms, U-Boot support building with Clang as the C compiler and +building and booting our "sandbox" target is part of CI. + +There are however some specific issues that need to be addressed to fully +support building with Clang on all targets. + +* Given the issue reported in https://github.com/llvm/llvm-project/issues/78778 + currently one has to configure the build first with GCC. +* Support for passing the correct flags along to `$(CPP)` needs to be + backported from the Linux Kernel. +* Support for using Clang as the linker is required to support the LTO feature + which some platforms require in order to create an appropriately small + binary. + +In general, when building with Clang we make use of the CROSS_COMPILE variable +to derive the build target which is passed as the --target parameter to clang. +The CROSS_COMPILE variable further determines the paths to other build tools. +As assembler we use the binary pointed to by '$(CROSS_COMPILE)as' instead of +the LLVM integrated assembler (IAS). After installing clang as per the +instructions for your specific distribution, in order to build for example the +Raspberry Pi 2 using clang:
.. code-block:: bash
@@ -72,39 +65,3 @@ simplified with a simple wrapper script - saved as
#!/bin/sh exec clang -target arm-freebsd-eabi --sysroot /usr/arm-freebsd "$@" - - -Known Issues ------------- - -When build U-boot for `xenguest_arm64_defconfig` target, it reports linkage -error: - -.. code-block:: bash - - aarch64-linux-gnu-ld.bfd: drivers/xen/hypervisor.o: in function `do_hypervisor_callback': - /home/leoy/Dev2/u-boot/drivers/xen/hypervisor.c:188: undefined reference to `__aarch64_swp8_acq_rel' - aarch64-linux-gnu-ld.bfd: drivers/xen/hypervisor.o: in function `synch_test_and_set_bit': - /home/leoy/Dev2/u-boot/./arch/arm/include/asm/xen/system.h:40: undefined reference to `__aarch64_ldset1_acq_rel' - aarch64-linux-gnu-ld.bfd: drivers/xen/hypervisor.o: in function `synch_test_and_clear_bit': - /home/leoy/Dev2/u-boot/./arch/arm/include/asm/xen/system.h:28: undefined reference to `__aarch64_ldclr1_acq_rel' - aarch64-linux-gnu-ld.bfd: drivers/xen/hypervisor.o: in function `synch_test_and_set_bit': - /home/leoy/Dev2/u-boot/./arch/arm/include/asm/xen/system.h:40: undefined reference to `__aarch64_ldset1_acq_rel' - aarch64-linux-gnu-ld.bfd: drivers/xen/hypervisor.o: in function `synch_test_and_clear_bit': - /home/leoy/Dev2/u-boot/./arch/arm/include/asm/xen/system.h:28: undefined reference to `__aarch64_ldclr1_acq_rel' - aarch64-linux-gnu-ld.bfd: drivers/xen/events.o: in function `synch_test_and_clear_bit': - /home/leoy/Dev2/u-boot/./arch/arm/include/asm/xen/system.h:28: undefined reference to `__aarch64_ldclr1_acq_rel' - aarch64-linux-gnu-ld.bfd: drivers/xen/events.o: in function `synch_test_and_set_bit': - /home/leoy/Dev2/u-boot/./arch/arm/include/asm/xen/system.h:40: undefined reference to `__aarch64_ldset1_acq_rel' - aarch64-linux-gnu-ld.bfd: drivers/xen/gnttab.o: in function `gnttab_end_access': - /home/leoy/Dev2/u-boot/drivers/xen/gnttab.c:109: undefined reference to `__aarch64_cas2_acq_rel' - Segmentation fault - -To fix the failure, we need to append option `-mno-outline-atomics` in Clang -command to not generate local calls to out-of-line atomic operations: - -.. code-block:: bash - - make HOSTCC=clang xenguest_arm64_defconfig - make HOSTCC=clang CROSS_COMPILE=aarch64-linux-gnu- \ - CC="clang -target aarch64-linux-gnueabi -mno-outline-atomics" -j8
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@konsulko.com --- Cc: Heinrich Schuchardt xypron.glpk@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
.. code-block:: bash
- CROSS_COMPILE=aarch64-linux-gnu- make + CROSS_COMPILE=aarch64-linux- make
Build parameters ~~~~~~~~~~~~~~~~ @@ -131,13 +150,40 @@ You can speed up compilation by parallelization using the -j parameter, e.g.
.. code-block:: bash
- CROSS_COMPILE=aarch64-linux-gnu- make -j$(nproc) + CROSS_COMPILE=aarch64-linux- make -j$(nproc)
Further important build parameters are
* O=<dir> - generate all output files in directory <dir>, including .config * V=1 - verbose build
+ +Reproducible builds +~~~~~~~~~~~~~~~~~~~ + +In order to achieve reproducible builds, timestamps used in the U-Boot build +process have to be set to a fixed value. + +This is done using the SOURCE_DATE_EPOCH environment variable which specifies +the number of seconds since 1970-01-01T00:00:00Z. + + +To build the sandbox with 2023-01-01T00:00:00Z as timestamp we can use: + +.. code-block:: bash + + make sandbox_defconfig + SOURCE_DATE_EPOCH=1672531200 make + +This date is shown when we launch U-Boot: + +.. code-block:: console + + ./u-boot -T + U-Boot 2023.01 (Jan 01 2023 - 00:00:00 +0000) + +The same effect can be obtained with buildman using the `-r` flag. + Devicetree compiler ~~~~~~~~~~~~~~~~~~~
@@ -176,6 +222,8 @@ builds during development, you can disable it by setting `NO_LTO` to `1`.
NO_LTO=1 make
+Note that not all platforms which enable LTO support disabling it however. + Other build targets ~~~~~~~~~~~~~~~~~~~
@@ -195,3 +243,5 @@ Installation
The process for installing U-Boot on the target device is device specific. Please, refer to the board specific documentation :doc:`../board/index`. + +.. _`kernel.org`: https://mirrors.edge.kernel.org/pub/tools/crosstool/files/bin/ diff --git a/doc/build/index.rst b/doc/build/index.rst index 7a4507b57461..5262b4f3c1b9 100644 --- a/doc/build/index.rst +++ b/doc/build/index.rst @@ -7,9 +7,8 @@ Build U-Boot :maxdepth: 2
source - gcc + compile clang - reproducible docker tools buildman diff --git a/doc/build/reproducible.rst b/doc/build/reproducible.rst deleted file mode 100644 index 8b030f469d7c..000000000000 --- a/doc/build/reproducible.rst +++ /dev/null @@ -1,27 +0,0 @@ -Reproducible builds -=================== - -In order to achieve reproducible builds, timestamps used in the U-Boot build -process have to be set to a fixed value. - -This is done using the SOURCE_DATE_EPOCH environment variable which specifies -the number of seconds since 1970-01-01T00:00:00Z. - -Example -------- - -To build the sandbox with 2023-01-01T00:00:00Z as timestamp we can use: - -.. code-block:: bash - - make sandbox_defconfig - SOURCE_DATE_EPOCH=1672531200 make - -This date is shown when we launch U-Boot: - -.. code-block:: console - - ./u-boot -T - U-Boot 2023.01 (Jan 01 2023 - 00:00:00 +0000) - -The same effect can be obtained with buildman using the `-r` flag.
Am 15. Februar 2024 22:10:25 MEZ schrieb Tom Rini trini@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@konsulko.com
Cc: Heinrich Schuchardt xypron.glpk@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 .. 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
Build parameters
@@ -131,13 +150,40 @@ You can speed up compilation by parallelization using the -j parameter, e.g. .. code-block:: bash - CROSS_COMPILE=aarch64-linux-gnu- make -j$(nproc) + CROSS_COMPILE=aarch64-linux- make -j$(nproc)
ditto
Best regards
Heinrich
Further important build parameters are
- O=<dir> - generate all output files in directory <dir>, including .config
- V=1 - verbose build
+Reproducible builds +~~~~~~~~~~~~~~~~~~~
+In order to achieve reproducible builds, timestamps used in the U-Boot build +process have to be set to a fixed value.
+This is done using the SOURCE_DATE_EPOCH environment variable which specifies +the number of seconds since 1970-01-01T00:00:00Z.
+To build the sandbox with 2023-01-01T00:00:00Z as timestamp we can use:
+.. code-block:: bash
- make sandbox_defconfig
- SOURCE_DATE_EPOCH=1672531200 make
+This date is shown when we launch U-Boot:
+.. code-block:: console
- ./u-boot -T
- U-Boot 2023.01 (Jan 01 2023 - 00:00:00 +0000)
+The same effect can be obtained with buildman using the `-r` flag.
Devicetree compiler
@@ -176,6 +222,8 @@ builds during development, you can disable it by setting `NO_LTO` to `1`. NO_LTO=1 make +Note that not all platforms which enable LTO support disabling it however. + Other build targets@@ -195,3 +243,5 @@ Installation
The process for installing U-Boot on the target device is device specific. Please, refer to the board specific documentation :doc:`../board/index`.
+.. _`kernel.org`: https://mirrors.edge.kernel.org/pub/tools/crosstool/files/bin/ diff --git a/doc/build/index.rst b/doc/build/index.rst index 7a4507b57461..5262b4f3c1b9 100644 --- a/doc/build/index.rst +++ b/doc/build/index.rst @@ -7,9 +7,8 @@ Build U-Boot :maxdepth: 2
source
- gcc
- compile clang
- reproducible docker tools buildman
diff --git a/doc/build/reproducible.rst b/doc/build/reproducible.rst deleted file mode 100644 index 8b030f469d7c..000000000000 --- a/doc/build/reproducible.rst +++ /dev/null @@ -1,27 +0,0 @@
-Reproducible builds
-In order to achieve reproducible builds, timestamps used in the U-Boot build -process have to be set to a fixed value.
-This is done using the SOURCE_DATE_EPOCH environment variable which specifies -the number of seconds since 1970-01-01T00:00:00Z.
-Example
-To build the sandbox with 2023-01-01T00:00:00Z as timestamp we can use:
-.. code-block:: bash
- make sandbox_defconfig
- SOURCE_DATE_EPOCH=1672531200 make
-This date is shown when we launch U-Boot:
-.. code-block:: console
- ./u-boot -T
- U-Boot 2023.01 (Jan 01 2023 - 00:00:00 +0000)
-The same effect can be obtained with buildman using the `-r` flag.
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@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@konsulko.com
Cc: Heinrich Schuchardt xypron.glpk@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 .. code-block:: bash - CROSS_COMPILE=aarch64-linux-gnu- make + CROSS_COMPILE=aarch64-linux- makeGCC uses triples to specify the architecture. With the suggested change building will fail on many distros, e.g. in our CI image.
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.
Am 15. Februar 2024 22:28:24 MEZ schrieb Tom Rini trini@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@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@konsulko.com
Cc: Heinrich Schuchardt xypron.glpk@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 .. code-block:: bash - CROSS_COMPILE=aarch64-linux-gnu- make + CROSS_COMPILE=aarch64-linux- makeGCC uses triples to specify the architecture. With the suggested change building will fail on many distros, e.g. in our CI image.
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.
Best regards
Heinrich
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@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@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@konsulko.com
Cc: Heinrich Schuchardt xypron.glpk@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 .. code-block:: bash - CROSS_COMPILE=aarch64-linux-gnu- make + CROSS_COMPILE=aarch64-linux- makeGCC uses triples to specify the architecture. With the suggested change building will fail on many distros, e.g. in our CI image.
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.
Am 15. Februar 2024 23:00:32 MEZ schrieb Tom Rini trini@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@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@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@konsulko.com
Cc: Heinrich Schuchardt xypron.glpk@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 .. code-block:: bash - CROSS_COMPILE=aarch64-linux-gnu- make + CROSS_COMPILE=aarch64-linux- makeGCC uses triples to specify the architecture. With the suggested change building will fail on many distros, e.g. in our CI image.
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?
Best regards
Heinrich
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@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@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@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@konsulko.com
Cc: Heinrich Schuchardt xypron.glpk@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 .. code-block:: bash - CROSS_COMPILE=aarch64-linux-gnu- make + CROSS_COMPILE=aarch64-linux- makeGCC uses triples to specify the architecture. With the suggested change building will fail on many distros, e.g. in our CI image.
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.
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@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@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@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@konsulko.com > --- > Cc: Heinrich Schuchardt xypron.glpk@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.
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.
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@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@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@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@konsulko.com > > --- > > Cc: Heinrich Schuchardt xypron.glpk@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.
On 15/02/2024 21:10, Tom Rini wrote:
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@konsulko.com
Cc: Heinrich Schuchardt xypron.glpk@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.
I find this a little unclear. Perhaps:
To enable display support, SDL2 libraries need to be available in addition to the normal dependencies shown in the :doc:`general build instructions <../../build/compile>`.
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
s/dependinng/depending/
Thanks,
On Fri, Feb 16, 2024 at 10:10:19AM +0000, Paul Barker wrote:
On 15/02/2024 21:10, Tom Rini wrote:
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@konsulko.com
Cc: Heinrich Schuchardt xypron.glpk@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.
I find this a little unclear. Perhaps:
To enable display support, SDL2 libraries need to be available in addition to the normal dependencies shown in the :doc:`general build instructions <../../build/compile>`.
The issue is that SDL2 is required by default, so I'll try and reword this a bit more still, thanks.
On 15/02/2024 21:10, Tom Rini wrote:
First, since this document was written the biggest challenges at the time are simply not applicable anymore. Second, we need to list the challenges which are preventing more platforms from being able to be built with Clang today. Next, we update the general wording to be host distribution agnostic. Finally, the section about xenguest_arm64 issues is not present anymore.
Signed-off-by: Tom Rini trini@konsulko.com
Cc: Mark Kettenis kettenis@openbsd.org This does leave the FreeBSD section unchanged and should likely be looked at again by someone with a BSD build machine available.
doc/build/clang.rst | 85 +++++++++++---------------------------------- 1 file changed, 21 insertions(+), 64 deletions(-)
diff --git a/doc/build/clang.rst b/doc/build/clang.rst index 09bb988e9236..d8c554982567 100644 --- a/doc/build/clang.rst +++ b/doc/build/clang.rst @@ -1,34 +1,27 @@ Building with Clang ===================
-The biggest problem when trying to compile U-Boot with Clang is that almost all -archs rely on storing gd in a global register and the Clang 3.5 user manual -states: "Clang does not support global register variables; this is unlikely to -be implemented soon because it requires additional LLVM backend support."
-The ARM backend can be instructed not to use the r9 and x18 registers using --ffixed-r9 or -ffixed-x18 respectively. As global registers themselves are not -supported inline assembly is needed to get and set the r9 or x18 value. This -leads to larger code then strictly necessary, but at least works.
-Debian based
-Required packages can be installed via apt, e.g.
-.. code-block:: bash
- sudo apt-get install clang
-We make use of the CROSS_COMPILE variable to derive the build target which is -passed as the --target parameter to clang.
-The CROSS_COMPILE variable further determines the paths to other build -tools. As assembler we use the binary pointed to by '$(CROSS_COMPILE)as' -instead of the LLVM integrated assembler (IAS).
-Here is an example demonstrating building U-Boot for the Raspberry Pi 2 -using clang: +In general terms, U-Boot support building with Clang as the C compiler and
s/support/supports/
+building and booting our "sandbox" target is part of CI.
Are you saying that building the sandbox target with Clang then booting it is part of CI? I think this sentence needs re-wording to make it a little clearer.
Thanks,
On Fri, Feb 16, 2024 at 10:06:03AM +0000, Paul Barker wrote:
On 15/02/2024 21:10, Tom Rini wrote:
First, since this document was written the biggest challenges at the time are simply not applicable anymore. Second, we need to list the challenges which are preventing more platforms from being able to be built with Clang today. Next, we update the general wording to be host distribution agnostic. Finally, the section about xenguest_arm64 issues is not present anymore.
Signed-off-by: Tom Rini trini@konsulko.com
Cc: Mark Kettenis kettenis@openbsd.org This does leave the FreeBSD section unchanged and should likely be looked at again by someone with a BSD build machine available.
doc/build/clang.rst | 85 +++++++++++---------------------------------- 1 file changed, 21 insertions(+), 64 deletions(-)
diff --git a/doc/build/clang.rst b/doc/build/clang.rst index 09bb988e9236..d8c554982567 100644 --- a/doc/build/clang.rst +++ b/doc/build/clang.rst @@ -1,34 +1,27 @@ Building with Clang ===================
-The biggest problem when trying to compile U-Boot with Clang is that almost all -archs rely on storing gd in a global register and the Clang 3.5 user manual -states: "Clang does not support global register variables; this is unlikely to -be implemented soon because it requires additional LLVM backend support."
-The ARM backend can be instructed not to use the r9 and x18 registers using --ffixed-r9 or -ffixed-x18 respectively. As global registers themselves are not -supported inline assembly is needed to get and set the r9 or x18 value. This -leads to larger code then strictly necessary, but at least works.
-Debian based
-Required packages can be installed via apt, e.g.
-.. code-block:: bash
- sudo apt-get install clang
-We make use of the CROSS_COMPILE variable to derive the build target which is -passed as the --target parameter to clang.
-The CROSS_COMPILE variable further determines the paths to other build -tools. As assembler we use the binary pointed to by '$(CROSS_COMPILE)as' -instead of the LLVM integrated assembler (IAS).
-Here is an example demonstrating building U-Boot for the Raspberry Pi 2 -using clang: +In general terms, U-Boot support building with Clang as the C compiler and
s/support/supports/
+building and booting our "sandbox" target is part of CI.
Are you saying that building the sandbox target with Clang then booting it is part of CI? I think this sentence needs re-wording to make it a little clearer.
It is so I'll reword this a bit more then, thanks.
participants (3)
-
Heinrich Schuchardt -
Paul Barker -
Tom Rini