3 files changed, 64 insertions, 0 deletions

diff --git a/documentation/ref-manual/closer-look.xml b/documentation/ref-manual/closer-look.xml
index 136f9389f7..77ab4d2633 100644
--- a/documentation/ref-manual/closer-look.xml
+++ b/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>
diff --git a/documentation/ref-manual/ref-classes.xml b/documentation/ref-manual/ref-classes.xml
index de8448febf..58004cbee1 100644
--- a/documentation/ref-manual/ref-classes.xml
+++ b/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'>
diff --git a/documentation/ref-manual/technical-details.xml b/documentation/ref-manual/technical-details.xml
index 106bb2c315..3485ee3506 100644
--- a/documentation/ref-manual/technical-details.xml
+++ b/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">