sdk-manual: Edits to add extensible SDK configuration sections.

(From yocto-docs rev: 378bbceb8ea06c225c4758807e25a35521faa3a9)

Signed-off-by: Scott Rifenbark <srifenbark@gmail.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

4 files changed, 506 insertions, 101 deletions

diff --git a/documentation/sdk-manual/sdk-appendix-customizing.xml b/documentation/sdk-manual/sdk-appendix-customizing.xml
index 2068143df3..3ee0d7c90a 100644
--- a/documentation/sdk-manual/sdk-appendix-customizing.xml
+++ b/documentation/sdk-manual/sdk-appendix-customizing.xml
@@ -6,17 +6,380 @@
 
 <title>Customizing the SDK</title>
 
-<para role='writernotes'>
-    This chapter is going to cover the details on extending the SDK through
-    user customizations.
-    I am not sure if this is possible for both the standard and extensible
-    SDK or what.
+<para>
+    This appendix presents customizations you can apply to both the standard
+    and extensible SDK.
+    Each subsection identifies the type of SDK to which the section applies.
 </para>
 
-<para role='writernotes'>
-    I do not have a feel for what sub-topics need to be covered here.
-    I need to get this information from Paul.
-</para>
+<section id='sdk-configuring-the-extensible-sdk'>
+    <title>Configuring the Extensible SDK</title>
+
+    <para>
+        The extensible SDK primarily consists of a pre-configured copy of
+        the build system from which it was produced.
+        Thus, the SDK's configuration is derived using that build system.
+        However, filters exist that are applied such as the following that
+        are applied to <filename>local.conf</filename> and
+        <filename>auto.conf</filename> when present:
+        <itemizedlist>
+            <listitem><para>
+                Variables whose values start with "/" are excluded since the
+                assumption is that those values are paths that are likely to
+                be specific to the build host.
+                </para></listitem>
+            <listitem><para>
+                Variables listed in
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_LOCAL_CONF_BLACKLIST'><filename>SDK_LOCAL_CONF_BLACKLIST</filename></ulink>
+                are excluded.
+                The default value blacklists
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-CONF_VERSION'><filename>CONF_VERSION</filename></ulink>,
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-BB_NUMBER_THREADS'><filename>BB_NUMBER_THREADS</filename></ulink>,
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></ulink>,
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-PRSERV_HOST'><filename>PRSERV_HOST</filename></ulink>,
+                and
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-SSTATE_MIRRORS'><filename>SSTATE_MIRRORS</filename></ulink>.
+                </para></listitem>
+            <listitem><para>
+                Variables listed in
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_LOCAL_CONF_WHITELIST'><filename>SDK_LOCAL_CONF_WHITELIST</filename></ulink>
+                are included.
+                Including these variables overrides either of the above two
+                conditions.
+                The default value is blank.
+                </para></listitem>
+            <listitem><para>
+                Classes inherited globally with
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-INHERIT'><filename>INHERIT</filename></ulink>
+                that are listed in
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_INHERIT_BLACKLIST'><filename>SDK_INHERIT_BLACKLIST</filename></ulink>
+                are disabled.
+                Using <filename>SDK_INHERIT_BLACKLIST</filename> to disable
+                these classes is is the typical method to disable classes that
+                are problematic or unnecessary in the SDK context.
+                The default value blacklists the
+                <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-buildhistory'><filename>buildhistory</filename></ulink>
+                and
+                <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-icecc'><filename>icecc</filename></ulink>
+                classes.
+                </para></listitem>
+        </itemizedlist>
+        Additionally, the contents of <filename>conf/sdk-extra.conf</filename>,
+        when present, are appended to the end of
+        <filename>conf/local.conf</filename> within the produced SDK, without
+        any filtering.
+        Not filtering these contents is particularly useful if you want to
+        set a variable value just for the SDK and not the build system used to
+        create the SDK.
+    </para>
+</section>
+
+<section id='adjusting-the-extensible-sdk-to-suit-your-build-system-setup'>
+    <title>Adjusting the Extensible SDK to Suit Your Build System Setup</title>
+
+    <para>
+        In most cases, the extensible SDK defaults should work.
+        However, some cases exist for which you might consider making
+        adjustments:
+        <itemizedlist>
+            <listitem><para>
+                If your SDK configuration inherits additional classes
+                using the
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-INHERIT'><filename>INHERIT</filename></ulink>
+                variable and you do not need or want those classes enabled in
+                the SDK, you can blacklist them by adding them to the
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_INHERIT_BLACKLIST'><filename>SDK_INHERIT_BLACKLIST</filename></ulink>
+                variable.
+                The default value of <filename>SDK_INHERIT_BLACKLIST</filename>
+                is set using the "?=" operator.
+                Consequently, you will need to either set the complete value
+                using "=" or append the value using "_append".
+                </para></listitem>
+            <listitem><para>
+                If you have classes or recipes that add additional tasks to
+                the standard build flow (i.e. that execute as part of building
+                the recipe as opposed to needing to be called explicitly), then
+                you need to do one of the following:
+                <itemizedlist>
+                    <listitem><para>
+                        Ensure the tasks are shared state tasks (i.e. their
+                        output is saved to and can be restored from the shared
+                        state cache), or that the tasks are able to be
+                        produced quickly from a task that is a shared state
+                        task and add the task name to the value of
+                        <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_RECRDEP_TASKS'><filename>SDK_RECRDEP_TASKS</filename></ulink>.
+                        </para></listitem>
+                    <listitem><para>
+                        Disable the tasks if they are added by a class and
+                        you do not need the functionality the class provides
+                        in the extensible SDK.
+                        To disable the tasks, add the class to
+                        <filename>SDK_INHERIT_BLACKLIST</filename> as previously
+                        described.
+                        </para></listitem>
+                </itemizedlist>
+                </para></listitem>
+            <listitem><para>
+                Generally, you want to have a shared state mirror set up so
+                users of the SDK can add additional items to the SDK after
+                installation without needing to build the items from source.
+                See the
+                "<link linkend='sdk-providing-additional-installable-extensible-sdk-content'>Providing Additional Installable Extensible SDK Content</link>"
+                section for information.
+                </para></listitem>
+            <listitem><para>
+                If you want users of the SDK to be able to easily update the
+                SDK, you need to set the
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_UPDATE_URL'><filename>SDK_UPDATE_URL</filename></ulink>
+                variable.
+                For more information, see the
+                "<link linkend='sdk-providing-updates-after-installing-the-extensible-sdk'>Providing Updates After Installing the Extensible SDK</link>"
+                section.
+                </para></listitem>
+            <listitem><para>
+                If you have adjusted the list of files and directories that
+                appear in
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-COREBASE'><filename>COREBASE</filename></ulink>
+                (other than layers that are enabled through
+                <filename>bblayers.conf</filename>), then must list these
+                files in
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-COREBASE_FILES'><filename>COREBASE_FILES</filename></ulink>
+                so that the files are copied into the SDK.
+                </para></listitem>
+            <listitem><para>
+                If your build system setup uses a different environment setup
+                script other than
+                <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
+                or
+                <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>,
+                then you must set
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-OE_INIT_ENV_SCRIPT'><filename>OE_INIT_ENV_SCRIPT</filename></ulink>
+                to point to the environment setup script you use.
+                <note>
+                    You must also reflect this change in the value used for the
+                    <filename>COREBASE_FILES</filename> variable as previously
+                    described.
+                </note>
+                </para></listitem>
+        </itemizedlist>
+    </para>
+</section>
+
+<section id='sdk-changing-the-appearance-of-the-extensible-sdk'>
+    <title>Changing the Appearance of the Extensible SDK</title>
+
+    <para>
+        You can change the title shown by the SDK installer by setting the
+        <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_TITLE'><filename>SDK_TITLE</filename></ulink>
+        variable.
+        By default, this title is derived from
+        <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_NAME'><filename>DISTRO_NAME</filename></ulink>
+        when it is set.
+        If the <filename>DISTRO_NAME</filename> variable is not set, the title
+        is derived from the
+        <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO'><filename>DISTRO</filename></ulink>
+        variable.
+    </para>
+</section>
+
+<section id='sdk-providing-updates-after-installing-the-extensible-sdk'>
+    <title>Providing Updates After Installing the Extensible SDK</title>
+
+    <para>
+        When you make changes to your configuration or to the metadata and
+        if you want those changes to be reflected in installed SDKs, you need
+        to perform additional steps to make it possible for those that use
+        the SDK to update their installations with the
+        <filename>devtool sdk-update</filename> command:
+        <orderedlist>
+            <listitem><para>
+                Arrange to be created a directory that can be shared over
+                HTTP or HTTPS.
+                </para></listitem>
+            <listitem><para>
+                Set the
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_UPDATE_URL'><filename>SDK_UPDATE_URL</filename></ulink>
+                variable to point to the corresponding HTTP or HTTPS URL.
+                Setting this variable causes any SDK built to default to that
+                URL and thus, the user does not have to pass the URL to the
+                <filename>devtool sdk-update</filename> command.
+                </para></listitem>
+            <listitem><para>
+                Build the extensible SDK normally (i.e., use the
+                <filename>bitbake -c populate_sdk_ext</filename> <replaceable>imagename</replaceable>
+                command).
+                </para></listitem>
+            <listitem><para>
+                Publish the SDK using the following command:
+                <literallayout class='monospaced'>
+     $ oe-publish-sdk <replaceable>some_path</replaceable>/sdk-installer.sh <replaceable>path_to_shared/http_directory</replaceable>
+                </literallayout>
+                You must repeat this step each time you rebuild the SDK
+                with changes that you want to make available through the
+                update mechanism.
+                </para></listitem>
+        </orderedlist>
+    </para>
+
+    <para>
+        Completing the above steps allows users of the existing SDKs to
+        simply run <filename>devtool sdk-update</filename> to retrieve the
+        latest updates.
+        See the
+        "<link linkend='sdk-updating-the-extensible-sdk'>Updating the Extensible SDK</link>"
+        section for further information.
+    </para>
+</section>
+
+<section id='sdk-providing-additional-installable-extensible-sdk-content'>
+    <title>Providing Additional Installable Extensible SDK Content</title>
+
+    <para>
+        If you want the users of the extensible SDK you are building to be
+        able to add items to the SDK without needing to build the
+        items from source, you need to do a number of things:
+        <orderedlist>
+            <listitem><para>
+                Ensure the additional items you want the user to be able to
+                install are actually built.
+                You can ensure these items are built a number of different
+                ways: 1) Build them explicitly, perhaps using one or more
+                "meta" recipes that depend on lists of other recipes to keep
+                things tidy, or 2) Build the "world" target and set
+                <filename>EXCLUDE_FROM_WORLD_pn-</filename><replaceable>recipename</replaceable>
+                for the recipes you do not want built.
+                See the
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-EXCLUDE_FROM_WORLD'><filename>EXCLUDE_FROM_WORLD</filename></ulink>
+                variable for additional information.
+                </para></listitem>
+            <listitem><para>
+                Expose the <filename>sstate-cache</filename> directory
+                produced by the build.
+                Typically, you expose this directory over HTTP or HTTPS.
+                </para></listitem>
+            <listitem><para>
+                Set the appropriate configuration so that the produced SDK
+                knows how to find the configuration.
+                The variable you need to set is
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-SSTATE_MIRRORS'><filename>SSTATE_MIRRORS</filename></ulink>:
+                <literallayout class='monospaced'>
+     SSTATE_MIRRORS = "file://.*  http://<replaceable>example</replaceable>.com/<replaceable>some_path</replaceable>/sstate-cache/PATH"
+                </literallayout>
+                You can set the <filename>SSTATE_MIRRORS</filename> variable
+                in two different places:
+                <itemizedlist>
+                    <listitem><para>
+                        If the mirror value you are setting is appropriate to
+                        be set for both the build system that is actually
+                        building the SDK and the SDK itself (i.e. the mirror
+                        is accessible in both places or it will fail quickly
+                        on the build system side, and its contents will not
+                        interfere with the build), then you can set the
+                        variable in your <filename>local.conf</filename>
+                        or custom distro configuration file.
+                        You can "whitelist" the variable through the SDK by
+                        adding the following:
+                        <literallayout class='monospaced'>
+     SDK_LOCAL_CONF_WHITELIST = "SSTATE_MIRRORS"
+                        </literallayout>
+                        </para></listitem>
+                    <listitem><para>
+                        Alternatively, if you just want to set the
+                        <filename>SSTATE_MIRRORS</filename> variable's value
+                        for the SDK alone, create a
+                        <filename>conf/sdk-extra.conf</filename> either in
+                        your
+                        <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
+                        or within any layer and put your
+                        <filename>SSTATE_MIRRORS</filename> setting within
+                        that file.
+                        <note>
+                            This second option is the safest option should
+                            you have any doubts as to which method to use when
+                            setting <filename>SSTATE_MIRRORS</filename>.
+                        </note>
+                        </para></listitem>
+                </itemizedlist>
+                </para></listitem>
+        </orderedlist>
+    </para>
+</section>
+
+<section id='sdk-minimizing-the-size-of-the-extensible-sdk-installer-download'>
+    <title>Minimizing the Size of the Extensible SDK Installer Download</title>
+
+    <para>
+        By default, the extensible SDK bundles the shared state artifacts for
+        everything needed to reconstruct the image for which the SDK was built.
+        This bundling can lead to an SDK installer file that is a Gigabyte or
+        more in size.
+        If the size of this file causes a problem, you can build an SDK that
+        has just enough in it to install and provide access to the
+        <filename>devtool command</filename> by setting the following in your
+        configuration:
+        <literallayout class='monospaced'>
+     SDK_EXT_TYPE = "minimal"
+        </literallayout>
+        Setting
+        <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_EXT_TYPE'><filename>SDK_EXT_TYPE</filename></ulink>
+        to "minimal" produces an SDK installer that is around 35 Mbytes in
+        size, which downloads and installs quickly.
+        You need to realize, though, that the installer does not install any
+        libraries or tools out of the box.
+        These must be installed either "on the fly" or through actions you
+        perform using <filename>devtool</filename> or explicitly with the
+        <filename>devtool sdk-install</filename> command.
+    </para>
+
+    <para>
+        In most cases, when building a minimal SDK you will need to also enable
+        bringing in the information on a wider range of packages produced by
+        the system.
+        This is particularly true so that <filename>devtool add</filename>
+        is able to effectively map dependencies it discovers in a source tree
+        to the appropriate recipes.
+        Also so that the <filename>devtool search</filename> command
+        is able to return useful results.
+    </para>
+
+    <para>
+        To facilitate this wider range of information, you would additionally
+        set the following:
+        <literallayout class='monospaced'>
+     SDK_INCLUDE_PKGDATA = "1"
+        </literallayout>
+        See the
+        <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_INCLUDE_PKGDATA'><filename>SDK_INCLUDE_PKGDATA</filename></ulink>
+        variable for additional information.
+    </para>
+
+    <para>
+        Setting the <filename>SDK_INCLUDE_PKGDATA</filename> variable as
+        shown causes the "world" target to be built so that information
+        for all of the recipes included within it are available.
+        Having these recipes available increases build time significantly and
+        increases the size of the SDK installer by 30-80 Mbytes depending on
+        how many recipes are included in your configuration.
+    </para>
+
+    <para>
+        You can use
+        <filename>EXCLUDE_FROM_WORLD_pn-</filename><replaceable>recipename</replaceable>
+        for recipes you want to exclude.
+        However, it is assumed that you would need to be building the "world"
+        target if you want to provide additional items to the SDK.
+        Consequently, building for "world" should not represent undue
+        overhead in most cases.
+        <note>
+            If you set <filename>SDK_EXT_TYPE</filename> to "minimal",
+            then providing a shared state mirror is mandatory so that items
+            can be installed as needed.
+            See the
+            "<link linkend='sdk-providing-additional-installable-extensible-sdk-content'>Providing Additional Installable Extensible SDK Content</link>"
+            section for more information.
+        </note>
+    </para>
+</section>
 
 </appendix>
 <!--
