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 @@
Customizing the SDK
-
- 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.
+
+ 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.
-
- I do not have a feel for what sub-topics need to be covered here.
- I need to get this information from Paul.
-
+
+ Configuring the Extensible SDK
+
+
+ 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 local.conf and
+ auto.conf when present:
+
+
+ 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.
+
+
+ Variables listed in
+ SDK_LOCAL_CONF_BLACKLIST
+ are excluded.
+ The default value blacklists
+ CONF_VERSION,
+ BB_NUMBER_THREADS,
+ PARALLEL_MAKE,
+ PRSERV_HOST,
+ and
+ SSTATE_MIRRORS.
+
+
+ Variables listed in
+ SDK_LOCAL_CONF_WHITELIST
+ are included.
+ Including these variables overrides either of the above two
+ conditions.
+ The default value is blank.
+
+
+ Classes inherited globally with
+ INHERIT
+ that are listed in
+ SDK_INHERIT_BLACKLIST
+ are disabled.
+ Using SDK_INHERIT_BLACKLIST 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
+ buildhistory
+ and
+ icecc
+ classes.
+
+
+ Additionally, the contents of conf/sdk-extra.conf,
+ when present, are appended to the end of
+ conf/local.conf 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.
+
+
+
+
+ Adjusting the Extensible SDK to Suit Your Build System Setup
+
+
+ In most cases, the extensible SDK defaults should work.
+ However, some cases exist for which you might consider making
+ adjustments:
+
+
+ If your SDK configuration inherits additional classes
+ using the
+ INHERIT
+ variable and you do not need or want those classes enabled in
+ the SDK, you can blacklist them by adding them to the
+ SDK_INHERIT_BLACKLIST
+ variable.
+ The default value of SDK_INHERIT_BLACKLIST
+ is set using the "?=" operator.
+ Consequently, you will need to either set the complete value
+ using "=" or append the value using "_append".
+
+
+ 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:
+
+
+ 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
+ SDK_RECRDEP_TASKS.
+
+
+ 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
+ SDK_INHERIT_BLACKLIST as previously
+ described.
+
+
+
+
+ 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
+ "Providing Additional Installable Extensible SDK Content"
+ section for information.
+
+
+ If you want users of the SDK to be able to easily update the
+ SDK, you need to set the
+ SDK_UPDATE_URL
+ variable.
+ For more information, see the
+ "Providing Updates After Installing the Extensible SDK"
+ section.
+
+
+ If you have adjusted the list of files and directories that
+ appear in
+ COREBASE
+ (other than layers that are enabled through
+ bblayers.conf), then must list these
+ files in
+ COREBASE_FILES
+ so that the files are copied into the SDK.
+
+
+ If your build system setup uses a different environment setup
+ script other than
+ &OE_INIT_FILE;
+ or
+ oe-init-build-env-memres,
+ then you must set
+ OE_INIT_ENV_SCRIPT
+ to point to the environment setup script you use.
+
+ You must also reflect this change in the value used for the
+ COREBASE_FILES variable as previously
+ described.
+
+
+
+
+
+
+
+ Changing the Appearance of the Extensible SDK
+
+
+ You can change the title shown by the SDK installer by setting the
+ SDK_TITLE
+ variable.
+ By default, this title is derived from
+ DISTRO_NAME
+ when it is set.
+ If the DISTRO_NAME variable is not set, the title
+ is derived from the
+ DISTRO
+ variable.
+
+
+
+
+ Providing Updates After Installing the Extensible SDK
+
+
+ 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
+ devtool sdk-update command:
+
+
+ Arrange to be created a directory that can be shared over
+ HTTP or HTTPS.
+
+
+ Set the
+ SDK_UPDATE_URL
+ 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
+ devtool sdk-update command.
+
+
+ Build the extensible SDK normally (i.e., use the
+ bitbake -c populate_sdk_extimagename
+ command).
+
+
+ Publish the SDK using the following command:
+
+ $ oe-publish-sdk some_path/sdk-installer.sh path_to_shared/http_directory
+
+ You must repeat this step each time you rebuild the SDK
+ with changes that you want to make available through the
+ update mechanism.
+
+
+
+
+
+ Completing the above steps allows users of the existing SDKs to
+ simply run devtool sdk-update to retrieve the
+ latest updates.
+ See the
+ "Updating the Extensible SDK"
+ section for further information.
+
+
+
+
+ Providing Additional Installable Extensible SDK Content
+
+
+ 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:
+
+
+ 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
+ EXCLUDE_FROM_WORLD_pn-recipename
+ for the recipes you do not want built.
+ See the
+ EXCLUDE_FROM_WORLD
+ variable for additional information.
+
+
+ Expose the sstate-cache directory
+ produced by the build.
+ Typically, you expose this directory over HTTP or HTTPS.
+
+
+ Set the appropriate configuration so that the produced SDK
+ knows how to find the configuration.
+ The variable you need to set is
+ SSTATE_MIRRORS:
+
+ SSTATE_MIRRORS = "file://.* http://example.com/some_path/sstate-cache/PATH"
+
+ You can set the SSTATE_MIRRORS variable
+ in two different places:
+
+
+ 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 local.conf
+ or custom distro configuration file.
+ You can "whitelist" the variable through the SDK by
+ adding the following:
+
+ SDK_LOCAL_CONF_WHITELIST = "SSTATE_MIRRORS"
+
+
+
+ Alternatively, if you just want to set the
+ SSTATE_MIRRORS variable's value
+ for the SDK alone, create a
+ conf/sdk-extra.conf either in
+ your
+ Build Directory
+ or within any layer and put your
+ SSTATE_MIRRORS setting within
+ that file.
+
+ This second option is the safest option should
+ you have any doubts as to which method to use when
+ setting SSTATE_MIRRORS.
+
+
+
+
+
+
+
+
+
+ Minimizing the Size of the Extensible SDK Installer Download
+
+
+ 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
+ devtool command by setting the following in your
+ configuration:
+
+ SDK_EXT_TYPE = "minimal"
+
+ Setting
+ SDK_EXT_TYPE
+ 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 devtool or explicitly with the
+ devtool sdk-install command.
+
+
+
+ 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 devtool add
+ is able to effectively map dependencies it discovers in a source tree
+ to the appropriate recipes.
+ Also so that the devtool search command
+ is able to return useful results.
+
+
+
+ To facilitate this wider range of information, you would additionally
+ set the following:
+
+ SDK_INCLUDE_PKGDATA = "1"
+
+ See the
+ SDK_INCLUDE_PKGDATA
+ variable for additional information.
+
+
+
+ Setting the SDK_INCLUDE_PKGDATA 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.
+
+
+
+ You can use
+ EXCLUDE_FROM_WORLD_pn-recipename
+ 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.
+
+ If you set SDK_EXT_TYPE to "minimal",
+ then providing a shared state mirror is mandatory so that items
+ can be installed as needed.
+ See the
+ "Providing Additional Installable Extensible SDK Content"
+ section for more information.
+
+
+