| Message ID | 20240215211025.690964-2-trini@konsulko.com |
|---|---|
| State | Changes Requested |
| Delegated to: | Heinrich Schuchardt |
| Headers | show |
| Series | [1/2] doc: Update our clang documentation to reflect current status | expand |
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- 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.
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- 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. 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- 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.
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- 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? Best regards Heinrich
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 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- 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.
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 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. >>>>>> >>>>>> 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. >
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.
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.
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