poky/documentation/sdk-manual/sdk-appendix-customizing.xml - mdmillerii/openbmc - Gitiles

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

 <title>Customizing the Extensible SDK</title>

 <para>
     This appendix describes customizations you can apply to the extensible SDK.
 </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 OpenEmbedded build system from which it was produced.
         Thus, the SDK's configuration is derived using that build system and
         the filters shown in the following list.
         When these filters are present, the OpenEmbedded build system applies
         them against <filename>local.conf</filename> and
         <filename>auto.conf</filename>:
         <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
                 <ulink url='&YOCTO_DOCS_REF_URL;#hardware-build-system-term'>build host</ulink>.
                 </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.
                 These variables are not allowed through from the OpenEmbedded
                 build system configuration into the extensible SDK
                 configuration.
                 Typically, these variables are specific to the machine on
                 which the build system is running and could be problematic
                 as part of the extensible SDK configuration.</para>

                 <para>For a list of the variables excluded by default, see the
                 <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_LOCAL_CONF_BLACKLIST'><filename>SDK_LOCAL_CONF_BLACKLIST</filename></ulink>
                 in the glossary of the Yocto Project Reference Manual.
                 </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 a variable in the value of
                 <filename>SDK_LOCAL_CONF_WHITELIST</filename> overrides either
                 of the previous two filters.
                 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 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.
         The <filename>sdk-extra.conf</filename> file is particularly useful
         if you want to set a variable value just for the SDK and not the
         OpenEmbedded build system used to create the SDK.
     </para>
 </section>

 <section id='adjusting-the-extensible-sdk-to-suit-your-build-hosts-setup'>
     <title>Adjusting the Extensible SDK to Suit Your Build Host's Setup</title>

     <para>
         In most cases, the extensible SDK defaults should work with your
         <ulink url='&YOCTO_DOCS_REF_URL;#hardware-build-system-term'>build host's</ulink>
         setup.
         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 as described in the fourth bullet of the previous
                 section.
                 <note>
                     The default value of
                     <filename>SDK_INHERIT_BLACKLIST</filename> is set using
                     the "?=" operator.
                     Consequently, you will need to either define the entire
                     list by using the "=" operator, or you will need to append
                     a value using either "_append" or the "+=" operator.
                     You can learn more about these operators in the
                     "<ulink url='&YOCTO_DOCS_BB_URL;#basic-syntax'>Basic Syntax</ulink>"
                     section of the BitBake User Manual.
                 </note>.
                 </para></listitem>
             <listitem><para>
                 If you have classes or recipes that add additional tasks to
                 the standard build flow (i.e. the tasks execute as the recipe
                 builds as opposed to being called explicitly), then you need
                 to do one of the following:
                 <itemizedlist>
                     <listitem><para>
                         After ensuring the tasks are
                         <ulink url='&YOCTO_DOCS_OM_URL;#shared-state-cache'>shared state</ulink>
                         tasks (i.e. the output of the task is saved to and
                         can be restored from the shared state cache) or
                         ensuring the tasks are able to be produced quickly from
                         a task that is a shared state task, 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 the
                         <filename>SDK_INHERIT_BLACKLIST</filename> variable
                         as described in the previous section.
                         </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-to-the-extensible-sdk-after-installation'>Providing Updates to the Extensible SDK After Installation</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 you 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 OpenEmbedded 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>,
                 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-sdk-installer-title'>
     <title>Changing the Extensible SDK Installer Title</title>

     <para>
         You can change the displayed title for the SDK installer by setting
         the
         <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_TITLE'><filename>SDK_TITLE</filename></ulink>
         variable and then rebuilding the the SDK installer.
         For information on how to build an SDK installer, see the
         "<link linkend='sdk-building-an-sdk-installer'>Building an SDK Installer</link>"
         section.
     </para>

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

     <para>
         The
         <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-populate-sdk-*'><filename>populate_sdk_base</filename></ulink>
         class defines the default value of the <filename>SDK_TITLE</filename>
         variable as follows:
         <literallayout class='monospaced'>
      SDK_TITLE ??= "${@d.getVar('DISTRO_NAME') or d.getVar('DISTRO')} SDK"
         </literallayout>
     </para>

     <para>
         While several ways exist to change this variable, an efficient method
         is to set the variable in your distribution's configuration file.
         Doing so creates an SDK installer title that applies across your
         distribution.
         As an example, assume you have your own layer for your distribution
         named "meta-mydistro" and you are using the same type of file
         hierarchy as does the default "poky" distribution.
         If so, you could update the <filename>SDK_TITLE</filename> variable
         in the
         <filename>~/meta-mydistro/conf/distro/mydistro.conf</filename> file
         using the following form:
         <literallayout class='monospaced'>
      SDK_TITLE = "<replaceable>your_title</replaceable>"
         </literallayout>
     </para>
 </section>

 <section id='sdk-providing-updates-to-the-extensible-sdk-after-installation'>
     <title>Providing Updates to the Extensible SDK After Installation</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.
         These steps make it possible for anyone using the installed SDKs to
         update the installed SDKs by using the
         <filename>devtool sdk-update</filename> command:
         <orderedlist>
             <listitem><para>
                 Create a directory that can be shared over HTTP or HTTPS.
                 You can do this by setting up a web server such as an
                 <ulink url='https://en.wikipedia.org/wiki/Apache_HTTP_Server'>Apache HTTP Server</ulink>
                 or
                 <ulink url='https://en.wikipedia.org/wiki/Nginx'>Nginx</ulink>
                 server in the cloud to host the directory.
                 This directory must contain the published SDK.
                 </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 as described
                 in the
                 "<link linkend='sdk-applying-updates-to-an-installed-extensible-sdk'>Applying Updates to an Installed Extensible SDK</link>"
                 section.
                 </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 installed
         SDKs to simply run <filename>devtool sdk-update</filename> to
         retrieve and apply the latest updates.
         See the
         "<link linkend='sdk-applying-updates-to-an-installed-extensible-sdk'>Applying Updates to an Installed Extensible SDK</link>"
         section for further information.
     </para>
 </section>

 <section id='sdk-changing-the-default-sdk-installation-directory'>
     <title>Changing the Default SDK Installation Directory</title>

     <para>
         When you build the installer for the Extensible SDK, the default
         installation directory for the SDK is based on the
         <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO'><filename>DISTRO</filename></ulink>
         and
         <ulink url='&YOCTO_DOCS_REF_URL;#var-SDKEXTPATH'><filename>SDKEXTPATH</filename></ulink>
         variables from within the
         <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-populate-sdk-*'><filename>populate_sdk_base</filename></ulink>
         class as follows:
         <literallayout class='monospaced'>
      SDKEXTPATH ??= "~/${@d.getVar('DISTRO')}_sdk"
         </literallayout>
         You can change this default installation directory by specifically
         setting the <filename>SDKEXTPATH</filename> variable.
     </para>

     <para>
         While a number of ways exist through which you can set this variable,
         the method that makes the most sense is to set the variable in your
         distribution's configuration file.
         Doing so creates an SDK installer default directory that applies
         across your distribution.
         As an example, assume you have your own layer for your distribution
         named "meta-mydistro" and you are using the same type of file
         hierarchy as does the default "poky" distribution.
         If so, you could update the <filename>SDKEXTPATH</filename> variable
         in the
         <filename>~/meta-mydistro/conf/distro/mydistro.conf</filename> file
         using the following form:
         <literallayout class='monospaced'>
      SDKEXTPATH = "<replaceable>some_path_for_your_installed_sdk</replaceable>"
         </literallayout>
     </para>

     <para>
         After building your installer, running it prompts the user for
         acceptance of the
         <replaceable>some_path_for_your_installed_sdk</replaceable> directory
         as the default location to install the Extensible SDK.
     </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 an extensible SDK you build to be
         able to add items to the SDK without requiring the users 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 already built:
                 <itemizedlist>
                     <listitem><para>
                         Build the items explicitly.
                         You could use one or more "meta" recipes that depend
                         on lists of other recipes.
                         </para></listitem>
                     <listitem><para>
                         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>
                 </itemizedlist>
                 </para></listitem>
             <listitem><para>
                 Expose the <filename>sstate-cache</filename> directory
                 produced by the build.
                 Typically, you expose this directory by making it available
                 through an
                 <ulink url='https://en.wikipedia.org/wiki/Apache_HTTP_Server'>Apache HTTP Server</ulink>
                 or
                 <ulink url='https://en.wikipedia.org/wiki/Nginx'>Nginx</ulink>
                 server.
                 </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 OpenEmbedded 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 OpenEmbedded 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 then "whitelist" the variable through
                         to 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> file either in
                         your
                         <ulink url='&YOCTO_DOCS_REF_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 minimal installer does not
         install any libraries or tools out of the box.
         These libraries and tools 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 need to also enable
         bringing in the information on a wider range of packages produced by
         the system.
         Requiring this wider range of information 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.
         Additionally, the information enables the
         <filename>devtool search</filename> command to return useful results.
     </para>

     <para>
         To facilitate this wider range of information, you would need to
         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>

     <para>
         You can explicitly control whether or not to include the toolchain
         when you build an SDK by setting the
         <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_INCLUDE_TOOLCHAIN'><filename>SDK_INCLUDE_TOOLCHAIN</filename></ulink>
         variable to "1".
         In particular, it is useful to include the toolchain when you
         have set <filename>SDK_EXT_TYPE</filename> to "minimal", which by
         default, excludes the toolchain.
         Also, it is helpful if you are building a small SDK for use with
         an IDE, such as <trademark class='trade'>Eclipse</trademark>, or some
         other tool where you do not want to take extra steps to install a
         toolchain.
     </para>
 </section>
 </appendix>
 <!--
 vim: expandtab tw=80 ts=4
 -->
	<!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'>

	<title>Customizing the Extensible SDK</title>

	<para>
	This appendix describes customizations you can apply to the extensible SDK.
	</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 OpenEmbedded build system from which it was produced.
	Thus, the SDK's configuration is derived using that build system and
	the filters shown in the following list.
	When these filters are present, the OpenEmbedded build system applies
	them against <filename>local.conf</filename> and
	<filename>auto.conf</filename>:
	<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
	<ulink url='&YOCTO_DOCS_REF_URL;#hardware-build-system-term'>build host</ulink>.
	</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.
	These variables are not allowed through from the OpenEmbedded
	build system configuration into the extensible SDK
	configuration.
	Typically, these variables are specific to the machine on
	which the build system is running and could be problematic
	as part of the extensible SDK configuration.</para>

	<para>For a list of the variables excluded by default, see the
	<ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_LOCAL_CONF_BLACKLIST'><filename>SDK_LOCAL_CONF_BLACKLIST</filename></ulink>
	in the glossary of the Yocto Project Reference Manual.
	</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 a variable in the value of
	<filename>SDK_LOCAL_CONF_WHITELIST</filename> overrides either
	of the previous two filters.
	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 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.
	The <filename>sdk-extra.conf</filename> file is particularly useful
	if you want to set a variable value just for the SDK and not the
	OpenEmbedded build system used to create the SDK.
	</para>
	</section>

	<section id='adjusting-the-extensible-sdk-to-suit-your-build-hosts-setup'>
	<title>Adjusting the Extensible SDK to Suit Your Build Host's Setup</title>

	<para>
	In most cases, the extensible SDK defaults should work with your
	<ulink url='&YOCTO_DOCS_REF_URL;#hardware-build-system-term'>build host's</ulink>
	setup.
	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 as described in the fourth bullet of the previous
	section.
	<note>
	The default value of
	<filename>SDK_INHERIT_BLACKLIST</filename> is set using
	the "?=" operator.
	Consequently, you will need to either define the entire
	list by using the "=" operator, or you will need to append
	a value using either "_append" or the "+=" operator.
	You can learn more about these operators in the
	"<ulink url='&YOCTO_DOCS_BB_URL;#basic-syntax'>Basic Syntax</ulink>"
	section of the BitBake User Manual.
	</note>.
	</para></listitem>
	<listitem><para>
	If you have classes or recipes that add additional tasks to
	the standard build flow (i.e. the tasks execute as the recipe
	builds as opposed to being called explicitly), then you need
	to do one of the following:
	<itemizedlist>
	<listitem><para>
	After ensuring the tasks are
	<ulink url='&YOCTO_DOCS_OM_URL;#shared-state-cache'>shared state</ulink>
	tasks (i.e. the output of the task is saved to and
	can be restored from the shared state cache) or
	ensuring the tasks are able to be produced quickly from
	a task that is a shared state task, 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 the
	<filename>SDK_INHERIT_BLACKLIST</filename> variable
	as described in the previous section.
	</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-to-the-extensible-sdk-after-installation'>Providing Updates to the Extensible SDK After Installation</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 you 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 OpenEmbedded 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>,
	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-sdk-installer-title'>
	<title>Changing the Extensible SDK Installer Title</title>

	<para>
	You can change the displayed title for the SDK installer by setting
	the
	<ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_TITLE'><filename>SDK_TITLE</filename></ulink>
	variable and then rebuilding the the SDK installer.
	For information on how to build an SDK installer, see the
	"<link linkend='sdk-building-an-sdk-installer'>Building an SDK Installer</link>"
	section.
	</para>

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

	<para>
	The
	<ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-populate-sdk-*'><filename>populate_sdk_base</filename></ulink>
	class defines the default value of the <filename>SDK_TITLE</filename>
	variable as follows:
	<literallayout class='monospaced'>
	SDK_TITLE ??= "${@d.getVar('DISTRO_NAME') or d.getVar('DISTRO')} SDK"
	</literallayout>
	</para>

	<para>
	While several ways exist to change this variable, an efficient method
	is to set the variable in your distribution's configuration file.
	Doing so creates an SDK installer title that applies across your
	distribution.
	As an example, assume you have your own layer for your distribution
	named "meta-mydistro" and you are using the same type of file
	hierarchy as does the default "poky" distribution.
	If so, you could update the <filename>SDK_TITLE</filename> variable
	in the
	<filename>~/meta-mydistro/conf/distro/mydistro.conf</filename> file
	using the following form:
	<literallayout class='monospaced'>
	SDK_TITLE = "<replaceable>your_title</replaceable>"
	</literallayout>
	</para>
	</section>

	<section id='sdk-providing-updates-to-the-extensible-sdk-after-installation'>
	<title>Providing Updates to the Extensible SDK After Installation</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.
	These steps make it possible for anyone using the installed SDKs to
	update the installed SDKs by using the
	<filename>devtool sdk-update</filename> command:
	<orderedlist>
	<listitem><para>
	Create a directory that can be shared over HTTP or HTTPS.
	You can do this by setting up a web server such as an
	<ulink url='https://en.wikipedia.org/wiki/Apache_HTTP_Server'>Apache HTTP Server</ulink>
	or
	<ulink url='https://en.wikipedia.org/wiki/Nginx'>Nginx</ulink>
	server in the cloud to host the directory.
	This directory must contain the published SDK.
	</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 as described
	in the
	"<link linkend='sdk-applying-updates-to-an-installed-extensible-sdk'>Applying Updates to an Installed Extensible SDK</link>"
	section.
	</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 installed
	SDKs to simply run <filename>devtool sdk-update</filename> to
	retrieve and apply the latest updates.
	See the
	"<link linkend='sdk-applying-updates-to-an-installed-extensible-sdk'>Applying Updates to an Installed Extensible SDK</link>"
	section for further information.
	</para>
	</section>

	<section id='sdk-changing-the-default-sdk-installation-directory'>
	<title>Changing the Default SDK Installation Directory</title>

	<para>
	When you build the installer for the Extensible SDK, the default
	installation directory for the SDK is based on the
	<ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO'><filename>DISTRO</filename></ulink>
	and
	<ulink url='&YOCTO_DOCS_REF_URL;#var-SDKEXTPATH'><filename>SDKEXTPATH</filename></ulink>
	variables from within the
	<ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-populate-sdk-*'><filename>populate_sdk_base</filename></ulink>
	class as follows:
	<literallayout class='monospaced'>
	SDKEXTPATH ??= "~/${@d.getVar('DISTRO')}_sdk"
	</literallayout>
	You can change this default installation directory by specifically
	setting the <filename>SDKEXTPATH</filename> variable.
	</para>

	<para>
	While a number of ways exist through which you can set this variable,
	the method that makes the most sense is to set the variable in your
	distribution's configuration file.
	Doing so creates an SDK installer default directory that applies
	across your distribution.
	As an example, assume you have your own layer for your distribution
	named "meta-mydistro" and you are using the same type of file
	hierarchy as does the default "poky" distribution.
	If so, you could update the <filename>SDKEXTPATH</filename> variable
	in the
	<filename>~/meta-mydistro/conf/distro/mydistro.conf</filename> file
	using the following form:
	<literallayout class='monospaced'>
	SDKEXTPATH = "<replaceable>some_path_for_your_installed_sdk</replaceable>"
	</literallayout>
	</para>

	<para>
	After building your installer, running it prompts the user for
	acceptance of the
	<replaceable>some_path_for_your_installed_sdk</replaceable> directory
	as the default location to install the Extensible SDK.
	</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 an extensible SDK you build to be
	able to add items to the SDK without requiring the users 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 already built:
	<itemizedlist>
	<listitem><para>
	Build the items explicitly.
	You could use one or more "meta" recipes that depend
	on lists of other recipes.
	</para></listitem>
	<listitem><para>
	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>
	</itemizedlist>
	</para></listitem>
	<listitem><para>
	Expose the <filename>sstate-cache</filename> directory
	produced by the build.
	Typically, you expose this directory by making it available
	through an
	<ulink url='https://en.wikipedia.org/wiki/Apache_HTTP_Server'>Apache HTTP Server</ulink>
	or
	<ulink url='https://en.wikipedia.org/wiki/Nginx'>Nginx</ulink>
	server.
	</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 OpenEmbedded 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 OpenEmbedded 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 then "whitelist" the variable through
	to 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> file either in
	your
	<ulink url='&YOCTO_DOCS_REF_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 minimal installer does not
	install any libraries or tools out of the box.
	These libraries and tools 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 need to also enable
	bringing in the information on a wider range of packages produced by
	the system.
	Requiring this wider range of information 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.
	Additionally, the information enables the
	<filename>devtool search</filename> command to return useful results.
	</para>

	<para>
	To facilitate this wider range of information, you would need to
	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>

	<para>
	You can explicitly control whether or not to include the toolchain
	when you build an SDK by setting the
	<ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_INCLUDE_TOOLCHAIN'><filename>SDK_INCLUDE_TOOLCHAIN</filename></ulink>
	variable to "1".
	In particular, it is useful to include the toolchain when you
	have set <filename>SDK_EXT_TYPE</filename> to "minimal", which by
	default, excludes the toolchain.
	Also, it is helpful if you are building a small SDK for use with
	an IDE, such as <trademark class='trade'>Eclipse</trademark>, or some
	other tool where you do not want to take extra steps to install a
	toolchain.
	</para>
	</section>
	</appendix>
	<!--
	vim: expandtab tw=80 ts=4
	-->