diff --git a/documentation/sdk-manual/sdk-appendix-obtain.xml b/documentation/sdk-manual/sdk-appendix-obtain.xml
index 6ffc958695..daa5e79fe8 100644
--- a/documentation/sdk-manual/sdk-appendix-obtain.xml
+++ b/documentation/sdk-manual/sdk-appendix-obtain.xml
@@ -52,18 +52,20 @@
 
     <para>
         As an alternative to locating and downloading a toolchain installer,
-        you can build the toolchain installer if you have a
-        <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
-        <note>
-            Although not the preferred method, it is also possible to use
-            <filename>bitbake meta-toolchain</filename> to build the toolchain
-            installer.
-            If you do use this method, you must separately install and extract
-            the target sysroot.
-            For information on how to install the sysroot, see the
-            "<link linkend='sdk-extracting-the-root-filesystem'>Extracting the Root Filesystem</link>"
-            section.
-        </note>
+        you can build the toolchain installer assuming you have first sourced
+        the environment setup script.
+        See the
+        "<ulink url='&YOCTO_DOCS_QS_URL;#qs-building-images'>Building Images</ulink>"
+        section in the Yocto Project Quick Start for steps that show you
+        how to set up the Yocto Project environment.
+        In particular, you need to be sure the
+        <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
+        variable matches the architecture for which you are building and that
+        the
+        <ulink url='&YOCTO_DOCS_REF_URL;#var-SDKMACHINE'><filename>SDKMACHINE</filename></ulink>
+        variable is correctly set if you are building a toolchain designed to
+        run on an architecture that differs from your current development host
+        machine (i.e. the build machine).
     </para>
 
     <para>
