summaryrefslogtreecommitdiffstats
path: root/documentation/sdk-manual
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/sdk-manual')
-rw-r--r--documentation/sdk-manual/sdk-appendix-customizing.xml381
-rw-r--r--documentation/sdk-manual/sdk-appendix-obtain.xml82
-rw-r--r--documentation/sdk-manual/sdk-extensible.xml116
-rw-r--r--documentation/sdk-manual/sdk-intro.xml28
4 files changed, 506 insertions, 101 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<!--
diff --git a/documentation/sdk-manual/sdk-appendix-obtain.xml b/documentation/sdk-manual/sdk-appendix-obtain.xml
index 6ffc958695..daa5e79fe8 100644
--- a/documentation/sdk-manual/sdk-appendix-obtain.xml
+++ b/documentation/sdk-manual/sdk-appendix-obtain.xml
@@ -52,18 +52,20 @@
52 52
53 <para> 53 <para>
54 As an alternative to locating and downloading a toolchain installer, 54 As an alternative to locating and downloading a toolchain installer,
55 you can build the toolchain installer if you have a 55 you can build the toolchain installer assuming you have first sourced
56 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>. 56 the environment setup script.
57 <note> 57 See the
58 Although not the preferred method, it is also possible to use 58 "<ulink url='&YOCTO_DOCS_QS_URL;#qs-building-images'>Building Images</ulink>"
59 <filename>bitbake meta-toolchain</filename> to build the toolchain 59 section in the Yocto Project Quick Start for steps that show you
60 installer. 60 how to set up the Yocto Project environment.
61 If you do use this method, you must separately install and extract 61 In particular, you need to be sure the
62 the target sysroot. 62 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
63 For information on how to install the sysroot, see the 63 variable matches the architecture for which you are building and that
64 "<link linkend='sdk-extracting-the-root-filesystem'>Extracting the Root Filesystem</link>" 64 the
65 section. 65 <ulink url='&YOCTO_DOCS_REF_URL;#var-SDKMACHINE'><filename>SDKMACHINE</filename></ulink>
66 </note> 66 variable is correctly set if you are building a toolchain designed to
67 run on an architecture that differs from your current development host
68 machine (i.e. the build machine).
67 </para> 69 </para>
68 70
69 <para> 71 <para>
@@ -81,54 +83,6 @@
81 </para> 83 </para>
82 84
83 <para> 85 <para>
84 Another powerful feature is that the toolchain is completely
85 self-contained.
86 The binaries are linked against their own copy of
87 <filename>libc</filename>, which results in no dependencies
88 on the target system.
89 To achieve this, the pointer to the dynamic loader is
90 configured at install time since that path cannot be dynamically
91 altered.
92 This is the reason for a wrapper around the
93 <filename>populate_sdk</filename> and
94 <filename>populate_sdk_ext</filename> archives.
95 </para>
96
97 <para>
98 Another feature is that only one set of cross-canadian toolchain
99 binaries are produced per architecture.
100 This feature takes advantage of the fact that the target hardware can
101 be passed to <filename>gcc</filename> as a set of compiler options.
102 Those options are set up by the environment script and contained in
103 variables such as
104 <ulink url='&YOCTO_DOCS_REF_URL;#var-CC'><filename>CC</filename></ulink>
105 and
106 <ulink url='&YOCTO_DOCS_REF_URL;#var-LD'><filename>LD</filename></ulink>.
107 This reduces the space needed for the tools.
108 Understand, however, that a sysroot is still needed for every target
109 since those binaries are target-specific.
110 </para>
111
112 <para>
113 Remember, before using any BitBake command, you
114 must source the build environment setup script
115 (i.e.
116 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
117 or
118 <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>)
119 located in the Source Directory and you must make sure your
120 <filename>conf/local.conf</filename> variables are correct.
121 In particular, you need to be sure the
122 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
123 variable matches the architecture for which you are building and that
124 the
125 <ulink url='&YOCTO_DOCS_REF_URL;#var-SDKMACHINE'><filename>SDKMACHINE</filename></ulink>
126 variable is correctly set if you are building a toolchain designed to
127 run on an architecture that differs from your current development host
128 machine (i.e. the build machine).
129 </para>
130
131 <para>
132 When the <filename>bitbake</filename> command completes, the toolchain 86 When the <filename>bitbake</filename> command completes, the toolchain
133 installer will be in 87 installer will be in
134 <filename>tmp/deploy/sdk</filename> in the Build Directory. 88 <filename>tmp/deploy/sdk</filename> in the Build Directory.
@@ -154,12 +108,8 @@
154 <title>Extracting the Root Filesystem</title> 108 <title>Extracting the Root Filesystem</title>
155 109
156 <para> 110 <para>
157 After installing the toolchain or building it using BitBake, 111 After installing the toolchain, for some use cases you
158 you need a root filesystem, which you need to separately extract. 112 might need to separately extract a root filesystem:
159 </para>
160
161 <para>
162 Here are some cases where you need to extract the root filesystem:
163 <itemizedlist> 113 <itemizedlist>
164 <listitem><para>You want to boot the image using NFS. 114 <listitem><para>You want to boot the image using NFS.
165 </para></listitem> 115 </para></listitem>
diff --git a/documentation/sdk-manual/sdk-extensible.xml b/documentation/sdk-manual/sdk-extensible.xml
index bc9ccd28d3..f9f04072d7 100644
--- a/documentation/sdk-manual/sdk-extensible.xml
+++ b/documentation/sdk-manual/sdk-extensible.xml
@@ -540,39 +540,103 @@
540 </para> 540 </para>
541</section> 541</section>
542 542
543<section id='sdk-using-the-extensible-sdk-to-task-2'> 543<section id='sdk-installing-additional-items-into-the-extensible-sdk'>
544 <title>Using the Extensible SDK to <replaceable>item-2</replaceable></title> 544 <title>Installing Additional Items Into the Extensible SDK</title>
545 545
546 <para role='writernotes'> 546 <para>
547 Describe the specific task you are going to accomplish with the 547 The extensible SDK typically only comes with a small number of tools
548 extensible SDK. 548 and libraries out of the box.
549 Provide a diagram showing the rough flow of the task. 549 If you have a minimal SDK, then it starts mostly empty and is
550 Provide specific steps using a real example that works through the 550 populated on-demand.
551 task. 551 However, sometimes you will need to explicitly install extra items
552 into the SDK.
553 If you need these extra items, you can first search for the items
554 using the <filename>devtool search</filename> command.
555 For example, suppose you need to link to libGL but you are not sure
556 which recipe provides it.
557 You can use the following command to find out:
558 <literallayout class='monospaced'>
559 $ devtool search libGL
560 mesa A free implementation of the OpenGL API
561 </literallayout>
562 Once you know the recipe (i.e. <filename>mesa</filename> in this
563 example), you can install it:
564 <literallayout class='monospaced'>
565 $ devtool sdk-install mesa
566 </literallayout>
567 By default, the <filename>devtool sdk-install</filename> assumes the
568 item is available in pre-built form from your SDK provider.
569 If the item is not available and it is acceptable to build the item
570 from source, you can add the "-s" option as follows:
571 <literallayout class='monospaced'>
572 $ devtool sdk-install -s mesa
573 </literallayout>
574 It is important to remember that building the item from source takes
575 significantly longer than installing the pre-built artifact.
576 Also, if no recipe exists for the item you want to add to the SDK, you
577 must add it using the <filename>devtool add</filename> command.
552 </para> 578 </para>
553</section> 579</section>
554 580
555<section id='sdk-using-the-extensible-sdk-to-task-3'> 581<section id='sdk-updating-the-extensible-sdk'>
556 <title>Using the Extensible SDK to <replaceable>item-3</replaceable></title> 582 <title>Updating the Extensible SDK</title>
557 583
558 <para role='writernotes'> 584 <para>
559 Describe the specific task you are going to accomplish with the 585 If you are working with an extensible SDK that gets occasionally
560 extensible SDK. 586 updated (e.g. typically when that SDK has been provided to you by
561 Provide a diagram showing the rough flow of the task. 587 another party), then you will need to manually pull down those
562 Provide specific steps using a real example that works through the 588 updates to your installed SDK.
563 task. 589 </para>
590
591 <para>
592 To update your installed SDK, run the following:
593 <literallayout class='monospaced'>
594 $ devtool sdk-update
595 </literallayout>
596 The previous command assumes your SDK provider has set the default
597 update URL for you.
598 If that URL has not been set, you need to specify it yourself as
599 follows:
600 <literallayout class='monospaced'>
601 $ devtool sdk-update <replaceable>path_to_update_directory</replaceable>
602 </literallayout>
603 <note>
604 The URL needs to point specifically to a published SDK and not an
605 SDK installer that you would download and install.
606 </note>
564 </para> 607 </para>
565</section> 608</section>
566 609
567<section id='sdk-using-the-extensible-sdk-to-task-x'> 610<section id='sdk-creating-a-derivative-sdk-with-additional-components'>
568 <title>Using the Extensible SDK to <replaceable>item-x</replaceable></title> 611 <title>Creating a Derivative SDK With Additional Components</title>
569 612
570 <para role='writernotes'> 613 <para>
571 Describe the specific task you are going to accomplish with the 614 You might need to produce an SDK that contains your own custom
572 extensible SDK. 615 libraries for sending to a third party (e.g., if you are a vendor with
573 Provide a diagram showing the rough flow of the task. 616 customers needing to build their own software for the target platform).
574 Provide specific steps using a real example that works through the 617 If that is the case, then you can produce a derivative SDK based on
575 task. 618 the currently installed SDK fairly easily.
619 Use these steps:
620 <orderedlist>
621 <listitem><para>If necessary, install an extensible SDK that
622 you want to use as a base for your derivative SDK.
623 </para></listitem>
624 <listitem><para>Source the environment script for the SDK.
625 </para></listitem>
626 <listitem><para>Add the extra libraries or other components
627 you want by using the <filename>devtool add</filename>
628 command.
629 </para></listitem>
630 <listitem><para>Run the <filename>devtool build-sdk</filename>
631 command.
632 </para></listitem>
633 </orderedlist>
634 The above procedure takes the recipes added to the workspace and
635 constructs a new SDK installer containing those recipes and the
636 resulting binary artifacts.
637 The recipes go into their own separate layer in the constructed
638 derivative SDK, leaving the workspace clean and ready for you
639 to add your own recipes.
576 </para> 640 </para>
577</section> 641</section>
578 642
diff --git a/documentation/sdk-manual/sdk-intro.xml b/documentation/sdk-manual/sdk-intro.xml
index 36d946459d..d71aafeba1 100644
--- a/documentation/sdk-manual/sdk-intro.xml
+++ b/documentation/sdk-manual/sdk-intro.xml
@@ -46,6 +46,34 @@
46 </para> 46 </para>
47 47
48 <para> 48 <para>
49 SDKs are completely self-contained.
50 The binaries are linked against their own copy of
51 <filename>libc</filename>, which results in no dependencies
52 on the target system.
53 To achieve this, the pointer to the dynamic loader is
54 configured at install time since that path cannot be dynamically
55 altered.
56 This is the reason for a wrapper around the
57 <filename>populate_sdk</filename> and
58 <filename>populate_sdk_ext</filename> archives.
59 </para>
60
61 <para>
62 Another feature for the SDKs is that only one set of cross-canadian
63 toolchain binaries are produced per architecture.
64 This feature takes advantage of the fact that the target hardware can
65 be passed to <filename>gcc</filename> as a set of compiler options.
66 Those options are set up by the environment script and contained in
67 variables such as
68 <ulink url='&YOCTO_DOCS_REF_URL;#var-CC'><filename>CC</filename></ulink>
69 and
70 <ulink url='&YOCTO_DOCS_REF_URL;#var-LD'><filename>LD</filename></ulink>.
71 This reduces the space needed for the tools.
72 Understand, however, that a sysroot is still needed for every target
73 since those binaries are target-specific.
74 </para>
75
76 <para>
49 Going beyond the actual SDK, the SDK development environment consists 77 Going beyond the actual SDK, the SDK development environment consists
50 of the following: 78 of the following:
51 <itemizedlist> 79 <itemizedlist>
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-11-14 00:11:44 +0000