blob: cac199bf7a8911ccddbefb7569120b09c0b5229b [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
Andrew Geissler595f6302022-01-24 19:11:47 +000046 or unnecessary in the SDK context. The default value disables the
Andrew Geisslerc9f78652020-09-18 14:11:35 -050047 :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
Andrew Geissler595f6302022-01-24 19:11:47 +000066 disable them by adding them to the :term:`SDK_INHERIT_BLACKLIST`
67 variable as described in the previous section.
Andrew Geisslerc9f78652020-09-18 14:11:35 -050068
69 .. note::
70
71 The default value of
72 SDK_INHERIT_BLACKLIST
73 is set using the "?=" operator. Consequently, you will need to
74 either define the entire list by using the "=" operator, or you
Patrick Williams0ca19cc2021-08-16 14:03:13 -050075 will need to append a value using either ":append" or the "+="
Andrew Geissler09036742021-06-25 14:25:14 -050076 operator. You can learn more about these operators in the
77 ":ref:`bitbake:bitbake-user-manual/bitbake-user-manual-metadata:basic syntax`"
78 section of the BitBake User Manual.
Andrew Geisslerc9f78652020-09-18 14:11:35 -050079
80- If you have classes or recipes that add additional tasks to the
81 standard build flow (i.e. the tasks execute as the recipe builds as
82 opposed to being called explicitly), then you need to do one of the
83 following:
84
85 - After ensuring the tasks are :ref:`shared
Andrew Geissler09209ee2020-12-13 08:44:15 -060086 state <overview-manual/concepts:shared state cache>` tasks (i.e. the
Andrew Geisslerc9f78652020-09-18 14:11:35 -050087 output of the task is saved to and can be restored from the shared
88 state cache) or ensuring the tasks are able to be produced quickly
89 from a task that is a shared state task, add the task name to the
90 value of
91 :term:`SDK_RECRDEP_TASKS`.
92
93 - Disable the tasks if they are added by a class and you do not need
94 the functionality the class provides in the extensible SDK. To
Andrew Geissler09036742021-06-25 14:25:14 -050095 disable the tasks, add the class to the :term:`SDK_INHERIT_BLACKLIST`
Andrew Geisslerc9f78652020-09-18 14:11:35 -050096 variable as described in the previous section.
97
98- Generally, you want to have a shared state mirror set up so users of
99 the SDK can add additional items to the SDK after installation
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500100 without needing to build the items from source. See the
101 ":ref:`sdk-manual/appendix-customizing:providing additional installable extensible sdk content`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500102 section for information.
103
104- If you want users of the SDK to be able to easily update the SDK, you
105 need to set the
106 :term:`SDK_UPDATE_URL`
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500107 variable. For more information, see the
108 ":ref:`sdk-manual/appendix-customizing:providing updates to the extensible sdk after installation`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500109 section.
110
111- If you have adjusted the list of files and directories that appear in
112 :term:`COREBASE` (other than
113 layers that are enabled through ``bblayers.conf``), then you must
114 list these files in
115 :term:`COREBASE_FILES` so
116 that the files are copied into the SDK.
117
118- If your OpenEmbedded build system setup uses a different environment
119 setup script other than
120 :ref:`structure-core-script`, then you must
121 set
122 :term:`OE_INIT_ENV_SCRIPT`
123 to point to the environment setup script you use.
124
125 .. note::
126
127 You must also reflect this change in the value used for the
Andrew Geissler09036742021-06-25 14:25:14 -0500128 :term:`COREBASE_FILES` variable as previously described.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500129
130Changing the Extensible SDK Installer Title
131===========================================
132
133You can change the displayed title for the SDK installer by setting the
134:term:`SDK_TITLE` variable and then
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500135rebuilding the SDK installer. For information on how to build an SDK
136installer, see the ":ref:`sdk-manual/appendix-obtain:building an sdk installer`"
137section.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500138
139By default, this title is derived from
140:term:`DISTRO_NAME` when it is
Andrew Geissler09036742021-06-25 14:25:14 -0500141set. If the :term:`DISTRO_NAME` variable is not set, the title is derived
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500142from the :term:`DISTRO` variable.
143
144The
145:ref:`populate_sdk_base <ref-classes-populate-sdk-*>`
Andrew Geissler09036742021-06-25 14:25:14 -0500146class defines the default value of the :term:`SDK_TITLE` variable as
Andrew Geisslerc926e172021-05-07 16:11:35 -0500147follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500148
149 SDK_TITLE ??= "${@d.getVar('DISTRO_NAME') or d.getVar('DISTRO')} SDK"
150
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700151While there are several ways of changing this variable, an efficient method is
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500152to set the variable in your distribution's configuration file. Doing so
153creates an SDK installer title that applies across your distribution. As
154an example, assume you have your own layer for your distribution named
155"meta-mydistro" and you are using the same type of file hierarchy as
156does the default "poky" distribution. If so, you could update the
Andrew Geissler09036742021-06-25 14:25:14 -0500157:term:`SDK_TITLE` variable in the
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500158``~/meta-mydistro/conf/distro/mydistro.conf`` file using the following
Andrew Geisslerc926e172021-05-07 16:11:35 -0500159form::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500160
161 SDK_TITLE = "your_title"
162
163Providing Updates to the Extensible SDK After Installation
164==========================================================
165
166When you make changes to your configuration or to the metadata and if
167you want those changes to be reflected in installed SDKs, you need to
168perform additional steps. These steps make it possible for anyone using
169the installed SDKs to update the installed SDKs by using the
170``devtool sdk-update`` command:
171
1721. Create a directory that can be shared over HTTP or HTTPS. You can do
173 this by setting up a web server such as an `Apache HTTP
174 Server <https://en.wikipedia.org/wiki/Apache_HTTP_Server>`__ or
175 `Nginx <https://en.wikipedia.org/wiki/Nginx>`__ server in the cloud
176 to host the directory. This directory must contain the published SDK.
177
1782. Set the
179 :term:`SDK_UPDATE_URL`
180 variable to point to the corresponding HTTP or HTTPS URL. Setting
181 this variable causes any SDK built to default to that URL and thus,
182 the user does not have to pass the URL to the ``devtool sdk-update``
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500183 command as described in the
184 ":ref:`sdk-manual/extensible:applying updates to an installed extensible sdk`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500185 section.
186
1873. Build the extensible SDK normally (i.e., use the
188 ``bitbake -c populate_sdk_ext`` imagename command).
189
Andrew Geisslerc926e172021-05-07 16:11:35 -05001904. Publish the SDK using the following command::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500191
192 $ oe-publish-sdk some_path/sdk-installer.sh path_to_shared_http_directory
193
194 You must
195 repeat this step each time you rebuild the SDK with changes that you
196 want to make available through the update mechanism.
197
198Completing the above steps allows users of the existing installed SDKs
199to simply run ``devtool sdk-update`` to retrieve and apply the latest
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500200updates. See the
201":ref:`sdk-manual/extensible:applying updates to an installed extensible sdk`"
202section for further information.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500203
204Changing the Default SDK Installation Directory
205===============================================
206
207When you build the installer for the Extensible SDK, the default
208installation directory for the SDK is based on the
209:term:`DISTRO` and
210:term:`SDKEXTPATH` variables from
211within the
212:ref:`populate_sdk_base <ref-classes-populate-sdk-*>`
Andrew Geisslerc926e172021-05-07 16:11:35 -0500213class as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500214
215 SDKEXTPATH ??= "~/${@d.getVar('DISTRO')}_sdk"
216
217You can
218change this default installation directory by specifically setting the
Andrew Geissler09036742021-06-25 14:25:14 -0500219:term:`SDKEXTPATH` variable.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500220
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700221While there are several ways of setting this variable,
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500222the method that makes the most sense is to set the variable in your
223distribution's configuration file. Doing so creates an SDK installer
224default directory that applies across your distribution. As an example,
225assume you have your own layer for your distribution named
226"meta-mydistro" and you are using the same type of file hierarchy as
227does the default "poky" distribution. If so, you could update the
Andrew Geissler09036742021-06-25 14:25:14 -0500228:term:`SDKEXTPATH` variable in the
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500229``~/meta-mydistro/conf/distro/mydistro.conf`` file using the following
Andrew Geisslerc926e172021-05-07 16:11:35 -0500230form::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500231
232 SDKEXTPATH = "some_path_for_your_installed_sdk"
233
234After building your installer, running it prompts the user for
235acceptance of the some_path_for_your_installed_sdk directory as the
236default location to install the Extensible SDK.
237
238Providing Additional Installable Extensible SDK Content
239=======================================================
240
241If you want the users of an extensible SDK you build to be able to add
242items to the SDK without requiring the users to build the items from
243source, you need to do a number of things:
244
2451. Ensure the additional items you want the user to be able to install
246 are already built:
247
248 - Build the items explicitly. You could use one or more "meta"
249 recipes that depend on lists of other recipes.
250
251 - Build the "world" target and set
Patrick Williams0ca19cc2021-08-16 14:03:13 -0500252 ``EXCLUDE_FROM_WORLD:pn-``\ recipename for the recipes you do not
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500253 want built. See the
254 :term:`EXCLUDE_FROM_WORLD`
255 variable for additional information.
256
2572. Expose the ``sstate-cache`` directory produced by the build.
258 Typically, you expose this directory by making it available through
259 an `Apache HTTP
260 Server <https://en.wikipedia.org/wiki/Apache_HTTP_Server>`__ or
261 `Nginx <https://en.wikipedia.org/wiki/Nginx>`__ server.
262
2633. Set the appropriate configuration so that the produced SDK knows how
264 to find the configuration. The variable you need to set is
Andrew Geisslerc926e172021-05-07 16:11:35 -0500265 :term:`SSTATE_MIRRORS`::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500266
267 SSTATE_MIRRORS = "file://.* http://example.com/some_path/sstate-cache/PATH"
268
Andrew Geissler09036742021-06-25 14:25:14 -0500269 You can set the :term:`SSTATE_MIRRORS` variable in two different places:
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500270
271 - If the mirror value you are setting is appropriate to be set for
272 both the OpenEmbedded build system that is actually building the
273 SDK and the SDK itself (i.e. the mirror is accessible in both
274 places or it will fail quickly on the OpenEmbedded build system
275 side, and its contents will not interfere with the build), then
276 you can set the variable in your ``local.conf`` or custom distro
Andrew Geissler595f6302022-01-24 19:11:47 +0000277 configuration file. You can then pass the variable to the SDK by
278 adding the following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500279
280 SDK_LOCAL_CONF_WHITELIST = "SSTATE_MIRRORS"
281
Andrew Geissler09036742021-06-25 14:25:14 -0500282 - Alternatively, if you just want to set the :term:`SSTATE_MIRRORS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500283 variable's value for the SDK alone, create a
284 ``conf/sdk-extra.conf`` file either in your
285 :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.