@@ -81,54 +83,6 @@
     </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> and
-        <filename>populate_sdk_ext</filename> archives.
-    </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 such as
-        <ulink url='&YOCTO_DOCS_REF_URL;#var-CC'><filename>CC</filename></ulink>
-        and
-        <ulink url='&YOCTO_DOCS_REF_URL;#var-LD'><filename>LD</filename></ulink>.
-        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>
-
-    <para>
-         Remember, before using any BitBake command, you
-         must source the build environment setup script
-         (i.e.
-         <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
-         or
-         <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>)
-         located in the Source Directory and you must make sure your
-         <filename>conf/local.conf</filename> variables are correct.
-         In particular, you need to be sure the
-         <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
-         variable matches the architecture for which you are building and that
-         the
-         <ulink url='&YOCTO_DOCS_REF_URL;#var-SDKMACHINE'><filename>SDKMACHINE</filename></ulink>
-         variable is correctly set if you are building a toolchain designed to
-         run on an architecture that differs from your current development host
-         machine (i.e. the build machine).
-    </para>
-
-    <para>
         When the <filename>bitbake</filename> command completes, the toolchain
         installer will be in
         <filename>tmp/deploy/sdk</filename> in the Build Directory.
@@ -154,12 +108,8 @@
     <title>Extracting the Root Filesystem</title>
 
     <para>
