adt-manual, ref-manual: Cross-toolchain details added. New class also.

In the adt-manual in the "Optionally Building a Toolchain Installer"
setion, I added some basic advantage information for building a
toolchain installer using bitbake image -c populate_sdk.

In the ref-manual, I added cross-referencing to this basic information
in several strategic areas: "SDK Generation", the populate_sdk class
reference section, the populate_sdk_* class reference section, and the
"Cross-Development Toolchain Generation" sections.

Finally, I also put in documentation for a new class called
autotools-brokensep.

(From yocto-docs rev: cde7dd2fbd7bdc0d71dc678ee7a5422459654287)

Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

documentation/adt-manual/adt-prepare.xml

@@ -584,17 +584,42 @@
         you can build the toolchain installer one of two ways if you have a
         <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>:
         <itemizedlist>
-            <listitem><para>Use <filename>bitbake meta-toolchain</filename>.
+            <listitem><para>
+                Use <filename>bitbake meta-toolchain</filename>.
                 This method requires you to still install the target
                 sysroot by installing and extracting it separately.
                 For information on how to install the sysroot, see the
                 "<link linkend='extracting-the-root-filesystem'>Extracting the Root Filesystem</link>"
-                section.</para></listitem>
-            <listitem><para>Use
-                <filename>bitbake image -c populate_sdk</filename>.
+                section.
+                </para></listitem>
+            <listitem><para>
+                Use <filename>bitbake image -c populate_sdk</filename>.
                 This method has significant advantages over the previous method
                 because it results in a toolchain installer that contains the
                 sysroot that matches your target root filesystem.
+                </para>
+
+                <para>Another powerful feature is that the toolchain is
+                completely self-contained.
+                The binaries are linked against their own copy of
+                <filename>libc</filename>, which results in no dependencies
+                on the target system.
+                To achieve this, the pointer to the dynamic loader is
+                configured at install time since that path cannot be dynamically
+                altered.
+                This is the reason for a wrapper around the
+                <filename>populate_sdk</filename> archive.</para>
+
+                <para>Another feature is that only one set of cross-canadian
+                toolchain binaries are produced per architecture.
+                This feature takes advantage of the fact that the target
+                hardware can be passed to <filename>gcc</filename> as a set of
+                compiler options.
+                Those options are set up by the environment script and
+                contained in variables like CC and LD.
+                This reduces the space needed for the tools.
+                Understand, however, that a sysroot is still needed for every
+                target since those binaries are target-specific.
                 </para></listitem>
         </itemizedlist>
     </para>

documentation/ref-manual/closer-look.xml

@@ -1022,6 +1022,11 @@
                 generation, see the
                 "<link linkend='cross-development-toolchain-generation'>Cross-Development Toolchain Generation</link>"
                 section.
+                For information on advantages gained when building a
+                cross-development toolchain using the
+                <filename>do_populate_sdk</filename> task, see the
+                "<ulink url='&YOCTO_DOCS_ADT_URL;#optionally-building-a-toolchain-installer'>Optionally Building a Toolchain Installer</ulink>"
+                section in the Yocto Project Application Developer's Guide.
             </note>
 
             <para>

documentation/ref-manual/ref-classes.xml

@@ -130,6 +130,36 @@
                 </para></listitem>
         </itemizedlist>
     </para>
+
+    <note>
+        It is planned for future Yocto Project releases that by default, the
+        <filename>autotools</filename> class supports out-of-tree builds
+        (<link linkend='var-B'><filename>B</filename></link> !=
+        <link linkend='var-S'><filename>S</filename></link>).
+        If your recipes do not support out-of-tree builds, you should
+        have them inherit the
+        <link linkend='ref-classes-autotools-brokensep'><filename>autotools-brokensep</filename></link>
+        class.
+    </note>
+</section>
+
+<section id='ref-classes-autotools-brokensep'>
+    <title><filename>autotools-brokensep.bbclass</filename></title>
+
+    <para>
+        The <filename>autotools-brokensep</filename> class behaves the same
+        as the
+        <link linkend='ref-classes-autotools'><filename>autotools</filename></link>
+        class but builds with
+        <link linkend='var-B'><filename>B</filename></link> ==
+        <link linkend='var-S'><filename>S</filename></link>.
+        This method is useful when out-of-tree build support is either not
+        present or is broken.
+        <note>
+            It is recommended that out-of-tree support be fixed and used
+            if at all possible.
+        </note>
+    </para>
 </section>
 
 <section id='ref-classes-base'>
@@ -2220,6 +2250,10 @@
     <para>
         The <filename>populate_sdk</filename> class provides support for
         SDK-only recipes.
+        For information on advantages gained when building a cross-development
+        toolchain using the <filename>do_populate_sdk</filename> task, see the
+        "<ulink url='&YOCTO_DOCS_ADT_URL;#optionally-building-a-toolchain-installer'>Optionally Building a Toolchain Installer</ulink>"
+        section in the Yocto Project Application Developer's Guide.
     </para>
 </section>
 
@@ -2284,6 +2318,18 @@
         These classes are inherited by and used with the
         <filename>populate_sdk_base</filename> class.
     </para>
+
+    <para>
+        For more information on the cross-development toolchain
+        generation, see the
+        "<link linkend='cross-development-toolchain-generation'>Cross-Development Toolchain Generation</link>"
+        section.
+        For information on advantages gained when building a
+        cross-development toolchain using the
+        <filename>do_populate_sdk</filename> task, see the
+        "<ulink url='&YOCTO_DOCS_ADT_URL;#optionally-building-a-toolchain-installer'>Optionally Building a Toolchain Installer</ulink>"
+        section in the Yocto Project Application Developer's Guide.
+    </para>
 </section>
 
 <section id='ref-classes-prexport'>

documentation/ref-manual/technical-details.xml

@@ -327,9 +327,22 @@
                 <link linkend='var-SDKMACHINE'><filename>SDKMACHINE</filename></link>,
                 this tool
                 produces executable code that runs on the target device.
+                Only one cross-canadian compiler is produced per architecture
+                since they can be targeted at different processor optimizations
+                using configurations passed to the compiler through the
+                compile commands.
+                This saves the need to have multiple compilers present and
+                hence reduces the size of the toolchains.
                 </para></listitem>
         </itemizedlist>
     </para>
+
+    <note>
+        For information on advantages gained when building a
+        cross-development toolchain installer, see the
+        "<ulink url='&YOCTO_DOCS_ADT_URL;#optionally-building-a-toolchain-installer'>Optionally Building a Toolchain Installer</ulink>"
+        section in the Yocto Project Application Developer's Guide.
+    </note>
 </section>
 
 <section id="shared-state-cache">