diff options
Diffstat (limited to 'poky/documentation/sdk-manual/sdk-appendix-customizing.xml')
| -rw-r--r-- | poky/documentation/sdk-manual/sdk-appendix-customizing.xml | 515 |
1 files changed, 515 insertions, 0 deletions
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 000000000..08054f8b7 --- /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 +--> |