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.xml381
1 files changed, 372 insertions, 9 deletions
diff --git a/documentation/sdk-manual/sdk-appendix-customizing.xml b/documentation/sdk-manual/sdk-appendix-customizing.xml
index 2068143df3..3ee0d7c90a 100644
--- a/documentation/sdk-manual/sdk-appendix-customizing.xml
+++ b/documentation/sdk-manual/sdk-appendix-customizing.xml
@@ -6,17 +6,380 @@
6 6
7<title>Customizing the SDK</title> 7<title>Customizing the SDK</title>
8 8
9<para role='writernotes'> 9<para>
10 This chapter is going to cover the details on extending the SDK through 10 This appendix presents customizations you can apply to both the standard
11 user customizations. 11 and extensible SDK.
12 I am not sure if this is possible for both the standard and extensible 12 Each subsection identifies the type of SDK to which the section applies.
13 SDK or what.
14</para> 13</para>
15 14
16<para role='writernotes'> 15<section id='sdk-configuring-the-extensible-sdk'>
17 I do not have a feel for what sub-topics need to be covered here. 16 <title>Configuring the Extensible SDK</title>
18 I need to get this information from Paul. 17
19</para> 18 <para>
19 The extensible SDK primarily consists of a pre-configured copy of
20 the build system from which it was produced.
21 Thus, the SDK's configuration is derived using that build system.
22 However, filters exist that are applied such as the following that
23 are applied to <filename>local.conf</filename> and
24 <filename>auto.conf</filename> when present:
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 build host.
30 </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.
35 The default value blacklists
36 <ulink url='&YOCTO_DOCS_REF_URL;#var-CONF_VERSION'><filename>CONF_VERSION</filename></ulink>,
37 <ulink url='&YOCTO_DOCS_REF_URL;#var-BB_NUMBER_THREADS'><filename>BB_NUMBER_THREADS</filename></ulink>,
38 <ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></ulink>,
39 <ulink url='&YOCTO_DOCS_REF_URL;#var-PRSERV_HOST'><filename>PRSERV_HOST</filename></ulink>,
40 and
41 <ulink url='&YOCTO_DOCS_REF_URL;#var-SSTATE_MIRRORS'><filename>SSTATE_MIRRORS</filename></ulink>.
42 </para></listitem>
43 <listitem><para>
44 Variables listed in
45 <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_LOCAL_CONF_WHITELIST'><filename>SDK_LOCAL_CONF_WHITELIST</filename></ulink>
46 are included.
47 Including these variables overrides either of the above two
48 conditions.
49 The default value is blank.
50 </para></listitem>
51 <listitem><para>
52 Classes inherited globally with
53 <ulink url='&YOCTO_DOCS_REF_URL;#var-INHERIT'><filename>INHERIT</filename></ulink>
54 that are listed in
55 <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_INHERIT_BLACKLIST'><filename>SDK_INHERIT_BLACKLIST</filename></ulink>
56 are disabled.
57 Using <filename>SDK_INHERIT_BLACKLIST</filename> to disable
58 these classes is is the typical method to disable classes that
59 are problematic or unnecessary in the SDK context.
60 The default value blacklists the
61 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-buildhistory'><filename>buildhistory</filename></ulink>
62 and
63 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-icecc'><filename>icecc</filename></ulink>
64 classes.
65 </para></listitem>
66 </itemizedlist>
67 Additionally, the contents of <filename>conf/sdk-extra.conf</filename>,
68 when present, are appended to the end of
69 <filename>conf/local.conf</filename> within the produced SDK, without
70 any filtering.
71 Not filtering these contents is particularly useful if you want to
72 set a variable value just for the SDK and not the build system used to
73 create the SDK.
74 </para>
75</section>
76
77<section id='adjusting-the-extensible-sdk-to-suit-your-build-system-setup'>
78 <title>Adjusting the Extensible SDK to Suit Your Build System Setup</title>
79
80 <para>
81 In most cases, the extensible SDK defaults should work.
82 However, some cases exist for which you might consider making
83 adjustments:
84 <itemizedlist>
85 <listitem><para>
86 If your SDK configuration inherits additional classes
87 using the
88 <ulink url='&YOCTO_DOCS_REF_URL;#var-INHERIT'><filename>INHERIT</filename></ulink>
89 variable and you do not need or want those classes enabled in
90 the SDK, you can blacklist them by adding them to the
91 <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_INHERIT_BLACKLIST'><filename>SDK_INHERIT_BLACKLIST</filename></ulink>
92 variable.
93 The default value of <filename>SDK_INHERIT_BLACKLIST</filename>
94 is set using the "?=" operator.
95 Consequently, you will need to either set the complete value
96 using "=" or append the value using "_append".
97 </para></listitem>
98 <listitem><para>
99 If you have classes or recipes that add additional tasks to
100 the standard build flow (i.e. that execute as part of building
101 the recipe as opposed to needing to be called explicitly), then
102 you need to do one of the following:
103 <itemizedlist>
104 <listitem><para>
105 Ensure the tasks are shared state tasks (i.e. their
106 output is saved to and can be restored from the shared
107 state cache), or that the tasks are able to be
108 produced quickly from a task that is a shared state
109 task and add the task name to the value of
110 <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_RECRDEP_TASKS'><filename>SDK_RECRDEP_TASKS</filename></ulink>.
111 </para></listitem>
112 <listitem><para>
113 Disable the tasks if they are added by a class and
114 you do not need the functionality the class provides
115 in the extensible SDK.
116 To disable the tasks, add the class to
117 <filename>SDK_INHERIT_BLACKLIST</filename> as previously
118 described.
119 </para></listitem>
120 </itemizedlist>
121 </para></listitem>
122 <listitem><para>
123 Generally, you want to have a shared state mirror set up so
124 users of the SDK can add additional items to the SDK after
125 installation without needing to build the items from source.
126 See the
127 "<link linkend='sdk-providing-additional-installable-extensible-sdk-content'>Providing Additional Installable Extensible SDK Content</link>"
128 section for information.
129 </para></listitem>
130 <listitem><para>
131 If you want users of the SDK to be able to easily update the
132 SDK, you need to set the
133 <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_UPDATE_URL'><filename>SDK_UPDATE_URL</filename></ulink>
134 variable.
135 For more information, see the
136 "<link linkend='sdk-providing-updates-after-installing-the-extensible-sdk'>Providing Updates After Installing the Extensible SDK</link>"
137 section.
138 </para></listitem>
139 <listitem><para>
140 If you have adjusted the list of files and directories that
141 appear in
142 <ulink url='&YOCTO_DOCS_REF_URL;#var-COREBASE'><filename>COREBASE</filename></ulink>
143 (other than layers that are enabled through
144 <filename>bblayers.conf</filename>), then must list these
145 files in
146 <ulink url='&YOCTO_DOCS_REF_URL;#var-COREBASE_FILES'><filename>COREBASE_FILES</filename></ulink>
147 so that the files are copied into the SDK.
148 </para></listitem>
149 <listitem><para>
150 If your build system setup uses a different environment setup
151 script other than
152 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
153 or
154 <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>,
155 then you must set
156 <ulink url='&YOCTO_DOCS_REF_URL;#var-OE_INIT_ENV_SCRIPT'><filename>OE_INIT_ENV_SCRIPT</filename></ulink>
157 to point to the environment setup script you use.
158 <note>
159 You must also reflect this change in the value used for the
160 <filename>COREBASE_FILES</filename> variable as previously
161 described.
162 </note>
163 </para></listitem>
164 </itemizedlist>
165 </para>
166</section>
167
168<section id='sdk-changing-the-appearance-of-the-extensible-sdk'>
169 <title>Changing the Appearance of the Extensible SDK</title>
170
171 <para>
172 You can change the title shown by the SDK installer by setting the
173 <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_TITLE'><filename>SDK_TITLE</filename></ulink>
174 variable.
175 By default, this title is derived from
176 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_NAME'><filename>DISTRO_NAME</filename></ulink>
177 when it is set.
178 If the <filename>DISTRO_NAME</filename> variable is not set, the title
179 is derived from the
180 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO'><filename>DISTRO</filename></ulink>
181 variable.
182 </para>
183</section>
184
185<section id='sdk-providing-updates-after-installing-the-extensible-sdk'>
186 <title>Providing Updates After Installing the Extensible SDK</title>
187
188 <para>
189 When you make changes to your configuration or to the metadata and
190 if you want those changes to be reflected in installed SDKs, you need
191 to perform additional steps to make it possible for those that use
192 the SDK to update their installations with the
193 <filename>devtool sdk-update</filename> command:
194 <orderedlist>
195 <listitem><para>
196 Arrange to be created a directory that can be shared over
197 HTTP or HTTPS.
198 </para></listitem>
199 <listitem><para>
200 Set the
201 <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_UPDATE_URL'><filename>SDK_UPDATE_URL</filename></ulink>
202 variable to point to the corresponding HTTP or HTTPS URL.
203 Setting this variable causes any SDK built to default to that
204 URL and thus, the user does not have to pass the URL to the
205 <filename>devtool sdk-update</filename> command.
206 </para></listitem>
207 <listitem><para>
208 Build the extensible SDK normally (i.e., use the
209 <filename>bitbake -c populate_sdk_ext</filename> <replaceable>imagename</replaceable>
210 command).
211 </para></listitem>
212 <listitem><para>
213 Publish the SDK using the following command:
214 <literallayout class='monospaced'>
215 $ oe-publish-sdk <replaceable>some_path</replaceable>/sdk-installer.sh <replaceable>path_to_shared/http_directory</replaceable>
216 </literallayout>
217 You must repeat this step each time you rebuild the SDK
218 with changes that you want to make available through the
219 update mechanism.
220 </para></listitem>
221 </orderedlist>
222 </para>
223
224 <para>
225 Completing the above steps allows users of the existing SDKs to
226 simply run <filename>devtool sdk-update</filename> to retrieve the
227 latest updates.
228 See the
229 "<link linkend='sdk-updating-the-extensible-sdk'>Updating the Extensible SDK</link>"
230 section for further information.
231 </para>
232</section>
233
234<section id='sdk-providing-additional-installable-extensible-sdk-content'>
235 <title>Providing Additional Installable Extensible SDK Content</title>
236
237 <para>
238 If you want the users of the extensible SDK you are building to be
239 able to add items to the SDK without needing to build the
240 items from source, you need to do a number of things:
241 <orderedlist>
242 <listitem><para>
243 Ensure the additional items you want the user to be able to
244 install are actually built.
245 You can ensure these items are built a number of different
246 ways: 1) Build them explicitly, perhaps using one or more
247 "meta" recipes that depend on lists of other recipes to keep
248 things tidy, or 2) Build the "world" target and set
249 <filename>EXCLUDE_FROM_WORLD_pn-</filename><replaceable>recipename</replaceable>
250 for the recipes you do not want built.
251 See the
252 <ulink url='&YOCTO_DOCS_REF_URL;#var-EXCLUDE_FROM_WORLD'><filename>EXCLUDE_FROM_WORLD</filename></ulink>
253 variable for additional information.
254 </para></listitem>
255 <listitem><para>
256 Expose the <filename>sstate-cache</filename> directory
257 produced by the build.
258 Typically, you expose this directory over HTTP or HTTPS.
259 </para></listitem>
260 <listitem><para>
261 Set the appropriate configuration so that the produced SDK
262 knows how to find the configuration.
263 The variable you need to set is
264 <ulink url='&YOCTO_DOCS_REF_URL;#var-SSTATE_MIRRORS'><filename>SSTATE_MIRRORS</filename></ulink>:
265 <literallayout class='monospaced'>
266 SSTATE_MIRRORS = "file://.* http://<replaceable>example</replaceable>.com/<replaceable>some_path</replaceable>/sstate-cache/PATH"
267 </literallayout>
268 You can set the <filename>SSTATE_MIRRORS</filename> variable
269 in two different places:
270 <itemizedlist>
271 <listitem><para>
272 If the mirror value you are setting is appropriate to
273 be set for both the build system that is actually
274 building the SDK and the SDK itself (i.e. the mirror
275 is accessible in both places or it will fail quickly
276 on the build system side, and its contents will not
277 interfere with the build), then you can set the
278 variable in your <filename>local.conf</filename>
279 or custom distro configuration file.
280 You can "whitelist" the variable through the SDK by
281 adding the following:
282 <literallayout class='monospaced'>
283 SDK_LOCAL_CONF_WHITELIST = "SSTATE_MIRRORS"
284 </literallayout>
285 </para></listitem>
286 <listitem><para>
287 Alternatively, if you just want to set the
288 <filename>SSTATE_MIRRORS</filename> variable's value
289 for the SDK alone, create a
290 <filename>conf/sdk-extra.conf</filename> either in
291 your
292 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
293 or within any layer and put your
294 <filename>SSTATE_MIRRORS</filename> setting within
295 that file.
296 <note>
297 This second option is the safest option should
298 you have any doubts as to which method to use when
299 setting <filename>SSTATE_MIRRORS</filename>.
300 </note>
301 </para></listitem>
302 </itemizedlist>
303 </para></listitem>
304 </orderedlist>
305 </para>
306</section>
307
308<section id='sdk-minimizing-the-size-of-the-extensible-sdk-installer-download'>
309 <title>Minimizing the Size of the Extensible SDK Installer Download</title>
310
311 <para>
312 By default, the extensible SDK bundles the shared state artifacts for
313 everything needed to reconstruct the image for which the SDK was built.
314 This bundling can lead to an SDK installer file that is a Gigabyte or
315 more in size.
316 If the size of this file causes a problem, you can build an SDK that
317 has just enough in it to install and provide access to the
318 <filename>devtool command</filename> by setting the following in your
319 configuration:
320 <literallayout class='monospaced'>
321 SDK_EXT_TYPE = "minimal"
322 </literallayout>
323 Setting
324 <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_EXT_TYPE'><filename>SDK_EXT_TYPE</filename></ulink>
325 to "minimal" produces an SDK installer that is around 35 Mbytes in
326 size, which downloads and installs quickly.
327 You need to realize, though, that the installer does not install any
328 libraries or tools out of the box.
329 These must be installed either "on the fly" or through actions you
330 perform using <filename>devtool</filename> or explicitly with the
331 <filename>devtool sdk-install</filename> command.
332 </para>
333
334 <para>
335 In most cases, when building a minimal SDK you will need to also enable
336 bringing in the information on a wider range of packages produced by
337 the system.
338 This is particularly true so that <filename>devtool add</filename>
339 is able to effectively map dependencies it discovers in a source tree
340 to the appropriate recipes.
341 Also so that the <filename>devtool search</filename> command
342 is able to return useful results.
343 </para>
344
345 <para>
346 To facilitate this wider range of information, you would additionally
347 set the following:
348 <literallayout class='monospaced'>
349 SDK_INCLUDE_PKGDATA = "1"
350 </literallayout>
351 See the
352 <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_INCLUDE_PKGDATA'><filename>SDK_INCLUDE_PKGDATA</filename></ulink>
353 variable for additional information.
354 </para>
355
356 <para>
357 Setting the <filename>SDK_INCLUDE_PKGDATA</filename> variable as
358 shown causes the "world" target to be built so that information
359 for all of the recipes included within it are available.
360 Having these recipes available increases build time significantly and
361 increases the size of the SDK installer by 30-80 Mbytes depending on
362 how many recipes are included in your configuration.
363 </para>
364
365 <para>
366 You can use
367 <filename>EXCLUDE_FROM_WORLD_pn-</filename><replaceable>recipename</replaceable>
368 for recipes you want to exclude.
369 However, it is assumed that you would need to be building the "world"
370 target if you want to provide additional items to the SDK.
371 Consequently, building for "world" should not represent undue
372 overhead in most cases.
373 <note>
374 If you set <filename>SDK_EXT_TYPE</filename> to "minimal",
375 then providing a shared state mirror is mandatory so that items
376 can be installed as needed.
377 See the
378 "<link linkend='sdk-providing-additional-installable-extensible-sdk-content'>Providing Additional Installable Extensible SDK Content</link>"
379 section for more information.
380 </note>
381 </para>
382</section>
20 383
21</appendix> 384</appendix>
22<!-- 385<!--
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2025-12-05 07:02:05 +0000