From eb8dc40360f0cfef56fb6947cc817a547d6d9bc6 Mon Sep 17 00:00:00 2001 From: Dave Cobbley Date: Tue, 14 Aug 2018 10:05:37 -0700 Subject: [Subtree] Removing import-layers directory As part of the move to subtrees, need to bring all the import layers content to the top level. Change-Id: I4a163d10898cbc6e11c27f776f60e1a470049d8f Signed-off-by: Dave Cobbley Signed-off-by: Brad Bishop --- .../sdk-manual/sdk-appendix-customizing.xml | 398 +++++++++++++++++++++ 1 file changed, 398 insertions(+) create mode 100644 poky/documentation/sdk-manual/sdk-appendix-customizing.xml (limited to 'poky/documentation/sdk-manual/sdk-appendix-customizing.xml') 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..5b56e738d --- /dev/null +++ b/poky/documentation/sdk-manual/sdk-appendix-customizing.xml @@ -0,0 +1,398 @@ + %poky; ] > + + + +Customizing the Extensible SDK + + + This appendix presents customizations you can apply to 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 following filters, which the OpenEmbedded build system applies + against local.conf and + auto.conf if they are 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 a variable in the value of + SDK_LOCAL_CONF_WHITELIST 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. + 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 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 you must list these + files in + 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 + &OE_INIT_FILE;, + 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_ext imagename + 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 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 "whitelist" the variable through + to 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 minimal 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. + + + + + You can explicitly control whether or not to include the toolchain + when you build an SDK by setting the + 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, excludes the toolchain. + Also, it is helpful if you are building a small SDK for use with + an IDE, such as Eclipse, or some + other tool where you do not want to take extra steps to install a + toolchain. + +
+ + -- cgit v1.2.3