-        After installing the toolchain or building it using BitBake,
-        you need a root filesystem, which you need to separately extract.
-    </para>
-
-    <para>
-        Here are some cases where you need to extract the root filesystem:
+        After installing the toolchain, for some use cases you
+        might need to separately extract a root filesystem:
         <itemizedlist>
             <listitem><para>You want to boot the image using NFS.
                 </para></listitem>
diff --git a/documentation/sdk-manual/sdk-extensible.xml b/documentation/sdk-manual/sdk-extensible.xml
index bc9ccd28d3..f9f04072d7 100644
--- a/documentation/sdk-manual/sdk-extensible.xml
+++ b/documentation/sdk-manual/sdk-extensible.xml
@@ -540,39 +540,103 @@
     </para>
 </section>
 
-<section id='sdk-using-the-extensible-sdk-to-task-2'>
-    <title>Using the Extensible SDK to <replaceable>item-2</replaceable></title>
-
-    <para role='writernotes'>
-        Describe the specific task you are going to accomplish with the
-        extensible SDK.
-        Provide a diagram showing the rough flow of the task.
-        Provide specific steps using a real example that works through the
-        task.
+<section id='sdk-installing-additional-items-into-the-extensible-sdk'>
+    <title>Installing Additional Items Into the Extensible SDK</title>
+
+    <para>
+        The extensible SDK typically only comes with a small number of tools
+        and libraries out of the box.
+        If you have a minimal SDK, then it starts mostly empty and is
+        populated on-demand.
+        However, sometimes you will need to explicitly install extra items
+        into the SDK.
+        If you need these extra items, you can first search for the items
+        using the <filename>devtool search</filename> command.
+        For example, suppose you need to link to libGL but you are not sure
+        which recipe provides it.
+        You can use the following command to find out:
+        <literallayout class='monospaced'>
+     $ devtool search libGL
+     mesa                  A free implementation of the OpenGL API
+        </literallayout>
+        Once you know the recipe (i.e. <filename>mesa</filename> in this
+        example), you can install it:
+        <literallayout class='monospaced'>
+     $ devtool sdk-install mesa
+        </literallayout>
+        By default, the <filename>devtool sdk-install</filename> assumes the
+        item is available in pre-built form from your SDK provider.
+        If the item is not available and it is acceptable to build the item
+        from source, you can add the "-s" option as follows:
+        <literallayout class='monospaced'>
+     $ devtool sdk-install -s mesa
+        </literallayout>
+        It is important to remember that building the item from source takes
+        significantly longer than installing the pre-built artifact.
+        Also, if no recipe exists for the item you want to add to the SDK, you
+        must add it using the <filename>devtool add</filename> command.
     </para>
 </section>
 
