blob: 61091d83bafcf6e91838a3b06aa4e54209db8feb [file] [log] [blame]
Andrew Geisslerf0343792020-11-18 10:42:21 -06001.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002
Patrick Williams92b42cb2022-09-03 06:53:57 -05003***************************************************
4Customizing the Extensible SDK standalone installer
5***************************************************
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006
7This appendix describes customizations you can apply to the extensible
Patrick Williams92b42cb2022-09-03 06:53:57 -05008SDK when using in the standalone installer version.
9
10.. note::
11
12 It is also possible to use the Extensible SDK functionality directly in a
13 Yocto build, avoiding separate installer artefacts. Please refer to
14 ":ref:`sdk-manual/extensible:Installing the Extensible SDK`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -050015
16Configuring the Extensible SDK
17==============================
18
19The extensible SDK primarily consists of a pre-configured copy of the
20OpenEmbedded build system from which it was produced. Thus, the SDK's
21configuration is derived using that build system and the filters shown
22in the following list. When these filters are present, the OpenEmbedded
23build system applies them against ``local.conf`` and ``auto.conf``:
24
25- Variables whose values start with "/" are excluded since the
26 assumption is that those values are paths that are likely to be
27 specific to the :term:`Build Host`.
28
29- Variables listed in
Andrew Geissler9aee5002022-03-30 16:27:02 +000030 :term:`ESDK_LOCALCONF_REMOVE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -050031 are excluded. These variables are not allowed through from the
32 OpenEmbedded build system configuration into the extensible SDK
33 configuration. Typically, these variables are specific to the machine
34 on which the build system is running and could be problematic as part
35 of the extensible SDK configuration.
36
37 For a list of the variables excluded by default, see the
Andrew Geissler9aee5002022-03-30 16:27:02 +000038 :term:`ESDK_LOCALCONF_REMOVE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -050039 in the glossary of the Yocto Project Reference Manual.
40
41- Variables listed in
Andrew Geissler9aee5002022-03-30 16:27:02 +000042 :term:`ESDK_LOCALCONF_ALLOW`
Andrew Geisslerc9f78652020-09-18 14:11:35 -050043 are included. Including a variable in the value of
Andrew Geissler9aee5002022-03-30 16:27:02 +000044 :term:`ESDK_LOCALCONF_ALLOW` overrides either of the previous two
Andrew Geisslerc9f78652020-09-18 14:11:35 -050045 filters. The default value is blank.
46
Andrew Geissler517393d2023-01-13 08:55:19 -060047- Classes inherited globally with :term:`INHERIT` that are listed in
48 :term:`ESDK_CLASS_INHERIT_DISABLE` are disabled. Using
49 :term:`ESDK_CLASS_INHERIT_DISABLE` to disable these classes is the typical
50 method to disable classes that are problematic or unnecessary in the SDK
51 context. The default value disables the
52 :ref:`ref-classes-buildhistory` and :ref:`ref-classes-icecc` classes.
Andrew Geisslerc9f78652020-09-18 14:11:35 -050053
54Additionally, the contents of ``conf/sdk-extra.conf``, when present, are
55appended to the end of ``conf/local.conf`` within the produced SDK,
56without any filtering. The ``sdk-extra.conf`` file is particularly
57useful if you want to set a variable value just for the SDK and not the
58OpenEmbedded build system used to create the SDK.
59
60Adjusting the Extensible SDK to Suit Your Build Host's Setup
61============================================================
62
63In most cases, the extensible SDK defaults should work with your :term:`Build
William A. Kennington IIIac69b482021-06-02 12:28:27 -070064Host`'s setup. However, there are cases when you might consider making
Andrew Geisslerc9f78652020-09-18 14:11:35 -050065adjustments:
66
67- If your SDK configuration inherits additional classes using the
68 :term:`INHERIT` variable and you
69 do not need or want those classes enabled in the SDK, you can
Andrew Geissler9aee5002022-03-30 16:27:02 +000070 disable them by adding them to the :term:`ESDK_CLASS_INHERIT_DISABLE`
Andrew Geissler595f6302022-01-24 19:11:47 +000071 variable as described in the previous section.
Andrew Geisslerc9f78652020-09-18 14:11:35 -050072
73 .. note::
74
Andrew Geissler517393d2023-01-13 08:55:19 -060075 The default value of :term:`ESDK_CLASS_INHERIT_DISABLE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -050076 is set using the "?=" operator. Consequently, you will need to
77 either define the entire list by using the "=" operator, or you
Patrick Williams0ca19cc2021-08-16 14:03:13 -050078 will need to append a value using either ":append" or the "+="
Andrew Geissler09036742021-06-25 14:25:14 -050079 operator. You can learn more about these operators in the
Andrew Geisslerfc113ea2023-03-31 09:59:46 -050080 ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:basic syntax`"
Andrew Geissler09036742021-06-25 14:25:14 -050081 section of the BitBake User Manual.
Andrew Geisslerc9f78652020-09-18 14:11:35 -050082
83- If you have classes or recipes that add additional tasks to the
84 standard build flow (i.e. the tasks execute as the recipe builds as
85 opposed to being called explicitly), then you need to do one of the
86 following:
87
88 - After ensuring the tasks are :ref:`shared
Andrew Geissler09209ee2020-12-13 08:44:15 -060089 state <overview-manual/concepts:shared state cache>` tasks (i.e. the
Andrew Geisslerc9f78652020-09-18 14:11:35 -050090 output of the task is saved to and can be restored from the shared
91 state cache) or ensuring the tasks are able to be produced quickly
92 from a task that is a shared state task, add the task name to the
93 value of
94 :term:`SDK_RECRDEP_TASKS`.
95
96 - Disable the tasks if they are added by a class and you do not need
97 the functionality the class provides in the extensible SDK. To
Andrew Geissler9aee5002022-03-30 16:27:02 +000098 disable the tasks, add the class to the :term:`ESDK_CLASS_INHERIT_DISABLE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -050099 variable as described in the previous section.
100
101- Generally, you want to have a shared state mirror set up so users of
102 the SDK can add additional items to the SDK after installation
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500103 without needing to build the items from source. See the
104 ":ref:`sdk-manual/appendix-customizing:providing additional installable extensible sdk content`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500105 section for information.
106
107- If you want users of the SDK to be able to easily update the SDK, you
108 need to set the
109 :term:`SDK_UPDATE_URL`
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500110 variable. For more information, see the
111 ":ref:`sdk-manual/appendix-customizing:providing updates to the extensible sdk after installation`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500112 section.
113
114- If you have adjusted the list of files and directories that appear in
115 :term:`COREBASE` (other than
116 layers that are enabled through ``bblayers.conf``), then you must
117 list these files in
118 :term:`COREBASE_FILES` so
119 that the files are copied into the SDK.
120
121- If your OpenEmbedded build system setup uses a different environment
122 setup script other than
123 :ref:`structure-core-script`, then you must
124 set
125 :term:`OE_INIT_ENV_SCRIPT`
126 to point to the environment setup script you use.
127
128 .. note::
129
130 You must also reflect this change in the value used for the
Andrew Geissler09036742021-06-25 14:25:14 -0500131 :term:`COREBASE_FILES` variable as previously described.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500132
133Changing the Extensible SDK Installer Title
134===========================================
135
136You can change the displayed title for the SDK installer by setting the
137:term:`SDK_TITLE` variable and then
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500138rebuilding the SDK installer. For information on how to build an SDK
139installer, see the ":ref:`sdk-manual/appendix-obtain:building an sdk installer`"
140section.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500141
142By default, this title is derived from
143:term:`DISTRO_NAME` when it is
Andrew Geissler09036742021-06-25 14:25:14 -0500144set. If the :term:`DISTRO_NAME` variable is not set, the title is derived
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500145from the :term:`DISTRO` variable.
146
147The
148:ref:`populate_sdk_base <ref-classes-populate-sdk-*>`
Andrew Geissler09036742021-06-25 14:25:14 -0500149class defines the default value of the :term:`SDK_TITLE` variable as
Andrew Geisslerc926e172021-05-07 16:11:35 -0500150follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500151
152 SDK_TITLE ??= "${@d.getVar('DISTRO_NAME') or d.getVar('DISTRO')} SDK"
153
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700154While there are several ways of changing this variable, an efficient method is
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500155to set the variable in your distribution's configuration file. Doing so
156creates an SDK installer title that applies across your distribution. As
157an example, assume you have your own layer for your distribution named
158"meta-mydistro" and you are using the same type of file hierarchy as
159does the default "poky" distribution. If so, you could update the
Andrew Geissler09036742021-06-25 14:25:14 -0500160:term:`SDK_TITLE` variable in the
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500161``~/meta-mydistro/conf/distro/mydistro.conf`` file using the following
Andrew Geisslerc926e172021-05-07 16:11:35 -0500162form::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500163
164 SDK_TITLE = "your_title"
165
166Providing Updates to the Extensible SDK After Installation
167==========================================================
168
169When you make changes to your configuration or to the metadata and if
170you want those changes to be reflected in installed SDKs, you need to
171perform additional steps. These steps make it possible for anyone using
172the installed SDKs to update the installed SDKs by using the
173``devtool sdk-update`` command:
174
Andrew Geissler517393d2023-01-13 08:55:19 -0600175#. Create a directory that can be shared over HTTP or HTTPS. You can do
Patrick Williams7784c422022-11-17 07:29:11 -0600176 this by setting up a web server such as an :wikipedia:`Apache HTTP Server
177 <Apache_HTTP_Server>` or :wikipedia:`Nginx <Nginx>` server in the cloud
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500178 to host the directory. This directory must contain the published SDK.
179
Andrew Geissler517393d2023-01-13 08:55:19 -0600180#. Set the
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500181 :term:`SDK_UPDATE_URL`
182 variable to point to the corresponding HTTP or HTTPS URL. Setting
183 this variable causes any SDK built to default to that URL and thus,
184 the user does not have to pass the URL to the ``devtool sdk-update``
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500185 command as described in the
186 ":ref:`sdk-manual/extensible:applying updates to an installed extensible sdk`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500187 section.
188
Andrew Geissler517393d2023-01-13 08:55:19 -0600189#. Build the extensible SDK normally (i.e., use the
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500190 ``bitbake -c populate_sdk_ext`` imagename command).
191
Andrew Geissler517393d2023-01-13 08:55:19 -0600192#. Publish the SDK using the following command::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500193
194 $ oe-publish-sdk some_path/sdk-installer.sh path_to_shared_http_directory
195
196 You must
197 repeat this step each time you rebuild the SDK with changes that you
198 want to make available through the update mechanism.
199
200Completing the above steps allows users of the existing installed SDKs
201to simply run ``devtool sdk-update`` to retrieve and apply the latest
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500202updates. See the
203":ref:`sdk-manual/extensible:applying updates to an installed extensible sdk`"
204section for further information.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500205
206Changing the Default SDK Installation Directory
207===============================================
208
209When you build the installer for the Extensible SDK, the default
210installation directory for the SDK is based on the
211:term:`DISTRO` and
212:term:`SDKEXTPATH` variables from
213within the
214:ref:`populate_sdk_base <ref-classes-populate-sdk-*>`
Andrew Geisslerc926e172021-05-07 16:11:35 -0500215class as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500216
217 SDKEXTPATH ??= "~/${@d.getVar('DISTRO')}_sdk"
218
219You can
220change this default installation directory by specifically setting the
Andrew Geissler09036742021-06-25 14:25:14 -0500221:term:`SDKEXTPATH` variable.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500222
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700223While there are several ways of setting this variable,
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500224the method that makes the most sense is to set the variable in your
225distribution's configuration file. Doing so creates an SDK installer
226default directory that applies across your distribution. As an example,
227assume you have your own layer for your distribution named
228"meta-mydistro" and you are using the same type of file hierarchy as
229does the default "poky" distribution. If so, you could update the
Andrew Geissler09036742021-06-25 14:25:14 -0500230:term:`SDKEXTPATH` variable in the
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500231``~/meta-mydistro/conf/distro/mydistro.conf`` file using the following
Andrew Geisslerc926e172021-05-07 16:11:35 -0500232form::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500233
234 SDKEXTPATH = "some_path_for_your_installed_sdk"
235
236After building your installer, running it prompts the user for
237acceptance of the some_path_for_your_installed_sdk directory as the
238default location to install the Extensible SDK.
239
240Providing Additional Installable Extensible SDK Content
241=======================================================
242
243If you want the users of an extensible SDK you build to be able to add
244items to the SDK without requiring the users to build the items from
245source, you need to do a number of things:
246
Andrew Geissler517393d2023-01-13 08:55:19 -0600247#. Ensure the additional items you want the user to be able to install
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500248 are already built:
249
250 - Build the items explicitly. You could use one or more "meta"
251 recipes that depend on lists of other recipes.
252
253 - Build the "world" target and set
Patrick Williams0ca19cc2021-08-16 14:03:13 -0500254 ``EXCLUDE_FROM_WORLD:pn-``\ recipename for the recipes you do not
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500255 want built. See the
256 :term:`EXCLUDE_FROM_WORLD`
257 variable for additional information.
258
Andrew Geissler517393d2023-01-13 08:55:19 -0600259#. Expose the ``sstate-cache`` directory produced by the build.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500260 Typically, you expose this directory by making it available through
Patrick Williams7784c422022-11-17 07:29:11 -0600261 an :wikipedia:`Apache HTTP Server <Apache_HTTP_Server>` or
262 :wikipedia:`Nginx <Nginx>` server.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500263
Andrew Geissler517393d2023-01-13 08:55:19 -0600264#. Set the appropriate configuration so that the produced SDK knows how
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500265 to find the configuration. The variable you need to set is
Andrew Geisslerc926e172021-05-07 16:11:35 -0500266 :term:`SSTATE_MIRRORS`::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500267
Andrew Geissler7e0e3c02022-02-25 20:34:39 +0000268 SSTATE_MIRRORS = "file://.* https://example.com/some_path/sstate-cache/PATH"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500269
Andrew Geissler09036742021-06-25 14:25:14 -0500270 You can set the :term:`SSTATE_MIRRORS` variable in two different places:
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500271
272 - If the mirror value you are setting is appropriate to be set for
273 both the OpenEmbedded build system that is actually building the
274 SDK and the SDK itself (i.e. the mirror is accessible in both
275 places or it will fail quickly on the OpenEmbedded build system
276 side, and its contents will not interfere with the build), then
277 you can set the variable in your ``local.conf`` or custom distro
Andrew Geissler595f6302022-01-24 19:11:47 +0000278 configuration file. You can then pass the variable to the SDK by
279 adding the following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500280
Andrew Geissler9aee5002022-03-30 16:27:02 +0000281 ESDK_LOCALCONF_ALLOW = "SSTATE_MIRRORS"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500282
Andrew Geissler09036742021-06-25 14:25:14 -0500283 - Alternatively, if you just want to set the :term:`SSTATE_MIRRORS`
Patrick Williams2390b1b2022-11-03 13:47:49 -0500284 variable's value for the SDK alone, create a ``conf/sdk-extra.conf``
285 file either in your :term:`Build Directory` or within any
Andrew Geissler09036742021-06-25 14:25:14 -0500286 layer and put your :term:`SSTATE_MIRRORS` setting within that file.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500287
288 .. note::
289
290 This second option is the safest option should you have any
291 doubts as to which method to use when setting
Andrew Geissler09036742021-06-25 14:25:14 -0500292 :term:`SSTATE_MIRRORS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500293
294Minimizing the Size of the Extensible SDK Installer Download
295============================================================
296
297By default, the extensible SDK bundles the shared state artifacts for
298everything needed to reconstruct the image for which the SDK was built.
299This bundling can lead to an SDK installer file that is a Gigabyte or
300more in size. If the size of this file causes a problem, you can build
301an SDK that has just enough in it to install and provide access to the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500302``devtool command`` by setting the following in your configuration::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500303
304 SDK_EXT_TYPE = "minimal"
305
306Setting
307:term:`SDK_EXT_TYPE` to
308"minimal" produces an SDK installer that is around 35 Mbytes in size,
309which downloads and installs quickly. You need to realize, though, that
310the minimal installer does not install any libraries or tools out of the
311box. These libraries and tools must be installed either "on the fly" or
312through actions you perform using ``devtool`` or explicitly with the
313``devtool sdk-install`` command.
314
315In most cases, when building a minimal SDK you need to also enable
316bringing in the information on a wider range of packages produced by the
317system. Requiring this wider range of information is particularly true
318so that ``devtool add`` is able to effectively map dependencies it
319discovers in a source tree to the appropriate recipes. Additionally, the
320information enables the ``devtool search`` command to return useful
321results.
322
323To facilitate this wider range of information, you would need to set the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500324following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500325
326 SDK_INCLUDE_PKGDATA = "1"
327
328See the :term:`SDK_INCLUDE_PKGDATA` variable for additional information.
329
Andrew Geissler09036742021-06-25 14:25:14 -0500330Setting the :term:`SDK_INCLUDE_PKGDATA` variable as shown causes the "world"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500331target to be built so that information for all of the recipes included
332within it are available. Having these recipes available increases build
333time significantly and increases the size of the SDK installer by 30-80
334Mbytes depending on how many recipes are included in your configuration.
335
Patrick Williams0ca19cc2021-08-16 14:03:13 -0500336You can use ``EXCLUDE_FROM_WORLD:pn-``\ recipename for recipes you want
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500337to exclude. However, it is assumed that you would need to be building
338the "world" target if you want to provide additional items to the SDK.
339Consequently, building for "world" should not represent undue overhead
340in most cases.
341
342.. note::
343
344 If you set
345 SDK_EXT_TYPE
346 to "minimal", then providing a shared state mirror is mandatory so
Andrew Geissler09036742021-06-25 14:25:14 -0500347 that items can be installed as needed. See the
348 :ref:`sdk-manual/appendix-customizing:providing additional installable extensible sdk content`
349 section for more information.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500350
351You can explicitly control whether or not to include the toolchain when
352you build an SDK by setting the
353:term:`SDK_INCLUDE_TOOLCHAIN`
354variable to "1". In particular, it is useful to include the toolchain
Andrew Geissler09036742021-06-25 14:25:14 -0500355when you have set :term:`SDK_EXT_TYPE` to "minimal", which by default,
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500356excludes the toolchain. Also, it is helpful if you are building a small
357SDK for use with an IDE or some other tool where you do not want to take
358extra steps to install a toolchain.