[gnome-continuous-yocto/gnomeostree-3.28-rocko: 3356/8267] documentation: Added new appendix for customizing standard SDK

[Emmanuele Bassi <ebassi src gnome org>]

commit d2523d535f2ed7a5e76f754087cd6256d3483db3
Author: Scott Rifenbark <srifenbark gmail com>
Date:   Tue Nov 15 09:40:34 2016 -0800

    documentation: Added new appendix for customizing standard SDK
    
    Fixes [YOCTO #8584]
    
    This fix essentially had to document how to add the API
    documentation to the standard SDK.  The fix required adding a
    new appendix to the SDK manual on how to customize that
    standard SDK.  I could not put just one topic in a new appendix
    so I also added a sub-section on how to add indidual packages
    to the standard SDK.
    
    Other changes here were the introduction of a new file for the new
    appendix, updated the mega-manual.xml file so that it would include
    the new chapter when the MM was built.  Finally, I added some
    cross-referencing to the new appendix from the TOOLCHAIN_HOST_TASK
    and TOOLCHAIN_TARGET_TASK variables.  And a cross reference from the
    distro features section on the api-documentation bullet.
    
    (From yocto-docs rev: 1fb4321ae42253d1fc9602496b5e9e8b495197dd)
    
    Signed-off-by: Scott Rifenbark <srifenbark gmail com>
    Signed-off-by: Richard Purdie <richard purdie linuxfoundation org>

 documentation/mega-manual/mega-manual.xml          |    2 +
 documentation/ref-manual/ref-features.xml          |    4 +
 documentation/ref-manual/ref-variables.xml         |   10 +++
 .../sdk-appendix-customizing-standard.xml          |   63 ++++++++++++++++++++
 documentation/sdk-manual/sdk-manual.xml            |    2 +
 5 files changed, 81 insertions(+), 0 deletions(-)
---
diff --git a/documentation/mega-manual/mega-manual.xml b/documentation/mega-manual/mega-manual.xml
index c16e928..eba8b8d 100644
--- a/documentation/mega-manual/mega-manual.xml
+++ b/documentation/mega-manual/mega-manual.xml
@@ -126,6 +126,8 @@
     <xi:include
         xmlns:xi="http://www.w3.org/2003/XInclude"; href="../sdk-manual/sdk-appendix-customizing.xml"/>
     <xi:include
+        xmlns:xi="http://www.w3.org/2003/XInclude"; 
href="../sdk-manual/sdk-appendix-customizing-standard.xml"/>
+    <xi:include
         xmlns:xi="http://www.w3.org/2003/XInclude"; href="../sdk-manual/sdk-appendix-mars.xml"/>
 
 <!-- Includes bsp-guide title image and then bsp-guide chapters -->
diff --git a/documentation/ref-manual/ref-features.xml b/documentation/ref-manual/ref-features.xml
index 03ff9ad..282a517 100644
--- a/documentation/ref-manual/ref-features.xml
+++ b/documentation/ref-manual/ref-features.xml
@@ -149,6 +149,10 @@
                     when the
                     <filename>bitbake -c populate_sdk</filename> command
                     is used.
+                    See the
+                    "<ulink url='&YOCTO_DOCS_SDK_URL;#adding-api-documentation-to-the-standard-sdk'>Adding 
API Documentation to the Standard SDK</ulink>"
+                    section in the Yocto Project Software Development Kit (SDK)
+                    Developer's Guide for more information.
                     </para></listitem>
                 <listitem><para><emphasis>bluetooth:</emphasis> Include
                     bluetooth support (integrated BT only).</para></listitem>
diff --git a/documentation/ref-manual/ref-variables.xml b/documentation/ref-manual/ref-variables.xml
index f0384a8..9d6fab0 100644
--- a/documentation/ref-manual/ref-variables.xml
+++ b/documentation/ref-manual/ref-variables.xml
@@ -14426,6 +14426,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
                     </literallayout>
                     In this case, a default list of packages is set in this
                     variable, but you can add additional packages to the list.
+                    See the
+                    "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-adding-individual-packages'>Adding Individual 
Packages to the Standard SDK</ulink>"
+                    section in the Yocto Project Software Development Kit (SDK)
+                    Developer's Guide for more information.
                 </para>
 
                 <para>
@@ -14477,6 +14481,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
                     uses when it creates the target part of an SDK
                     (i.e. the part built for the target hardware), which
                     includes libraries and headers.
+                    Use this variable to add individual packages to the
+                    part of the SDK that runs on the target.
+                    See the
+                    "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-adding-individual-packages'>Adding Individual 
Packages to the Standard SDK</ulink>"
+                    section in the Yocto Project Software Development Kit (SDK)
+                    Developer's Guide for more information.
                 </para>
 
                 <para>
diff --git a/documentation/sdk-manual/sdk-appendix-customizing-standard.xml 
b/documentation/sdk-manual/sdk-appendix-customizing-standard.xml
new file mode 100644
index 0000000..fd903e3
--- /dev/null
+++ b/documentation/sdk-manual/sdk-appendix-customizing-standard.xml
@@ -0,0 +1,63 @@
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd";
+[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
+
+<appendix id='sdk-appendix-customizing-standard'>
+
+<title>Customizing the Standard SDK</title>
+
+<para>
+    This appendix presents customizations you can apply to the standard SDK.
+</para>
+
+<section id='sdk-adding-individual-packages'>
+    <title>Adding Individual Packages to the Standard SDK</title>
+
+    <para>
+         When you build a standard SDK using the
+         <filename>bitbake -c populate_sdk</filename>, a default set of
+         packages is included in the resulting SDK.
+         The
+         <ulink 
url='&YOCTO_DOCS_REF_URL;#var-TOOLCHAIN_HOST_TASK'><filename>TOOLCHAIN_HOST_TASK</filename></ulink>
+         and
+         <ulink 
url='&YOCTO_DOCS_REF_URL;#var-TOOLCHAIN_TARGET_TASK'><filename>TOOLCHAIN_TARGET_TASK</filename></ulink>
+         variables contol the set of packages adding to the SDK.
+    </para>
+
+    <para>
+        If you want to add individual packages to the toolchain that runs on
+        the host, simply add those packages to the
+        <filename>TOOLCHAIN_HOST_TASK</filename> variable.
+        Similarly, if you want to add packages to the default set that is
+        part of the toolchain that runs on the target, add the packages to the
+        <filename>TOOLCHAIN_TARGET_TASK</filename> variable.
+    </para>
+</section>
+
+<section id='adding-api-documentation-to-the-standard-sdk'>
+    <title>Adding API Documentation to the Standard SDK</title>
+
+    <para>
+        You might want to include documentation as part of the standard SDK.
+        For example, you might want the API documentation to be built and
+        included with the SDK.
+        You can include API documentation as well as any other documentation
+        with the standard SDK by setting the
+        <ulink 
url='&YOCTO_DOCS_REF_URL;#var-SDKIMAGE_FEATURES'><filename>SDKIMAGE_FEATURES</filename></ulink>
+        and
+        <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></ulink>
+        variables:
+        <literallayout class='monospaced'>
+     SDKIMAGE_FEATURES = "doc-pkgs"
+     DISTRO_FEATURES = "api-documentation"
+        </literallayout>
+        Setting these variables as shown here causes the OpenEmbedded build
+        system to build the documentation and then include it in the
+        standard SDK.
+    </para>
+</section>
+
+</appendix>
+<!--
+vim: expandtab tw=80 ts=4
+-->
diff --git a/documentation/sdk-manual/sdk-manual.xml b/documentation/sdk-manual/sdk-manual.xml
index 6c72a03..1b4e198 100644
--- a/documentation/sdk-manual/sdk-manual.xml
+++ b/documentation/sdk-manual/sdk-manual.xml
@@ -76,6 +76,8 @@
 
     <xi:include href="sdk-appendix-customizing.xml"/>
 
+    <xi:include href="sdk-appendix-customizing-standard.xml"/>
+
     <xi:include href="sdk-appendix-mars.xml"/>
 
 <!--    <index id='index'>