Revert "poky: subtree update:b23aa6b753..ad30a6d470"
This reverts commit af5e4ef732faedf66c6dc1756432e9de2ac72988.
This commit introduced openbmc/openbmc#3720 and no solution has been
forthcoming. Revert until we can get to the bottom of this.
Change-Id: I2fb0d81eb26cf3dadb2f2abdd1a1bb7a95eaf03c
diff --git a/poky/documentation/sdk-manual/sdk-appendix-customizing.xml b/poky/documentation/sdk-manual/sdk-appendix-customizing.xml
new file mode 100644
index 0000000..08054f8
--- /dev/null
+++ b/poky/documentation/sdk-manual/sdk-appendix-customizing.xml
@@ -0,0 +1,515 @@
+<!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; ] >
+<!--SPDX-License-Identifier: CC-BY-2.0-UK-->
+
+<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 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
+-->