diff options
Diffstat (limited to 'documentation/sdk-manual/appendix-customizing.rst')
| -rw-r--r-- | documentation/sdk-manual/appendix-customizing.rst | 137 |
1 files changed, 65 insertions, 72 deletions
diff --git a/documentation/sdk-manual/appendix-customizing.rst b/documentation/sdk-manual/appendix-customizing.rst index fb2d78452b..61091d83ba 100644 --- a/documentation/sdk-manual/appendix-customizing.rst +++ b/documentation/sdk-manual/appendix-customizing.rst @@ -1,11 +1,17 @@ .. SPDX-License-Identifier: CC-BY-SA-2.0-UK -****************************** -Customizing the Extensible SDK -****************************** +*************************************************** +Customizing the Extensible SDK standalone installer +*************************************************** This appendix describes customizations you can apply to the extensible -SDK. +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 ============================== @@ -21,7 +27,7 @@ build system applies them against ``local.conf`` and ``auto.conf``: specific to the :term:`Build Host`. - Variables listed in - :term:`SDK_LOCAL_CONF_BLACKLIST` + :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 @@ -29,23 +35,21 @@ build system applies them against ``local.conf`` and ``auto.conf``: of the extensible SDK configuration. For a list of the variables excluded by default, see the - :term:`SDK_LOCAL_CONF_BLACKLIST` + :term:`ESDK_LOCALCONF_REMOVE` in the glossary of the Yocto Project Reference Manual. - Variables listed in - :term:`SDK_LOCAL_CONF_WHITELIST` + :term:`ESDK_LOCALCONF_ALLOW` are included. Including a variable in the value of - ``SDK_LOCAL_CONF_WHITELIST`` overrides either of the previous two + :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:`SDK_INHERIT_BLACKLIST` - are disabled. Using ``SDK_INHERIT_BLACKLIST`` 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 - :ref:`buildhistory <ref-classes-buildhistory>` - and :ref:`icecc <ref-classes-icecc>` classes. +- 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:`ref-classes-buildhistory` and :ref:`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, @@ -57,29 +61,24 @@ 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, some cases exist for which you might consider making +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 - blacklist them by adding them to the - :term:`SDK_INHERIT_BLACKLIST` - variable as described in the fourth bullet of the previous section. + disable them by adding them to the :term:`ESDK_CLASS_INHERIT_DISABLE` + variable as described in the previous section. .. note:: - The default value of - SDK_INHERIT_BLACKLIST + The default value of :term:`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 " - Basic Syntax - " section of the BitBake User Manual. - - . + will need to append a value using either ":append" or the "+=" + operator. You can learn more about these operators in the + ":ref:`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 @@ -96,7 +95,7 @@ adjustments: - 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 ``SDK_INHERIT_BLACKLIST`` + 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 @@ -129,8 +128,7 @@ adjustments: .. note:: You must also reflect this change in the value used for the - COREBASE_FILES - variable as previously described. + :term:`COREBASE_FILES` variable as previously described. Changing the Extensible SDK Installer Title =========================================== @@ -143,23 +141,23 @@ section. By default, this title is derived from :term:`DISTRO_NAME` when it is -set. If the ``DISTRO_NAME`` variable is not set, the title is derived +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 ``SDK_TITLE`` variable as +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 several ways exist to change this variable, an efficient method is +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 -``SDK_TITLE`` variable in the +:term:`SDK_TITLE` variable in the ``~/meta-mydistro/conf/distro/mydistro.conf`` file using the following form:: @@ -174,13 +172,12 @@ 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 +#. Create a directory that can be shared over HTTP or HTTPS. You can do + this by setting up a web server such as an :wikipedia:`Apache HTTP Server + <Apache_HTTP_Server>` or :wikipedia:`Nginx <Nginx>` server in the cloud to host the directory. This directory must contain the published SDK. -2. Set the +#. 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, @@ -189,10 +186,10 @@ the installed SDKs to update the installed SDKs by using the ":ref:`sdk-manual/extensible:applying updates to an installed extensible sdk`" section. -3. Build the extensible SDK normally (i.e., use the +#. Build the extensible SDK normally (i.e., use the ``bitbake -c populate_sdk_ext`` imagename command). -4. Publish the SDK using the following command:: +#. Publish the SDK using the following command:: $ oe-publish-sdk some_path/sdk-installer.sh path_to_shared_http_directory @@ -221,16 +218,16 @@ class as follows:: You can change this default installation directory by specifically setting the -``SDKEXTPATH`` variable. +:term:`SDKEXTPATH` variable. -While a number of ways exist through which you can set this 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 -``SDKEXTPATH`` variable in the +:term:`SDKEXTPATH` variable in the ``~/meta-mydistro/conf/distro/mydistro.conf`` file using the following form:: @@ -247,32 +244,30 @@ 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 +#. 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 + ``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. +#. 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. + an :wikipedia:`Apache HTTP Server <Apache_HTTP_Server>` or + :wikipedia:`Nginx <Nginx>` server. -3. Set the appropriate configuration so that the produced SDK knows how +#. 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://.* http://example.com/some_path/sstate-cache/PATH" + SSTATE_MIRRORS = "file://.* https://example.com/some_path/sstate-cache/PATH" - You can set the - ``SSTATE_MIRRORS`` variable in two different places: + 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 @@ -280,23 +275,21 @@ source, you need to do a number of things: 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 "whitelist" the variable through - to the SDK by adding the following:: + configuration file. You can then pass the variable to the SDK by + adding the following:: - SDK_LOCAL_CONF_WHITELIST = "SSTATE_MIRRORS" + ESDK_LOCALCONF_ALLOW = "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`` file either in your - :term:`Build Directory` or within any - layer and put your ``SSTATE_MIRRORS`` setting within that file. + - 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 - SSTATE_MIRRORS - . + :term:`SSTATE_MIRRORS` Minimizing the Size of the Extensible SDK Installer Download ============================================================ @@ -334,13 +327,13 @@ following:: See the :term:`SDK_INCLUDE_PKGDATA` variable for additional information. -Setting the ``SDK_INCLUDE_PKGDATA`` variable as shown causes the "world" +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 +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 @@ -351,15 +344,15 @@ 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. + 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 ``SDK_EXT_TYPE`` to "minimal", which by default, +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. |