blob: 5a33f6385e7eabd7e68f7cd19ca18a61e900b372 [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
38 ``SDK_LOCAL_CONF_WHITELIST`` overrides either of the previous two
39 filters. The default value is blank.
40
41- Classes inherited globally with
42 :term:`INHERIT` that are listed in
43 :term:`SDK_INHERIT_BLACKLIST`
44 are disabled. Using ``SDK_INHERIT_BLACKLIST`` to disable these
45 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
60Host`'s setup.
61However, some cases exist for which you might consider making
62adjustments:
63
64- If your SDK configuration inherits additional classes using the
65 :term:`INHERIT` variable and you
66 do not need or want those classes enabled in the SDK, you can
67 blacklist them by adding them to the
68 :term:`SDK_INHERIT_BLACKLIST`
69 variable as described in the fourth bullet of the previous section.
70
71 .. note::
72
73 The default value of
74 SDK_INHERIT_BLACKLIST
75 is set using the "?=" operator. Consequently, you will need to
76 either define the entire list by using the "=" operator, or you
77 will need to append a value using either "_append" or the "+="
78 operator. You can learn more about these operators in the "
79 Basic Syntax
80 " section of the BitBake User Manual.
81
82 .
83
84- If you have classes or recipes that add additional tasks to the
85 standard build flow (i.e. the tasks execute as the recipe builds as
86 opposed to being called explicitly), then you need to do one of the
87 following:
88
89 - After ensuring the tasks are :ref:`shared
90 state <overview-manual/overview-manual-concepts:shared state cache>` tasks (i.e. the
91 output of the task is saved to and can be restored from the shared
92 state cache) or ensuring the tasks are able to be produced quickly
93 from a task that is a shared state task, add the task name to the
94 value of
95 :term:`SDK_RECRDEP_TASKS`.
96
97 - Disable the tasks if they are added by a class and you do not need
98 the functionality the class provides in the extensible SDK. To
99 disable the tasks, add the class to the ``SDK_INHERIT_BLACKLIST``
100 variable as described in the previous section.
101
102- Generally, you want to have a shared state mirror set up so users of
103 the SDK can add additional items to the SDK after installation
104 without needing to build the items from source. See the "`Providing
105 Additional Installable Extensible SDK
106 Content <#sdk-providing-additional-installable-extensible-sdk-content>`__"
107 section for information.
108
109- If you want users of the SDK to be able to easily update the SDK, you
110 need to set the
111 :term:`SDK_UPDATE_URL`
112 variable. For more information, see the "`Providing Updates to the
113 Extensible SDK After
114 Installation <#sdk-providing-updates-to-the-extensible-sdk-after-installation>`__"
115 section.
116
117- If you have adjusted the list of files and directories that appear in
118 :term:`COREBASE` (other than
119 layers that are enabled through ``bblayers.conf``), then you must
120 list these files in
121 :term:`COREBASE_FILES` so
122 that the files are copied into the SDK.
123
124- If your OpenEmbedded build system setup uses a different environment
125 setup script other than
126 :ref:`structure-core-script`, then you must
127 set
128 :term:`OE_INIT_ENV_SCRIPT`
129 to point to the environment setup script you use.
130
131 .. note::
132
133 You must also reflect this change in the value used for the
134 COREBASE_FILES
135 variable as previously described.
136
137Changing the Extensible SDK Installer Title
138===========================================
139
140You can change the displayed title for the SDK installer by setting the
141:term:`SDK_TITLE` variable and then
142rebuilding the the SDK installer. For information on how to build an SDK
143installer, see the "`Building an SDK
144Installer <#sdk-building-an-sdk-installer>`__" section.
145
146By default, this title is derived from
147:term:`DISTRO_NAME` when it is
148set. If the ``DISTRO_NAME`` variable is not set, the title is derived
149from the :term:`DISTRO` variable.
150
151The
152:ref:`populate_sdk_base <ref-classes-populate-sdk-*>`
153class defines the default value of the ``SDK_TITLE`` variable as
154follows:
155::
156
157 SDK_TITLE ??= "${@d.getVar('DISTRO_NAME') or d.getVar('DISTRO')} SDK"
158
159While several ways exist to change this variable, an efficient method is
160to set the variable in your distribution's configuration file. Doing so
161creates an SDK installer title that applies across your distribution. As
162an example, assume you have your own layer for your distribution named
163"meta-mydistro" and you are using the same type of file hierarchy as
164does the default "poky" distribution. If so, you could update the
165``SDK_TITLE`` variable in the
166``~/meta-mydistro/conf/distro/mydistro.conf`` file using the following
167form:
168::
169
170 SDK_TITLE = "your_title"
171
172Providing Updates to the Extensible SDK After Installation
173==========================================================
174
175When you make changes to your configuration or to the metadata and if
176you want those changes to be reflected in installed SDKs, you need to
177perform additional steps. These steps make it possible for anyone using
178the installed SDKs to update the installed SDKs by using the
179``devtool sdk-update`` command:
180
1811. Create a directory that can be shared over HTTP or HTTPS. You can do
182 this by setting up a web server such as an `Apache HTTP
183 Server <https://en.wikipedia.org/wiki/Apache_HTTP_Server>`__ or
184 `Nginx <https://en.wikipedia.org/wiki/Nginx>`__ server in the cloud
185 to host the directory. This directory must contain the published SDK.
186
1872. Set the
188 :term:`SDK_UPDATE_URL`
189 variable to point to the corresponding HTTP or HTTPS URL. Setting
190 this variable causes any SDK built to default to that URL and thus,
191 the user does not have to pass the URL to the ``devtool sdk-update``
192 command as described in the "`Applying Updates to an Installed
193 Extensible
194 SDK <#sdk-applying-updates-to-an-installed-extensible-sdk>`__"
195 section.
196
1973. Build the extensible SDK normally (i.e., use the
198 ``bitbake -c populate_sdk_ext`` imagename command).
199
2004. Publish the SDK using the following command:
201 ::
202
203 $ oe-publish-sdk some_path/sdk-installer.sh path_to_shared_http_directory
204
205 You must
206 repeat this step each time you rebuild the SDK with changes that you
207 want to make available through the update mechanism.
208
209Completing the above steps allows users of the existing installed SDKs
210to simply run ``devtool sdk-update`` to retrieve and apply the latest
211updates. See the "`Applying Updates to an Installed Extensible
212SDK <#sdk-applying-updates-to-an-installed-extensible-sdk>`__" section
213for further information.
214
215Changing the Default SDK Installation Directory
216===============================================
217
218When you build the installer for the Extensible SDK, the default
219installation directory for the SDK is based on the
220:term:`DISTRO` and
221:term:`SDKEXTPATH` variables from
222within the
223:ref:`populate_sdk_base <ref-classes-populate-sdk-*>`
224class as follows:
225::
226
227 SDKEXTPATH ??= "~/${@d.getVar('DISTRO')}_sdk"
228
229You can
230change this default installation directory by specifically setting the
231``SDKEXTPATH`` variable.
232
233While a number of ways exist through which you can set this variable,
234the method that makes the most sense is to set the variable in your
235distribution's configuration file. Doing so creates an SDK installer
236default directory that applies across your distribution. As an example,
237assume you have your own layer for your distribution named
238"meta-mydistro" and you are using the same type of file hierarchy as
239does the default "poky" distribution. If so, you could update the
240``SDKEXTPATH`` variable in the
241``~/meta-mydistro/conf/distro/mydistro.conf`` file using the following
242form:
243::
244
245 SDKEXTPATH = "some_path_for_your_installed_sdk"
246
247After building your installer, running it prompts the user for
248acceptance of the some_path_for_your_installed_sdk directory as the
249default location to install the Extensible SDK.
250
251Providing Additional Installable Extensible SDK Content
252=======================================================
253
254If you want the users of an extensible SDK you build to be able to add
255items to the SDK without requiring the users to build the items from
256source, you need to do a number of things:
257
2581. Ensure the additional items you want the user to be able to install
259 are already built:
260
261 - Build the items explicitly. You could use one or more "meta"
262 recipes that depend on lists of other recipes.
263
264 - Build the "world" target and set
265 ``EXCLUDE_FROM_WORLD_pn-``\ recipename for the recipes you do not
266 want built. See the
267 :term:`EXCLUDE_FROM_WORLD`
268 variable for additional information.
269
2702. Expose the ``sstate-cache`` directory produced by the build.
271 Typically, you expose this directory by making it available through
272 an `Apache HTTP
273 Server <https://en.wikipedia.org/wiki/Apache_HTTP_Server>`__ or
274 `Nginx <https://en.wikipedia.org/wiki/Nginx>`__ server.
275
2763. Set the appropriate configuration so that the produced SDK knows how
277 to find the configuration. The variable you need to set is
278 :term:`SSTATE_MIRRORS`:
279 ::
280
281 SSTATE_MIRRORS = "file://.* http://example.com/some_path/sstate-cache/PATH"
282
283 You can set the
284 ``SSTATE_MIRRORS`` variable in two different places:
285
286 - If the mirror value you are setting is appropriate to be set for
287 both the OpenEmbedded build system that is actually building the
288 SDK and the SDK itself (i.e. the mirror is accessible in both
289 places or it will fail quickly on the OpenEmbedded build system
290 side, and its contents will not interfere with the build), then
291 you can set the variable in your ``local.conf`` or custom distro
292 configuration file. You can then "whitelist" the variable through
293 to the SDK by adding the following:
294 ::
295
296 SDK_LOCAL_CONF_WHITELIST = "SSTATE_MIRRORS"
297
298 - Alternatively, if you just want to set the ``SSTATE_MIRRORS``
299 variable's value for the SDK alone, create a
300 ``conf/sdk-extra.conf`` file either in your
301 :term:`Build Directory` or within any
302 layer and put your ``SSTATE_MIRRORS`` setting within that file.
303
304 .. note::
305
306 This second option is the safest option should you have any
307 doubts as to which method to use when setting
308 SSTATE_MIRRORS
309 .
310
311Minimizing the Size of the Extensible SDK Installer Download
312============================================================
313
314By default, the extensible SDK bundles the shared state artifacts for
315everything needed to reconstruct the image for which the SDK was built.
316This bundling can lead to an SDK installer file that is a Gigabyte or
317more in size. If the size of this file causes a problem, you can build
318an SDK that has just enough in it to install and provide access to the
319``devtool command`` by setting the following in your configuration:
320::
321
322 SDK_EXT_TYPE = "minimal"
323
324Setting
325:term:`SDK_EXT_TYPE` to
326"minimal" produces an SDK installer that is around 35 Mbytes in size,
327which downloads and installs quickly. You need to realize, though, that
328the minimal installer does not install any libraries or tools out of the
329box. These libraries and tools must be installed either "on the fly" or
330through actions you perform using ``devtool`` or explicitly with the
331``devtool sdk-install`` command.
332
333In most cases, when building a minimal SDK you need to also enable
334bringing in the information on a wider range of packages produced by the
335system. Requiring this wider range of information is particularly true
336so that ``devtool add`` is able to effectively map dependencies it
337discovers in a source tree to the appropriate recipes. Additionally, the
338information enables the ``devtool search`` command to return useful
339results.
340
341To facilitate this wider range of information, you would need to set the
342following:
343::
344
345 SDK_INCLUDE_PKGDATA = "1"
346
347See the :term:`SDK_INCLUDE_PKGDATA` variable for additional information.
348
349Setting the ``SDK_INCLUDE_PKGDATA`` variable as shown causes the "world"
350target to be built so that information for all of the recipes included
351within it are available. Having these recipes available increases build
352time significantly and increases the size of the SDK installer by 30-80
353Mbytes depending on how many recipes are included in your configuration.
354
355You can use ``EXCLUDE_FROM_WORLD_pn-``\ recipename for recipes you want
356to exclude. However, it is assumed that you would need to be building
357the "world" target if you want to provide additional items to the SDK.
358Consequently, building for "world" should not represent undue overhead
359in most cases.
360
361.. note::
362
363 If you set
364 SDK_EXT_TYPE
365 to "minimal", then providing a shared state mirror is mandatory so
366 that items can be installed as needed. See the "
367 Providing Additional Installable Extensible SDK Content
368 " section for more information.
369
370You can explicitly control whether or not to include the toolchain when
371you build an SDK by setting the
372:term:`SDK_INCLUDE_TOOLCHAIN`
373variable to "1". In particular, it is useful to include the toolchain
374when you have set ``SDK_EXT_TYPE`` to "minimal", which by default,
375excludes the toolchain. Also, it is helpful if you are building a small
376SDK for use with an IDE or some other tool where you do not want to take
377extra steps to install a toolchain.