-<section id='sdk-using-the-extensible-sdk-to-task-3'>
-    <title>Using the Extensible SDK to <replaceable>item-3</replaceable></title>
-
-    <para role='writernotes'>
-        Describe the specific task you are going to accomplish with the
-        extensible SDK.
-        Provide a diagram showing the rough flow of the task.
-        Provide specific steps using a real example that works through the
-        task.
+<section id='sdk-updating-the-extensible-sdk'>
+     <title>Updating the Extensible SDK</title>
+
+     <para>
+         If you are working with an extensible SDK that gets occasionally
+         updated (e.g. typically when that SDK has been provided to you by
+         another party), then you will need to manually pull down those
+         updates to your installed SDK.
+     </para>
+
+     <para>
+         To update your installed SDK, run the following:
+         <literallayout class='monospaced'>
+     $ devtool sdk-update
+         </literallayout>
+         The previous command assumes your SDK provider has set the default
+         update URL for you.
+         If that URL has not been set, you need to specify it yourself as
+         follows:
+         <literallayout class='monospaced'>
+     $ devtool sdk-update <replaceable>path_to_update_directory</replaceable>
+         </literallayout>
+         <note>
+             The URL needs to point specifically to a published SDK and not an
+             SDK installer that you would download and install.
+         </note>
     </para>
 </section>
 
