poky/documentation/sdk-manual/appendix-customizing.rst - stefanberger/openbmc - Gitiles

 .. SPDX-License-Identifier: CC-BY-SA-2.0-UK

 ***************************************************
 Customizing the Extensible SDK standalone installer
 ***************************************************

 This appendix describes customizations you can apply to the extensible
 SDK when using in the standalone installer version.

 .. note::

    It is also possible to use the Extensible SDK functionality directly in a
    Yocto build, avoiding separate installer artefacts. Please refer to
    ":ref:`sdk-manual/extensible:Installing the Extensible SDK`"

 Configuring the Extensible SDK
 ==============================

 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 ``local.conf`` and ``auto.conf``:

 -  Variables whose values start with "/" are excluded since the
    assumption is that those values are paths that are likely to be
    specific to the :term:`Build Host`.

 -  Variables listed in
    :term:`ESDK_LOCALCONF_REMOVE`
    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.

    For a list of the variables excluded by default, see the
    :term:`ESDK_LOCALCONF_REMOVE`
    in the glossary of the Yocto Project Reference Manual.

 -  Variables listed in
    :term:`ESDK_LOCALCONF_ALLOW`
    are included. Including a variable in the value of
    :term:`ESDK_LOCALCONF_ALLOW` overrides either of the previous two
    filters. The default value is blank.

 -  Classes inherited globally with
    :term:`INHERIT` that are listed in
    :term:`ESDK_CLASS_INHERIT_DISABLE`
    are disabled. Using :term:`ESDK_CLASS_INHERIT_DISABLE` to disable these
    classes is the typical method to disable classes that are problematic
    or unnecessary in the SDK context. The default value disables the
    :ref:`buildhistory <ref-classes-buildhistory>`
    and :ref:`icecc <ref-classes-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. The ``sdk-extra.conf`` 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.

 Adjusting the Extensible SDK to Suit Your Build Host's Setup
 ============================================================

 In most cases, the extensible SDK defaults should work with your :term:`Build
 Host`'s setup. However, there are cases when you might consider making
 adjustments:

 -  If your SDK configuration inherits additional classes using the
    :term:`INHERIT` variable and you
    do not need or want those classes enabled in the SDK, you can
    disable them by adding them to the :term:`ESDK_CLASS_INHERIT_DISABLE`
    variable as described in the previous section.

    .. note::

       The default value of
       ESDK_CLASS_INHERIT_DISABLE
       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
       ":ref:`bitbake:bitbake-user-manual/bitbake-user-manual-metadata:basic syntax`"
       section of the BitBake User Manual.

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

    -  After ensuring the tasks are :ref:`shared
       state <overview-manual/concepts:shared state cache>` 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
       :term:`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 the :term:`ESDK_CLASS_INHERIT_DISABLE`
       variable as described in the previous section.

 -  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
    ":ref:`sdk-manual/appendix-customizing: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
    :term:`SDK_UPDATE_URL`
    variable. For more information, see the
    ":ref:`sdk-manual/appendix-customizing:providing updates to the extensible sdk after installation`"
    section.

 -  If you have adjusted the list of files and directories that appear in
    :term:`COREBASE` (other than
    layers that are enabled through ``bblayers.conf``), then you must
    list these files in
    :term:`COREBASE_FILES` so
    that the files are copied into the SDK.

 -  If your OpenEmbedded build system setup uses a different environment
    setup script other than
    :ref:`structure-core-script`, then you must
    set
    :term:`OE_INIT_ENV_SCRIPT`
    to point to the environment setup script you use.

    .. note::

       You must also reflect this change in the value used for the
       :term:`COREBASE_FILES` variable as previously described.

 Changing the Extensible SDK Installer Title
 ===========================================

 You can change the displayed title for the SDK installer by setting the
 :term:`SDK_TITLE` variable and then
 rebuilding the SDK installer. For information on how to build an SDK
 installer, see the ":ref:`sdk-manual/appendix-obtain:building an sdk installer`"
 section.

 By default, this title is derived from
 :term:`DISTRO_NAME` when it is
 set. If the :term:`DISTRO_NAME` variable is not set, the title is derived
 from the :term:`DISTRO` variable.

 The
 :ref:`populate_sdk_base <ref-classes-populate-sdk-*>`
 class defines the default value of the :term:`SDK_TITLE` variable as
 follows::

    SDK_TITLE ??= "${@d.getVar('DISTRO_NAME') or d.getVar('DISTRO')} SDK"

 While there are several ways of changing 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
 :term:`SDK_TITLE` variable in the
 ``~/meta-mydistro/conf/distro/mydistro.conf`` file using the following
 form::

    SDK_TITLE = "your_title"

 Providing Updates to the Extensible SDK After Installation
 ==========================================================

 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
 ``devtool sdk-update`` command:

 1. Create a directory that can be shared over HTTP or HTTPS. You can do
    this by setting up a web server such as an `Apache HTTP
    Server <https://en.wikipedia.org/wiki/Apache_HTTP_Server>`__ or
    `Nginx <https://en.wikipedia.org/wiki/Nginx>`__ server in the cloud
    to host the directory. This directory must contain the published SDK.

 2. Set the
    :term:`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 as described in the
    ":ref:`sdk-manual/extensible:applying updates to an installed extensible sdk`"
    section.

 3. Build the extensible SDK normally (i.e., use the
    ``bitbake -c populate_sdk_ext`` imagename command).

 4. 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 installed SDKs
 to simply run ``devtool sdk-update`` to retrieve and apply the latest
 updates. See the
 ":ref:`sdk-manual/extensible:applying updates to an installed extensible sdk`"
 section for further information.

 Changing the Default SDK Installation Directory
 ===============================================

 When you build the installer for the Extensible SDK, the default
 installation directory for the SDK is based on the
 :term:`DISTRO` and
 :term:`SDKEXTPATH` variables from
 within the
 :ref:`populate_sdk_base <ref-classes-populate-sdk-*>`
 class as follows::

    SDKEXTPATH ??= "~/${@d.getVar('DISTRO')}_sdk"

 You can
 change this default installation directory by specifically setting the
 :term:`SDKEXTPATH` variable.

 While there are several ways of setting 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
 :term:`SDKEXTPATH` variable in the
 ``~/meta-mydistro/conf/distro/mydistro.conf`` file using the following
 form::

    SDKEXTPATH = "some_path_for_your_installed_sdk"

 After building your installer, running it prompts the user for
 acceptance of the some_path_for_your_installed_sdk directory as the
 default location to install the Extensible SDK.

 Providing Additional Installable Extensible SDK Content
 =======================================================

 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:

 1. Ensure the additional items you want the user to be able to install
    are already built:

    -  Build the items explicitly. You could use one or more "meta"
       recipes that depend on lists of other recipes.

    -  Build the "world" target and set
       ``EXCLUDE_FROM_WORLD:pn-``\ recipename for the recipes you do not
       want built. See the
       :term:`EXCLUDE_FROM_WORLD`
       variable for additional information.

 2. Expose the ``sstate-cache`` directory produced by the build.
    Typically, you expose this directory by making it available through
    an `Apache HTTP
    Server <https://en.wikipedia.org/wiki/Apache_HTTP_Server>`__ or
    `Nginx <https://en.wikipedia.org/wiki/Nginx>`__ server.

 3. Set the appropriate configuration so that the produced SDK knows how
    to find the configuration. The variable you need to set is
    :term:`SSTATE_MIRRORS`::

       SSTATE_MIRRORS = "file://.* https://example.com/some_path/sstate-cache/PATH"

    You can set the :term:`SSTATE_MIRRORS` variable in two different places:

    -  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 ``local.conf`` or custom distro
       configuration file. You can then pass the variable to the SDK by
       adding the following::

          ESDK_LOCALCONF_ALLOW = "SSTATE_MIRRORS"

    -  Alternatively, if you just want to set the :term:`SSTATE_MIRRORS`
       variable's value for the SDK alone, create a ``conf/sdk-extra.conf``
       file either in your :term:`Build Directory` or within any
       layer and put your :term:`SSTATE_MIRRORS` 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
          :term:`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
 :term:`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 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 ``devtool`` or explicitly with the
 ``devtool sdk-install`` command.

 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 ``devtool add`` is able to effectively map dependencies it
 discovers in a source tree to the appropriate recipes. Additionally, the
 information enables the ``devtool search`` command to return useful
 results.

 To facilitate this wider range of information, you would need to set the
 following::

    SDK_INCLUDE_PKGDATA = "1"

 See the :term:`SDK_INCLUDE_PKGDATA` variable for additional information.

 Setting the :term:`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.

 .. note::

    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
    :ref:`sdk-manual/appendix-customizing:providing additional installable extensible sdk content`
    section for more information.

 You can explicitly control whether or not to include the toolchain when
 you build an SDK by setting the
 :term:`SDK_INCLUDE_TOOLCHAIN`
 variable to "1". In particular, it is useful to include the toolchain
 when you have set :term:`SDK_EXT_TYPE` 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.
	.. SPDX-License-Identifier: CC-BY-SA-2.0-UK

	***************************************************
	Customizing the Extensible SDK standalone installer
	***************************************************

	This appendix describes customizations you can apply to the extensible
	SDK when using in the standalone installer version.

	.. note::

	It is also possible to use the Extensible SDK functionality directly in a
	Yocto build, avoiding separate installer artefacts. Please refer to
	":ref:`sdk-manual/extensible:Installing the Extensible SDK`"

	Configuring the Extensible SDK
	==============================

	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 ``local.conf`` and ``auto.conf``:

	- Variables whose values start with "/" are excluded since the
	assumption is that those values are paths that are likely to be
	specific to the :term:`Build Host`.

	- Variables listed in
	:term:`ESDK_LOCALCONF_REMOVE`
	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.

	For a list of the variables excluded by default, see the
	:term:`ESDK_LOCALCONF_REMOVE`
	in the glossary of the Yocto Project Reference Manual.

	- Variables listed in
	:term:`ESDK_LOCALCONF_ALLOW`
	are included. Including a variable in the value of
	:term:`ESDK_LOCALCONF_ALLOW` overrides either of the previous two
	filters. The default value is blank.

	- Classes inherited globally with
	:term:`INHERIT` that are listed in
	:term:`ESDK_CLASS_INHERIT_DISABLE`
	are disabled. Using :term:`ESDK_CLASS_INHERIT_DISABLE` to disable these
	classes is the typical method to disable classes that are problematic
	or unnecessary in the SDK context. The default value disables the
	:ref:`buildhistory <ref-classes-buildhistory>`
	and :ref:`icecc <ref-classes-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. The ``sdk-extra.conf`` 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.

	Adjusting the Extensible SDK to Suit Your Build Host's Setup
	============================================================

	In most cases, the extensible SDK defaults should work with your :term:`Build
	Host`'s setup. However, there are cases when you might consider making
	adjustments:

	- If your SDK configuration inherits additional classes using the
	:term:`INHERIT` variable and you
	do not need or want those classes enabled in the SDK, you can
	disable them by adding them to the :term:`ESDK_CLASS_INHERIT_DISABLE`
	variable as described in the previous section.

	.. note::

	The default value of
	ESDK_CLASS_INHERIT_DISABLE
	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
	":ref:`bitbake:bitbake-user-manual/bitbake-user-manual-metadata:basic syntax`"
	section of the BitBake User Manual.

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

	- After ensuring the tasks are :ref:`shared
	state <overview-manual/concepts:shared state cache>` 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
	:term:`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 the :term:`ESDK_CLASS_INHERIT_DISABLE`
	variable as described in the previous section.

	- 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
	":ref:`sdk-manual/appendix-customizing: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
	:term:`SDK_UPDATE_URL`
	variable. For more information, see the
	":ref:`sdk-manual/appendix-customizing:providing updates to the extensible sdk after installation`"
	section.

	- If you have adjusted the list of files and directories that appear in
	:term:`COREBASE` (other than
	layers that are enabled through ``bblayers.conf``), then you must
	list these files in
	:term:`COREBASE_FILES` so
	that the files are copied into the SDK.

	- If your OpenEmbedded build system setup uses a different environment
	setup script other than
	:ref:`structure-core-script`, then you must
	set
	:term:`OE_INIT_ENV_SCRIPT`
	to point to the environment setup script you use.

	.. note::

	You must also reflect this change in the value used for the
	:term:`COREBASE_FILES` variable as previously described.

	Changing the Extensible SDK Installer Title
	===========================================

	You can change the displayed title for the SDK installer by setting the
	:term:`SDK_TITLE` variable and then
	rebuilding the SDK installer. For information on how to build an SDK
	installer, see the ":ref:`sdk-manual/appendix-obtain:building an sdk installer`"
	section.

	By default, this title is derived from
	:term:`DISTRO_NAME` when it is
	set. If the :term:`DISTRO_NAME` variable is not set, the title is derived
	from the :term:`DISTRO` variable.

	The
	:ref:`populate_sdk_base <ref-classes-populate-sdk-*>`
	class defines the default value of the :term:`SDK_TITLE` variable as
	follows::

	SDK_TITLE ??= "${@d.getVar('DISTRO_NAME') or d.getVar('DISTRO')} SDK"

	While there are several ways of changing 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
	:term:`SDK_TITLE` variable in the
	``~/meta-mydistro/conf/distro/mydistro.conf`` file using the following
	form::

	SDK_TITLE = "your_title"

	Providing Updates to the Extensible SDK After Installation
	==========================================================

	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
	``devtool sdk-update`` command:

	1. Create a directory that can be shared over HTTP or HTTPS. You can do
	this by setting up a web server such as an `Apache HTTP
	Server <https://en.wikipedia.org/wiki/Apache_HTTP_Server>`__ or
	`Nginx <https://en.wikipedia.org/wiki/Nginx>`__ server in the cloud
	to host the directory. This directory must contain the published SDK.

	2. Set the
	:term:`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 as described in the
	":ref:`sdk-manual/extensible:applying updates to an installed extensible sdk`"
	section.

	3. Build the extensible SDK normally (i.e., use the
	``bitbake -c populate_sdk_ext`` imagename command).

	4. 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 installed SDKs
	to simply run ``devtool sdk-update`` to retrieve and apply the latest
	updates. See the
	":ref:`sdk-manual/extensible:applying updates to an installed extensible sdk`"
	section for further information.

	Changing the Default SDK Installation Directory
	===============================================

	When you build the installer for the Extensible SDK, the default
	installation directory for the SDK is based on the
	:term:`DISTRO` and
	:term:`SDKEXTPATH` variables from
	within the
	:ref:`populate_sdk_base <ref-classes-populate-sdk-*>`
	class as follows::

	SDKEXTPATH ??= "~/${@d.getVar('DISTRO')}_sdk"

	You can
	change this default installation directory by specifically setting the
	:term:`SDKEXTPATH` variable.

	While there are several ways of setting 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
	:term:`SDKEXTPATH` variable in the
	``~/meta-mydistro/conf/distro/mydistro.conf`` file using the following
	form::

	SDKEXTPATH = "some_path_for_your_installed_sdk"

	After building your installer, running it prompts the user for
	acceptance of the some_path_for_your_installed_sdk directory as the
	default location to install the Extensible SDK.

	Providing Additional Installable Extensible SDK Content
	=======================================================

	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:

	1. Ensure the additional items you want the user to be able to install
	are already built:

	- Build the items explicitly. You could use one or more "meta"
	recipes that depend on lists of other recipes.

	- Build the "world" target and set
	``EXCLUDE_FROM_WORLD:pn-``\ recipename for the recipes you do not
	want built. See the
	:term:`EXCLUDE_FROM_WORLD`
	variable for additional information.

	2. Expose the ``sstate-cache`` directory produced by the build.
	Typically, you expose this directory by making it available through
	an `Apache HTTP
	Server <https://en.wikipedia.org/wiki/Apache_HTTP_Server>`__ or
	`Nginx <https://en.wikipedia.org/wiki/Nginx>`__ server.

	3. Set the appropriate configuration so that the produced SDK knows how
	to find the configuration. The variable you need to set is
	:term:`SSTATE_MIRRORS`::

	SSTATE_MIRRORS = "file://.* https://example.com/some_path/sstate-cache/PATH"

	You can set the :term:`SSTATE_MIRRORS` variable in two different places:

	- 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 ``local.conf`` or custom distro
	configuration file. You can then pass the variable to the SDK by
	adding the following::

	ESDK_LOCALCONF_ALLOW = "SSTATE_MIRRORS"

	- Alternatively, if you just want to set the :term:`SSTATE_MIRRORS`
	variable's value for the SDK alone, create a ``conf/sdk-extra.conf``
	file either in your :term:`Build Directory` or within any
	layer and put your :term:`SSTATE_MIRRORS` 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
	:term:`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
	:term:`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 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 ``devtool`` or explicitly with the
	``devtool sdk-install`` command.

	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 ``devtool add`` is able to effectively map dependencies it
	discovers in a source tree to the appropriate recipes. Additionally, the
	information enables the ``devtool search`` command to return useful
	results.

	To facilitate this wider range of information, you would need to set the
	following::

	SDK_INCLUDE_PKGDATA = "1"

	See the :term:`SDK_INCLUDE_PKGDATA` variable for additional information.

	Setting the :term:`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.

	.. note::

	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
	:ref:`sdk-manual/appendix-customizing:providing additional installable extensible sdk content`
	section for more information.

	You can explicitly control whether or not to include the toolchain when
	you build an SDK by setting the
	:term:`SDK_INCLUDE_TOOLCHAIN`
	variable to "1". In particular, it is useful to include the toolchain
	when you have set :term:`SDK_EXT_TYPE` 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.