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>

1 files changed, 29 insertions, 4 deletions

diff --git a/documentation/adt-manual/adt-prepare.xml b/documentation/adt-manual/adt-prepare.xml
index 0dbbe4dcc8..bb35c28f25 100644
--- a/documentation/adt-manual/adt-prepare.xml
+++ b/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>