-<section id='sdk-using-the-extensible-sdk-to-task-x'>
-    <title>Using the Extensible SDK to <replaceable>item-x</replaceable></title>
+<section id='sdk-creating-a-derivative-sdk-with-additional-components'>
+    <title>Creating a Derivative SDK With Additional Components</title>
 
-    <para role='writernotes'>
-        Describe the specific task you are going to accomplish with the
-        extensible SDK.
-        Provide a diagram showing the rough flow of the task.
-        Provide specific steps using a real example that works through the
-        task.
+    <para>
+        You might need to produce an SDK that contains your own custom
+        libraries for sending to a third party (e.g., if you are a vendor with
+        customers needing to build their own software for the target platform).
+        If that is the case, then you can produce a derivative SDK based on
+        the currently installed SDK fairly easily.
+        Use these steps:
+        <orderedlist>
+            <listitem><para>If necessary, install an extensible SDK that
+                you want to use as a base for your derivative SDK.
+                </para></listitem>
+            <listitem><para>Source the environment script for the SDK.
+                </para></listitem>
+            <listitem><para>Add the extra libraries or other components
+                you want by using the <filename>devtool add</filename>
+                command.
+                </para></listitem>
+            <listitem><para>Run the <filename>devtool build-sdk</filename>
+                command.
+                </para></listitem>
+        </orderedlist>
+        The above procedure takes the recipes added to the workspace and
+        constructs a new SDK installer containing those recipes and the
+        resulting binary artifacts.
+        The recipes go into their own separate layer in the constructed
+        derivative SDK, leaving the workspace clean and ready for you
+        to add your own recipes.
     </para>
 </section>
 
diff --git a/documentation/sdk-manual/sdk-intro.xml b/documentation/sdk-manual/sdk-intro.xml
index 36d946459d..d71aafeba1 100644
--- a/documentation/sdk-manual/sdk-intro.xml
+++ b/documentation/sdk-manual/sdk-intro.xml
@@ -46,6 +46,34 @@
     </para>
 
     <para>
+        SDKs are 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> and
+        <filename>populate_sdk_ext</filename> archives.
+    </para>
+
+    <para>
+        Another feature for the SDKs 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 such as
+        <ulink url='&YOCTO_DOCS_REF_URL;#var-CC'><filename>CC</filename></ulink>
+        and
+        <ulink url='&YOCTO_DOCS_REF_URL;#var-LD'><filename>LD</filename></ulink>.
+        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>
+
+    <para>
         Going beyond the actual SDK, the SDK development environment consists
         of the following:
         <itemizedlist>