summaryrefslogtreecommitdiffstats
path: root/documentation/sdk-manual
diff options
context:
space:
mode:
authorNicolas Dechesne <nicolas.dechesne@linaro.org>2020-10-05 16:30:32 +0200
committerRichard Purdie <richard.purdie@linuxfoundation.org>2021-01-04 10:55:01 +0000
commitb175f353436eb7411ba3d5010fd8588652393982 (patch)
treee7a4d5215f53a9042698ec7be24a37717fc1d78f /documentation/sdk-manual
parenta934ad95cfafba4219732fa6c5c40a2d16220f23 (diff)
downloadpoky-b175f353436eb7411ba3d5010fd8588652393982.tar.gz
sphinx: remove DocBook files
The Yocto Project documentation was migrated to Sphinx. Let's remove the deprecated DocBook files. (From yocto-docs rev: abdb6b6bdfef3dc8e8cc13779e44a8d6df903469) Signed-off-by: Nicolas Dechesne <nicolas.dechesne@linaro.org> (cherry picked from commit 28fb0e63b2fbfd6426b00498bf2682bb53fdd862) Signed-off-by: Nicolas Dechesne <nicolas.dechesne@linaro.org> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/sdk-manual')
-rw-r--r--documentation/sdk-manual/sdk-appendix-customizing-standard.xml59
-rw-r--r--documentation/sdk-manual/sdk-appendix-customizing.xml515
-rw-r--r--documentation/sdk-manual/sdk-appendix-obtain.xml444
-rw-r--r--documentation/sdk-manual/sdk-extensible.xml1847
-rw-r--r--documentation/sdk-manual/sdk-intro.xml353
-rw-r--r--documentation/sdk-manual/sdk-manual-customization.xsl28
-rwxr-xr-xdocumentation/sdk-manual/sdk-manual.xml159
-rw-r--r--documentation/sdk-manual/sdk-style.css991
-rw-r--r--documentation/sdk-manual/sdk-using.xml201
-rw-r--r--documentation/sdk-manual/sdk-working-projects.xml511
10 files changed, 0 insertions, 5108 deletions
diff --git a/documentation/sdk-manual/sdk-appendix-customizing-standard.xml b/documentation/sdk-manual/sdk-appendix-customizing-standard.xml
deleted file mode 100644
index 3a6b4c8d82..0000000000
--- a/documentation/sdk-manual/sdk-appendix-customizing-standard.xml
+++ /dev/null
@@ -1,59 +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-standard'>
7
8<title>Customizing the Standard SDK</title>
9
10<para>
11 This appendix presents customizations you can apply to the standard SDK.
12</para>
13
14<section id='sdk-adding-individual-packages'>
15 <title>Adding Individual Packages to the Standard SDK</title>
16
17 <para>
18 When you build a standard SDK using the
19 <filename>bitbake -c populate_sdk</filename>, a default set of
20 packages is included in the resulting SDK.
21 The
22 <ulink url='&YOCTO_DOCS_REF_URL;#var-TOOLCHAIN_HOST_TASK'><filename>TOOLCHAIN_HOST_TASK</filename></ulink>
23 and
24 <ulink url='&YOCTO_DOCS_REF_URL;#var-TOOLCHAIN_TARGET_TASK'><filename>TOOLCHAIN_TARGET_TASK</filename></ulink>
25 variables control the set of packages adding to the SDK.
26 </para>
27
28 <para>
29 If you want to add individual packages to the toolchain that runs on
30 the host, simply add those packages to the
31 <filename>TOOLCHAIN_HOST_TASK</filename> variable.
32 Similarly, if you want to add packages to the default set that is
33 part of the toolchain that runs on the target, add the packages to the
34 <filename>TOOLCHAIN_TARGET_TASK</filename> variable.
35 </para>
36</section>
37
38<section id='adding-api-documentation-to-the-standard-sdk'>
39 <title>Adding API Documentation to the Standard SDK</title>
40
41 <para>
42 You can include API documentation as well as any other
43 documentation provided by recipes with the standard SDK by
44 adding "api-documentation" to the
45 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></ulink>
46 variable:
47 <literallayout class='monospaced'>
48 DISTRO_FEATURES_append = " api-documentation"
49 </literallayout>
50 Setting this variable as shown here causes the OpenEmbedded build
51 system to build the documentation and then include it in the standard
52 SDK.
53 </para>
54</section>
55
56</appendix>
57<!--
58vim: expandtab tw=80 ts=4
59-->
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-->
diff --git a/documentation/sdk-manual/sdk-appendix-obtain.xml b/documentation/sdk-manual/sdk-appendix-obtain.xml
deleted file mode 100644
index de7f75e2bb..0000000000
--- a/documentation/sdk-manual/sdk-appendix-obtain.xml
+++ /dev/null
@@ -1,444 +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-obtain'>
7
8<title>Obtaining the SDK</title>
9
10<section id='sdk-locating-pre-built-sdk-installers'>
11 <title>Locating Pre-Built SDK Installers</title>
12
13 <para>
14 You can use existing, pre-built toolchains by locating and running
15 an SDK installer script that ships with the Yocto Project.
16 Using this method, you select and download an architecture-specific
17 SDK installer and then run the script to hand-install the
18 toolchain.
19 </para>
20
21 <para>
22 Follow these steps to locate and hand-install the toolchain:
23 <orderedlist>
24 <listitem><para>
25 <emphasis>Go to the Installers Directory:</emphasis>
26 Go to <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'></ulink>
27 </para></listitem>
28 <listitem><para>
29 <emphasis>Open the Folder for Your Build Host:</emphasis>
30 Open the folder that matches your
31 <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>build host</ulink>
32 (i.e. <filename>i686</filename> for 32-bit machines or
33 <filename>x86_64</filename> for 64-bit machines).
34 </para></listitem>
35 <listitem><para>
36 <emphasis>Locate and Download the SDK Installer:</emphasis>
37 You need to find and download the installer appropriate for
38 your build host, target hardware, and image type.
39 </para>
40
41 <para>The installer files (<filename>*.sh</filename>) follow
42 this naming convention:
43 <literallayout class='monospaced'>
44 poky-glibc-<replaceable>host_system</replaceable>-core-image-<replaceable>type</replaceable>-<replaceable>arch</replaceable>-toolchain[-ext]-<replaceable>release</replaceable>.sh
45
46 Where:
47 <replaceable>host_system</replaceable> is a string representing your development system:
48 "i686" or "x86_64"
49
50 <replaceable>type</replaceable> is a string representing the image:
51 "sato" or "minimal"
52
53 <replaceable>arch</replaceable> is a string representing the target architecture:
54 "aarch64", "armv5e", "core2-64", "coretexa8hf-neon", "i586", "mips32r2",
55 "mips64", or "ppc7400"
56
57 <replaceable>release</replaceable> is the version of Yocto Project.
58
59 NOTE:
60 The standard SDK installer does not have the "-ext" string as
61 part of the filename.
62
63 </literallayout>
64 The toolchains provided by the Yocto Project are based off of
65 the <filename>core-image-sato</filename> and
66 <filename>core-image-minimal</filename> images and contain
67 libraries appropriate for developing against those images.
68 </para>
69
70 <para>For example, if your build host is a 64-bit x86 system
71 and you need an extended SDK for a 64-bit core2 target, go
72 into the <filename>x86_64</filename> folder and download the
73 following installer:
74 <literallayout class='monospaced'>
75 poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-&DISTRO;.sh
76 </literallayout>
77 </para></listitem>
78 <listitem><para>
79 <emphasis>Run the Installer:</emphasis>
80 Be sure you have execution privileges and run the installer.
81 Following is an example from the <filename>Downloads</filename>
82 directory:
83 <literallayout class='monospaced'>
84 $ ~/Downloads/poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-&DISTRO;.sh
85 </literallayout>
86 During execution of the script, you choose the root location
87 for the toolchain.
88 See the
89 "<link linkend='sdk-installed-standard-sdk-directory-structure'>Installed Standard SDK Directory Structure</link>"
90 section and the
91 "<link linkend='sdk-installed-extensible-sdk-directory-structure'>Installed Extensible SDK Directory Structure</link>"
92 section for more information.
93 </para></listitem>
94 </orderedlist>
95 </para>
96</section>
97
98<section id='sdk-building-an-sdk-installer'>
99 <title>Building an SDK Installer</title>
100
101 <para>
102 As an alternative to locating and downloading an SDK installer,
103 you can build the SDK installer.
104 Follow these steps:
105 <orderedlist>
106 <listitem><para>
107 <emphasis>Set Up the Build Environment:</emphasis>
108 Be sure you are set up to use BitBake in a shell.
109 See the
110 "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-preparing-the-build-host'>Preparing the Build Host</ulink>"
111 section in the Yocto Project Development Tasks Manual for
112 information on how to get a build host ready that is either a
113 native Linux machine or a machine that uses CROPS.
114 </para></listitem>
115 <listitem><para>
116 <emphasis>Clone the <filename>poky</filename> Repository:</emphasis>
117 You need to have a local copy of the Yocto Project
118 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
119 (i.e. a local <filename>poky</filename> repository).
120 See the
121 "<ulink url='&YOCTO_DOCS_DEV_URL;#cloning-the-poky-repository'>Cloning the <filename>poky</filename> Repository</ulink>"
122 and possibly the
123 "<ulink url='&YOCTO_DOCS_DEV_URL;#checking-out-by-branch-in-poky'>Checking Out by Branch in Poky</ulink>"
124 and
125 "<ulink url='&YOCTO_DOCS_DEV_URL;#checkout-out-by-tag-in-poky'>Checking Out by Tag in Poky</ulink>"
126 sections all in the Yocto Project Development Tasks Manual for
127 information on how to clone the <filename>poky</filename>
128 repository and check out the appropriate branch for your work.
129 </para></listitem>
130 <listitem><para>
131 <emphasis>Initialize the Build Environment:</emphasis>
132 While in the root directory of the Source Directory (i.e.
133 <filename>poky</filename>), run the
134 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
135 environment setup script to define the OpenEmbedded
136 build environment on your build host.
137 <literallayout class='monospaced'>
138 $ source &OE_INIT_FILE;
139 </literallayout>
140 Among other things, the script creates the
141 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>,
142 which is <filename>build</filename> in this case
143 and is located in the Source Directory.
144 After the script runs, your current working directory
145 is set to the <filename>build</filename> directory.
146 </para></listitem>
147 <listitem><para>
148 <emphasis>Make Sure You Are Building an Installer for the Correct Machine:</emphasis>
149 Check to be sure that your
150 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
151 variable in the <filename>local.conf</filename> file in your
152 Build Directory matches the architecture for which you are
153 building.
154 </para></listitem>
155 <listitem><para>
156 <emphasis>Make Sure Your SDK Machine is Correctly Set:</emphasis>
157 If you are building a toolchain designed to run on an
158 architecture that differs from your current development host
159 machine (i.e. the build host), be sure that the
160 <ulink url='&YOCTO_DOCS_REF_URL;#var-SDKMACHINE'><filename>SDKMACHINE</filename></ulink>
161 variable in the <filename>local.conf</filename> file in your
162 Build Directory is correctly set.
163 <note>
164 If you are building an SDK installer for the Extensible
165 SDK, the <filename>SDKMACHINE</filename> value must be
166 set for the architecture of the machine you are using to
167 build the installer.
168 If <filename>SDKMACHINE</filename> is not set appropriately,
169 the build fails and provides an error message similar to
170 the following:
171 <literallayout class='monospaced'>
172 The extensible SDK can currently only be built for the same architecture as the machine being built on - SDK_ARCH is
173 set to i686 (likely via setting SDKMACHINE) which is different from the architecture of the build machine (x86_64).
174 Unable to continue.
175 </literallayout>
176 </note>
177 </para></listitem>
178 <listitem><para>
179 <emphasis>Build the SDK Installer:</emphasis>
180 To build the SDK installer for a standard SDK and populate
181 the SDK image, use the following command form.
182 Be sure to replace <replaceable>image</replaceable> with
183 an image (e.g. "core-image-sato"):
184 <literallayout class='monospaced'>
185 $ bitbake <replaceable>image</replaceable> -c populate_sdk
186 </literallayout>
187 You can do the same for the extensible SDK using this command
188 form:
189 <literallayout class='monospaced'>
190 $ bitbake <replaceable>image</replaceable> -c populate_sdk_ext
191 </literallayout>
192 These commands produce an SDK installer that contains the
193 sysroot that matches your target root filesystem.</para>
194
195 <para>When the <filename>bitbake</filename> command completes,
196 the SDK installer will be in
197 <filename>tmp/deploy/sdk</filename> in the Build Directory.
198 <note><title>Notes</title>
199 <itemizedlist>
200 <listitem><para>
201 By default, the previous BitBake command does not
202 build static binaries.
203 If you want to use the toolchain to build these
204 types of libraries, you need to be sure your SDK
205 has the appropriate static development libraries.
206 Use the
207 <ulink url='&YOCTO_DOCS_REF_URL;#var-TOOLCHAIN_TARGET_TASK'><filename>TOOLCHAIN_TARGET_TASK</filename></ulink>
208 variable inside your <filename>local.conf</filename>
209 file before building the SDK installer.
210 Doing so ensures that the eventual SDK installation
211 process installs the appropriate library packages
212 as part of the SDK.
213 Following is an example using
214 <filename>libc</filename> static development
215 libraries:
216 <literallayout class='monospaced'>
217 TOOLCHAIN_TARGET_TASK_append = " libc-staticdev"
218 </literallayout>
219 </para></listitem>
220 </itemizedlist>
221 </note>
222 </para></listitem>
223 <listitem><para>
224 <emphasis>Run the Installer:</emphasis>
225 You can now run the SDK installer from
226 <filename>tmp/deploy/sdk</filename> in the Build Directory.
227 Following is an example:
228 <literallayout class='monospaced'>
229 $ cd ~/poky/build/tmp/deploy/sdk
230 $ ./poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-&DISTRO;.sh
231 </literallayout>
232 During execution of the script, you choose the root location
233 for the toolchain.
234 See the
235 "<link linkend='sdk-installed-standard-sdk-directory-structure'>Installed Standard SDK Directory Structure</link>"
236 section and the
237 "<link linkend='sdk-installed-extensible-sdk-directory-structure'>Installed Extensible SDK Directory Structure</link>"
238 section for more information.
239 </para></listitem>
240 </orderedlist>
241 </para>
242</section>
243
244<section id='sdk-extracting-the-root-filesystem'>
245 <title>Extracting the Root Filesystem</title>
246
247 <para>
248 After installing the toolchain, for some use cases you
249 might need to separately extract a root filesystem:
250 <itemizedlist>
251 <listitem><para>
252 You want to boot the image using NFS.
253 </para></listitem>
254 <listitem><para>
255 You want to use the root filesystem as the
256 target sysroot.
257 </para></listitem>
258 <listitem><para>
259 You want to develop your target application
260 using the root filesystem as the target sysroot.
261 </para></listitem>
262 </itemizedlist>
263 </para>
264
265 <para>
266 Follow these steps to extract the root filesystem:
267 <orderedlist>
268 <listitem><para>
269 <emphasis>Locate and Download the Tarball for the Pre-Built
270 Root Filesystem Image File:</emphasis>
271 You need to find and download the root filesystem image
272 file that is appropriate for your target system.
273 These files are kept in machine-specific folders in the
274 <ulink url='&YOCTO_DL_URL;/releases/yocto/yocto-&DISTRO;/machines/'>Index of Releases</ulink>
275 in the "machines" directory.</para>
276
277 <para>The machine-specific folders of the "machines" directory
278 contain tarballs (<filename>*.tar.bz2</filename>) for supported
279 machines.
280 These directories also contain flattened root filesystem
281 image files (<filename>*.ext4</filename>), which you can use
282 with QEMU directly.</para>
283
284 <para>The pre-built root filesystem image files
285 follow these naming conventions:
286 <literallayout class='monospaced'>
287<!--
288 core-image-<replaceable>profile</replaceable>-<replaceable>arch</replaceable>-<replaceable>date_time</replaceable>.rootfs.tar.bz2
289-->
290 core-image-<replaceable>profile</replaceable>-<replaceable>arch</replaceable>.tar.bz2
291
292 Where:
293 <replaceable>profile</replaceable> is the filesystem image's profile:
294 lsb, lsb-dev, lsb-sdk, minimal, minimal-dev, minimal-initramfs,
295 sato, sato-dev, sato-sdk, sato-sdk-ptest. For information on
296 these types of image profiles, see the "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>" chapter in
297 the Yocto Project Reference Manual.
298
299 <replaceable>arch</replaceable> is a string representing the target architecture:
300 beaglebone-yocto, beaglebone-yocto-lsb, edgerouter, edgerouter-lsb,
301 genericx86, genericx86-64, genericx86-64-lsb, genericx86-lsb and qemu*.
302
303<!-->
304 <replaceable>date_time</replaceable> is a date and time stamp.
305-->
306
307 </literallayout>
308 The root filesystems provided by the Yocto Project are based
309 off of the <filename>core-image-sato</filename> and
310 <filename>core-image-minimal</filename> images.
311 </para>
312
313 <para>For example, if you plan on using a BeagleBone device
314 as your target hardware and your image is a
315 <filename>core-image-sato-sdk</filename>
316 image, you can download the following file:
317 <literallayout class='monospaced'>
318 core-image-sato-sdk-beaglebone-yocto.tar.bz2
319 </literallayout>
320 </para></listitem>
321 <listitem><para>
322 <emphasis>Initialize the Cross-Development Environment:</emphasis>
323 You must <filename>source</filename> the cross-development
324 environment setup script to establish necessary environment
325 variables.</para>
326
327 <para>This script is located in the top-level directory in
328 which you installed the toolchain (e.g.
329 <filename>poky_sdk</filename>).</para>
330
331 <para>Following is an example based on the toolchain installed
332 in the
333 "<link linkend='sdk-locating-pre-built-sdk-installers'>Locating Pre-Built SDK Installers</link>"
334 section:
335 <literallayout class='monospaced'>
336 $ source ~/poky_sdk/environment-setup-core2-64-poky-linux
337 </literallayout>
338 </para></listitem>
339 <listitem><para>
340 <emphasis>Extract the Root Filesystem:</emphasis>
341 Use the <filename>runqemu-extract-sdk</filename> command
342 and provide the root filesystem image.</para>
343
344 <para>Following is an example command that extracts the root
345 filesystem from a previously built root filesystem image that
346 was downloaded from the
347 <ulink url='&YOCTO_DOCS_OM_URL;#index-downloads'>Index of Releases</ulink>.
348 This command extracts the root filesystem into the
349 <filename>core2-64-sato</filename> directory:
350 <literallayout class='monospaced'>
351 $ runqemu-extract-sdk ~/Downloads/core-image-sato-sdk-beaglebone-yocto.tar.bz2 ~/beaglebone-sato
352 </literallayout>
353 You could now point to the target sysroot at
354 <filename>beablebone-sato</filename>.
355 </para></listitem>
356 </orderedlist>
357 </para>
358</section>
359
360<section id='sdk-installed-standard-sdk-directory-structure'>
361 <title>Installed Standard SDK Directory Structure</title>
362
363 <para>
364 The following figure shows the resulting directory structure after
365 you install the Standard SDK by running the <filename>*.sh</filename>
366 SDK installation script:
367 </para>
368
369 <para>
370 <imagedata fileref="figures/sdk-installed-standard-sdk-directory.png" scale="80" align="center" />
371 </para>
372
373 <para>
374 The installed SDK consists of an environment setup script for the SDK,
375 a configuration file for the target, a version file for the target,
376 and the root filesystem (<filename>sysroots</filename>) needed to
377 develop objects for the target system.
378 </para>
379
380 <para>
381 Within the figure, italicized text is used to indicate replaceable
382 portions of the file or directory name.
383 For example,
384 <replaceable>install_dir</replaceable>/<replaceable>version</replaceable>
385 is the directory where the SDK is installed.
386 By default, this directory is <filename>/opt/poky/</filename>.
387 And, <replaceable>version</replaceable> represents the specific
388 snapshot of the SDK (e.g. <filename>&DISTRO;</filename>).
389 Furthermore, <replaceable>target</replaceable> represents the target
390 architecture (e.g. <filename>i586</filename>) and
391 <replaceable>host</replaceable> represents the development system's
392 architecture (e.g. <filename>x86_64</filename>).
393 Thus, the complete names of the two directories within the
394 <filename>sysroots</filename> could be
395 <filename>i586-poky-linux</filename> and
396 <filename>x86_64-pokysdk-linux</filename> for the target and host,
397 respectively.
398 </para>
399</section>
400
401<section id='sdk-installed-extensible-sdk-directory-structure'>
402 <title>Installed Extensible SDK Directory Structure</title>
403
404 <para>
405 The following figure shows the resulting directory structure after
406 you install the Extensible SDK by running the <filename>*.sh</filename>
407 SDK installation script:
408 </para>
409
410 <para>
411 <imagedata fileref="figures/sdk-installed-extensible-sdk-directory.png" scale="80" align="center" />
412 </para>
413
414 <para>
415 The installed directory structure for the extensible SDK is quite
416 different than the installed structure for the standard SDK.
417 The extensible SDK does not separate host and target parts in the
418 same manner as does the standard SDK.
419 The extensible SDK uses an embedded copy of the OpenEmbedded
420 build system, which has its own sysroots.
421 </para>
422
423 <para>
424 Of note in the directory structure are an environment setup script
425 for the SDK, a configuration file for the target, a version file for
426 the target, and log files for the OpenEmbedded build system
427 preparation script run by the installer and BitBake.
428 </para>
429
430 <para>
431 Within the figure, italicized text is used to indicate replaceable
432 portions of the file or directory name.
433 For example,
434 <replaceable>install_dir</replaceable> is the directory where the SDK
435 is installed, which is <filename>poky_sdk</filename> by default, and
436 <replaceable>target</replaceable> represents the target
437 architecture (e.g. <filename>i586</filename>).
438 </para>
439</section>
440
441</appendix>
442<!--
443vim: expandtab tw=80 ts=4
444-->
diff --git a/documentation/sdk-manual/sdk-extensible.xml b/documentation/sdk-manual/sdk-extensible.xml
deleted file mode 100644
index a73a07a7b9..0000000000
--- a/documentation/sdk-manual/sdk-extensible.xml
+++ /dev/null
@@ -1,1847 +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<chapter id='sdk-extensible'>
7
8 <title>Using the Extensible SDK</title>
9
10 <para>
11 This chapter describes the extensible SDK and how to install it.
12 Information covers the pieces of the SDK, how to install it, and
13 presents a look at using the <filename>devtool</filename>
14 functionality.
15 The extensible SDK makes it easy to add new applications and libraries
16 to an image, modify the source for an existing component, test
17 changes on the target hardware, and ease integration into the rest of
18 the
19 <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>OpenEmbedded build system</ulink>.
20 <note>
21 For a side-by-side comparison of main features supported for an
22 extensible SDK as compared to a standard SDK, see the
23 "<link linkend='sdk-manual-intro'>Introduction</link>"
24 section.
25 </note>
26 </para>
27
28 <para>
29 In addition to the functionality available through
30 <filename>devtool</filename>, you can alternatively make use of the
31 toolchain directly, for example from Makefile and Autotools.
32 See the
33 "<link linkend='sdk-working-projects'>Using the SDK Toolchain Directly</link>"
34 chapter for more information.
35 </para>
36
37 <section id='sdk-extensible-sdk-intro'>
38 <title>Why use the Extensible SDK and What is in It?</title>
39
40 <para>
41 The extensible SDK provides a cross-development toolchain and
42 libraries tailored to the contents of a specific image.
43 You would use the Extensible SDK if you want a toolchain experience
44 supplemented with the powerful set of <filename>devtool</filename>
45 commands tailored for the Yocto Project environment.
46 </para>
47
48 <para>
49 The installed extensible SDK consists of several files and
50 directories.
51 Basically, it contains an SDK environment setup script, some
52 configuration files, an internal build system, and the
53 <filename>devtool</filename> functionality.
54 </para>
55 </section>
56
57 <section id='sdk-installing-the-extensible-sdk'>
58 <title>Installing the Extensible SDK</title>
59
60 <para>
61 The first thing you need to do is install the SDK on your
62 <ulink url='&YOCTO_DOCS_REF_URL;#hardware-build-system-term'>Build Host</ulink>
63 by running the <filename>*.sh</filename> installation script.
64 </para>
65
66 <para>
67 You can download a tarball installer, which includes the
68 pre-built toolchain, the <filename>runqemu</filename>
69 script, the internal build system, <filename>devtool</filename>,
70 and support files from the appropriate
71 <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'>toolchain</ulink>
72 directory within the Index of Releases.
73 Toolchains are available for several 32-bit and 64-bit
74 architectures with the <filename>x86_64</filename> directories,
75 respectively.
76 The toolchains the Yocto Project provides are based off the
77 <filename>core-image-sato</filename> and
78 <filename>core-image-minimal</filename> images and contain
79 libraries appropriate for developing against that image.
80 </para>
81
82 <para>
83 The names of the tarball installer scripts are such that a
84 string representing the host system appears first in the
85 filename and then is immediately followed by a string
86 representing the target architecture.
87 An extensible SDK has the string "-ext" as part of the name.
88 Following is the general form:
89 <literallayout class='monospaced'>
90 poky-glibc-<replaceable>host_system</replaceable>-<replaceable>image_type</replaceable>-<replaceable>arch</replaceable>-toolchain-ext-<replaceable>release_version</replaceable>.sh
91
92 Where:
93 <replaceable>host_system</replaceable> is a string representing your development system:
94
95 i686 or x86_64.
96
97 <replaceable>image_type</replaceable> is the image for which the SDK was built:
98
99 core-image-sato or core-image-minimal
100
101 <replaceable>arch</replaceable> is a string representing the tuned target architecture:
102
103 aarch64, armv5e, core2-64, i586, mips32r2, mips64, ppc7400, or cortexa8hf-neon
104
105 <replaceable>release_version</replaceable> is a string representing the release number of the Yocto Project:
106
107 &DISTRO;, &DISTRO;+snapshot
108 </literallayout>
109 For example, the following SDK installer is for a 64-bit
110 development host system and a i586-tuned target architecture
111 based off the SDK for <filename>core-image-sato</filename> and
112 using the current &DISTRO; snapshot:
113 <literallayout class='monospaced'>
114 poky-glibc-x86_64-core-image-sato-i586-toolchain-ext-&DISTRO;.sh
115 </literallayout>
116 <note>
117 As an alternative to downloading an SDK, you can build the
118 SDK installer.
119 For information on building the installer, see the
120 "<link linkend='sdk-building-an-sdk-installer'>Building an SDK Installer</link>"
121 section.
122 </note>
123 </para>
124
125 <para>
126 The SDK and toolchains are self-contained and by default are
127 installed into the <filename>poky_sdk</filename> folder in your
128 home directory.
129 You can choose to install the extensible SDK in any location when
130 you run the installer.
131 However, because files need to be written under that directory
132 during the normal course of operation, the location you choose
133 for installation must be writable for whichever
134 users need to use the SDK.
135 </para>
136
137 <para>
138 The following command shows how to run the installer given a
139 toolchain tarball for a 64-bit x86 development host system and
140 a 64-bit x86 target architecture.
141 The example assumes the SDK installer is located in
142 <filename>~/Downloads/</filename> and has execution rights.
143 <note>
144 If you do not have write permissions for the directory
145 into which you are installing the SDK, the installer
146 notifies you and exits.
147 For that case, set up the proper permissions in the directory
148 and run the installer again.
149 </note>
150 <literallayout class='monospaced'>
151 $ ./Downloads/poky-glibc-x86_64-core-image-minimal-core2-64-toolchain-ext-2.5.sh
152 Poky (Yocto Project Reference Distro) Extensible SDK installer version 2.5
153 ==========================================================================
154 Enter target directory for SDK (default: ~/poky_sdk):
155 You are about to install the SDK to "/home/scottrif/poky_sdk". Proceed [Y/n]? Y
156 Extracting SDK..............done
157 Setting it up...
158 Extracting buildtools...
159 Preparing build system...
160 Parsing recipes: 100% |##################################################################| Time: 0:00:52
161 Initialising tasks: 100% |###############################################################| Time: 0:00:00
162 Checking sstate mirror object availability: 100% |#######################################| Time: 0:00:00
163 Loading cache: 100% |####################################################################| Time: 0:00:00
164 Initialising tasks: 100% |###############################################################| Time: 0:00:00
165 done
166 SDK has been successfully set up and is ready to be used.
167 Each time you wish to use the SDK in a new shell session, you need to source the environment setup script e.g.
168 $ . /home/scottrif/poky_sdk/environment-setup-core2-64-poky-linux
169
170 </literallayout>
171 </para>
172 </section>
173
174 <section id='sdk-running-the-extensible-sdk-environment-setup-script'>
175 <title>Running the Extensible SDK Environment Setup Script</title>
176
177 <para>
178 Once you have the SDK installed, you must run the SDK environment
179 setup script before you can actually use the SDK.
180 This setup script resides in the directory you chose when you
181 installed the SDK, which is either the default
182 <filename>poky_sdk</filename> directory or the directory you
183 chose during installation.
184 </para>
185
186 <para>
187 Before running the script, be sure it is the one that matches the
188 architecture for which you are developing.
189 Environment setup scripts begin with the string
190 "<filename>environment-setup</filename>" and include as part of
191 their name the tuned target architecture.
192 As an example, the following commands set the working directory
193 to where the SDK was installed and then source the environment
194 setup script.
195 In this example, the setup script is for an IA-based
196 target machine using i586 tuning:
197 <literallayout class='monospaced'>
198 $ cd /home/scottrif/poky_sdk
199 $ source environment-setup-core2-64-poky-linux
200 SDK environment now set up; additionally you may now run devtool to perform development tasks.
201 Run devtool --help for further details.
202 </literallayout>
203 Running the setup script defines many environment variables needed
204 in order to use the SDK (e.g. <filename>PATH</filename>,
205 <ulink url='&YOCTO_DOCS_REF_URL;#var-CC'><filename>CC</filename></ulink>,
206 <ulink url='&YOCTO_DOCS_REF_URL;#var-LD'><filename>LD</filename></ulink>,
207 and so forth).
208 If you want to see all the environment variables the script
209 exports, examine the installation file itself.
210 </para>
211 </section>
212
213 <section id='using-devtool-in-your-sdk-workflow'>
214 <title>Using <filename>devtool</filename> in Your SDK Workflow</title>
215
216 <para>
217 The cornerstone of the extensible SDK is a command-line tool
218 called <filename>devtool</filename>.
219 This tool provides a number of features that help
220 you build, test and package software within the extensible SDK, and
221 optionally integrate it into an image built by the OpenEmbedded
222 build system.
223 <note><title>Tip</title>
224 The use of <filename>devtool</filename> is not limited to
225 the extensible SDK.
226 You can use <filename>devtool</filename> to help you easily
227 develop any project whose build output must be part of an
228 image built using the build system.
229 </note>
230 </para>
231
232 <para>
233 The <filename>devtool</filename> command line is organized
234 similarly to
235 <ulink url='&YOCTO_DOCS_OM_URL;#git'>Git</ulink> in that it
236 has a number of sub-commands for each function.
237 You can run <filename>devtool --help</filename> to see all the
238 commands.
239 <note>
240 See the
241 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-devtool-reference'><filename>devtool</filename>&nbsp;Quick Reference</ulink>"
242 in the Yocto Project Reference Manual for a
243 <filename>devtool</filename> quick reference.
244 </note>
245 </para>
246
247 <para>
248 Three <filename>devtool</filename> subcommands exist that provide
249 entry-points into development:
250 <itemizedlist>
251 <listitem><para>
252 <emphasis><filename>devtool add</filename></emphasis>:
253 Assists in adding new software to be built.
254 </para></listitem>
255 <listitem><para>
256 <emphasis><filename>devtool modify</filename></emphasis>:
257 Sets up an environment to enable you to modify the source of
258 an existing component.
259 </para></listitem>
260 <listitem><para>
261 <emphasis><filename>devtool upgrade</filename></emphasis>:
262 Updates an existing recipe so that you can build it for
263 an updated set of source files.
264 </para></listitem>
265 </itemizedlist>
266 As with the build system, "recipes" represent software packages
267 within <filename>devtool</filename>.
268 When you use <filename>devtool add</filename>, a recipe is
269 automatically created.
270 When you use <filename>devtool modify</filename>, the specified
271 existing recipe is used in order to determine where to get the
272 source code and how to patch it.
273 In both cases, an environment is set up so that when you build the
274 recipe a source tree that is under your control is used in order to
275 allow you to make changes to the source as desired.
276 By default, new recipes and the source go into a "workspace"
277 directory under the SDK.
278 </para>
279
280 <para>
281 The remainder of this section presents the
282 <filename>devtool add</filename>,
283 <filename>devtool modify</filename>, and
284 <filename>devtool upgrade</filename> workflows.
285 </para>
286
287 <section id='sdk-use-devtool-to-add-an-application'>
288 <title>Use <filename>devtool add</filename> to Add an Application</title>
289
290 <para>
291 The <filename>devtool add</filename> command generates
292 a new recipe based on existing source code.
293 This command takes advantage of the
294 <ulink url='&YOCTO_DOCS_REF_URL;#devtool-the-workspace-layer-structure'>workspace</ulink>
295 layer that many <filename>devtool</filename> commands
296 use.
297 The command is flexible enough to allow you to extract source
298 code into both the workspace or a separate local Git repository
299 and to use existing code that does not need to be extracted.
300 </para>
301
302 <para>
303 Depending on your particular scenario, the arguments and options
304 you use with <filename>devtool add</filename> form different
305 combinations.
306 The following diagram shows common development flows
307 you would use with the <filename>devtool add</filename>
308 command:
309 </para>
310
311 <para>
312 <imagedata fileref="figures/sdk-devtool-add-flow.png" align="center" />
313 </para>
314
315 <para>
316 <orderedlist>
317 <listitem><para><emphasis>Generating the New Recipe</emphasis>:
318 The top part of the flow shows three scenarios by which
319 you could use <filename>devtool add</filename> to
320 generate a recipe based on existing source code.</para>
321
322 <para>In a shared development environment, it is
323 typical for other developers to be responsible for
324 various areas of source code.
325 As a developer, you are probably interested in using
326 that source code as part of your development within
327 the Yocto Project.
328 All you need is access to the code, a recipe, and a
329 controlled area in which to do your work.</para>
330
331 <para>Within the diagram, three possible scenarios
332 feed into the <filename>devtool add</filename> workflow:
333 <itemizedlist>
334 <listitem><para>
335 <emphasis>Left</emphasis>:
336 The left scenario in the figure represents a
337 common situation where the source code does not
338 exist locally and needs to be extracted.
339 In this situation, the source code is extracted
340 to the default workspace - you do not
341 want the files in some specific location
342 outside of the workspace.
343 Thus, everything you need will be located in
344 the workspace:
345 <literallayout class='monospaced'>
346 $ devtool add <replaceable>recipe fetchuri</replaceable>
347 </literallayout>
348 With this command, <filename>devtool</filename>
349 extracts the upstream source files into a local
350 Git repository within the
351 <filename>sources</filename> folder.
352 The command then creates a recipe named
353 <replaceable>recipe</replaceable> and a
354 corresponding append file in the workspace.
355 If you do not provide
356 <replaceable>recipe</replaceable>, the command
357 makes an attempt to determine the recipe name.
358 </para></listitem>
359 <listitem><para>
360 <emphasis>Middle</emphasis>:
361 The middle scenario in the figure also
362 represents a situation where the source code
363 does not exist locally.
364 In this case, the code is again upstream
365 and needs to be extracted to some
366 local area - this time outside of the default
367 workspace.
368 <note>
369 If required, <filename>devtool</filename>
370 always creates
371 a Git repository locally during the
372 extraction.
373 </note>
374 Furthermore, the first positional argument
375 <replaceable>srctree</replaceable> in this
376 case identifies where the
377 <filename>devtool add</filename> command
378 will locate the extracted code outside of the
379 workspace.
380 You need to specify an empty directory:
381 <literallayout class='monospaced'>
382 $ devtool add <replaceable>recipe srctree fetchuri</replaceable>
383 </literallayout>
384 In summary, the source code is pulled from
385 <replaceable>fetchuri</replaceable> and
386 extracted into the location defined by
387 <replaceable>srctree</replaceable> as a local
388 Git repository.</para>
389
390 <para>Within workspace,
391 <filename>devtool</filename> creates a
392 recipe named <replaceable>recipe</replaceable>
393 along with an associated append file.
394 </para></listitem>
395 <listitem><para>
396 <emphasis>Right</emphasis>:
397 The right scenario in the figure represents a
398 situation where the
399 <replaceable>srctree</replaceable> has been
400 previously prepared outside of the
401 <filename>devtool</filename> workspace.</para>
402
403 <para>The following command provides a new
404 recipe name and identifies the existing source
405 tree location:
406 <literallayout class='monospaced'>
407 $ devtool add <replaceable>recipe srctree</replaceable>
408 </literallayout>
409 The command examines the source code and
410 creates a recipe named
411 <replaceable>recipe</replaceable> for the code
412 and places the recipe into the workspace.
413 </para>
414
415 <para>Because the extracted source code already
416 exists, <filename>devtool</filename> does not
417 try to relocate the source code into the
418 workspace - only the new recipe is placed
419 in the workspace.</para>
420
421 <para>Aside from a recipe folder, the command
422 also creates an associated append folder and
423 places an initial
424 <filename>*.bbappend</filename> file within.
425 </para></listitem>
426 </itemizedlist>
427 </para></listitem>
428 <listitem><para>
429 <emphasis>Edit the Recipe</emphasis>:
430 You can use <filename>devtool edit-recipe</filename>
431 to open up the editor as defined by the
432 <filename>$EDITOR</filename> environment variable
433 and modify the file:
434 <literallayout class='monospaced'>
435 $ devtool edit-recipe <replaceable>recipe</replaceable>
436 </literallayout>
437 From within the editor, you can make modifications to
438 the recipe that take affect when you build it later.
439 </para></listitem>
440 <listitem><para>
441 <emphasis>Build the Recipe or Rebuild the Image</emphasis>:
442 The next step you take depends on what you are going
443 to do with the new code.</para>
444
445 <para>If you need to eventually move the build output
446 to the target hardware, use the following
447 <filename>devtool</filename> command:
448 <literallayout class='monospaced'>
449 $ devtool build <replaceable>recipe</replaceable>
450 </literallayout></para>
451
452 <para>On the other hand, if you want an image to
453 contain the recipe's packages from the workspace
454 for immediate deployment onto a device (e.g. for
455 testing purposes), you can use
456 the <filename>devtool build-image</filename> command:
457 <literallayout class='monospaced'>
458 $ devtool build-image <replaceable>image</replaceable>
459 </literallayout>
460 </para></listitem>
461 <listitem><para>
462 <emphasis>Deploy the Build Output</emphasis>:
463 When you use the <filename>devtool build</filename>
464 command to build out your recipe, you probably want to
465 see if the resulting build output works as expected
466 on the target hardware.
467 <note>
468 This step assumes you have a previously built
469 image that is already either running in QEMU or
470 is running on actual hardware.
471 Also, it is assumed that for deployment of the
472 image to the target, SSH is installed in the image
473 and, if the image is running on real hardware,
474 you have network access to and from your
475 development machine.
476 </note>
477 You can deploy your build output to that target
478 hardware by using the
479 <filename>devtool deploy-target</filename> command:
480 <literallayout class='monospaced'>
481 $ devtool deploy-target <replaceable>recipe target</replaceable>
482 </literallayout>
483 The <replaceable>target</replaceable> is a live target
484 machine running as an SSH server.</para>
485
486 <para>You can, of course, also deploy the image you
487 build to actual hardware by using the
488 <filename>devtool build-image</filename> command.
489 However, <filename>devtool</filename> does not provide
490 a specific command that allows you to deploy the
491 image to actual hardware.
492 </para></listitem>
493 <listitem><para>
494 <emphasis>Finish Your Work With the Recipe</emphasis>:
495 The <filename>devtool finish</filename> command creates
496 any patches corresponding to commits in the local
497 Git repository, moves the new recipe to a more permanent
498 layer, and then resets the recipe so that the recipe is
499 built normally rather than from the workspace.
500 <literallayout class='monospaced'>
501 $ devtool finish <replaceable>recipe layer</replaceable>
502 </literallayout>
503 <note>
504 Any changes you want to turn into patches must be
505 committed to the Git repository in the source tree.
506 </note></para>
507
508 <para>As mentioned, the
509 <filename>devtool finish</filename> command moves the
510 final recipe to its permanent layer.
511 </para>
512
513 <para>As a final process of the
514 <filename>devtool finish</filename> command, the state
515 of the standard layers and the upstream source is
516 restored so that you can build the recipe from those
517 areas rather than the workspace.
518 <note>
519 You can use the <filename>devtool reset</filename>
520 command to put things back should you decide you
521 do not want to proceed with your work.
522 If you do use this command, realize that the source
523 tree is preserved.
524 </note>
525 </para></listitem>
526 </orderedlist>
527 </para>
528 </section>
529
530 <section id='sdk-devtool-use-devtool-modify-to-modify-the-source-of-an-existing-component'>
531 <title>Use <filename>devtool modify</filename> to Modify the Source of an Existing Component</title>
532
533 <para>
534 The <filename>devtool modify</filename> command prepares the
535 way to work on existing code that already has a local recipe in
536 place that is used to build the software.
537 The command is flexible enough to allow you to extract code
538 from an upstream source, specify the existing recipe, and
539 keep track of and gather any patch files from other developers
540 that are associated with the code.
541 </para>
542
543 <para>
544 Depending on your particular scenario, the arguments and options
545 you use with <filename>devtool modify</filename> form different
546 combinations.
547 The following diagram shows common development flows for the
548 <filename>devtool modify</filename> command:
549 </para>
550
551 <para>
552 <imagedata fileref="figures/sdk-devtool-modify-flow.png" align="center" />
553 </para>
554
555 <para>
556 <orderedlist>
557 <listitem><para>
558 <emphasis>Preparing to Modify the Code</emphasis>:
559 The top part of the flow shows three scenarios by which
560 you could use <filename>devtool modify</filename> to
561 prepare to work on source files.
562 Each scenario assumes the following:
563 <itemizedlist>
564 <listitem><para>
565 The recipe exists locally in a layer external
566 to the <filename>devtool</filename> workspace.
567 </para></listitem>
568 <listitem><para>
569 The source files exist either upstream in an
570 un-extracted state or locally in a previously
571 extracted state.
572 </para></listitem>
573 </itemizedlist>
574 The typical situation is where another developer has
575 created a layer for use with the Yocto Project and
576 their recipe already resides in that layer.
577 Furthermore, their source code is readily available
578 either upstream or locally.
579 <itemizedlist>
580 <listitem><para>
581 <emphasis>Left</emphasis>:
582 The left scenario in the figure represents a
583 common situation where the source code does
584 not exist locally and it needs to be extracted
585 from an upstream source.
586 In this situation, the source is extracted
587 into the default <filename>devtool</filename>
588 workspace location.
589 The recipe, in this scenario, is in its own
590 layer outside the workspace
591 (i.e.
592 <filename>meta-</filename><replaceable>layername</replaceable>).
593 </para>
594
595 <para>The following command identifies the
596 recipe and, by default, extracts the source
597 files:
598 <literallayout class='monospaced'>
599 $ devtool modify <replaceable>recipe</replaceable>
600 </literallayout>
601 Once <filename>devtool</filename>locates the
602 recipe, <filename>devtool</filename> uses the
603 recipe's
604 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
605 statements to locate the source code and any
606 local patch files from other developers.</para>
607
608 <para>With this scenario, no
609 <replaceable>srctree</replaceable> argument
610 exists.
611 Consequently, the default behavior of the
612 <filename>devtool modify</filename> command is
613 to extract the source files pointed to by the
614 <filename>SRC_URI</filename> statements into a
615 local Git structure.
616 Furthermore, the location for the extracted
617 source is the default area within the
618 <filename>devtool</filename> workspace.
619 The result is that the command sets up both
620 the source code and an append file within the
621 workspace while the recipe remains in its
622 original location.</para>
623
624 <para>Additionally, if you have any non-patch
625 local files (i.e. files referred to with
626 <filename>file://</filename> entries in
627 <filename>SRC_URI</filename> statement excluding
628 <filename>*.patch/</filename> or
629 <filename>*.diff</filename>), these files are
630 copied to an
631 <filename>oe-local-files</filename> folder
632 under the newly created source tree.
633 Copying the files here gives you a convenient
634 area from which you can modify the files.
635 Any changes or additions you make to those
636 files are incorporated into the build the next
637 time you build the software just as are other
638 changes you might have made to the source.
639 </para></listitem>
640 <listitem><para>
641 <emphasis>Middle</emphasis>:
642 The middle scenario in the figure represents a
643 situation where the source code also does not
644 exist locally.
645 In this case, the code is again upstream
646 and needs to be extracted to some
647 local area as a Git repository.
648 The recipe, in this scenario, is again local
649 and in its own layer outside the workspace.
650 </para>
651
652 <para>The following command tells
653 <filename>devtool</filename> the recipe with
654 which to work and, in this case, identifies a
655 local area for the extracted source files that
656 exists outside of the default
657 <filename>devtool</filename> workspace:
658 <literallayout class='monospaced'>
659 $ devtool modify <replaceable>recipe srctree</replaceable>
660 </literallayout>
661 <note>
662 You cannot provide a URL for
663 <replaceable>srctree</replaceable> using
664 the <filename>devtool</filename> command.
665 </note>
666 As with all extractions, the command uses
667 the recipe's <filename>SRC_URI</filename>
668 statements to locate the source files and any
669 associated patch files.
670 Non-patch files are copied to an
671 <filename>oe-local-files</filename> folder
672 under the newly created source tree.</para>
673
674 <para>Once the files are located, the command
675 by default extracts them into
676 <replaceable>srctree</replaceable>.</para>
677
678 <para>Within workspace,
679 <filename>devtool</filename> creates an append
680 file for the recipe.
681 The recipe remains in its original location but
682 the source files are extracted to the location
683 you provide with
684 <replaceable>srctree</replaceable>.
685 </para></listitem>
686 <listitem><para>
687 <emphasis>Right</emphasis>:
688 The right scenario in the figure represents a
689 situation where the source tree
690 (<replaceable>srctree</replaceable>) already
691 exists locally as a previously extracted Git
692 structure outside of the
693 <filename>devtool</filename> workspace.
694 In this example, the recipe also exists
695 elsewhere locally in its own layer.
696 </para>
697
698 <para>The following command tells
699 <filename>devtool</filename> the recipe
700 with which to work, uses the "-n" option to
701 indicate source does not need to be extracted,
702 and uses <replaceable>srctree</replaceable> to
703 point to the previously extracted source files:
704 <literallayout class='monospaced'>
705 $ devtool modify -n <replaceable>recipe srctree</replaceable>
706 </literallayout>
707 </para>
708
709 <para>If an <filename>oe-local-files</filename>
710 subdirectory happens to exist and it contains
711 non-patch files, the files are used.
712 However, if the subdirectory does not exist and
713 you run the <filename>devtool finish</filename>
714 command, any non-patch files that might exist
715 next to the recipe are removed because it
716 appears to <filename>devtool</filename> that
717 you have deleted those files.</para>
718
719 <para>Once the
720 <filename>devtool modify</filename> command
721 finishes, it creates only an append file for
722 the recipe in the <filename>devtool</filename>
723 workspace.
724 The recipe and the source code remain in their
725 original locations.
726 </para></listitem>
727 </itemizedlist>
728 </para></listitem>
729 <listitem><para>
730 <emphasis>Edit the Source</emphasis>:
731 Once you have used the
732 <filename>devtool modify</filename> command, you are
733 free to make changes to the source files.
734 You can use any editor you like to make and save
735 your source code modifications.
736 </para></listitem>
737 <listitem><para>
738 <emphasis>Build the Recipe or Rebuild the Image</emphasis>:
739 The next step you take depends on what you are going
740 to do with the new code.</para>
741
742 <para>If you need to eventually move the build output
743 to the target hardware, use the following
744 <filename>devtool</filename> command:
745 <literallayout class='monospaced'>
746 $ devtool build <replaceable>recipe</replaceable>
747 </literallayout></para>
748
749 <para>On the other hand, if you want an image to
750 contain the recipe's packages from the workspace
751 for immediate deployment onto a device (e.g. for
752 testing purposes), you can use
753 the <filename>devtool build-image</filename> command:
754 <literallayout class='monospaced'>
755 $ devtool build-image <replaceable>image</replaceable>
756 </literallayout>
757 </para></listitem>
758 <listitem><para>
759 <emphasis>Deploy the Build Output</emphasis>:
760 When you use the <filename>devtool build</filename>
761 command to build out your recipe, you probably want to
762 see if the resulting build output works as expected
763 on target hardware.
764 <note>
765 This step assumes you have a previously built
766 image that is already either running in QEMU or
767 running on actual hardware.
768 Also, it is assumed that for deployment of the image
769 to the target, SSH is installed in the image and if
770 the image is running on real hardware that you have
771 network access to and from your development machine.
772 </note>
773 You can deploy your build output to that target
774 hardware by using the
775 <filename>devtool deploy-target</filename> command:
776 <literallayout class='monospaced'>
777 $ devtool deploy-target <replaceable>recipe target</replaceable>
778 </literallayout>
779 The <replaceable>target</replaceable> is a live target
780 machine running as an SSH server.</para>
781
782 <para>You can, of course, use other methods to deploy
783 the image you built using the
784 <filename>devtool build-image</filename> command to
785 actual hardware.
786 <filename>devtool</filename> does not provide
787 a specific command to deploy the image to actual
788 hardware.
789 </para></listitem>
790 <listitem><para>
791 <emphasis>Finish Your Work With the Recipe</emphasis>:
792 The <filename>devtool finish</filename> command creates
793 any patches corresponding to commits in the local
794 Git repository, updates the recipe to point to them
795 (or creates a <filename>.bbappend</filename> file to do
796 so, depending on the specified destination layer), and
797 then resets the recipe so that the recipe is built
798 normally rather than from the workspace.
799 <literallayout class='monospaced'>
800 $ devtool finish <replaceable>recipe layer</replaceable>
801 </literallayout>
802 <note>
803 Any changes you want to turn into patches must be
804 staged and committed within the local Git
805 repository before you use the
806 <filename>devtool finish</filename> command.
807 </note></para>
808
809 <para>Because there is no need to move the recipe,
810 <filename>devtool finish</filename> either updates the
811 original recipe in the original layer or the command
812 creates a <filename>.bbappend</filename> file in a
813 different layer as provided by
814 <replaceable>layer</replaceable>.
815 Any work you did in the
816 <filename>oe-local-files</filename> directory is
817 preserved in the original files next to the recipe
818 during the <filename>devtool finish</filename>
819 command.</para>
820
821 <para>As a final process of the
822 <filename>devtool finish</filename> command, the state
823 of the standard layers and the upstream source is
824 restored so that you can build the recipe from those
825 areas rather than from the workspace.
826 <note>
827 You can use the <filename>devtool reset</filename>
828 command to put things back should you decide you
829 do not want to proceed with your work.
830 If you do use this command, realize that the source
831 tree is preserved.
832 </note>
833 </para></listitem>
834 </orderedlist>
835 </para>
836 </section>
837
838 <section id='sdk-devtool-use-devtool-upgrade-to-create-a-version-of-the-recipe-that-supports-a-newer-version-of-the-software'>
839 <title>Use <filename>devtool upgrade</filename> to Create a Version of the Recipe that Supports a Newer Version of the Software</title>
840
841 <para>
842 The <filename>devtool upgrade</filename> command upgrades
843 an existing recipe to that of a more up-to-date version
844 found upstream.
845 Throughout the life of software, recipes continually undergo
846 version upgrades by their upstream publishers.
847 You can use the <filename>devtool upgrade</filename>
848 workflow to make sure your recipes you are using for builds
849 are up-to-date with their upstream counterparts.
850 <note>
851 Several methods exist by which you can upgrade recipes -
852 <filename>devtool upgrade</filename> happens to be one.
853 You can read about all the methods by which you can
854 upgrade recipes in the
855 "<ulink url='&YOCTO_DOCS_DEV_URL;#gs-upgrading-recipes'>Upgrading Recipes</ulink>"
856 section of the Yocto Project Development Tasks Manual.
857 </note>
858 </para>
859
860 <para>
861 The <filename>devtool upgrade</filename> command is flexible
862 enough to allow you to specify source code revision and
863 versioning schemes, extract code into or out of the
864 <filename>devtool</filename>
865 <ulink url='&YOCTO_DOCS_REF_URL;#devtool-the-workspace-layer-structure'>workspace</ulink>,
866 and work with any source file forms that the
867 <ulink url='&YOCTO_DOCS_BB_URL;#bb-fetchers'>fetchers</ulink>
868 support.
869 </para>
870
871 <para>
872 The following diagram shows the common development flow
873 used with the <filename>devtool upgrade</filename> command:
874 </para>
875
876 <para>
877 <imagedata fileref="figures/sdk-devtool-upgrade-flow.png" align="center" />
878 </para>
879
880 <para>
881 <orderedlist>
882 <listitem><para>
883 <emphasis>Initiate the Upgrade</emphasis>:
884 The top part of the flow shows the typical scenario by
885 which you use the <filename>devtool upgrade</filename>
886 command.
887 The following conditions exist:
888 <itemizedlist>
889 <listitem><para>
890 The recipe exists in a local layer external
891 to the <filename>devtool</filename> workspace.
892 </para></listitem>
893 <listitem><para>
894 The source files for the new release
895 exist in the same location pointed to by
896 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
897 in the recipe (e.g. a tarball with the new
898 version number in the name, or as a different
899 revision in the upstream Git repository).
900 </para></listitem>
901 </itemizedlist>
902 A common situation is where third-party software has
903 undergone a revision so that it has been upgraded.
904 The recipe you have access to is likely in your own
905 layer.
906 Thus, you need to upgrade the recipe to use the
907 newer version of the software:
908 <literallayout class='monospaced'>
909 $ devtool upgrade -V <replaceable>version recipe</replaceable>
910 </literallayout>
911 By default, the <filename>devtool upgrade</filename>
912 command extracts source code into the
913 <filename>sources</filename> directory in the
914 <ulink url='&YOCTO_DOCS_REF_URL;#devtool-the-workspace-layer-structure'>workspace</ulink>.
915 If you want the code extracted to any other location,
916 you need to provide the
917 <replaceable>srctree</replaceable> positional argument
918 with the command as follows:
919 <literallayout class='monospaced'>
920 $ devtool upgrade -V <replaceable>version recipe srctree</replaceable>
921 </literallayout>
922 <note>
923 In this example, the "-V" option specifies the new
924 version.
925 If you don't use "-V", the command upgrades the
926 recipe to the latest version.
927 </note>
928 If the source files pointed to by the
929 <filename>SRC_URI</filename> statement in the recipe
930 are in a Git repository, you must provide the "-S"
931 option and specify a revision for the software.</para>
932
933 <para>Once <filename>devtool</filename> locates the
934 recipe, it uses the <filename>SRC_URI</filename>
935 variable to locate the source code and any local patch
936 files from other developers.
937 The result is that the command sets up the source
938 code, the new version of the recipe, and an append file
939 all within the workspace.</para>
940
941 <para>Additionally, if you have any non-patch
942 local files (i.e. files referred to with
943 <filename>file://</filename> entries in
944 <filename>SRC_URI</filename> statement excluding
945 <filename>*.patch/</filename> or
946 <filename>*.diff</filename>), these files are
947 copied to an
948 <filename>oe-local-files</filename> folder
949 under the newly created source tree.
950 Copying the files here gives you a convenient
951 area from which you can modify the files.
952 Any changes or additions you make to those
953 files are incorporated into the build the next
954 time you build the software just as are other
955 changes you might have made to the source.
956 </para></listitem>
957 <listitem><para>
958 <emphasis>Resolve any Conflicts created by the Upgrade</emphasis>:
959 Conflicts could exist due to the software being
960 upgraded to a new version.
961 Conflicts occur if your recipe specifies some patch
962 files in <filename>SRC_URI</filename> that conflict
963 with changes made in the new version of the software.
964 For such cases, you need to resolve the conflicts
965 by editing the source and following the normal
966 <filename>git rebase</filename> conflict resolution
967 process.</para>
968
969 <para>Before moving onto the next step, be sure to
970 resolve any such conflicts created through use of a
971 newer or different version of the software.
972 </para></listitem>
973 <listitem><para>
974 <emphasis>Build the Recipe or Rebuild the Image</emphasis>:
975 The next step you take depends on what you are going
976 to do with the new code.</para>
977
978 <para>If you need to eventually move the build output
979 to the target hardware, use the following
980 <filename>devtool</filename> command:
981 <literallayout class='monospaced'>
982 $ devtool build <replaceable>recipe</replaceable>
983 </literallayout></para>
984
985 <para>On the other hand, if you want an image to
986 contain the recipe's packages from the workspace
987 for immediate deployment onto a device (e.g. for
988 testing purposes), you can use
989 the <filename>devtool build-image</filename> command:
990 <literallayout class='monospaced'>
991 $ devtool build-image <replaceable>image</replaceable>
992 </literallayout>
993 </para></listitem>
994 <listitem><para>
995 <emphasis>Deploy the Build Output</emphasis>:
996 When you use the <filename>devtool build</filename>
997 command or <filename>bitbake</filename> to build
998 your recipe, you probably want to see if the resulting
999 build output works as expected on target hardware.
1000 <note>
1001 This step assumes you have a previously built
1002 image that is already either running in QEMU or
1003 running on actual hardware.
1004 Also, it is assumed that for deployment of the
1005 image to the target, SSH is installed in the image
1006 and if the image is running on real hardware that
1007 you have network access to and from your
1008 development machine.
1009 </note>
1010 You can deploy your build output to that target
1011 hardware by using the
1012 <filename>devtool deploy-target</filename> command:
1013 <literallayout class='monospaced'>
1014 $ devtool deploy-target <replaceable>recipe target</replaceable>
1015 </literallayout>
1016 The <replaceable>target</replaceable> is a live target
1017 machine running as an SSH server.</para>
1018
1019 <para>You can, of course, also deploy the image you
1020 build using the
1021 <filename>devtool build-image</filename> command
1022 to actual hardware.
1023 However, <filename>devtool</filename> does not provide
1024 a specific command that allows you to do this.
1025 </para></listitem>
1026 <listitem><para>
1027 <emphasis>Finish Your Work With the Recipe</emphasis>:
1028 The <filename>devtool finish</filename> command creates
1029 any patches corresponding to commits in the local
1030 Git repository, moves the new recipe to a more
1031 permanent layer, and then resets the recipe so that
1032 the recipe is built normally rather than from the
1033 workspace.</para>
1034
1035 <para>Any work you did in the
1036 <filename>oe-local-files</filename> directory is
1037 preserved in the original files next to the recipe
1038 during the <filename>devtool finish</filename>
1039 command.</para>
1040
1041 <para>
1042 If you specify a destination layer that is the same as
1043 the original source, then the old version of the
1044 recipe and associated files are removed prior to
1045 adding the new version.
1046 <literallayout class='monospaced'>
1047 $ devtool finish <replaceable>recipe layer</replaceable>
1048 </literallayout>
1049 <note>
1050 Any changes you want to turn into patches must be
1051 committed to the Git repository in the source tree.
1052 </note></para>
1053
1054 <para>As a final process of the
1055 <filename>devtool finish</filename> command, the state
1056 of the standard layers and the upstream source is
1057 restored so that you can build the recipe from those
1058 areas rather than the workspace.
1059 <note>
1060 You can use the <filename>devtool reset</filename>
1061 command to put things back should you decide you
1062 do not want to proceed with your work.
1063 If you do use this command, realize that the source
1064 tree is preserved.
1065 </note>
1066 </para></listitem>
1067 </orderedlist>
1068 </para>
1069 </section>
1070 </section>
1071
1072 <section id='sdk-a-closer-look-at-devtool-add'>
1073 <title>A Closer Look at <filename>devtool add</filename></title>
1074
1075 <para>
1076 The <filename>devtool add</filename> command automatically creates
1077 a recipe based on the source tree you provide with the command.
1078 Currently, the command has support for the following:
1079 <itemizedlist>
1080 <listitem><para>
1081 Autotools (<filename>autoconf</filename> and
1082 <filename>automake</filename>)
1083 </para></listitem>
1084 <listitem><para>
1085 CMake
1086 </para></listitem>
1087 <listitem><para>
1088 Scons
1089 </para></listitem>
1090 <listitem><para>
1091 <filename>qmake</filename>
1092 </para></listitem>
1093 <listitem><para>
1094 Plain <filename>Makefile</filename>
1095 </para></listitem>
1096 <listitem><para>
1097 Out-of-tree kernel module
1098 </para></listitem>
1099 <listitem><para>
1100 Binary package (i.e. "-b" option)
1101 </para></listitem>
1102 <listitem><para>
1103 Node.js module
1104 </para></listitem>
1105 <listitem><para>
1106 Python modules that use <filename>setuptools</filename>
1107 or <filename>distutils</filename>
1108 </para></listitem>
1109 </itemizedlist>
1110 </para>
1111
1112 <para>
1113 Apart from binary packages, the determination of how a source tree
1114 should be treated is automatic based on the files present within
1115 that source tree.
1116 For example, if a <filename>CMakeLists.txt</filename> file is found,
1117 then the source tree is assumed to be using
1118 CMake and is treated accordingly.
1119 <note>
1120 In most cases, you need to edit the automatically generated
1121 recipe in order to make it build properly.
1122 Typically, you would go through several edit and build cycles
1123 until the recipe successfully builds.
1124 Once the recipe builds, you could use possible further
1125 iterations to test the recipe on the target device.
1126 </note>
1127 </para>
1128
1129 <para>
1130 The remainder of this section covers specifics regarding how parts
1131 of the recipe are generated.
1132 </para>
1133
1134 <section id='sdk-name-and-version'>
1135 <title>Name and Version</title>
1136
1137 <para>
1138 If you do not specify a name and version on the command
1139 line, <filename>devtool add</filename> uses various metadata
1140 within the source tree in an attempt to determine
1141 the name and version of the software being built.
1142 Based on what the tool determines, <filename>devtool</filename>
1143 sets the name of the created recipe file accordingly.
1144 </para>
1145
1146 <para>
1147 If <filename>devtool</filename> cannot determine the name and
1148 version, the command prints an error.
1149 For such cases, you must re-run the command and provide
1150 the name and version, just the name, or just the version as
1151 part of the command line.
1152 </para>
1153
1154 <para>
1155 Sometimes the name or version determined from the source tree
1156 might be incorrect.
1157 For such a case, you must reset the recipe:
1158 <literallayout class='monospaced'>
1159 $ devtool reset -n <replaceable>recipename</replaceable>
1160 </literallayout>
1161 After running the <filename>devtool reset</filename> command,
1162 you need to run <filename>devtool add</filename> again and
1163 provide the name or the version.
1164 </para>
1165 </section>
1166
1167 <section id='sdk-dependency-detection-and-mapping'>
1168 <title>Dependency Detection and Mapping</title>
1169
1170 <para>
1171 The <filename>devtool add</filename> command attempts to
1172 detect build-time dependencies and map them to other recipes
1173 in the system.
1174 During this mapping, the command fills in the names of those
1175 recipes as part of the
1176 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink>
1177 variable within the recipe.
1178 If a dependency cannot be mapped, <filename>devtool</filename>
1179 places a comment in the recipe indicating such.
1180 The inability to map a dependency can result from naming not
1181 being recognized or because the dependency simply is not
1182 available.
1183 For cases where the dependency is not available, you must use
1184 the <filename>devtool add</filename> command to add an
1185 additional recipe that satisfies the dependency.
1186 Once you add that recipe, you need to update the
1187 <filename>DEPENDS</filename> variable in the original recipe
1188 to include the new recipe.
1189 </para>
1190
1191 <para>
1192 If you need to add runtime dependencies, you can do so by
1193 adding the following to your recipe:
1194 <literallayout class='monospaced'>
1195 RDEPENDS_${PN} += "<replaceable>dependency1 dependency2 ...</replaceable>"
1196 </literallayout>
1197 <note>
1198 The <filename>devtool add</filename> command often cannot
1199 distinguish between mandatory and optional dependencies.
1200 Consequently, some of the detected dependencies might
1201 in fact be optional.
1202 When in doubt, consult the documentation or the configure
1203 script for the software the recipe is building for further
1204 details.
1205 In some cases, you might find you can substitute the
1206 dependency with an option that disables the associated
1207 functionality passed to the configure script.
1208 </note>
1209 </para>
1210 </section>
1211
1212 <section id='sdk-license-detection'>
1213 <title>License Detection</title>
1214
1215 <para>
1216 The <filename>devtool add</filename> command attempts to
1217 determine if the software you are adding is able to be
1218 distributed under a common, open-source license.
1219 If so, the command sets the
1220 <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE'><filename>LICENSE</filename></ulink>
1221 value accordingly.
1222 You should double-check the value added by the command against
1223 the documentation or source files for the software you are
1224 building and, if necessary, update that
1225 <filename>LICENSE</filename> value.
1226 </para>
1227
1228 <para>
1229 The <filename>devtool add</filename> command also sets the
1230 <ulink url='&YOCTO_DOCS_REF_URL;#var-LIC_FILES_CHKSUM'><filename>LIC_FILES_CHKSUM</filename></ulink>
1231 value to point to all files that appear to be license-related.
1232 Realize that license statements often appear in comments at
1233 the top of source files or within the documentation.
1234 In such cases, the command does not recognize those license
1235 statements.
1236 Consequently, you might need to amend the
1237 <filename>LIC_FILES_CHKSUM</filename> variable to point to one
1238 or more of those comments if present.
1239 Setting <filename>LIC_FILES_CHKSUM</filename> is particularly
1240 important for third-party software.
1241 The mechanism attempts to ensure correct licensing should you
1242 upgrade the recipe to a newer upstream version in future.
1243 Any change in licensing is detected and you receive an error
1244 prompting you to check the license text again.
1245 </para>
1246
1247 <para>
1248 If the <filename>devtool add</filename> command cannot
1249 determine licensing information, <filename>devtool</filename>
1250 sets the <filename>LICENSE</filename> value to "CLOSED" and
1251 leaves the <filename>LIC_FILES_CHKSUM</filename> value unset.
1252 This behavior allows you to continue with development even
1253 though the settings are unlikely to be correct in all cases.
1254 You should check the documentation or source files for the
1255 software you are building to determine the actual license.
1256 </para>
1257 </section>
1258
1259 <section id='sdk-adding-makefile-only-software'>
1260 <title>Adding Makefile-Only Software</title>
1261
1262 <para>
1263 The use of Make by itself is very common in both proprietary
1264 and open-source software.
1265 Unfortunately, Makefiles are often not written with
1266 cross-compilation in mind.
1267 Thus, <filename>devtool add</filename> often cannot do very
1268 much to ensure that these Makefiles build correctly.
1269 It is very common, for example, to explicitly call
1270 <filename>gcc</filename> instead of using the
1271 <ulink url='&YOCTO_DOCS_REF_URL;#var-CC'><filename>CC</filename></ulink>
1272 variable.
1273 Usually, in a cross-compilation environment,
1274 <filename>gcc</filename> is the compiler for the build host
1275 and the cross-compiler is named something similar to
1276 <filename>arm-poky-linux-gnueabi-gcc</filename> and might
1277 require arguments (e.g. to point to the associated sysroot
1278 for the target machine).
1279 </para>
1280
1281 <para>
1282 When writing a recipe for Makefile-only software, keep the
1283 following in mind:
1284 <itemizedlist>
1285 <listitem><para>
1286 You probably need to patch the Makefile to use
1287 variables instead of hardcoding tools within the
1288 toolchain such as <filename>gcc</filename> and
1289 <filename>g++</filename>.
1290 </para></listitem>
1291 <listitem><para>
1292 The environment in which Make runs is set up with
1293 various standard variables for compilation (e.g.
1294 <filename>CC</filename>, <filename>CXX</filename>, and
1295 so forth) in a similar manner to the environment set
1296 up by the SDK's environment setup script.
1297 One easy way to see these variables is to run the
1298 <filename>devtool build</filename> command on the
1299 recipe and then look in
1300 <filename>oe-logs/run.do_compile</filename>.
1301 Towards the top of this file, a list of environment
1302 variables exists that are being set.
1303 You can take advantage of these variables within the
1304 Makefile.
1305 </para></listitem>
1306 <listitem><para>
1307 If the Makefile sets a default for a variable using "=",
1308 that default overrides the value set in the environment,
1309 which is usually not desirable.
1310 For this case, you can either patch the Makefile
1311 so it sets the default using the "?=" operator, or
1312 you can alternatively force the value on the
1313 <filename>make</filename> command line.
1314 To force the value on the command line, add the
1315 variable setting to
1316 <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OEMAKE'><filename>EXTRA_OEMAKE</filename></ulink>
1317 or
1318 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGECONFIG_CONFARGS'><filename>PACKAGECONFIG_CONFARGS</filename></ulink>
1319 within the recipe.
1320 Here is an example using <filename>EXTRA_OEMAKE</filename>:
1321 <literallayout class='monospaced'>
1322 EXTRA_OEMAKE += "'CC=${CC}' 'CXX=${CXX}'"
1323 </literallayout>
1324 In the above example, single quotes are used around the
1325 variable settings as the values are likely to contain
1326 spaces because required default options are passed to
1327 the compiler.
1328 </para></listitem>
1329 <listitem><para>
1330 Hardcoding paths inside Makefiles is often problematic
1331 in a cross-compilation environment.
1332 This is particularly true because those hardcoded paths
1333 often point to locations on the build host and thus
1334 will either be read-only or will introduce
1335 contamination into the cross-compilation because they
1336 are specific to the build host rather than the target.
1337 Patching the Makefile to use prefix variables or other
1338 path variables is usually the way to handle this
1339 situation.
1340 </para></listitem>
1341 <listitem><para>
1342 Sometimes a Makefile runs target-specific commands such
1343 as <filename>ldconfig</filename>.
1344 For such cases, you might be able to apply patches that
1345 remove these commands from the Makefile.
1346 </para></listitem>
1347 </itemizedlist>
1348 </para>
1349 </section>
1350
1351 <section id='sdk-adding-native-tools'>
1352 <title>Adding Native Tools</title>
1353
1354 <para>
1355 Often, you need to build additional tools that run on the
1356 <ulink url='&YOCTO_DOCS_REF_URL;#hardware-build-system-term'>build host</ulink>
1357 as opposed to the target.
1358 You should indicate this requirement by using one of the
1359 following methods when you run
1360 <filename>devtool add</filename>:
1361 <itemizedlist>
1362 <listitem><para>
1363 Specify the name of the recipe such that it ends
1364 with "-native".
1365 Specifying the name like this produces a recipe that
1366 only builds for the build host.
1367 </para></listitem>
1368 <listitem><para>
1369 Specify the "&dash;&dash;also-native" option with the
1370 <filename>devtool add</filename> command.
1371 Specifying this option creates a recipe file that still
1372 builds for the target but also creates a variant with
1373 a "-native" suffix that builds for the build host.
1374 </para></listitem>
1375 </itemizedlist>
1376 <note>
1377 If you need to add a tool that is shipped as part of a
1378 source tree that builds code for the target, you can
1379 typically accomplish this by building the native and target
1380 parts separately rather than within the same compilation
1381 process.
1382 Realize though that with the "&dash;&dash;also-native"
1383 option, you can add the tool using just one recipe file.
1384 </note>
1385 </para>
1386 </section>
1387
1388 <section id='sdk-adding-node-js-modules'>
1389 <title>Adding Node.js Modules</title>
1390
1391 <para>
1392 You can use the <filename>devtool add</filename> command two
1393 different ways to add Node.js modules: 1) Through
1394 <filename>npm</filename> and, 2) from a repository or local
1395 source.
1396 </para>
1397
1398 <para>
1399 Use the following form to add Node.js modules through
1400 <filename>npm</filename>:
1401 <literallayout class='monospaced'>
1402 $ devtool add "npm://registry.npmjs.org;name=forever;version=0.15.1"
1403 </literallayout>
1404 The name and version parameters are mandatory.
1405 Lockdown and shrinkwrap files are generated and pointed to by
1406 the recipe in order to freeze the version that is fetched for
1407 the dependencies according to the first time.
1408 This also saves checksums that are verified on future fetches.
1409 Together, these behaviors ensure the reproducibility and
1410 integrity of the build.
1411 <note><title>Notes</title>
1412 <itemizedlist>
1413 <listitem><para>
1414 You must use quotes around the URL.
1415 The <filename>devtool add</filename> does not require
1416 the quotes, but the shell considers ";" as a splitter
1417 between multiple commands.
1418 Thus, without the quotes,
1419 <filename>devtool add</filename> does not receive the
1420 other parts, which results in several "command not
1421 found" errors.
1422 </para></listitem>
1423 <listitem><para>
1424 In order to support adding Node.js modules, a
1425 <filename>nodejs</filename> recipe must be part
1426 of your SDK.
1427 </para></listitem>
1428 </itemizedlist>
1429 </note>
1430 </para>
1431
1432 <para>
1433 As mentioned earlier, you can also add Node.js modules
1434 directly from a repository or local source tree.
1435 To add modules this way, use <filename>devtool add</filename>
1436 in the following form:
1437 <literallayout class='monospaced'>
1438 $ devtool add https://github.com/diversario/node-ssdp
1439 </literallayout>
1440 In this example, <filename>devtool</filename> fetches the
1441 specified Git repository, detects the code as Node.js
1442 code, fetches dependencies using <filename>npm</filename>, and
1443 sets
1444 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
1445 accordingly.
1446 </para>
1447 </section>
1448 </section>
1449
1450 <section id='sdk-working-with-recipes'>
1451 <title>Working With Recipes</title>
1452
1453 <para>
1454 When building a recipe using the
1455 <filename>devtool build</filename> command, the typical build
1456 progresses as follows:
1457 <orderedlist>
1458 <listitem><para>
1459 Fetch the source
1460 </para></listitem>
1461 <listitem><para>
1462 Unpack the source
1463 </para></listitem>
1464 <listitem><para>
1465 Configure the source
1466 </para></listitem>
1467 <listitem><para>
1468 Compile the source
1469 </para></listitem>
1470 <listitem><para>
1471 Install the build output
1472 </para></listitem>
1473 <listitem><para>
1474 Package the installed output
1475 </para></listitem>
1476 </orderedlist>
1477 For recipes in the workspace, fetching and unpacking is disabled
1478 as the source tree has already been prepared and is persistent.
1479 Each of these build steps is defined as a function (task), usually
1480 with a "do_" prefix (e.g.
1481 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-fetch'><filename>do_fetch</filename></ulink>,
1482 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-unpack'><filename>do_unpack</filename></ulink>,
1483 and so forth).
1484 These functions are typically shell scripts but can instead be
1485 written in Python.
1486 </para>
1487
1488 <para>
1489 If you look at the contents of a recipe, you will see that the
1490 recipe does not include complete instructions for building the
1491 software.
1492 Instead, common functionality is encapsulated in classes inherited
1493 with the <filename>inherit</filename> directive.
1494 This technique leaves the recipe to describe just the things that
1495 are specific to the software being built.
1496 A
1497 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-base'><filename>base</filename></ulink>
1498 class exists that is implicitly inherited by all recipes and
1499 provides the functionality that most recipes typically need.
1500 </para>
1501
1502 <para>
1503 The remainder of this section presents information useful when
1504 working with recipes.
1505 </para>
1506
1507 <section id='sdk-finding-logs-and-work-files'>
1508 <title>Finding Logs and Work Files</title>
1509
1510 <para>
1511 After the first run of the <filename>devtool build</filename>
1512 command, recipes that were previously created using the
1513 <filename>devtool add</filename> command or whose sources were
1514 modified using the <filename>devtool modify</filename>
1515 command contain symbolic links created within the source tree:
1516 <itemizedlist>
1517 <listitem><para>
1518 <filename>oe-logs</filename>:
1519 This link points to the directory in which log files
1520 and run scripts for each build step are created.
1521 </para></listitem>
1522 <listitem><para>
1523 <filename>oe-workdir</filename>:
1524 This link points to the temporary work area for the
1525 recipe.
1526 The following locations under
1527 <filename>oe-workdir</filename> are particularly
1528 useful:
1529 <itemizedlist>
1530 <listitem><para>
1531 <filename>image/</filename>:
1532 Contains all of the files installed during
1533 the
1534 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-install'><filename>do_install</filename></ulink>
1535 stage.
1536 Within a recipe, this directory is referred
1537 to by the expression
1538 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-D'><filename>D</filename></ulink><filename>}</filename>.
1539 </para></listitem>
1540 <listitem><para>
1541 <filename>sysroot-destdir/</filename>:
1542 Contains a subset of files installed within
1543 <filename>do_install</filename> that have
1544 been put into the shared sysroot.
1545 For more information, see the
1546 "<link linkend='sdk-sharing-files-between-recipes'>Sharing Files Between Recipes</link>"
1547 section.
1548 </para></listitem>
1549 <listitem><para>
1550 <filename>packages-split/</filename>:
1551 Contains subdirectories for each package
1552 produced by the recipe.
1553 For more information, see the
1554 "<link linkend='sdk-packaging'>Packaging</link>"
1555 section.
1556 </para></listitem>
1557 </itemizedlist>
1558 </para></listitem>
1559 </itemizedlist>
1560 You can use these links to get more information on what is
1561 happening at each build step.
1562 </para>
1563 </section>
1564
1565 <section id='sdk-setting-configure-arguments'>
1566 <title>Setting Configure Arguments</title>
1567
1568 <para>
1569 If the software your recipe is building uses GNU autoconf,
1570 then a fixed set of arguments is passed to it to enable
1571 cross-compilation plus any extras specified by
1572 <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></ulink>
1573 or
1574 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGECONFIG_CONFARGS'><filename>PACKAGECONFIG_CONFARGS</filename></ulink>
1575 set within the recipe.
1576 If you wish to pass additional options, add them to
1577 <filename>EXTRA_OECONF</filename> or
1578 <filename>PACKAGECONFIG_CONFARGS</filename>.
1579 Other supported build tools have similar variables
1580 (e.g.
1581 <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OECMAKE'><filename>EXTRA_OECMAKE</filename></ulink>
1582 for CMake,
1583 <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OESCONS'><filename>EXTRA_OESCONS</filename></ulink>
1584 for Scons, and so forth).
1585 If you need to pass anything on the <filename>make</filename>
1586 command line, you can use <filename>EXTRA_OEMAKE</filename> or the
1587 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGECONFIG_CONFARGS'><filename>PACKAGECONFIG_CONFARGS</filename></ulink>
1588 variables to do so.
1589 </para>
1590
1591 <para>
1592 You can use the <filename>devtool configure-help</filename> command
1593 to help you set the arguments listed in the previous paragraph.
1594 The command determines the exact options being passed, and shows
1595 them to you along with any custom arguments specified through
1596 <filename>EXTRA_OECONF</filename> or
1597 <filename>PACKAGECONFIG_CONFARGS</filename>.
1598 If applicable, the command also shows you the output of the
1599 configure script's "&dash;&dash;help" option as a reference.
1600 </para>
1601 </section>
1602
1603 <section id='sdk-sharing-files-between-recipes'>
1604 <title>Sharing Files Between Recipes</title>
1605
1606 <para>
1607 Recipes often need to use files provided by other recipes on
1608 the
1609 <ulink url='&YOCTO_DOCS_REF_URL;#hardware-build-system-term'>build host</ulink>.
1610 For example, an application linking to a common library needs
1611 access to the library itself and its associated headers.
1612 The way this access is accomplished within the extensible SDK is
1613 through the sysroot.
1614 One sysroot exists per "machine" for which the SDK is being
1615 built.
1616 In practical terms, this means a sysroot exists for the target
1617 machine, and a sysroot exists for the build host.
1618 </para>
1619
1620 <para>
1621 Recipes should never write files directly into the sysroot.
1622 Instead, files should be installed into standard locations
1623 during the
1624 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-install'><filename>do_install</filename></ulink>
1625 task within the
1626 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-D'><filename>D</filename></ulink><filename>}</filename>
1627 directory.
1628 A subset of these files automatically goes into the sysroot.
1629 The reason for this limitation is that almost all files that go
1630 into the sysroot are cataloged in manifests in order to ensure
1631 they can be removed later when a recipe is modified or removed.
1632 Thus, the sysroot is able to remain free from stale files.
1633 </para>
1634 </section>
1635
1636 <section id='sdk-packaging'>
1637 <title>Packaging</title>
1638
1639 <para>
1640 Packaging is not always particularly relevant within the
1641 extensible SDK.
1642 However, if you examine how build output gets into the final image
1643 on the target device, it is important to understand packaging
1644 because the contents of the image are expressed in terms of
1645 packages and not recipes.
1646 </para>
1647
1648 <para>
1649 During the
1650 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package'><filename>do_package</filename></ulink>
1651 task, files installed during the
1652 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-install'><filename>do_install</filename></ulink>
1653 task are split into one main package, which is almost always
1654 named the same as the recipe, and into several other packages.
1655 This separation exists because not all of those installed files
1656 are useful in every image.
1657 For example, you probably do not need any of the documentation
1658 installed in a production image.
1659 Consequently, for each recipe the documentation files are
1660 separated into a <filename>-doc</filename> package.
1661 Recipes that package software containing optional modules or
1662 plugins might undergo additional package splitting as well.
1663 </para>
1664
1665 <para>
1666 After building a recipe, you can see where files have gone by
1667 looking in the <filename>oe-workdir/packages-split</filename>
1668 directory, which contains a subdirectory for each package.
1669 Apart from some advanced cases, the
1670 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'><filename>PACKAGES</filename></ulink>
1671 and
1672 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILES'><filename>FILES</filename></ulink>
1673 variables controls splitting.
1674 The <filename>PACKAGES</filename> variable lists all of the
1675 packages to be produced, while the <filename>FILES</filename>
1676 variable specifies which files to include in each package by
1677 using an override to specify the package.
1678 For example, <filename>FILES_${PN}</filename> specifies the
1679 files to go into the main package (i.e. the main package has
1680 the same name as the recipe and
1681 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink><filename>}</filename>
1682 evaluates to the recipe name).
1683 The order of the <filename>PACKAGES</filename> value is
1684 significant.
1685 For each installed file, the first package whose
1686 <filename>FILES</filename> value matches the file is the
1687 package into which the file goes.
1688 Defaults exist for both the <filename>PACKAGES</filename> and
1689 <filename>FILES</filename> variables.
1690 Consequently, you might find you do not even need to set these
1691 variables in your recipe unless the software the recipe is
1692 building installs files into non-standard locations.
1693 </para>
1694 </section>
1695 </section>
1696
1697 <section id='sdk-restoring-the-target-device-to-its-original-state'>
1698 <title>Restoring the Target Device to its Original State</title>
1699
1700 <para>
1701 If you use the <filename>devtool deploy-target</filename>
1702 command to write a recipe's build output to the target, and
1703 you are working on an existing component of the system, then you
1704 might find yourself in a situation where you need to restore the
1705 original files that existed prior to running the
1706 <filename>devtool deploy-target</filename> command.
1707 Because the <filename>devtool deploy-target</filename> command
1708 backs up any files it overwrites, you can use the
1709 <filename>devtool undeploy-target</filename> command to restore
1710 those files and remove any other files the recipe deployed.
1711 Consider the following example:
1712 <literallayout class='monospaced'>
1713 $ devtool undeploy-target lighttpd root@192.168.7.2
1714 </literallayout>
1715 If you have deployed multiple applications, you can remove them
1716 all using the "-a" option thus restoring the target device to its
1717 original state:
1718 <literallayout class='monospaced'>
1719 $ devtool undeploy-target -a root@192.168.7.2
1720 </literallayout>
1721 Information about files deployed to the target as well as any
1722 backed up files are stored on the target itself.
1723 This storage, of course, requires some additional space
1724 on the target machine.
1725 <note>
1726 The <filename>devtool deploy-target</filename> and
1727 <filename>devtool undeploy-target</filename> commands do not
1728 currently interact with any package management system on the
1729 target device (e.g. RPM or OPKG).
1730 Consequently, you should not intermingle
1731 <filename>devtool deploy-target</filename> and package
1732 manager operations on the target device.
1733 Doing so could result in a conflicting set of files.
1734 </note>
1735 </para>
1736 </section>
1737
1738 <section id='sdk-installing-additional-items-into-the-extensible-sdk'>
1739 <title>Installing Additional Items Into the Extensible SDK</title>
1740
1741 <para>
1742 Out of the box the extensible SDK typically only comes with a small
1743 number of tools and libraries.
1744 A minimal SDK starts mostly empty and is populated on-demand.
1745 Sometimes you must explicitly install extra items into the SDK.
1746 If you need these extra items, you can first search for the items
1747 using the <filename>devtool search</filename> command.
1748 For example, suppose you need to link to libGL but you are not sure
1749 which recipe provides libGL.
1750 You can use the following command to find out:
1751 <literallayout class='monospaced'>
1752 $ devtool search libGL
1753 mesa A free implementation of the OpenGL API
1754 </literallayout>
1755 Once you know the recipe (i.e. <filename>mesa</filename> in this
1756 example), you can install it:
1757 <literallayout class='monospaced'>
1758 $ devtool sdk-install mesa
1759 </literallayout>
1760 By default, the <filename>devtool sdk-install</filename> command
1761 assumes the item is available in pre-built form from your SDK
1762 provider.
1763 If the item is not available and it is acceptable to build the item
1764 from source, you can add the "-s" option as follows:
1765 <literallayout class='monospaced'>
1766 $ devtool sdk-install -s mesa
1767 </literallayout>
1768 It is important to remember that building the item from source
1769 takes significantly longer than installing the pre-built artifact.
1770 Also, if no recipe exists for the item you want to add to the SDK,
1771 you must instead add the item using the
1772 <filename>devtool add</filename> command.
1773 </para>
1774 </section>
1775
1776 <section id='sdk-applying-updates-to-an-installed-extensible-sdk'>
1777 <title>Applying Updates to an Installed Extensible SDK</title>
1778
1779 <para>
1780 If you are working with an installed extensible SDK that gets
1781 occasionally updated (e.g. a third-party SDK), then you will need
1782 to manually "pull down" the updates into the installed SDK.
1783 </para>
1784
1785 <para>
1786 To update your installed SDK, use <filename>devtool</filename> as
1787 follows:
1788 <literallayout class='monospaced'>
1789 $ devtool sdk-update
1790 </literallayout>
1791 The previous command assumes your SDK provider has set the default
1792 update URL for you through the
1793 <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_UPDATE_URL'><filename>SDK_UPDATE_URL</filename></ulink>
1794 variable as described in the
1795 "<link linkend='sdk-providing-updates-to-the-extensible-sdk-after-installation'>Providing Updates to the Extensible SDK After Installation</link>"
1796 section.
1797 If the SDK provider has not set that default URL, you need to
1798 specify it yourself in the command as follows:
1799 <literallayout class='monospaced'>
1800 $ devtool sdk-update <replaceable>path_to_update_directory</replaceable>
1801 </literallayout>
1802 <note>
1803 The URL needs to point specifically to a published SDK and
1804 not to an SDK installer that you would download and install.
1805 </note>
1806 </para>
1807 </section>
1808
1809 <section id='sdk-creating-a-derivative-sdk-with-additional-components'>
1810 <title>Creating a Derivative SDK With Additional Components</title>
1811
1812 <para>
1813 You might need to produce an SDK that contains your own custom
1814 libraries.
1815 A good example would be if you were a vendor with customers that
1816 use your SDK to build their own platform-specific software and
1817 those customers need an SDK that has custom libraries.
1818 In such a case, you can produce a derivative SDK based on the
1819 currently installed SDK fairly easily by following these steps:
1820 <orderedlist>
1821 <listitem><para>
1822 If necessary, install an extensible SDK that
1823 you want to use as a base for your derivative SDK.
1824 </para></listitem>
1825 <listitem><para>
1826 Source the environment script for the SDK.
1827 </para></listitem>
1828 <listitem><para>
1829 Add the extra libraries or other components you want by
1830 using the <filename>devtool add</filename> command.
1831 </para></listitem>
1832 <listitem><para>
1833 Run the <filename>devtool build-sdk</filename> command.
1834 </para></listitem>
1835 </orderedlist>
1836 The previous steps take the recipes added to the workspace and
1837 construct a new SDK installer that contains those recipes and the
1838 resulting binary artifacts.
1839 The recipes go into their own separate layer in the constructed
1840 derivative SDK, which leaves the workspace clean and ready for
1841 users to add their own recipes.
1842 </para>
1843 </section>
1844</chapter>
1845<!--
1846vim: expandtab tw=80 ts=4
1847-->
diff --git a/documentation/sdk-manual/sdk-intro.xml b/documentation/sdk-manual/sdk-intro.xml
deleted file mode 100644
index f42670ea6e..0000000000
--- a/documentation/sdk-manual/sdk-intro.xml
+++ /dev/null
@@ -1,353 +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<chapter id='sdk-intro'>
7<title>Introduction</title>
8
9<section id='sdk-manual-intro'>
10 <title>Introduction</title>
11
12 <para>
13 Welcome to the Yocto Project Application Development and the
14 Extensible Software Development Kit (eSDK) manual.
15 This manual provides information that explains how to use both the
16 Yocto Project extensible and standard SDKs to develop
17 applications and images.
18 <note>
19 Prior to the 2.0 Release of the Yocto Project, application
20 development was primarily accomplished through the use of the
21 Application Development Toolkit (ADT) and the availability
22 of stand-alone cross-development toolchains and other tools.
23 With the 2.1 Release of the Yocto Project, application development
24 has transitioned to within a tool-rich extensible SDK and the more
25 traditional standard SDK.
26 </note>
27 </para>
28
29 <para>
30 All SDKs consist of the following:
31 <itemizedlist>
32 <listitem><para>
33 <emphasis>Cross-Development Toolchain</emphasis>:
34 This toolchain contains a compiler, debugger, and various
35 miscellaneous tools.
36 </para></listitem>
37 <listitem><para>
38 <emphasis>Libraries, Headers, and Symbols</emphasis>:
39 The libraries, headers, and symbols are specific to the image
40 (i.e. they match the image).
41 </para></listitem>
42 <listitem><para>
43 <emphasis>Environment Setup Script</emphasis>:
44 This <filename>*.sh</filename> file, once run, sets up the
45 cross-development environment by defining variables and
46 preparing for SDK use.
47 </para></listitem>
48 </itemizedlist>
49 </para>
50
51 <para>
52 Additionally, an extensible SDK has tools that allow you to easily add
53 new applications and libraries to an image, modify the source of an
54 existing component, test changes on the target hardware, and easily
55 integrate an application into the
56 <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>OpenEmbedded build system</ulink>.
57 </para>
58
59 <para>
60 You can use an SDK to independently develop and test code
61 that is destined to run on some target machine.
62 SDKs are completely self-contained.
63 The binaries are linked against their own copy of
64 <filename>libc</filename>, which results in no dependencies
65 on the target system.
66 To achieve this, the pointer to the dynamic loader is
67 configured at install time since that path cannot be dynamically
68 altered.
69 This is the reason for a wrapper around the
70 <filename>populate_sdk</filename> and
71 <filename>populate_sdk_ext</filename> archives.
72 </para>
73
74 <para>
75 Another feature for the SDKs is that only one set of cross-compiler
76 toolchain binaries are produced for any given architecture.
77 This feature takes advantage of the fact that the target hardware can
78 be passed to <filename>gcc</filename> as a set of compiler options.
79 Those options are set up by the environment script and contained in
80 variables such as
81 <ulink url='&YOCTO_DOCS_REF_URL;#var-CC'><filename>CC</filename></ulink>
82 and
83 <ulink url='&YOCTO_DOCS_REF_URL;#var-LD'><filename>LD</filename></ulink>.
84 This reduces the space needed for the tools.
85 Understand, however, that every target still needs a sysroot because
86 those binaries are target-specific.
87 </para>
88
89 <para>
90 The SDK development environment consists of the following:
91 <itemizedlist>
92 <listitem><para>
93 The self-contained SDK, which is an
94 architecture-specific cross-toolchain and
95 matching sysroots (target and native) all built by the
96 OpenEmbedded build system (e.g. the SDK).
97 The toolchain and sysroots are based on a
98 <ulink url='&YOCTO_DOCS_REF_URL;#metadata'>Metadata</ulink>
99 configuration and extensions,
100 which allows you to cross-develop on the host machine for the
101 target hardware.
102 Additionally, the extensible SDK contains the
103 <filename>devtool</filename> functionality.
104 </para></listitem>
105 <listitem><para>
106 The Quick EMUlator (QEMU), which lets you simulate
107 target hardware.
108 QEMU is not literally part of the SDK.
109 You must build and include this emulator separately.
110 However, QEMU plays an important role in the development
111 process that revolves around use of the SDK.
112 </para></listitem>
113 </itemizedlist>
114 </para>
115
116 <para>
117 In summary, the extensible and standard SDK share many features.
118 However, the extensible SDK has powerful development tools to help you
119 more quickly develop applications.
120 Following is a table that summarizes the primary differences between
121 the standard and extensible SDK types when considering which to
122 build:
123 <informaltable frame='none'>
124 <tgroup cols='3' align='left' colsep='1' rowsep='1'>
125 <colspec colname='c1' colwidth='1*'/>
126 <colspec colname='c2' colwidth='1*'/>
127 <colspec colname='c3' colwidth='1*'/>
128 <thead>
129 <row>
130 <entry align="left"><emphasis>Feature</emphasis></entry>
131 <entry align="left"><emphasis>Standard SDK</emphasis></entry>
132 <entry align="left"><emphasis>Extensible SDK</emphasis></entry>
133 </row>
134 </thead>
135 <tbody>
136 <row>
137 <entry align="left">Toolchain</entry>
138 <entry align="left">Yes</entry>
139 <entry align="left">Yes*</entry>
140 </row>
141 <row>
142 <entry align="left">Debugger</entry>
143 <entry align="left">Yes</entry>
144 <entry align="left">Yes*</entry>
145 </row>
146 <row>
147 <entry align="left">Size</entry>
148 <entry align="left">100+ MBytes</entry>
149 <entry align="left">1+ GBytes (or 300+ MBytes for minimal w/toolchain)</entry>
150 </row>
151 <row>
152 <entry align="left"><filename>devtool</filename></entry>
153 <entry align="left">No</entry>
154 <entry align="left">Yes</entry>
155 </row>
156 <row>
157 <entry align="left">Build Images</entry>
158 <entry align="left">No</entry>
159 <entry align="left">Yes</entry>
160 </row>
161 <row>
162 <entry align="left">Updateable</entry>
163 <entry align="left">No</entry>
164 <entry align="left">Yes</entry>
165 </row>
166 <row>
167 <entry align="left">Managed Sysroot**</entry>
168 <entry align="left">No</entry>
169 <entry align="left">Yes</entry>
170 </row>
171 <row>
172 <entry align="left">Installed Packages</entry>
173 <entry align="left">No***</entry>
174 <entry align="left">Yes****</entry>
175 </row>
176 <row>
177 <entry align="left">Construction</entry>
178 <entry align="left">Packages</entry>
179 <entry align="left">Shared State</entry>
180 </row>
181 </tbody>
182 </tgroup>
183 </informaltable>
184 <literallayout class='monospaced'>
185 * Extensible SDK contains the toolchain and debugger if <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_EXT_TYPE'><filename>SDK_EXT_TYPE</filename></ulink> is "full" or <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_INCLUDE_TOOLCHAIN'><filename>SDK_INCLUDE_TOOLCHAIN</filename></ulink> is "1", which is the default.
186
187 ** Sysroot is managed through the use of <filename>devtool</filename>. Thus, it is less likely that you will corrupt your SDK sysroot when you try to add additional libraries.
188
189 *** You can add runtime package management to the standard SDK but it is not supported by default.
190
191 **** You must build and make the shared state available to extensible SDK users for "packages" you want to enable users to install.
192 </literallayout>
193 </para>
194
195 <section id='the-cross-development-toolchain'>
196 <title>The Cross-Development Toolchain</title>
197
198 <para>
199 The
200 <ulink url='&YOCTO_DOCS_REF_URL;#cross-development-toolchain'>Cross-Development Toolchain</ulink>
201 consists of a cross-compiler, cross-linker, and cross-debugger
202 that are used to develop user-space applications for targeted
203 hardware.
204 Additionally, for an extensible SDK, the toolchain also has
205 built-in <filename>devtool</filename> functionality.
206 This toolchain is created by running a SDK installer script
207 or through a
208 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
209 that is based on your metadata configuration or extension for
210 your targeted device.
211 The cross-toolchain works with a matching target sysroot.
212 </para>
213 </section>
214
215 <section id='sysroot'>
216 <title>Sysroots</title>
217
218 <para>
219 The native and target sysroots contain needed headers and libraries
220 for generating binaries that run on the target architecture.
221 The target sysroot is based on the target root filesystem image
222 that is built by the OpenEmbedded build system and uses the same
223 metadata configuration used to build the cross-toolchain.
224 </para>
225 </section>
226
227 <section id='the-qemu-emulator'>
228 <title>The QEMU Emulator</title>
229
230 <para>
231 The QEMU emulator allows you to simulate your hardware while
232 running your application or image.
233 QEMU is not part of the SDK but is made available a number of
234 different ways:
235 <itemizedlist>
236 <listitem><para>
237 If you have cloned the <filename>poky</filename> Git
238 repository to create a
239 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
240 and you have sourced the environment setup script, QEMU is
241 installed and automatically available.
242 </para></listitem>
243 <listitem><para>
244 If you have downloaded a Yocto Project release and unpacked
245 it to create a Source Directory and you have sourced the
246 environment setup script, QEMU is installed and
247 automatically available.
248 </para></listitem>
249 <listitem><para>
250 If you have installed the cross-toolchain tarball and you
251 have sourced the toolchain's setup environment script, QEMU
252 is also installed and automatically available.
253 </para></listitem>
254 </itemizedlist>
255 </para>
256 </section>
257</section>
258
259<section id='sdk-development-model'>
260 <title>SDK Development Model</title>
261
262 <para>
263 Fundamentally, the SDK fits into the development process as follows:
264 <imagedata fileref="figures/sdk-environment.png" align="center" width="6in" depth="5in" scalefit="100" />
265 The SDK is installed on any machine and can be used to develop
266 applications, images, and kernels.
267 An SDK can even be used by a QA Engineer or Release Engineer.
268 The fundamental concept is that the machine that has the SDK installed
269 does not have to be associated with the machine that has the
270 Yocto Project installed.
271 A developer can independently compile and test an object on their
272 machine and then, when the object is ready for integration into an
273 image, they can simply make it available to the machine that has the
274 Yocto Project.
275 Once the object is available, the image can be rebuilt using the
276 Yocto Project to produce the modified image.
277 </para>
278
279 <para>
280 You just need to follow these general steps:
281 <orderedlist>
282 <listitem><para>
283 <emphasis>Install the SDK for your target hardware:</emphasis>
284 For information on how to install the SDK, see the
285 "<link linkend='sdk-installing-the-sdk'>Installing the SDK</link>"
286 section.
287 </para></listitem>
288 <listitem><para>
289 <emphasis>Download or Build the Target Image:</emphasis>
290 The Yocto Project supports several target architectures
291 and has many pre-built kernel images and root filesystem
292 images.</para>
293
294 <para>If you are going to develop your application on
295 hardware, go to the
296 <ulink url='&YOCTO_MACHINES_DL_URL;'><filename>machines</filename></ulink>
297 download area and choose a target machine area
298 from which to download the kernel image and root filesystem.
299 This download area could have several files in it that
300 support development using actual hardware.
301 For example, the area might contain
302 <filename>.hddimg</filename> files that combine the
303 kernel image with the filesystem, boot loaders, and
304 so forth.
305 Be sure to get the files you need for your particular
306 development process.</para>
307
308 <para>If you are going to develop your application and
309 then run and test it using the QEMU emulator, go to the
310 <ulink url='&YOCTO_QEMU_DL_URL;'><filename>machines/qemu</filename></ulink>
311 download area.
312 From this area, go down into the directory for your
313 target architecture (e.g. <filename>qemux86_64</filename>
314 for an <trademark class='registered'>Intel</trademark>-based
315 64-bit architecture).
316 Download the kernel, root filesystem, and any other files you
317 need for your process.
318 <note>
319 To use the root filesystem in QEMU, you need to extract it.
320 See the
321 "<link linkend='sdk-extracting-the-root-filesystem'>Extracting the Root Filesystem</link>"
322 section for information on how to extract the root
323 filesystem.
324 </note>
325 </para></listitem>
326 <listitem><para>
327 <emphasis>Develop and Test your Application:</emphasis>
328 At this point, you have the tools to develop your application.
329 If you need to separately install and use the QEMU emulator,
330 you can go to
331 <ulink url='http://wiki.qemu.org/Main_Page'>QEMU Home Page</ulink>
332 to download and learn about the emulator.
333 See the
334 "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-manual-qemu'>Using the Quick EMUlator (QEMU)</ulink>"
335 chapter in the Yocto Project Development Tasks Manual
336 for information on using QEMU within the Yocto
337 Project.
338 </para></listitem>
339 </orderedlist>
340 </para>
341
342 <para>
343 The remainder of this manual describes how to use the extensible
344 and standard SDKs.
345 Information also exists in appendix form that describes how you can
346 build, install, and modify an SDK.
347 </para>
348</section>
349
350</chapter>
351<!--
352vim: expandtab tw=80 ts=4
353-->
diff --git a/documentation/sdk-manual/sdk-manual-customization.xsl b/documentation/sdk-manual/sdk-manual-customization.xsl
deleted file mode 100644
index 4f8816f950..0000000000
--- a/documentation/sdk-manual/sdk-manual-customization.xsl
+++ /dev/null
@@ -1,28 +0,0 @@
1<?xml version='1.0'?>
2<!--SPDX-License-Identifier: CC-BY-2.0-UK-->
3
4<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns="http://www.w3.org/1999/xhtml" xmlns:fo="http://www.w3.org/1999/XSL/Format" version="1.0">
5
6 <xsl:import href="http://downloads.yoctoproject.org/mirror/docbook-mirror/docbook-xsl-1.76.1/xhtml/docbook.xsl" />
7
8<!--
9 <xsl:import href="../template/1.76.1/docbook-xsl-1.76.1/xhtml/docbook.xsl" />
10
11 <xsl:import href="http://docbook.sourceforge.net/release/xsl/1.76.1/xhtml/docbook.xsl" />
12
13-->
14
15 <xsl:include href="../template/permalinks.xsl"/>
16 <xsl:include href="../template/section.title.xsl"/>
17 <xsl:include href="../template/component.title.xsl"/>
18 <xsl:include href="../template/division.title.xsl"/>
19 <xsl:include href="../template/formal.object.heading.xsl"/>
20
21 <xsl:param name="html.stylesheet" select="'sdk-style.css'" />
22 <xsl:param name="chapter.autolabel" select="1" />
23 <xsl:param name="appendix.autolabel">A</xsl:param>
24 <xsl:param name="section.autolabel" select="1" />
25 <xsl:param name="section.label.includes.component.label" select="1" />
26 <xsl:param name="generate.id.attributes" select="1" />
27
28</xsl:stylesheet>
diff --git a/documentation/sdk-manual/sdk-manual.xml b/documentation/sdk-manual/sdk-manual.xml
deleted file mode 100755
index 6344478fb0..0000000000
--- a/documentation/sdk-manual/sdk-manual.xml
+++ /dev/null
@@ -1,159 +0,0 @@
1<!DOCTYPE book 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<book id='sdk-manual' lang='en'
7 xmlns:xi="http://www.w3.org/2003/XInclude"
8 xmlns="http://docbook.org/ns/docbook"
9 >
10 <bookinfo>
11
12 <mediaobject>
13 <imageobject>
14 <imagedata fileref='figures/sdk-title.png'
15 format='SVG'
16 align='left' scalefit='1' width='100%'/>
17 </imageobject>
18 </mediaobject>
19
20 <title>
21 Yocto Project Application Development and the Extensible Software Development Kit (eSDK)
22 </title>
23
24 <authorgroup>
25 <author>
26 <affiliation>
27 <orgname>&ORGNAME;</orgname>
28 </affiliation>
29 <email>&ORGEMAIL;</email>
30 </author>
31 </authorgroup>
32
33 <revhistory>
34 <revision>
35 <revnumber>2.1</revnumber>
36 <date>April 2016</date>
37 <revremark>The initial document released with the Yocto Project 2.1 Release.</revremark>
38 </revision>
39 <revision>
40 <revnumber>2.2</revnumber>
41 <date>October 2016</date>
42 <revremark>Released with the Yocto Project 2.2 Release.</revremark>
43 </revision>
44 <revision>
45 <revnumber>2.3</revnumber>
46 <date>May 2017</date>
47 <revremark>Released with the Yocto Project 2.3 Release.</revremark>
48 </revision>
49 <revision>
50 <revnumber>2.4</revnumber>
51 <date>October 2017</date>
52 <revremark>Released with the Yocto Project 2.4 Release.</revremark>
53 </revision>
54 <revision>
55 <revnumber>2.5</revnumber>
56 <date>May 2018</date>
57 <revremark>Released with the Yocto Project 2.5 Release.</revremark>
58 </revision>
59 <revision>
60 <revnumber>2.6</revnumber>
61 <date>November 2018</date>
62 <revremark>Released with the Yocto Project 2.6 Release.</revremark>
63 </revision>
64 <revision>
65 <revnumber>2.7</revnumber>
66 <date>May 2019</date>
67 <revremark>Released with the Yocto Project 2.7 Release.</revremark>
68 </revision>
69 <revision>
70 <revnumber>3.0</revnumber>
71 <date>October 2019</date>
72 <revremark>Released with the Yocto Project 3.0 Release.</revremark>
73 </revision>
74 <revision>
75 <revnumber>3.1</revnumber>
76 <date>&REL_MONTH_YEAR;</date>
77 <revremark>Released with the Yocto Project 3.1 Release.</revremark>
78 </revision>
79 </revhistory>
80
81 <copyright>
82 <year>&COPYRIGHT_YEAR;</year>
83 <holder>Linux Foundation</holder>
84 </copyright>
85
86 <legalnotice>
87 <para>
88 Permission is granted to copy, distribute and/or modify this document under
89 the terms of the <ulink type="http" url="http://creativecommons.org/licenses/by-sa/2.0/uk/">Creative Commons Attribution-Share Alike 2.0 UK: England &amp; Wales</ulink> as published by Creative Commons.
90 </para>
91 <note><title>Manual Notes</title>
92 <itemizedlist>
93 <listitem><para>
94 This version of the
95 <emphasis>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</emphasis>
96 manual is for the &YOCTO_DOC_VERSION; release of the
97 Yocto Project.
98 To be sure you have the latest version of the manual
99 for this release, go to the
100 <ulink url='&YOCTO_DOCS_URL;'>Yocto Project documentation page</ulink>
101 and select the manual from that site.
102 Manuals from the site are more up-to-date than manuals
103 derived from the Yocto Project released TAR files.
104 </para></listitem>
105 <listitem><para>
106 If you located this manual through a web search, the
107 version of the manual might not be the one you want
108 (e.g. the search might have returned a manual much
109 older than the Yocto Project version with which you
110 are working).
111 You can see all Yocto Project major releases by
112 visiting the
113 <ulink url='&YOCTO_WIKI_URL;/wiki/Releases'>Releases</ulink>
114 page.
115 If you need a version of this manual for a different
116 Yocto Project release, visit the
117 <ulink url='&YOCTO_DOCS_URL;'>Yocto Project documentation page</ulink>
118 and select the manual set by using the
119 "ACTIVE RELEASES DOCUMENTATION" or "DOCUMENTS ARCHIVE"
120 pull-down menus.
121 </para></listitem>
122 <listitem>
123 <para>
124 To report any inaccuracies or problems with this
125 (or any other Yocto Project) manual, send an email to
126 the Yocto Project documentation mailing list at
127 <filename>docs@lists.yoctoproject.org</filename> or
128 log into the freenode <filename>#yocto</filename> channel.
129 </para>
130 </listitem>
131 </itemizedlist>
132 </note>
133 </legalnotice>
134
135 </bookinfo>
136
137 <xi:include href="sdk-intro.xml"/>
138
139 <xi:include href="sdk-extensible.xml"/>
140
141 <xi:include href="sdk-using.xml"/>
142
143 <xi:include href="sdk-working-projects.xml"/>
144
145 <xi:include href="sdk-appendix-obtain.xml"/>
146
147 <xi:include href="sdk-appendix-customizing.xml"/>
148
149 <xi:include href="sdk-appendix-customizing-standard.xml"/>
150
151<!-- <index id='index'>
152 <title>Index</title>
153 </index>
154-->
155
156</book>
157<!--
158vim: expandtab tw=80 ts=4
159-->
diff --git a/documentation/sdk-manual/sdk-style.css b/documentation/sdk-manual/sdk-style.css
deleted file mode 100644
index e0c4416a15..0000000000
--- a/documentation/sdk-manual/sdk-style.css
+++ /dev/null
@@ -1,991 +0,0 @@
1/*
2
3 SPDX-License-Identifier: CC-BY-2.0-UK
4
5 Generic XHTML / DocBook XHTML CSS Stylesheet.
6
7 Browser wrangling and typographic design by
8 Oyvind Kolas / pippin@gimp.org
9
10 Customised for Poky by
11 Matthew Allum / mallum@o-hand.com
12
13 Thanks to:
14 Liam R. E. Quin
15 William Skaggs
16 Jakub Steiner
17
18 Structure
19 ---------
20
21 The stylesheet is divided into the following sections:
22
23 Positioning
24 Margins, paddings, width, font-size, clearing.
25 Decorations
26 Borders, style
27 Colors
28 Colors
29 Graphics
30 Graphical backgrounds
31 Nasty IE tweaks
32 Workarounds needed to make it work in internet explorer,
33 currently makes the stylesheet non validating, but up until
34 this point it is validating.
35 Mozilla extensions
36 Transparency for footer
37 Rounded corners on boxes
38
39*/
40
41
42 /*************** /
43 / Positioning /
44/ ***************/
45
46body {
47 font-family: Verdana, Sans, sans-serif;
48
49 min-width: 640px;
50 width: 80%;
51 margin: 0em auto;
52 padding: 2em 5em 5em 5em;
53 color: #333;
54}
55
56h1,h2,h3,h4,h5,h6,h7 {
57 font-family: Arial, Sans;
58 color: #00557D;
59 clear: both;
60}
61
62h1 {
63 font-size: 2em;
64 text-align: left;
65 padding: 0em 0em 0em 0em;
66 margin: 2em 0em 0em 0em;
67}
68
69h2.subtitle {
70 margin: 0.10em 0em 3.0em 0em;
71 padding: 0em 0em 0em 0em;
72 font-size: 1.8em;
73 padding-left: 20%;
74 font-weight: normal;
75 font-style: italic;
76}
77
78h2 {
79 margin: 2em 0em 0.66em 0em;
80 padding: 0.5em 0em 0em 0em;
81 font-size: 1.5em;
82 font-weight: bold;
83}
84
85h3.subtitle {
86 margin: 0em 0em 1em 0em;
87 padding: 0em 0em 0em 0em;
88 font-size: 142.14%;
89 text-align: right;
90}
91
92h3 {
93 margin: 1em 0em 0.5em 0em;
94 padding: 1em 0em 0em 0em;
95 font-size: 140%;
96 font-weight: bold;
97}
98
99h4 {
100 margin: 1em 0em 0.5em 0em;
101 padding: 1em 0em 0em 0em;
102 font-size: 120%;
103 font-weight: bold;
104}
105
106h5 {
107 margin: 1em 0em 0.5em 0em;
108 padding: 1em 0em 0em 0em;
109 font-size: 110%;
110 font-weight: bold;
111}
112
113h6 {
114 margin: 1em 0em 0em 0em;
115 padding: 1em 0em 0em 0em;
116 font-size: 110%;
117 font-weight: bold;
118}
119
120.authorgroup {
121 background-color: transparent;
122 background-repeat: no-repeat;
123 padding-top: 256px;
124 background-image: url("figures/sdk-title.png");
125 background-position: left top;
126 margin-top: -256px;
127 padding-right: 50px;
128 margin-left: 0px;
129 text-align: right;
130 width: 740px;
131}
132
133h3.author {
134 margin: 0em 0me 0em 0em;
135 padding: 0em 0em 0em 0em;
136 font-weight: normal;
137 font-size: 100%;
138 color: #333;
139 clear: both;
140}
141
142.author tt.email {
143 font-size: 66%;
144}
145
146.titlepage hr {
147 width: 0em;
148 clear: both;
149}
150
151.revhistory {
152 padding-top: 2em;
153 clear: both;
154}
155
156.toc,
157.list-of-tables,
158.list-of-examples,
159.list-of-figures {
160 padding: 1.33em 0em 2.5em 0em;
161 color: #00557D;
162}
163
164.toc p,
165.list-of-tables p,
166.list-of-figures p,
167.list-of-examples p {
168 padding: 0em 0em 0em 0em;
169 padding: 0em 0em 0.3em;
170 margin: 1.5em 0em 0em 0em;
171}
172
173.toc p b,
174.list-of-tables p b,
175.list-of-figures p b,
176.list-of-examples p b{
177 font-size: 100.0%;
178 font-weight: bold;
179}
180
181.toc dl,
182.list-of-tables dl,
183.list-of-figures dl,
184.list-of-examples dl {
185 margin: 0em 0em 0.5em 0em;
186 padding: 0em 0em 0em 0em;
187}
188
189.toc dt {
190 margin: 0em 0em 0em 0em;
191 padding: 0em 0em 0em 0em;
192}
193
194.toc dd {
195 margin: 0em 0em 0em 2.6em;
196 padding: 0em 0em 0em 0em;
197}
198
199div.glossary dl,
200div.variablelist dl {
201}
202
203.glossary dl dt,
204.variablelist dl dt,
205.variablelist dl dt span.term {
206 font-weight: normal;
207 width: 20em;
208 text-align: right;
209}
210
211.variablelist dl dt {
212 margin-top: 0.5em;
213}
214
215.glossary dl dd,
216.variablelist dl dd {
217 margin-top: -1em;
218 margin-left: 25.5em;
219}
220
221.glossary dd p,
222.variablelist dd p {
223 margin-top: 0em;
224 margin-bottom: 1em;
225}
226
227
228div.calloutlist table td {
229 padding: 0em 0em 0em 0em;
230 margin: 0em 0em 0em 0em;
231}
232
233div.calloutlist table td p {
234 margin-top: 0em;
235 margin-bottom: 1em;
236}
237
238div p.copyright {
239 text-align: left;
240}
241
242div.legalnotice p.legalnotice-title {
243 margin-bottom: 0em;
244}
245
246p {
247 line-height: 1.5em;
248 margin-top: 0em;
249
250}
251
252dl {
253 padding-top: 0em;
254}
255
256hr {
257 border: solid 1px;
258}
259
260
261.mediaobject,
262.mediaobjectco {
263 text-align: center;
264}
265
266img {
267 border: none;
268}
269
270ul {
271 padding: 0em 0em 0em 1.5em;
272}
273
274ul li {
275 padding: 0em 0em 0em 0em;
276}
277
278ul li p {
279 text-align: left;
280}
281
282table {
283 width :100%;
284}
285
286th {
287 padding: 0.25em;
288 text-align: left;
289 font-weight: normal;
290 vertical-align: top;
291}
292
293td {
294 padding: 0.25em;
295 vertical-align: top;
296}
297
298p a[id] {
299 margin: 0px;
300 padding: 0px;
301 display: inline;
302 background-image: none;
303}
304
305a {
306 text-decoration: underline;
307 color: #444;
308}
309
310pre {
311 overflow: auto;
312}
313
314a:hover {
315 text-decoration: underline;
316 /*font-weight: bold;*/
317}
318
319/* This style defines how the permalink character
320 appears by itself and when hovered over with
321 the mouse. */
322
323[alt='Permalink'] { color: #eee; }
324[alt='Permalink']:hover { color: black; }
325
326
327div.informalfigure,
328div.informalexample,
329div.informaltable,
330div.figure,
331div.table,
332div.example {
333 margin: 1em 0em;
334 padding: 1em;
335 page-break-inside: avoid;
336}
337
338
339div.informalfigure p.title b,
340div.informalexample p.title b,
341div.informaltable p.title b,
342div.figure p.title b,
343div.example p.title b,
344div.table p.title b{
345 padding-top: 0em;
346 margin-top: 0em;
347 font-size: 100%;
348 font-weight: normal;
349}
350
351.mediaobject .caption,
352.mediaobject .caption p {
353 text-align: center;
354 font-size: 80%;
355 padding-top: 0.5em;
356 padding-bottom: 0.5em;
357}
358
359.epigraph {
360 padding-left: 55%;
361 margin-bottom: 1em;
362}
363
364.epigraph p {
365 text-align: left;
366}
367
368.epigraph .quote {
369 font-style: italic;
370}
371.epigraph .attribution {
372 font-style: normal;
373 text-align: right;
374}
375
376span.application {
377 font-style: italic;
378}
379
380.programlisting {
381 font-family: monospace;
382 font-size: 80%;
383 white-space: pre;
384 margin: 1.33em 0em;
385 padding: 1.33em;
386}
387
388.tip,
389.warning,
390.caution,
391.note {
392 margin-top: 1em;
393 margin-bottom: 1em;
394
395}
396
397/* force full width of table within div */
398.tip table,
399.warning table,
400.caution table,
401.note table {
402 border: none;
403 width: 100%;
404}
405
406
407.tip table th,
408.warning table th,
409.caution table th,
410.note table th {
411 padding: 0.8em 0.0em 0.0em 0.0em;
412 margin : 0em 0em 0em 0em;
413}
414
415.tip p,
416.warning p,
417.caution p,
418.note p {
419 margin-top: 0.5em;
420 margin-bottom: 0.5em;
421 padding-right: 1em;
422 text-align: left;
423}
424
425.acronym {
426 text-transform: uppercase;
427}
428
429b.keycap,
430.keycap {
431 padding: 0.09em 0.3em;
432 margin: 0em;
433}
434
435.itemizedlist li {
436 clear: none;
437}
438
439.filename {
440 font-size: medium;
441 font-family: Courier, monospace;
442}
443
444
445div.navheader, div.heading{
446 position: absolute;
447 left: 0em;
448 top: 0em;
449 width: 100%;
450 background-color: #cdf;
451 width: 100%;
452}
453
454div.navfooter, div.footing{
455 position: fixed;
456 left: 0em;
457 bottom: 0em;
458 background-color: #eee;
459 width: 100%;
460}
461
462
463div.navheader td,
464div.navfooter td {
465 font-size: 66%;
466}
467
468div.navheader table th {
469 /*font-family: Georgia, Times, serif;*/
470 /*font-size: x-large;*/
471 font-size: 80%;
472}
473
474div.navheader table {
475 border-left: 0em;
476 border-right: 0em;
477 border-top: 0em;
478 width: 100%;
479}
480
481div.navfooter table {
482 border-left: 0em;
483 border-right: 0em;
484 border-bottom: 0em;
485 width: 100%;
486}
487
488div.navheader table td a,
489div.navfooter table td a {
490 color: #777;
491 text-decoration: none;
492}
493
494/* normal text in the footer */
495div.navfooter table td {
496 color: black;
497}
498
499div.navheader table td a:visited,
500div.navfooter table td a:visited {
501 color: #444;
502}
503
504
505/* links in header and footer */
506div.navheader table td a:hover,
507div.navfooter table td a:hover {
508 text-decoration: underline;
509 background-color: transparent;
510 color: #33a;
511}
512
513div.navheader hr,
514div.navfooter hr {
515 display: none;
516}
517
518
519.qandaset tr.question td p {
520 margin: 0em 0em 1em 0em;
521 padding: 0em 0em 0em 0em;
522}
523
524.qandaset tr.answer td p {
525 margin: 0em 0em 1em 0em;
526 padding: 0em 0em 0em 0em;
527}
528.answer td {
529 padding-bottom: 1.5em;
530}
531
532.emphasis {
533 font-weight: bold;
534}
535
536
537 /************* /
538 / decorations /
539/ *************/
540
541.titlepage {
542}
543
544.part .title {
545}
546
547.subtitle {
548 border: none;
549}
550
551/*
552h1 {
553 border: none;
554}
555
556h2 {
557 border-top: solid 0.2em;
558 border-bottom: solid 0.06em;
559}
560
561h3 {
562 border-top: 0em;
563 border-bottom: solid 0.06em;
564}
565
566h4 {
567 border: 0em;
568 border-bottom: solid 0.06em;
569}
570
571h5 {
572 border: 0em;
573}
574*/
575
576.programlisting {
577 border: solid 1px;
578}
579
580div.figure,
581div.table,
582div.informalfigure,
583div.informaltable,
584div.informalexample,
585div.example {
586 border: 1px solid;
587}
588
589
590
591.tip,
592.warning,
593.caution,
594.note {
595 border: 1px solid;
596}
597
598.tip table th,
599.warning table th,
600.caution table th,
601.note table th {
602 border-bottom: 1px solid;
603}
604
605.question td {
606 border-top: 1px solid black;
607}
608
609.answer {
610}
611
612
613b.keycap,
614.keycap {
615 border: 1px solid;
616}
617
618
619div.navheader, div.heading{
620 border-bottom: 1px solid;
621}
622
623
624div.navfooter, div.footing{
625 border-top: 1px solid;
626}
627
628 /********* /
629 / colors /
630/ *********/
631
632body {
633 color: #333;
634 background: white;
635}
636
637a {
638 background: transparent;
639}
640
641a:hover {
642 background-color: #dedede;
643}
644
645
646h1,
647h2,
648h3,
649h4,
650h5,
651h6,
652h7,
653h8 {
654 background-color: transparent;
655}
656
657hr {
658 border-color: #aaa;
659}
660
661
662.tip, .warning, .caution, .note {
663 border-color: #fff;
664}
665
666
667.tip table th,
668.warning table th,
669.caution table th,
670.note table th {
671 border-bottom-color: #fff;
672}
673
674
675.warning {
676 background-color: #f0f0f2;
677}
678
679.caution {
680 background-color: #f0f0f2;
681}
682
683.tip {
684 background-color: #f0f0f2;
685}
686
687.note {
688 background-color: #f0f0f2;
689}
690
691.writernotes {
692 color: #ff0000;
693}
694
695.glossary dl dt,
696.variablelist dl dt,
697.variablelist dl dt span.term {
698 color: #044;
699}
700
701div.figure,
702div.table,
703div.example,
704div.informalfigure,
705div.informaltable,
706div.informalexample {
707 border-color: #aaa;
708}
709
710pre.programlisting {
711 color: black;
712 background-color: #fff;
713 border-color: #aaa;
714 border-width: 2px;
715}
716
717.guimenu,
718.guilabel,
719.guimenuitem {
720 background-color: #eee;
721}
722
723
724b.keycap,
725.keycap {
726 background-color: #eee;
727 border-color: #999;
728}
729
730
731div.navheader {
732 border-color: black;
733}
734
735
736div.navfooter {
737 border-color: black;
738}
739
740
741 /*********** /
742 / graphics /
743/ ***********/
744
745/*
746body {
747 background-image: url("images/body_bg.jpg");
748 background-attachment: fixed;
749}
750
751.navheader,
752.note,
753.tip {
754 background-image: url("images/note_bg.jpg");
755 background-attachment: fixed;
756}
757
758.warning,
759.caution {
760 background-image: url("images/warning_bg.jpg");
761 background-attachment: fixed;
762}
763
764.figure,
765.informalfigure,
766.example,
767.informalexample,
768.table,
769.informaltable {
770 background-image: url("images/figure_bg.jpg");
771 background-attachment: fixed;
772}
773
774*/
775h1,
776h2,
777h3,
778h4,
779h5,
780h6,
781h7{
782}
783
784/*
785Example of how to stick an image as part of the title.
786
787div.article .titlepage .title
788{
789 background-image: url("figures/white-on-black.png");
790 background-position: center;
791 background-repeat: repeat-x;
792}
793*/
794
795div.preface .titlepage .title,
796div.colophon .title,
797div.chapter .titlepage .title,
798div.article .titlepage .title
799{
800}
801
802div.section div.section .titlepage .title,
803div.sect2 .titlepage .title {
804 background: none;
805}
806
807
808h1.title {
809 background-color: transparent;
810 background-repeat: no-repeat;
811 height: 256px;
812 text-indent: -9000px;
813 overflow:hidden;
814}
815
816h2.subtitle {
817 background-color: transparent;
818 text-indent: -9000px;
819 overflow:hidden;
820 width: 0px;
821 display: none;
822}
823
824 /*************************************** /
825 / pippin.gimp.org specific alterations /
826/ ***************************************/
827
828/*
829div.heading, div.navheader {
830 color: #777;
831 font-size: 80%;
832 padding: 0;
833 margin: 0;
834 text-align: left;
835 position: absolute;
836 top: 0px;
837 left: 0px;
838 width: 100%;
839 height: 50px;
840 background: url('/gfx/heading_bg.png') transparent;
841 background-repeat: repeat-x;
842 background-attachment: fixed;
843 border: none;
844}
845
846div.heading a {
847 color: #444;
848}
849
850div.footing, div.navfooter {
851 border: none;
852 color: #ddd;
853 font-size: 80%;
854 text-align:right;
855
856 width: 100%;
857 padding-top: 10px;
858 position: absolute;
859 bottom: 0px;
860 left: 0px;
861
862 background: url('/gfx/footing_bg.png') transparent;
863}
864*/
865
866
867
868 /****************** /
869 / nasty ie tweaks /
870/ ******************/
871
872/*
873div.heading, div.navheader {
874 width:expression(document.body.clientWidth + "px");
875}
876
877div.footing, div.navfooter {
878 width:expression(document.body.clientWidth + "px");
879 margin-left:expression("-5em");
880}
881body {
882 padding:expression("4em 5em 0em 5em");
883}
884*/
885
886 /**************************************** /
887 / mozilla vendor specific css extensions /
888/ ****************************************/
889/*
890div.navfooter, div.footing{
891 -moz-opacity: 0.8em;
892}
893
894div.figure,
895div.table,
896div.informalfigure,
897div.informaltable,
898div.informalexample,
899div.example,
900.tip,
901.warning,
902.caution,
903.note {
904 -moz-border-radius: 0.5em;
905}
906
907b.keycap,
908.keycap {
909 -moz-border-radius: 0.3em;
910}
911*/
912
913table tr td table tr td {
914 display: none;
915}
916
917
918hr {
919 display: none;
920}
921
922table {
923 border: 0em;
924}
925
926 .photo {
927 float: right;
928 margin-left: 1.5em;
929 margin-bottom: 1.5em;
930 margin-top: 0em;
931 max-width: 17em;
932 border: 1px solid gray;
933 padding: 3px;
934 background: white;
935}
936 .seperator {
937 padding-top: 2em;
938 clear: both;
939 }
940
941 #validators {
942 margin-top: 5em;
943 text-align: right;
944 color: #777;
945 }
946 @media print {
947 body {
948 font-size: 8pt;
949 }
950 .noprint {
951 display: none;
952 }
953 }
954
955
956.tip,
957.note {
958 background: #f0f0f2;
959 color: #333;
960 padding: 20px;
961 margin: 20px;
962}
963
964.tip h3,
965.note h3 {
966 padding: 0em;
967 margin: 0em;
968 font-size: 2em;
969 font-weight: bold;
970 color: #333;
971}
972
973.tip a,
974.note a {
975 color: #333;
976 text-decoration: underline;
977}
978
979.footnote {
980 font-size: small;
981 color: #333;
982}
983
984/* Changes the announcement text */
985.tip h3,
986.warning h3,
987.caution h3,
988.note h3 {
989 font-size:large;
990 color: #00557D;
991}
diff --git a/documentation/sdk-manual/sdk-using.xml b/documentation/sdk-manual/sdk-using.xml
deleted file mode 100644
index 28ee50d0b7..0000000000
--- a/documentation/sdk-manual/sdk-using.xml
+++ /dev/null
@@ -1,201 +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<chapter id='sdk-using-the-standard-sdk'>
7 <title>Using the Standard SDK</title>
8
9 <para>
10 This chapter describes the standard SDK and how to install it.
11 Information includes unique installation and setup aspects for the
12 standard SDK.
13 <note>
14 For a side-by-side comparison of main features supported for a
15 standard SDK as compared to an extensible SDK, see the
16 "<link linkend='sdk-manual-intro'>Introduction</link>"
17 section.
18 </note>
19 </para>
20
21 <para>
22 You can use a standard SDK to work on Makefile and Autotools-based
23 projects.
24 See the
25 "<link linkend='sdk-working-projects'>Using the SDK Toolchain Directly</link>"
26 chapter for more information.
27 </para>
28
29 <section id='sdk-standard-sdk-intro'>
30 <title>Why use the Standard SDK and What is in It?</title>
31
32 <para>
33 The Standard SDK provides a cross-development toolchain and
34 libraries tailored to the contents of a specific image.
35 You would use the Standard SDK if you want a more traditional
36 toolchain experience as compared to the extensible SDK, which
37 provides an internal build system and the
38 <filename>devtool</filename> functionality.
39 </para>
40
41 <para>
42 The installed Standard SDK consists of several files and
43 directories.
44 Basically, it contains an SDK environment setup script, some
45 configuration files, and host and target root filesystems to
46 support usage.
47 You can see the directory structure in the
48 "<link linkend='sdk-installed-standard-sdk-directory-structure'>Installed Standard SDK Directory Structure</link>"
49 section.
50 </para>
51 </section>
52
53 <section id='sdk-installing-the-sdk'>
54 <title>Installing the SDK</title>
55
56 <para>
57 The first thing you need to do is install the SDK on your
58 <ulink url='&YOCTO_DOCS_REF_URL;#hardware-build-system-term'>Build Host</ulink>
59 by running the <filename>*.sh</filename> installation script.
60 </para>
61
62 <para>
63 You can download a tarball installer, which includes the
64 pre-built toolchain, the <filename>runqemu</filename>
65 script, and support files from the appropriate
66 <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'>toolchain</ulink>
67 directory within the Index of Releases.
68 Toolchains are available for several 32-bit and 64-bit
69 architectures with the <filename>x86_64</filename> directories,
70 respectively.
71 The toolchains the Yocto Project provides are based off the
72 <filename>core-image-sato</filename> and
73 <filename>core-image-minimal</filename> images and contain
74 libraries appropriate for developing against that image.
75 </para>
76
77 <para>
78 The names of the tarball installer scripts are such that a
79 string representing the host system appears first in the
80 filename and then is immediately followed by a string
81 representing the target architecture.
82 <literallayout class='monospaced'>
83 poky-glibc-<replaceable>host_system</replaceable>-<replaceable>image_type</replaceable>-<replaceable>arch</replaceable>-toolchain-<replaceable>release_version</replaceable>.sh
84
85 Where:
86 <replaceable>host_system</replaceable> is a string representing your development system:
87
88 i686 or x86_64.
89
90 <replaceable>image_type</replaceable> is the image for which the SDK was built:
91
92 core-image-minimal or core-image-sato.
93
94 <replaceable>arch</replaceable> is a string representing the tuned target architecture:
95
96 aarch64, armv5e, core2-64, i586, mips32r2, mips64, ppc7400, or cortexa8hf-neon.
97
98 <replaceable>release_version</replaceable> is a string representing the release number of the Yocto Project:
99
100 &DISTRO;, &DISTRO;+snapshot
101 </literallayout>
102 For example, the following SDK installer is for a 64-bit
103 development host system and a i586-tuned target architecture
104 based off the SDK for <filename>core-image-sato</filename> and
105 using the current &DISTRO; snapshot:
106 <literallayout class='monospaced'>
107 poky-glibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh
108 </literallayout>
109 <note>
110 As an alternative to downloading an SDK, you can build the
111 SDK installer.
112 For information on building the installer, see the
113 "<link linkend='sdk-building-an-sdk-installer'>Building an SDK Installer</link>"
114 section.
115 </note>
116 </para>
117
118 <para>
119 The SDK and toolchains are self-contained and by default are
120 installed into the <filename>poky_sdk</filename> folder in your
121 home directory.
122 You can choose to install the extensible SDK in any location when
123 you run the installer.
124 However, because files need to be written under that directory
125 during the normal course of operation, the location you choose
126 for installation must be writable for whichever
127 users need to use the SDK.
128 </para>
129
130 <para>
131 The following command shows how to run the installer given a
132 toolchain tarball for a 64-bit x86 development host system and
133 a 64-bit x86 target architecture.
134 The example assumes the SDK installer is located in
135 <filename>~/Downloads/</filename> and has execution rights.
136 <note>
137 If you do not have write permissions for the directory
138 into which you are installing the SDK, the installer
139 notifies you and exits.
140 For that case, set up the proper permissions in the directory
141 and run the installer again.
142 </note>
143 <literallayout class='monospaced'>
144 $ ./Downloads/poky-glibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh
145 Poky (Yocto Project Reference Distro) SDK installer version &DISTRO;
146 ===============================================================
147 Enter target directory for SDK (default: /opt/poky/&DISTRO;):
148 You are about to install the SDK to "/opt/poky/&DISTRO;". Proceed [Y/n]? Y
149 Extracting SDK........................................ ..............................done
150 Setting it up...done
151 SDK has been successfully set up and is ready to be used.
152 Each time you wish to use the SDK in a new shell session, you need to source the environment setup script e.g.
153 $ . /opt/poky/&DISTRO;/environment-setup-i586-poky-linux
154 </literallayout>
155 </para>
156
157 <para>
158 Again, reference the
159 "<link linkend='sdk-installed-standard-sdk-directory-structure'>Installed Standard SDK Directory Structure</link>"
160 section for more details on the resulting directory structure of
161 the installed SDK.
162 </para>
163 </section>
164
165 <section id='sdk-running-the-sdk-environment-setup-script'>
166 <title>Running the SDK Environment Setup Script</title>
167
168 <para>
169 Once you have the SDK installed, you must run the SDK environment
170 setup script before you can actually use the SDK.
171 This setup script resides in the directory you chose when you
172 installed the SDK, which is either the default
173 <filename>/opt/poky/&DISTRO;</filename> directory or the directory
174 you chose during installation.
175 </para>
176
177 <para>
178 Before running the script, be sure it is the one that matches the
179 architecture for which you are developing.
180 Environment setup scripts begin with the string
181 "<filename>environment-setup</filename>" and include as part of
182 their name the tuned target architecture.
183 As an example, the following commands set the working directory
184 to where the SDK was installed and then source the environment
185 setup script.
186 In this example, the setup script is for an IA-based
187 target machine using i586 tuning:
188 <literallayout class='monospaced'>
189 $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux
190 </literallayout>
191 When you run the setup script, the same environment variables are
192 defined as are when you run the setup script for an extensible SDK.
193 See the
194 "<link linkend='sdk-running-the-extensible-sdk-environment-setup-script'>Running the Extensible SDK Environment Setup Script</link>"
195 section for more information.
196 </para>
197 </section>
198</chapter>
199<!--
200vim: expandtab tw=80 ts=4
201-->
diff --git a/documentation/sdk-manual/sdk-working-projects.xml b/documentation/sdk-manual/sdk-working-projects.xml
deleted file mode 100644
index 070d903c73..0000000000
--- a/documentation/sdk-manual/sdk-working-projects.xml
+++ /dev/null
@@ -1,511 +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<chapter id='sdk-working-projects'>
7
8 <title>Using the SDK Toolchain Directly</title>
9
10 <para>
11 You can use the SDK toolchain directly with Makefile and
12 Autotools-based projects.
13 </para>
14
15 <section id='autotools-based-projects'>
16 <title>Autotools-Based Projects</title>
17
18 <para>
19 Once you have a suitable
20 <ulink url='&YOCTO_DOCS_REF_URL;#cross-development-toolchain'>cross-development toolchain</ulink>
21 installed, it is very easy to develop a project using the
22 <ulink url='https://en.wikipedia.org/wiki/GNU_Build_System'>GNU Autotools-based</ulink>
23 workflow, which is outside of the
24 <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>OpenEmbedded build system</ulink>.
25 </para>
26
27 <para>
28 The following figure presents a simple Autotools workflow.
29 <imagedata fileref="figures/sdk-autotools-flow.png" width="7in" height="8in" align="center" />
30 </para>
31
32 <para>
33 Follow these steps to create a simple Autotools-based
34 "Hello World" project:
35 <note>
36 For more information on the GNU Autotools workflow,
37 see the same example on the
38 <ulink url='https://developer.gnome.org/anjuta-build-tutorial/stable/create-autotools.html.en'>GNOME Developer</ulink>
39 site.
40 </note>
41 <orderedlist>
42 <listitem><para>
43 <emphasis>Create a Working Directory and Populate It:</emphasis>
44 Create a clean directory for your project and then make
45 that directory your working location.
46 <literallayout class='monospaced'>
47 $ mkdir $HOME/helloworld
48 $ cd $HOME/helloworld
49 </literallayout>
50 After setting up the directory, populate it with files
51 needed for the flow.
52 You need a project source file, a file to help with
53 configuration, and a file to help create the Makefile,
54 and a README file:
55 <filename>hello.c</filename>,
56 <filename>configure.ac</filename>,
57 <filename>Makefile.am</filename>, and
58 <filename>README</filename>, respectively.</para>
59
60 <para> Use the following command to create an empty README
61 file, which is required by GNU Coding Standards:
62 <literallayout class='monospaced'>
63 $ touch README
64 </literallayout>
65 Create the remaining three files as follows:
66 <itemizedlist>
67 <listitem><para>
68 <emphasis><filename>hello.c</filename>:</emphasis>
69 <literallayout class='monospaced'>
70 #include &lt;stdio.h&gt;
71
72 main()
73 {
74 printf("Hello World!\n");
75 }
76 </literallayout>
77 </para></listitem>
78 <listitem><para>
79 <emphasis><filename>configure.ac</filename>:</emphasis>
80 <literallayout class='monospaced'>
81 AC_INIT(hello,0.1)
82 AM_INIT_AUTOMAKE([foreign])
83 AC_PROG_CC
84 AC_CONFIG_FILES(Makefile)
85 AC_OUTPUT
86 </literallayout>
87 </para></listitem>
88 <listitem><para>
89 <emphasis><filename>Makefile.am</filename>:</emphasis>
90 <literallayout class='monospaced'>
91 bin_PROGRAMS = hello
92 hello_SOURCES = hello.c
93 </literallayout>
94 </para></listitem>
95 </itemizedlist>
96 </para></listitem>
97 <listitem><para>
98 <emphasis>Source the Cross-Toolchain
99 Environment Setup File:</emphasis>
100 As described earlier in the manual, installing the
101 cross-toolchain creates a cross-toolchain
102 environment setup script in the directory that the SDK
103 was installed.
104 Before you can use the tools to develop your project,
105 you must source this setup script.
106 The script begins with the string "environment-setup"
107 and contains the machine architecture, which is
108 followed by the string "poky-linux".
109 For this example, the command sources a script from the
110 default SDK installation directory that uses the
111 32-bit Intel x86 Architecture and the
112 &DISTRO_NAME; Yocto Project release:
113 <literallayout class='monospaced'>
114 $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux
115 </literallayout>
116 </para></listitem>
117 <listitem><para>
118 <emphasis>Create the <filename>configure</filename> Script:</emphasis>
119 Use the <filename>autoreconf</filename> command to
120 generate the <filename>configure</filename> script.
121 <literallayout class='monospaced'>
122 $ autoreconf
123 </literallayout>
124 The <filename>autoreconf</filename> tool takes care
125 of running the other Autotools such as
126 <filename>aclocal</filename>,
127 <filename>autoconf</filename>, and
128 <filename>automake</filename>.
129 <note>
130 If you get errors from
131 <filename>configure.ac</filename>, which
132 <filename>autoreconf</filename> runs, that indicate
133 missing files, you can use the "-i" option, which
134 ensures missing auxiliary files are copied to the build
135 host.
136 </note>
137 </para></listitem>
138 <listitem><para>
139 <emphasis>Cross-Compile the Project:</emphasis>
140 This command compiles the project using the
141 cross-compiler.
142 The
143 <ulink url='&YOCTO_DOCS_REF_URL;#var-CONFIGURE_FLAGS'><filename>CONFIGURE_FLAGS</filename></ulink>
144 environment variable provides the minimal arguments for
145 GNU configure:
146 <literallayout class='monospaced'>
147 $ ./configure ${CONFIGURE_FLAGS}
148 </literallayout>
149 For an Autotools-based project, you can use the
150 cross-toolchain by just passing the appropriate host
151 option to <filename>configure.sh</filename>.
152 The host option you use is derived from the name of the
153 environment setup script found in the directory in which
154 you installed the cross-toolchain.
155 For example, the host option for an ARM-based target that
156 uses the GNU EABI is
157 <filename>armv5te-poky-linux-gnueabi</filename>.
158 You will notice that the name of the script is
159 <filename>environment-setup-armv5te-poky-linux-gnueabi</filename>.
160 Thus, the following command works to update your project
161 and rebuild it using the appropriate cross-toolchain tools:
162 <literallayout class='monospaced'>
163 $ ./configure --host=armv5te-poky-linux-gnueabi --with-libtool-sysroot=<replaceable>sysroot_dir</replaceable>
164 </literallayout>
165 </para></listitem>
166 <listitem><para>
167 <emphasis>Make and Install the Project:</emphasis>
168 These two commands generate and install the project
169 into the destination directory:
170 <literallayout class='monospaced'>
171 $ make
172 $ make install DESTDIR=./tmp
173 </literallayout>
174 <note>
175 To learn about environment variables established
176 when you run the cross-toolchain environment setup
177 script and how they are used or overridden when
178 the Makefile, see the
179 "<link linkend='makefile-based-projects'>Makefile-Based Projects</link>"
180 section.
181 </note>
182 This next command is a simple way to verify the
183 installation of your project.
184 Running the command prints the architecture on which
185 the binary file can run.
186 This architecture should be the same architecture that
187 the installed cross-toolchain supports.
188 <literallayout class='monospaced'>
189 $ file ./tmp/usr/local/bin/hello
190 </literallayout>
191 </para></listitem>
192 <listitem><para>
193 <emphasis>Execute Your Project:</emphasis>
194 To execute the project, you would need to run it on your
195 target hardware.
196 If your target hardware happens to be your build host,
197 you could run the project as follows:
198 <literallayout class='monospaced'>
199 $ ./tmp/usr/local/bin/hello
200 </literallayout>
201 As expected, the project displays the "Hello World!"
202 message.
203 </para></listitem>
204 </orderedlist>
205 </para>
206 </section>
207
208 <section id='makefile-based-projects'>
209 <title>Makefile-Based Projects</title>
210
211 <para>
212 Simple Makefile-based projects use and interact with the
213 cross-toolchain environment variables established when you run
214 the cross-toolchain environment setup script.
215 The environment variables are subject to general
216 <filename>make</filename> rules.
217 </para>
218
219 <para>
220 This section presents a simple Makefile development flow and
221 provides an example that lets you see how you can use
222 cross-toolchain environment variables and Makefile variables
223 during development.
224 <imagedata fileref="figures/sdk-makefile-flow.png" width="6in" height="7in" align="center" />
225 </para>
226
227 <para>
228 The main point of this section is to explain the following three
229 cases regarding variable behavior:
230 <itemizedlist>
231 <listitem><para>
232 <emphasis>Case 1 - No Variables Set in the
233 <filename>Makefile</filename> Map to Equivalent
234 Environment Variables Set in the SDK Setup Script:</emphasis>
235 Because matching variables are not specifically set in the
236 <filename>Makefile</filename>, the variables retain their
237 values based on the environment setup script.
238 </para></listitem>
239 <listitem><para>
240 <emphasis>Case 2 - Variables Are Set in the Makefile that
241 Map to Equivalent Environment Variables from the SDK
242 Setup Script:</emphasis>
243 Specifically setting matching variables in the
244 <filename>Makefile</filename> during the build results in
245 the environment settings of the variables being
246 overwritten.
247 In this case, the variables you set in the
248 <filename>Makefile</filename> are used.
249 </para></listitem>
250 <listitem><para>
251 <emphasis>Case 3 - Variables Are Set Using the Command Line
252 that Map to Equivalent Environment Variables from the
253 SDK Setup Script:</emphasis>
254 Executing the <filename>Makefile</filename> from the
255 command line results in the environment variables being
256 overwritten.
257 In this case, the command-line content is used.
258 </para></listitem>
259 </itemizedlist>
260 <note>
261 Regardless of how you set your variables, if you use
262 the "-e" option with <filename>make</filename>, the
263 variables from the SDK setup script take precedence:
264 <literallayout class='monospaced'>
265 $ make -e <replaceable>target</replaceable>
266 </literallayout>
267 </note>
268 </para>
269
270 <para>
271 The remainder of this section presents a simple Makefile example
272 that demonstrates these variable behaviors.
273 </para>
274
275 <para>
276 In a new shell environment variables are not established for the
277 SDK until you run the setup script.
278 For example, the following commands show a null value for the
279 compiler variable (i.e.
280 <ulink url='&YOCTO_DOCS_REF_URL;#var-CC'><filename>CC</filename></ulink>).
281 <literallayout class='monospaced'>
282 $ echo ${CC}
283
284 $
285 </literallayout>
286 Running the SDK setup script for a 64-bit build host and an
287 i586-tuned target architecture for a
288 <filename>core-image-sato</filename> image using the current
289 &DISTRO; Yocto Project release and then echoing that variable
290 shows the value established through the script:
291 <literallayout class='monospaced'>
292 $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux
293 $ echo ${CC}
294 i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux
295 </literallayout>
296 </para>
297
298 <para>
299 To illustrate variable use, work through this simple "Hello World!"
300 example:
301 <orderedlist>
302 <listitem><para>
303 <emphasis>Create a Working Directory and Populate It:</emphasis>
304 Create a clean directory for your project and then make
305 that directory your working location.
306 <literallayout class='monospaced'>
307 $ mkdir $HOME/helloworld
308 $ cd $HOME/helloworld
309 </literallayout>
310 After setting up the directory, populate it with files
311 needed for the flow.
312 You need a <filename>main.c</filename> file from which you
313 call your function, a <filename>module.h</filename> file
314 to contain headers, and a <filename>module.c</filename>
315 that defines your function.
316 </para>
317
318 <para>Create the three files as follows:
319 <itemizedlist>
320 <listitem><para>
321 <emphasis><filename>main.c</filename>:</emphasis>
322 <literallayout class='monospaced'>
323 #include "module.h"
324 void sample_func();
325 int main()
326 {
327 sample_func();
328 return 0;
329 }
330 </literallayout>
331 </para></listitem>
332 <listitem><para>
333 <emphasis><filename>module.h</filename>:</emphasis>
334 <literallayout class='monospaced'>
335 #include &lt;stdio.h&gt;
336 void sample_func();
337 </literallayout>
338 </para></listitem>
339 <listitem><para>
340 <emphasis><filename>module.c</filename>:</emphasis>
341 <literallayout class='monospaced'>
342 #include "module.h"
343 void sample_func()
344 {
345 printf("Hello World!");
346 printf("\n");
347 }
348 </literallayout>
349 </para></listitem>
350 </itemizedlist>
351 </para></listitem>
352 <listitem><para>
353 <emphasis>Source the Cross-Toolchain Environment Setup File:</emphasis>
354 As described earlier in the manual, installing the
355 cross-toolchain creates a cross-toolchain environment setup
356 script in the directory that the SDK was installed.
357 Before you can use the tools to develop your project,
358 you must source this setup script.
359 The script begins with the string "environment-setup"
360 and contains the machine architecture, which is
361 followed by the string "poky-linux".
362 For this example, the command sources a script from the
363 default SDK installation directory that uses the
364 32-bit Intel x86 Architecture and the
365 &DISTRO_NAME; Yocto Project release:
366 <literallayout class='monospaced'>
367 $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux
368 </literallayout>
369 </para></listitem>
370 <listitem><para>
371 <emphasis>Create the <filename>Makefile</filename>:</emphasis>
372 For this example, the Makefile contains two lines that
373 can be used to set the <filename>CC</filename> variable.
374 One line is identical to the value that is set when you
375 run the SDK environment setup script, and the other line
376 sets <filename>CC</filename> to "gcc", the default GNU
377 compiler on the build host:
378 <literallayout class='monospaced'>
379 # CC=i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux
380 # CC="gcc"
381 all: main.o module.o
382 ${CC} main.o module.o -o target_bin
383 main.o: main.c module.h
384 ${CC} -I . -c main.c
385 module.o: module.c module.h
386 ${CC} -I . -c module.c
387 clean:
388 rm -rf *.o
389 rm target_bin
390 </literallayout>
391 </para></listitem>
392 <listitem><para>
393 <emphasis>Make the Project:</emphasis>
394 Use the <filename>make</filename> command to create the
395 binary output file.
396 Because variables are commented out in the Makefile,
397 the value used for <filename>CC</filename> is the value
398 set when the SDK environment setup file was run:
399 <literallayout class='monospaced'>
400 $ make
401 i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c main.c
402 i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c module.c
403 i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux main.o module.o -o target_bin
404 </literallayout>
405 From the results of the previous command, you can see that
406 the compiler used was the compiler established through
407 the <filename>CC</filename> variable defined in the
408 setup script.</para>
409
410 <para>You can override the <filename>CC</filename>
411 environment variable with the same variable as set from
412 the Makefile by uncommenting the line in the Makefile
413 and running <filename>make</filename> again.
414 <literallayout class='monospaced'>
415 $ make clean
416 rm -rf *.o
417 rm target_bin
418 #
419 # Edit the Makefile by uncommenting the line that sets CC to "gcc"
420 #
421 $ make
422 gcc -I . -c main.c
423 gcc -I . -c module.c
424 gcc main.o module.o -o target_bin
425 </literallayout>
426 As shown in the previous example, the cross-toolchain
427 compiler is not used.
428 Rather, the default compiler is used.</para>
429
430 <para>This next case shows how to override a variable
431 by providing the variable as part of the command line.
432 Go into the Makefile and re-insert the comment character
433 so that running <filename>make</filename> uses
434 the established SDK compiler.
435 However, when you run <filename>make</filename>, use a
436 command-line argument to set <filename>CC</filename>
437 to "gcc":
438 <literallayout class='monospaced'>
439 $ make clean
440 rm -rf *.o
441 rm target_bin
442 #
443 # Edit the Makefile to comment out the line setting CC to "gcc"
444 #
445 $ make
446 i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c main.c
447 i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c module.c
448 i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux main.o module.o -o target_bin
449 $ make clean
450 rm -rf *.o
451 rm target_bin
452 $ make CC="gcc"
453 gcc -I . -c main.c
454 gcc -I . -c module.c
455 gcc main.o module.o -o target_bin
456 </literallayout>
457 In the previous case, the command-line argument overrides
458 the SDK environment variable.</para>
459
460 <para>In this last case, edit Makefile again to use the
461 "gcc" compiler but then use the "-e" option on the
462 <filename>make</filename> command line:
463 <literallayout class='monospaced'>
464 $ make clean
465 rm -rf *.o
466 rm target_bin
467 #
468 # Edit the Makefile to use "gcc"
469 #
470 $ make
471 gcc -I . -c main.c
472 gcc -I . -c module.c
473 gcc main.o module.o -o target_bin
474 $ make clean
475 rm -rf *.o
476 rm target_bin
477 $ make -e
478 i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c main.c
479 i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c module.c
480 i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux main.o module.o -o target_bin
481 </literallayout>
482 In the previous case, the "-e" option forces
483 <filename>make</filename> to use the SDK environment
484 variables regardless of the values in the Makefile.
485 </para></listitem>
486 <listitem><para>
487 <emphasis>Execute Your Project:</emphasis>
488 To execute the project (i.e.
489 <filename>target_bin</filename>), use the following
490 command:
491 <literallayout class='monospaced'>
492 $ ./target_bin
493 Hello World!
494 </literallayout>
495 <note>
496 If you used the cross-toolchain compiler to build
497 <filename>target_bin</filename> and your build host
498 differs in architecture from that of the target
499 machine, you need to run your project on the target
500 device.
501 </note>
502 As expected, the project displays the "Hello World!"
503 message.
504 </para></listitem>
505 </orderedlist>
506 </para>
507 </section>
508</chapter>
509<!--
510vim: expandtab tw=80 ts=4
511-->
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-06-11 12:09:09 +0000