manual: improve documentation about using external toolchains
PATCH 1/1 manual: improve documentation about using external toolchains
From: Michael Opdenacker <[email protected]>
- Remove the redundant FAQ entry about this topic,
already covered in a specific section of the Development Tasks manual
- Document the TOOLCHAIN_LOCATION variable
- Expand both the Development Tasks manual and
the TCMODE variable description using details from the FAQ entry.
- Mention the "meta-arm-toolchain" layer too.
--- .../dev-manual/external-toolchain.rst | 28 +++++++++++++------ documentation/ref-manual/faq.rst | 21 -------------- documentation/ref-manual/variables.rst | 20 +++++++++---- 3 files changed, 35 insertions(+), 34 deletions(-)
documentation/dev-manual/external-toolchain.rst +20 -8
@@ -15,14 +15,26 @@ follows: ``bblayers.conf`` file through the :term:`BBLAYERS` variable. -- Set the ``EXTERNAL_TOOLCHAIN`` variable in your ``local.conf`` file +- Set the :term:`EXTERNAL_TOOLCHAIN` variable in your ``local.conf`` file to the location in which you installed the toolchain. -A good example of an external toolchain used with the Yocto Project is -Mentor Graphics Sourcery G++ Toolchain. You can see information on how -to use that particular layer in the ``README`` file at -https://github.com/MentorEmbedded/meta-sourcery/. You can find -further information by reading about the -:term:`TCMODE` variable in the Yocto -Project Reference Manual's variable glossary. +The toolchain configuration is very flexible and customizable. It +is primarily controlled with the :term:`TCMODE` variable. This variable +controls which ``tcmode-*.inc`` file to include from the +``meta/conf/distro/include`` directory within the :term:`Source Directory`. +The default value of :term:`TCMODE` is "default", which tells the +OpenEmbedded build system to use its internally built toolchain (i.e. +``tcmode-default.inc``). However, other patterns are accepted. In +particular, "external-\*" refers to external toolchains. One example is +the Mentor Graphics Sourcery G++ Toolchain. Support for this toolchain resides +in the separate ``meta-sourcery`` layer at +https://github.com/MentorEmbedded/meta-sourcery/. +See its ``README`` file for details about how to use this layer. + +Another example of external toolchain layer is +:yocto_git:`meta-arm-toolchain </meta-arm/tree/meta-arm-toolchain/>` +supporting GNU toolchains released by ARM. + +You can find further information by reading about the :term:`TCMODE` variable +in the Yocto Project Reference Manual's variable glossary.
documentation/ref-manual/faq.rst +0 -21
@@ -165,27 +165,6 @@ how to configure CVS and Git proxy servers if needed. Using the OpenEmbedded Build system =================================== -How do I use an external toolchain? ------------------------------------ - -The toolchain configuration is very flexible and customizable. It -is primarily controlled with the :term:`TCMODE` variable. This variable -controls which ``tcmode-*.inc`` file to include from the -``meta/conf/distro/include`` directory within the :term:`Source Directory`. - -The default value of :term:`TCMODE` is "default", which tells the -OpenEmbedded build system to use its internally built toolchain (i.e. -``tcmode-default.inc``). However, other patterns are accepted. In -particular, "external-\*" refers to external toolchains. One example is -the Sourcery G++ Toolchain. The support for this toolchain resides in -the separate ``meta-sourcery`` layer at -https://github.com/MentorEmbedded/meta-sourcery/. - -In addition to the toolchain configuration, you also need a -corresponding toolchain recipe file. This recipe file needs to package -up any pre-built objects in the toolchain such as ``libgcc``, -``libstdcc++``, any locales, and ``libc``. - Why do I get chmod permission issues? -------------------------------------
documentation/ref-manual/variables.rst +15 -5
@@ -2420,6 +2420,12 @@ system and gives an overview of their function and contents. :ref:`kernel-yocto <ref-classes-kernel-yocto>` class in ``meta/classes-recipe`` to see how the variable is used. + :term:`EXTERNAL_TOOLCHAIN` + When you intend to use an + :ref:`external toolchain <dev-manual/external-toolchain:optionally using an external toolchain>`, + this variable allows to specify the directory in which this toolchain was + installed. + :term:`EXTERNALSRC` When inheriting the :ref:`externalsrc <ref-classes-externalsrc>` class, this variable points to the source tree, which is outside of
@@ -8481,16 +8487,20 @@ system and gives an overview of their function and contents. https://github.com/MentorEmbedded/meta-sourcery/. The layer's ``README`` file contains information on how to use the - Sourcery G++ Toolchain as an external toolchain. In summary, you must - be sure to add the layer to your ``bblayers.conf`` file in front of - the ``meta`` layer and then set the ``EXTERNAL_TOOLCHAIN`` variable - in your ``local.conf`` file to the location in which you installed - the toolchain. + Sourcery G++ Toolchain as an external toolchain. You will have to + add the layer to your ``bblayers.conf`` file and then set the + :term:`EXTERNAL_TOOLCHAIN` variable in your ``local.conf`` file to + the location in which you installed the toolchain. The fundamentals used for this example apply to any external toolchain. You can use ``meta-sourcery`` as a template for adding support for other external toolchains. + In addition to toolchain configuration, you will also need a + corresponding toolchain recipe file. This recipe file needs to package + up any pre-built objects in the toolchain such as ``libgcc``, + ``libstdcc++``, any locales, and ``libc``. + :term:`TC_CXX_RUNTIME` Specifies the C/C++ STL and runtime variant to use during the build process. Default value is 'gnu'
Signature · 1 line
2.37.2
Hi Quentin,
Thanks for the review!
Am 09.12.22 um 11:51 schrieb Quentin Schulz:
Quoted 1 line
We could still keep this section in the FAQ and redirect to the
documentation/dev-manual/external-toolchain.rstmanual, but no strong opinion on this.
Agreed, it makes sense. I did just that.
Quoted 44 lines
Quoted 24 lines
Why do I get chmod permission issues?
-------------------------------------
diff --gita/documentation/ref-manual/variables.rstb/documentation/ref-manual/variables.rstindex776c8a2792..0586760a48100644documentation/ref-manual/variables.rst +0
-0@@ -2420,6 +2420,12 @@ system and gives an overview of their functionand contents.
:ref:kernel-yocto <ref-classes-kernel-yocto>class in ``meta/classes-recipe`` to see how the variable is used. + :term:EXTERNAL_TOOLCHAIN
+ When you intend to use an
+ :ref:external toolchain <dev-manual/external-toolchain:optionally using an external toolchain>, + this variable allows to specify the directory in which this toolchain was
+ installed.
+
:term:EXTERNALSRC
When inheriting the :ref:externalsrc <ref-classes-externalsrc>class, this variable points to the source tree, which is outside ofdocumentation/ref-manual/variables.rst +0
-0@@ -8481,16 +8487,20 @@ system and gives an overview of theirfunction and contents.
Quoted 16 lines
https://urldefense.com/v3/__https://github.com/MentorEmbedded/meta-sourcery/__;!!OOPJP91ZZw!iVny7D_tgmsS9YRYu1nh93Aa322nmitTKLdI-iCobzRfKZxvczJxvv2fCJHvt2hjcknk0cDnc2dayQei4TR8zLinoTpD_oozAcyIkgsHUsxfwCNbs7B8$ . The layer's ``README`` file contains information on how to use the - Sourcery G++ Toolchain as an external toolchain. In summary, you must - be sure to add the layer to your ``bblayers.conf`` file in front of - the ``meta`` layer and then set the ``EXTERNAL_TOOLCHAIN`` variable - in your ``local.conf`` file to the location in which you installed - the toolchain. + Sourcery G++ Toolchain as an external toolchain. You will have to + add the layer to your ``bblayers.conf`` file and then set the + :term:`EXTERNAL_TOOLCHAIN` variable in your ``local.conf`` file to + the location in which you installed the toolchain.s/in which you installed/of/ ?
s/in which/where/ ?
Quoted 1 line
"the location in which" doesn't sound good to my non-native ears.
OK, I went for "of", which indeed is sufficient.
Thanks for correcting me on this!
Cheers
Michael.
Signature · 3 lines
Michael Opdenacker, Bootlin Embedded Linux and Kernel engineering https://bootlin.com