summaryrefslogtreecommitdiffstats
path: root/documentation/sdk-manual/sdk-appendix-customizing.xml
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/sdk-manual/sdk-appendix-customizing.xml')
-rw-r--r--documentation/sdk-manual/sdk-appendix-customizing.xml515
1 files changed, 0 insertions, 515 deletions
diff --git a/documentation/sdk-manual/sdk-appendix-customizing.xml b/documentation/sdk-manual/sdk-appendix-customizing.xml
deleted file mode 100644
index 08054f8b79..0000000000
--- a/documentation/sdk-manual/sdk-appendix-customizing.xml
+++ /dev/null
@@ -1,515 +0,0 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4<!--SPDX-License-Identifier: CC-BY-2.0-UK-->
5
6<appendix id='sdk-appendix-customizing'>
7
8<title>Customizing the Extensible SDK</title>
9
10<para>
11 This appendix describes customizations you can apply to the extensible SDK.
12</para>
13
14<section id='sdk-configuring-the-extensible-sdk'>
15 <title>Configuring the Extensible SDK</title>
16
17 <para>
18 The extensible SDK primarily consists of a pre-configured copy of
19 the OpenEmbedded build system from which it was produced.
20 Thus, the SDK's configuration is derived using that build system and
21 the filters shown in the following list.
22 When these filters are present, the OpenEmbedded build system applies
23 them against <filename>local.conf</filename> and
24 <filename>auto.conf</filename>:
25 <itemizedlist>
26 <listitem><para>
27 Variables whose values start with "/" are excluded since the
28 assumption is that those values are paths that are likely to
29 be specific to the
30 <ulink url='&YOCTO_DOCS_REF_URL;#hardware-build-system-term'>build host</ulink>.
31 </para></listitem>
32 <listitem><para>
33 Variables listed in
34 <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_LOCAL_CONF_BLACKLIST'><filename>SDK_LOCAL_CONF_BLACKLIST</filename></ulink>
35 are excluded.
36 These variables are not allowed through from the OpenEmbedded
37 build system configuration into the extensible SDK
38 configuration.
39 Typically, these variables are specific to the machine on
40 which the build system is running and could be problematic
41 as part of the extensible SDK configuration.</para>
42
43 <para>For a list of the variables excluded by default, see the
44 <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_LOCAL_CONF_BLACKLIST'><filename>SDK_LOCAL_CONF_BLACKLIST</filename></ulink>
45 in the glossary of the Yocto Project Reference Manual.
46 </para></listitem>
47 <listitem><para>
48 Variables listed in
49 <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_LOCAL_CONF_WHITELIST'><filename>SDK_LOCAL_CONF_WHITELIST</filename></ulink>
50 are included.
51 Including a variable in the value of
52 <filename>SDK_LOCAL_CONF_WHITELIST</filename> overrides either
53 of the previous two filters.
54 The default value is blank.
55 </para></listitem>
56 <listitem><para>
57 Classes inherited globally with
58 <ulink url='&YOCTO_DOCS_REF_URL;#var-INHERIT'><filename>INHERIT</filename></ulink>
59 that are listed in
60 <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_INHERIT_BLACKLIST'><filename>SDK_INHERIT_BLACKLIST</filename></ulink>
61 are disabled.
62 Using <filename>SDK_INHERIT_BLACKLIST</filename> to disable
63 these classes is the typical method to disable classes that
64 are problematic or unnecessary in the SDK context.
65 The default value blacklists the
66 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-buildhistory'><filename>buildhistory</filename></ulink>
67 and
68 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-icecc'><filename>icecc</filename></ulink>
69 classes.
70 </para></listitem>
71 </itemizedlist>
72 Additionally, the contents of <filename>conf/sdk-extra.conf</filename>,
73 when present, are appended to the end of
74 <filename>conf/local.conf</filename> within the produced SDK, without
75 any filtering.
76 The <filename>sdk-extra.conf</filename> file is particularly useful
77 if you want to set a variable value just for the SDK and not the
78 OpenEmbedded build system used to create the SDK.
79 </para>
80</section>
81
82<section id='adjusting-the-extensible-sdk-to-suit-your-build-hosts-setup'>
83 <title>Adjusting the Extensible SDK to Suit Your Build Host's Setup</title>
84
85 <para>
86 In most cases, the extensible SDK defaults should work with your
87 <ulink url='&YOCTO_DOCS_REF_URL;#hardware-build-system-term'>build host's</ulink>
88 setup.
89 However, some cases exist for which you might consider making
90 adjustments:
91 <itemizedlist>
92 <listitem><para>
93 If your SDK configuration inherits additional classes
94 using the
95 <ulink url='&YOCTO_DOCS_REF_URL;#var-INHERIT'><filename>INHERIT</filename></ulink>
96 variable and you do not need or want those classes enabled in
97 the SDK, you can blacklist them by adding them to the
98 <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_INHERIT_BLACKLIST'><filename>SDK_INHERIT_BLACKLIST</filename></ulink>
99 variable as described in the fourth bullet of the previous
100 section.
101 <note>
102 The default value of
103 <filename>SDK_INHERIT_BLACKLIST</filename> is set using
104 the "?=" operator.
105 Consequently, you will need to either define the entire
106 list by using the "=" operator, or you will need to append
107 a value using either "_append" or the "+=" operator.
108 You can learn more about these operators in the
109 "<ulink url='&YOCTO_DOCS_BB_URL;#basic-syntax'>Basic Syntax</ulink>"
110 section of the BitBake User Manual.
111 </note>.
112 </para></listitem>
113 <listitem><para>
114 If you have classes or recipes that add additional tasks to
115 the standard build flow (i.e. the tasks execute as the recipe
116 builds as opposed to being called explicitly), then you need
117 to do one of the following:
118 <itemizedlist>
119 <listitem><para>
120 After ensuring the tasks are
121 <ulink url='&YOCTO_DOCS_OM_URL;#shared-state-cache'>shared state</ulink>
122 tasks (i.e. the output of the task is saved to and
123 can be restored from the shared state cache) or
124 ensuring the tasks are able to be produced quickly from
125 a task that is a shared state task, add the task name
126 to the value of
127 <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_RECRDEP_TASKS'><filename>SDK_RECRDEP_TASKS</filename></ulink>.
128 </para></listitem>
129 <listitem><para>
130 Disable the tasks if they are added by a class and
131 you do not need the functionality the class provides
132 in the extensible SDK.
133 To disable the tasks, add the class to the
134 <filename>SDK_INHERIT_BLACKLIST</filename> variable
135 as described in the previous section.
136 </para></listitem>
137 </itemizedlist>
138 </para></listitem>
139 <listitem><para>
140 Generally, you want to have a shared state mirror set up so
141 users of the SDK can add additional items to the SDK after
142 installation without needing to build the items from source.
143 See the
144 "<link linkend='sdk-providing-additional-installable-extensible-sdk-content'>Providing Additional Installable Extensible SDK Content</link>"
145 section for information.
146 </para></listitem>
147 <listitem><para>
148 If you want users of the SDK to be able to easily update the
149 SDK, you need to set the
150 <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_UPDATE_URL'><filename>SDK_UPDATE_URL</filename></ulink>
151 variable.
152 For more information, see the
153 "<link linkend='sdk-providing-updates-to-the-extensible-sdk-after-installation'>Providing Updates to the Extensible SDK After Installation</link>"
154 section.
155 </para></listitem>
156 <listitem><para>
157 If you have adjusted the list of files and directories that
158 appear in
159 <ulink url='&YOCTO_DOCS_REF_URL;#var-COREBASE'><filename>COREBASE</filename></ulink>
160 (other than layers that are enabled through
161 <filename>bblayers.conf</filename>), then you must list these
162 files in
163 <ulink url='&YOCTO_DOCS_REF_URL;#var-COREBASE_FILES'><filename>COREBASE_FILES</filename></ulink>
164 so that the files are copied into the SDK.
165 </para></listitem>
166 <listitem><para>
167 If your OpenEmbedded build system setup uses a different
168 environment setup script other than
169 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>,
170 then you must set
171 <ulink url='&YOCTO_DOCS_REF_URL;#var-OE_INIT_ENV_SCRIPT'><filename>OE_INIT_ENV_SCRIPT</filename></ulink>
172 to point to the environment setup script you use.
173 <note>
174 You must also reflect this change in the value used for the
175 <filename>COREBASE_FILES</filename> variable as previously
176 described.
177 </note>
178 </para></listitem>
179 </itemizedlist>
180 </para>
181</section>
182
183<section id='sdk-changing-the-sdk-installer-title'>
184 <title>Changing the Extensible SDK Installer Title</title>
185
186 <para>
187 You can change the displayed title for the SDK installer by setting
188 the
189 <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_TITLE'><filename>SDK_TITLE</filename></ulink>
190 variable and then rebuilding the the SDK installer.
191 For information on how to build an SDK installer, see the
192 "<link linkend='sdk-building-an-sdk-installer'>Building an SDK Installer</link>"
193 section.
194 </para>
195
196 <para>
197 By default, this title is derived from
198 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_NAME'><filename>DISTRO_NAME</filename></ulink>
199 when it is set.
200 If the <filename>DISTRO_NAME</filename> variable is not set, the title
201 is derived from the
202 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO'><filename>DISTRO</filename></ulink>
203 variable.
204 </para>
205
206 <para>
207 The
208 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-populate-sdk-*'><filename>populate_sdk_base</filename></ulink>
209 class defines the default value of the <filename>SDK_TITLE</filename>
210 variable as follows:
211 <literallayout class='monospaced'>
212 SDK_TITLE ??= "${@d.getVar('DISTRO_NAME') or d.getVar('DISTRO')} SDK"
213 </literallayout>
214 </para>
215
216 <para>
217 While several ways exist to change this variable, an efficient method
218 is to set the variable in your distribution's configuration file.
219 Doing so creates an SDK installer title that applies across your
220 distribution.
221 As an example, assume you have your own layer for your distribution
222 named "meta-mydistro" and you are using the same type of file
223 hierarchy as does the default "poky" distribution.
224 If so, you could update the <filename>SDK_TITLE</filename> variable
225 in the
226 <filename>~/meta-mydistro/conf/distro/mydistro.conf</filename> file
227 using the following form:
228 <literallayout class='monospaced'>
229 SDK_TITLE = "<replaceable>your_title</replaceable>"
230 </literallayout>
231 </para>
232</section>
233
234<section id='sdk-providing-updates-to-the-extensible-sdk-after-installation'>
235 <title>Providing Updates to the Extensible SDK After Installation</title>
236
237 <para>
238 When you make changes to your configuration or to the metadata and
239 if you want those changes to be reflected in installed SDKs, you need
240 to perform additional steps.
241 These steps make it possible for anyone using the installed SDKs to
242 update the installed SDKs by using the
243 <filename>devtool sdk-update</filename> command:
244 <orderedlist>
245 <listitem><para>
246 Create a directory that can be shared over HTTP or HTTPS.
247 You can do this by setting up a web server such as an
248 <ulink url='https://en.wikipedia.org/wiki/Apache_HTTP_Server'>Apache HTTP Server</ulink>
249 or
250 <ulink url='https://en.wikipedia.org/wiki/Nginx'>Nginx</ulink>
251 server in the cloud to host the directory.
252 This directory must contain the published SDK.
253 </para></listitem>
254 <listitem><para>
255 Set the
256 <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_UPDATE_URL'><filename>SDK_UPDATE_URL</filename></ulink>
257 variable to point to the corresponding HTTP or HTTPS URL.
258 Setting this variable causes any SDK built to default to that
259 URL and thus, the user does not have to pass the URL to the
260 <filename>devtool sdk-update</filename> command as described
261 in the
262 "<link linkend='sdk-applying-updates-to-an-installed-extensible-sdk'>Applying Updates to an Installed Extensible SDK</link>"
263 section.
264 </para></listitem>
265 <listitem><para>
266 Build the extensible SDK normally (i.e., use the
267 <filename>bitbake -c populate_sdk_ext</filename> <replaceable>imagename</replaceable>
268 command).
269 </para></listitem>
270 <listitem><para>
271 Publish the SDK using the following command:
272 <literallayout class='monospaced'>
273 $ oe-publish-sdk <replaceable>some_path</replaceable>/sdk-installer.sh <replaceable>path_to_shared_http_directory</replaceable>
274 </literallayout>
275 You must repeat this step each time you rebuild the SDK
276 with changes that you want to make available through the
277 update mechanism.
278 </para></listitem>
279 </orderedlist>
280 </para>
281
282 <para>
283 Completing the above steps allows users of the existing installed
284 SDKs to simply run <filename>devtool sdk-update</filename> to
285 retrieve and apply the latest updates.
286 See the
287 "<link linkend='sdk-applying-updates-to-an-installed-extensible-sdk'>Applying Updates to an Installed Extensible SDK</link>"
288 section for further information.
289 </para>
290</section>
291
292<section id='sdk-changing-the-default-sdk-installation-directory'>
293 <title>Changing the Default SDK Installation Directory</title>
294
295 <para>
296 When you build the installer for the Extensible SDK, the default
297 installation directory for the SDK is based on the
298 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO'><filename>DISTRO</filename></ulink>
299 and
300 <ulink url='&YOCTO_DOCS_REF_URL;#var-SDKEXTPATH'><filename>SDKEXTPATH</filename></ulink>
301 variables from within the
302 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-populate-sdk-*'><filename>populate_sdk_base</filename></ulink>
303 class as follows:
304 <literallayout class='monospaced'>
305 SDKEXTPATH ??= "~/${@d.getVar('DISTRO')}_sdk"
306 </literallayout>
307 You can change this default installation directory by specifically
308 setting the <filename>SDKEXTPATH</filename> variable.
309 </para>
310
311 <para>
312 While a number of ways exist through which you can set this variable,
313 the method that makes the most sense is to set the variable in your
314 distribution's configuration file.
315 Doing so creates an SDK installer default directory that applies
316 across your distribution.
317 As an example, assume you have your own layer for your distribution
318 named "meta-mydistro" and you are using the same type of file
319 hierarchy as does the default "poky" distribution.
320 If so, you could update the <filename>SDKEXTPATH</filename> variable
321 in the
322 <filename>~/meta-mydistro/conf/distro/mydistro.conf</filename> file
323 using the following form:
324 <literallayout class='monospaced'>
325 SDKEXTPATH = "<replaceable>some_path_for_your_installed_sdk</replaceable>"
326 </literallayout>
327 </para>
328
329 <para>
330 After building your installer, running it prompts the user for
331 acceptance of the
332 <replaceable>some_path_for_your_installed_sdk</replaceable> directory
333 as the default location to install the Extensible SDK.
334 </para>
335</section>
336
337<section id='sdk-providing-additional-installable-extensible-sdk-content'>
338 <title>Providing Additional Installable Extensible SDK Content</title>
339
340 <para>
341 If you want the users of an extensible SDK you build to be
342 able to add items to the SDK without requiring the users to build
343 the items from source, you need to do a number of things:
344 <orderedlist>
345 <listitem><para>
346 Ensure the additional items you want the user to be able to
347 install are already built:
348 <itemizedlist>
349 <listitem><para>
350 Build the items explicitly.
351 You could use one or more "meta" recipes that depend
352 on lists of other recipes.
353 </para></listitem>
354 <listitem><para>
355 Build the "world" target and set
356 <filename>EXCLUDE_FROM_WORLD_pn-</filename><replaceable>recipename</replaceable>
357 for the recipes you do not want built.
358 See the
359 <ulink url='&YOCTO_DOCS_REF_URL;#var-EXCLUDE_FROM_WORLD'><filename>EXCLUDE_FROM_WORLD</filename></ulink>
360 variable for additional information.
361 </para></listitem>
362 </itemizedlist>
363 </para></listitem>
364 <listitem><para>
365 Expose the <filename>sstate-cache</filename> directory
366 produced by the build.
367 Typically, you expose this directory by making it available
368 through an
369 <ulink url='https://en.wikipedia.org/wiki/Apache_HTTP_Server'>Apache HTTP Server</ulink>
370 or
371 <ulink url='https://en.wikipedia.org/wiki/Nginx'>Nginx</ulink>
372 server.
373 </para></listitem>
374 <listitem><para>
375 Set the appropriate configuration so that the produced SDK
376 knows how to find the configuration.
377 The variable you need to set is
378 <ulink url='&YOCTO_DOCS_REF_URL;#var-SSTATE_MIRRORS'><filename>SSTATE_MIRRORS</filename></ulink>:
379 <literallayout class='monospaced'>
380 SSTATE_MIRRORS = "file://.* http://<replaceable>example</replaceable>.com/<replaceable>some_path</replaceable>/sstate-cache/PATH"
381 </literallayout>
382 You can set the <filename>SSTATE_MIRRORS</filename> variable
383 in two different places:
384 <itemizedlist>
385 <listitem><para>
386 If the mirror value you are setting is appropriate to
387 be set for both the OpenEmbedded build system that is
388 actually building the SDK and the SDK itself (i.e. the
389 mirror is accessible in both places or it will fail
390 quickly on the OpenEmbedded build system side, and its
391 contents will not interfere with the build), then you
392 can set the variable in your
393 <filename>local.conf</filename> or custom distro
394 configuration file.
395 You can then "whitelist" the variable through
396 to the SDK by adding the following:
397 <literallayout class='monospaced'>
398 SDK_LOCAL_CONF_WHITELIST = "SSTATE_MIRRORS"
399 </literallayout>
400 </para></listitem>
401 <listitem><para>
402 Alternatively, if you just want to set the
403 <filename>SSTATE_MIRRORS</filename> variable's value
404 for the SDK alone, create a
405 <filename>conf/sdk-extra.conf</filename> file either in
406 your
407 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
408 or within any layer and put your
409 <filename>SSTATE_MIRRORS</filename> setting within
410 that file.
411 <note>
412 This second option is the safest option should
413 you have any doubts as to which method to use when
414 setting <filename>SSTATE_MIRRORS</filename>.
415 </note>
416 </para></listitem>
417 </itemizedlist>
418 </para></listitem>
419 </orderedlist>
420 </para>
421</section>
422
423<section id='sdk-minimizing-the-size-of-the-extensible-sdk-installer-download'>
424 <title>Minimizing the Size of the Extensible SDK Installer Download</title>
425
426 <para>
427 By default, the extensible SDK bundles the shared state artifacts for
428 everything needed to reconstruct the image for which the SDK was built.
429 This bundling can lead to an SDK installer file that is a Gigabyte or
430 more in size.
431 If the size of this file causes a problem, you can build an SDK that
432 has just enough in it to install and provide access to the
433 <filename>devtool command</filename> by setting the following in your
434 configuration:
435 <literallayout class='monospaced'>
436 SDK_EXT_TYPE = "minimal"
437 </literallayout>
438 Setting
439 <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_EXT_TYPE'><filename>SDK_EXT_TYPE</filename></ulink>
440 to "minimal" produces an SDK installer that is around 35 Mbytes in
441 size, which downloads and installs quickly.
442 You need to realize, though, that the minimal installer does not
443 install any libraries or tools out of the box.
444 These libraries and tools must be installed either "on the fly" or
445 through actions you perform using <filename>devtool</filename> or
446 explicitly with the <filename>devtool sdk-install</filename> command.
447 </para>
448
449 <para>
450 In most cases, when building a minimal SDK you need to also enable
451 bringing in the information on a wider range of packages produced by
452 the system.
453 Requiring this wider range of information is particularly true
454 so that <filename>devtool add</filename> is able to effectively map
455 dependencies it discovers in a source tree to the appropriate recipes.
456 Additionally, the information enables the
457 <filename>devtool search</filename> command to return useful results.
458 </para>
459
460 <para>
461 To facilitate this wider range of information, you would need to
462 set the following:
463 <literallayout class='monospaced'>
464 SDK_INCLUDE_PKGDATA = "1"
465 </literallayout>
466 See the
467 <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_INCLUDE_PKGDATA'><filename>SDK_INCLUDE_PKGDATA</filename></ulink>
468 variable for additional information.
469 </para>
470
471 <para>
472 Setting the <filename>SDK_INCLUDE_PKGDATA</filename> variable as
473 shown causes the "world" target to be built so that information
474 for all of the recipes included within it are available.
475 Having these recipes available increases build time significantly and
476 increases the size of the SDK installer by 30-80 Mbytes depending on
477 how many recipes are included in your configuration.
478 </para>
479
480 <para>
481 You can use
482 <filename>EXCLUDE_FROM_WORLD_pn-</filename><replaceable>recipename</replaceable>
483 for recipes you want to exclude.
484 However, it is assumed that you would need to be building the "world"
485 target if you want to provide additional items to the SDK.
486 Consequently, building for "world" should not represent undue
487 overhead in most cases.
488 <note>
489 If you set <filename>SDK_EXT_TYPE</filename> to "minimal",
490 then providing a shared state mirror is mandatory so that items
491 can be installed as needed.
492 See the
493 "<link linkend='sdk-providing-additional-installable-extensible-sdk-content'>Providing Additional Installable Extensible SDK Content</link>"
494 section for more information.
495 </note>
496 </para>
497
498 <para>
499 You can explicitly control whether or not to include the toolchain
500 when you build an SDK by setting the
501 <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_INCLUDE_TOOLCHAIN'><filename>SDK_INCLUDE_TOOLCHAIN</filename></ulink>
502 variable to "1".
503 In particular, it is useful to include the toolchain when you
504 have set <filename>SDK_EXT_TYPE</filename> to "minimal", which by
505 default, excludes the toolchain.
506 Also, it is helpful if you are building a small SDK for use with
507 an IDE or some
508 other tool where you do not want to take extra steps to install a
509 toolchain.
510 </para>
511</section>
512</appendix>
513<!--
514vim: expandtab tw=80 ts=4
515-->
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-11-13 02:15:24 +0000