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