1 files changed, 46 insertions, 0 deletions

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