blob: 4eccc28e9b3eeeaab249e538aeacffbc952bc9bb [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
3******************************
4Customizing the Extensible SDK
5******************************
6
7This appendix describes customizations you can apply to the extensible
8SDK.
9
10Configuring the Extensible SDK
11==============================
12
13The extensible SDK primarily consists of a pre-configured copy of the
14OpenEmbedded build system from which it was produced. Thus, the SDK's
15configuration is derived using that build system and the filters shown
16in the following list. When these filters are present, the OpenEmbedded
17build system applies them against ``local.conf`` and ``auto.conf``:
18
19- Variables whose values start with "/" are excluded since the
20 assumption is that those values are paths that are likely to be
21 specific to the :term:`Build Host`.
22
23- Variables listed in
24 :term:`SDK_LOCAL_CONF_BLACKLIST`
25 are excluded. These variables are not allowed through from the
26 OpenEmbedded build system configuration into the extensible SDK
27 configuration. Typically, these variables are specific to the machine
28 on which the build system is running and could be problematic as part
29 of the extensible SDK configuration.
30
31 For a list of the variables excluded by default, see the
32 :term:`SDK_LOCAL_CONF_BLACKLIST`
33 in the glossary of the Yocto Project Reference Manual.
34
35- Variables listed in
36 :term:`SDK_LOCAL_CONF_WHITELIST`
37 are included. Including a variable in the value of
Andrew Geissler09036742021-06-25 14:25:14 -050038 :term:`SDK_LOCAL_CONF_WHITELIST` overrides either of the previous two
Andrew Geisslerc9f78652020-09-18 14:11:35 -050039 filters. The default value is blank.
40
41- Classes inherited globally with
42 :term:`INHERIT` that are listed in
43 :term:`SDK_INHERIT_BLACKLIST`
Andrew Geissler09036742021-06-25 14:25:14 -050044 are disabled. Using :term:`SDK_INHERIT_BLACKLIST` to disable these
Andrew Geisslerc9f78652020-09-18 14:11:35 -050045 classes is the typical method to disable classes that are problematic
46 or unnecessary in the SDK context. The default value blacklists the
47 :ref:`buildhistory <ref-classes-buildhistory>`
48 and :ref:`icecc <ref-classes-icecc>` classes.
49
50Additionally, the contents of ``conf/sdk-extra.conf``, when present, are
51appended to the end of ``conf/local.conf`` within the produced SDK,
52without any filtering. The ``sdk-extra.conf`` file is particularly
53useful if you want to set a variable value just for the SDK and not the
54OpenEmbedded build system used to create the SDK.
55
56Adjusting the Extensible SDK to Suit Your Build Host's Setup
57============================================================
58
59In most cases, the extensible SDK defaults should work with your :term:`Build
William A. Kennington IIIac69b482021-06-02 12:28:27 -070060Host`'s setup. However, there are cases when you might consider making
Andrew Geisslerc9f78652020-09-18 14:11:35 -050061adjustments:
62
63- If your SDK configuration inherits additional classes using the
64 :term:`INHERIT` variable and you
65 do not need or want those classes enabled in the SDK, you can
66 blacklist them by adding them to the
67 :term:`SDK_INHERIT_BLACKLIST`
68 variable as described in the fourth bullet of the previous section.
69
70 .. note::
71
72 The default value of
73 SDK_INHERIT_BLACKLIST
74 is set using the "?=" operator. Consequently, you will need to
75 either define the entire list by using the "=" operator, or you
Patrick Williams0ca19cc2021-08-16 14:03:13 -050076 will need to append a value using either ":append" or the "+="
Andrew Geissler09036742021-06-25 14:25:14 -050077 operator. You can learn more about these operators in the
78 ":ref:`bitbake:bitbake-user-manual/bitbake-user-manual-metadata:basic syntax`"
79 section of the BitBake User Manual.
Andrew Geisslerc9f78652020-09-18 14:11:35 -050080
81- If you have classes or recipes that add additional tasks to the
82 standard build flow (i.e. the tasks execute as the recipe builds as
83 opposed to being called explicitly), then you need to do one of the
84 following:
85
86 - After ensuring the tasks are :ref:`shared
Andrew Geissler09209ee2020-12-13 08:44:15 -060087 state <overview-manual/concepts:shared state cache>` tasks (i.e. the
Andrew Geisslerc9f78652020-09-18 14:11:35 -050088 output of the task is saved to and can be restored from the shared
89 state cache) or ensuring the tasks are able to be produced quickly
90 from a task that is a shared state task, add the task name to the
91 value of
92 :term:`SDK_RECRDEP_TASKS`.
93
94 - Disable the tasks if they are added by a class and you do not need
95 the functionality the class provides in the extensible SDK. To
Andrew Geissler09036742021-06-25 14:25:14 -050096 disable the tasks, add the class to the :term:`SDK_INHERIT_BLACKLIST`
Andrew Geisslerc9f78652020-09-18 14:11:35 -050097 variable as described in the previous section.
98
99- Generally, you want to have a shared state mirror set up so users of
100 the SDK can add additional items to the SDK after installation
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500101 without needing to build the items from source. See the
102 ":ref:`sdk-manual/appendix-customizing:providing additional installable extensible sdk content`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500103 section for information.
104
105- If you want users of the SDK to be able to easily update the SDK, you
106 need to set the
107 :term:`SDK_UPDATE_URL`
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500108 variable. For more information, see the
109 ":ref:`sdk-manual/appendix-customizing:providing updates to the extensible sdk after installation`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500110 section.
111
112- If you have adjusted the list of files and directories that appear in
113 :term:`COREBASE` (other than
114 layers that are enabled through ``bblayers.conf``), then you must
115 list these files in
116 :term:`COREBASE_FILES` so
117 that the files are copied into the SDK.
118
119- If your OpenEmbedded build system setup uses a different environment
120 setup script other than
121 :ref:`structure-core-script`, then you must
122 set
123 :term:`OE_INIT_ENV_SCRIPT`
124 to point to the environment setup script you use.
125
126 .. note::
127
128 You must also reflect this change in the value used for the
Andrew Geissler09036742021-06-25 14:25:14 -0500129 :term:`COREBASE_FILES` variable as previously described.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500130
131Changing the Extensible SDK Installer Title
132===========================================
133
134You can change the displayed title for the SDK installer by setting the
135:term:`SDK_TITLE` variable and then
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500136rebuilding the SDK installer. For information on how to build an SDK
137installer, see the ":ref:`sdk-manual/appendix-obtain:building an sdk installer`"
138section.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500139
140By default, this title is derived from
141:term:`DISTRO_NAME` when it is
Andrew Geissler09036742021-06-25 14:25:14 -0500142set. If the :term:`DISTRO_NAME` variable is not set, the title is derived
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500143from the :term:`DISTRO` variable.
144
145The
146:ref:`populate_sdk_base <ref-classes-populate-sdk-*>`
Andrew Geissler09036742021-06-25 14:25:14 -0500147class defines the default value of the :term:`SDK_TITLE` variable as
Andrew Geisslerc926e172021-05-07 16:11:35 -0500148follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500149
150 SDK_TITLE ??= "${@d.getVar('DISTRO_NAME') or d.getVar('DISTRO')} SDK"
151
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700152While there are several ways of changing this variable, an efficient method is
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500153to set the variable in your distribution's configuration file. Doing so
154creates an SDK installer title that applies across your distribution. As
155an example, assume you have your own layer for your distribution named
156"meta-mydistro" and you are using the same type of file hierarchy as
157does the default "poky" distribution. If so, you could update the
Andrew Geissler09036742021-06-25 14:25:14 -0500158:term:`SDK_TITLE` variable in the
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500159``~/meta-mydistro/conf/distro/mydistro.conf`` file using the following
Andrew Geisslerc926e172021-05-07 16:11:35 -0500160form::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500161
162 SDK_TITLE = "your_title"
163
164Providing Updates to the Extensible SDK After Installation
165==========================================================
166
167When you make changes to your configuration or to the metadata and if
168you want those changes to be reflected in installed SDKs, you need to
169perform additional steps. These steps make it possible for anyone using
170the installed SDKs to update the installed SDKs by using the
171``devtool sdk-update`` command:
172
1731. Create a directory that can be shared over HTTP or HTTPS. You can do
174 this by setting up a web server such as an `Apache HTTP
175 Server <https://en.wikipedia.org/wiki/Apache_HTTP_Server>`__ or
176 `Nginx <https://en.wikipedia.org/wiki/Nginx>`__ server in the cloud
177 to host the directory. This directory must contain the published SDK.
178
1792. Set the
180 :term:`SDK_UPDATE_URL`
181 variable to point to the corresponding HTTP or HTTPS URL. Setting
182 this variable causes any SDK built to default to that URL and thus,
183 the user does not have to pass the URL to the ``devtool sdk-update``
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500184 command as described in the
185 ":ref:`sdk-manual/extensible:applying updates to an installed extensible sdk`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500186 section.
187
1883. Build the extensible SDK normally (i.e., use the
189 ``bitbake -c populate_sdk_ext`` imagename command).
190
Andrew Geisslerc926e172021-05-07 16:11:35 -05001914. Publish the SDK using the following command::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500192
193 $ oe-publish-sdk some_path/sdk-installer.sh path_to_shared_http_directory
194
195 You must
196 repeat this step each time you rebuild the SDK with changes that you
197 want to make available through the update mechanism.
198
199Completing the above steps allows users of the existing installed SDKs
200to simply run ``devtool sdk-update`` to retrieve and apply the latest
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500201updates. See the
202":ref:`sdk-manual/extensible:applying updates to an installed extensible sdk`"
203section for further information.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500204
205Changing the Default SDK Installation Directory
206===============================================
207
208When you build the installer for the Extensible SDK, the default
209installation directory for the SDK is based on the
210:term:`DISTRO` and
211:term:`SDKEXTPATH` variables from
212within the
213:ref:`populate_sdk_base <ref-classes-populate-sdk-*>`
Andrew Geisslerc926e172021-05-07 16:11:35 -0500214class as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500215
216 SDKEXTPATH ??= "~/${@d.getVar('DISTRO')}_sdk"
217
218You can
219change this default installation directory by specifically setting the
Andrew Geissler09036742021-06-25 14:25:14 -0500220:term:`SDKEXTPATH` variable.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500221
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700222While there are several ways of setting this variable,
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500223the method that makes the most sense is to set the variable in your
224distribution's configuration file. Doing so creates an SDK installer
225default directory that applies across your distribution. As an example,
226assume you have your own layer for your distribution named
227"meta-mydistro" and you are using the same type of file hierarchy as
228does the default "poky" distribution. If so, you could update the
Andrew Geissler09036742021-06-25 14:25:14 -0500229:term:`SDKEXTPATH` variable in the
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500230``~/meta-mydistro/conf/distro/mydistro.conf`` file using the following
Andrew Geisslerc926e172021-05-07 16:11:35 -0500231form::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500232
233 SDKEXTPATH = "some_path_for_your_installed_sdk"
234
235After building your installer, running it prompts the user for
236acceptance of the some_path_for_your_installed_sdk directory as the
237default location to install the Extensible SDK.
238
239Providing Additional Installable Extensible SDK Content
240=======================================================
241
242If you want the users of an extensible SDK you build to be able to add
243items to the SDK without requiring the users to build the items from
244source, you need to do a number of things:
245
2461. Ensure the additional items you want the user to be able to install
247 are already built:
248
249 - Build the items explicitly. You could use one or more "meta"
250 recipes that depend on lists of other recipes.
251
252 - Build the "world" target and set
Patrick Williams0ca19cc2021-08-16 14:03:13 -0500253 ``EXCLUDE_FROM_WORLD:pn-``\ recipename for the recipes you do not
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500254 want built. See the
255 :term:`EXCLUDE_FROM_WORLD`
256 variable for additional information.
257
2582. Expose the ``sstate-cache`` directory produced by the build.
259 Typically, you expose this directory by making it available through
260 an `Apache HTTP
261 Server <https://en.wikipedia.org/wiki/Apache_HTTP_Server>`__ or
262 `Nginx <https://en.wikipedia.org/wiki/Nginx>`__ server.
263
2643. Set the appropriate configuration so that the produced SDK knows how
265 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
268 SSTATE_MIRRORS = "file://.* http://example.com/some_path/sstate-cache/PATH"
269
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
278 configuration file. You can then "whitelist" the variable through
Andrew Geisslerc926e172021-05-07 16:11:35 -0500279 to the SDK by adding the following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500280
281 SDK_LOCAL_CONF_WHITELIST = "SSTATE_MIRRORS"
282
Andrew Geissler09036742021-06-25 14:25:14 -0500283 - Alternatively, if you just want to set the :term:`SSTATE_MIRRORS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500284 variable's value for the SDK alone, create a
285 ``conf/sdk-extra.conf`` file either in your
286 :term:`Build Directory` or within any
Andrew Geissler09036742021-06-25 14:25:14 -0500287 layer and put your :term:`SSTATE_MIRRORS` setting within that file.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500288
289 .. note::
290
291 This second option is the safest option should you have any
292 doubts as to which method to use when setting
Andrew Geissler09036742021-06-25 14:25:14 -0500293 :term:`SSTATE_MIRRORS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500294
295Minimizing the Size of the Extensible SDK Installer Download
296============================================================
297
298By default, the extensible SDK bundles the shared state artifacts for
299everything needed to reconstruct the image for which the SDK was built.
300This bundling can lead to an SDK installer file that is a Gigabyte or
301more in size. If the size of this file causes a problem, you can build
302an SDK that has just enough in it to install and provide access to the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500303``devtool command`` by setting the following in your configuration::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500304
305 SDK_EXT_TYPE = "minimal"
306
307Setting
308:term:`SDK_EXT_TYPE` to
309"minimal" produces an SDK installer that is around 35 Mbytes in size,
310which downloads and installs quickly. You need to realize, though, that
311the minimal installer does not install any libraries or tools out of the
312box. These libraries and tools must be installed either "on the fly" or
313through actions you perform using ``devtool`` or explicitly with the
314``devtool sdk-install`` command.
315
316In most cases, when building a minimal SDK you need to also enable
317bringing in the information on a wider range of packages produced by the
318system. Requiring this wider range of information is particularly true
319so that ``devtool add`` is able to effectively map dependencies it
320discovers in a source tree to the appropriate recipes. Additionally, the
321information enables the ``devtool search`` command to return useful
322results.
323
324To facilitate this wider range of information, you would need to set the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500325following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500326
327 SDK_INCLUDE_PKGDATA = "1"
328
329See the :term:`SDK_INCLUDE_PKGDATA` variable for additional information.
330
Andrew Geissler09036742021-06-25 14:25:14 -0500331Setting the :term:`SDK_INCLUDE_PKGDATA` variable as shown causes the "world"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500332target to be built so that information for all of the recipes included
333within it are available. Having these recipes available increases build
334time significantly and increases the size of the SDK installer by 30-80
335Mbytes depending on how many recipes are included in your configuration.
336
Patrick Williams0ca19cc2021-08-16 14:03:13 -0500337You can use ``EXCLUDE_FROM_WORLD:pn-``\ recipename for recipes you want
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500338to exclude. However, it is assumed that you would need to be building
339the "world" target if you want to provide additional items to the SDK.
340Consequently, building for "world" should not represent undue overhead
341in most cases.
342
343.. note::
344
345 If you set
346 SDK_EXT_TYPE
347 to "minimal", then providing a shared state mirror is mandatory so
Andrew Geissler09036742021-06-25 14:25:14 -0500348 that items can be installed as needed. See the
349 :ref:`sdk-manual/appendix-customizing:providing additional installable extensible sdk content`
350 section for more information.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500351
352You can explicitly control whether or not to include the toolchain when
353you build an SDK by setting the
354:term:`SDK_INCLUDE_TOOLCHAIN`
355variable to "1". In particular, it is useful to include the toolchain
Andrew Geissler09036742021-06-25 14:25:14 -0500356when you have set :term:`SDK_EXT_TYPE` to "minimal", which by default,
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500357excludes the toolchain. Also, it is helpful if you are building a small
358SDK for use with an IDE or some other tool where you do not want to take
359extra steps to install a toolchain.