diff options
Diffstat (limited to 'documentation/sdk-manual/sdk-appendix-customizing.xml')
| -rw-r--r-- | documentation/sdk-manual/sdk-appendix-customizing.xml | 515 |
1 files changed, 0 insertions, 515 deletions
diff --git a/documentation/sdk-manual/sdk-appendix-customizing.xml b/documentation/sdk-manual/sdk-appendix-customizing.xml deleted file mode 100644 index 08054f8b79..0000000000 --- a/documentation/sdk-manual/sdk-appendix-customizing.xml +++ /dev/null @@ -1,515 +0,0 @@ -<!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 ---> |