[PATCH] manual: improve documentation about using external toolchains

[PATCH] manual: improve documentation about using external toolchains

[michael.opdenacker]

From: Michael Opdenacker <michael.opdenacker@bootlin.com>

- 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.

Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
---
 .../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(-)

diff --git a/documentation/dev-manual/external-toolchain.rst b/documentation/dev-manual/external-toolchain.rst
index e1fabbed22..238f8cf467 100644
--- a/documentation/dev-manual/external-toolchain.rst
+++ b/documentation/dev-manual/external-toolchain.rst
@@ -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.
diff --git a/documentation/ref-manual/faq.rst b/documentation/ref-manual/faq.rst
index 8f38808a78..525d9ab0ff 100644
--- a/documentation/ref-manual/faq.rst
+++ b/documentation/ref-manual/faq.rst
@@ -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?
 -------------------------------------
 
diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index 776c8a2792..0586760a48 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -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'
-- 
2.37.2

Re: [docs] [PATCH] manual: improve documentation about using external toolchains

[Michael Opdenacker]

Hi Quentin,

Thanks for the review!

Am 09.12.22 um 11:51 schrieb Quentin Schulz:
> We could still keep this section in the FAQ and redirect to the 
> documentation/dev-manual/external-toolchain.rst manual, but no strong 
> opinion on this.


Agreed, it makes sense. I did just that.

>
>>   Why do I get chmod permission issues?
>>   -------------------------------------
>>   diff --git a/documentation/ref-manual/variables.rst 
>> b/documentation/ref-manual/variables.rst
>> index 776c8a2792..0586760a48 100644
>> --- a/documentation/ref-manual/variables.rst
>> +++ b/documentation/ref-manual/variables.rst
>> @@ -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://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/ ?
>
> "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.

-- 
Michael Opdenacker, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com