summaryrefslogtreecommitdiffstats
path: root/documentation/sdk-manual/sdk-extensible.xml
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/sdk-manual/sdk-extensible.xml')
-rw-r--r--documentation/sdk-manual/sdk-extensible.xml2866
1 files changed, 1489 insertions, 1377 deletions
diff --git a/documentation/sdk-manual/sdk-extensible.xml b/documentation/sdk-manual/sdk-extensible.xml
index 73b317f5c8..8c568a739e 100644
--- a/documentation/sdk-manual/sdk-extensible.xml
+++ b/documentation/sdk-manual/sdk-extensible.xml
@@ -4,1516 +4,1628 @@
4 4
5<chapter id='sdk-extensible'> 5<chapter id='sdk-extensible'>
6 6
7<title>Using the Extensible SDK</title> 7 <title>Using the Extensible SDK</title>
8
9<para>
10 This chapter describes the extensible SDK and how to use it.
11 The extensible SDK makes it easy to add new applications and libraries
12 to an image, modify the source for an existing component, test
13 changes on the target hardware, and ease integration into the rest of the
14 <ulink url='&YOCTO_DOCS_DEV_URL;#build-system-term'>OpenEmbedded build system</ulink>.
15</para>
16
17<para>
18 Information in this chapter covers features that are not part of the
19 standard SDK.
20 In other words, the chapter presents information unique to the
21 extensible SDK only.
22 For information on how to use the standard SDK, see the
23 "<link linkend='sdk-using-the-standard-sdk'>Using the Standard SDK</link>"
24 chapter.
25</para>
26
27<section id='sdk-setting-up-to-use-the-extensible-sdk'>
28 <title>Setting Up to Use the Extensible SDK</title>
29 8
30 <para> 9 <para>
31 Getting set up to use the extensible SDK is identical to getting set 10 This chapter describes the extensible SDK and how to install it.
32 up to use the standard SDK. 11 Information covers the pieces of the SDK, how to install it, and
33 You still need to locate and run the installer and then run the 12 presents a look at using the <filename>devtool</filename>
34 environment setup script. 13 functionality.
35 See the 14 The extensible SDK makes it easy to add new applications and libraries
36 "<link linkend='sdk-installing-the-sdk'>Installing the SDK</link>" 15 to an image, modify the source for an existing component, test
37 and the 16 changes on the target hardware, and ease integration into the rest of
38 "<link linkend='sdk-running-the-sdk-environment-setup-script'>Running the SDK Environment Setup Script</link>" 17 the
39 sections for general information. 18 <ulink url='&YOCTO_DOCS_DEV_URL;#build-system-term'>OpenEmbedded build system</ulink>.
40 The following items highlight the only differences between getting
41 set up to use the extensible SDK as compared to the standard SDK:
42 <itemizedlist>
43 <listitem><para><emphasis>Default Installation Directory:</emphasis>
44 By default, the extensible SDK installs into the
45 <filename>poky_sdk</filename> folder of your home directory.
46 As with the standard SDK, you can choose to install the
47 extensible SDK in any location when you run the installer.
48 However, unlike the standard SDK, the location you choose needs
49 to be writable for whichever users need to use the SDK,
50 since files will need to be written under that directory during
51 the normal course of operation.
52 </para></listitem>
53 <listitem><para><emphasis>Build Tools and Build System:</emphasis>
54 The extensible SDK installer performs additional tasks as
55 compared to the standard SDK installer.
56 to the SDK and the installer also prepares the internal build
57 system within the SDK.
58 You can find pre-built extensible SDK installers in the same
59 <ulink url='http://downloads.yoctoproject.org/releases/yocto/yocto-&DISTRO;/toolchain/'>toolchain</ulink>
60 location as the pre-built standard SDK installers.
61 For extensible SDK installers, the
62 <filename>ext</filename> string is part of the name.
63 Here is an example:
64 <literallayout class='monospaced'>
65 poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-&DISTRO;.sh
66 </literallayout>
67 <note>
68 As an alternative to downloading an SDK, you can build the toolchain
69 installer.
70 For information on building the installer, see the
71 "<link linkend='sdk-building-an-sdk-installer'>Building an SDK Installer</link>"
72 section.
73 Another helpful resource for building an installer is the
74 <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>Cookbook guide to Making an Eclipse Debug Capable Image</ulink>
75 wiki page.
76 </note>
77 Here is example output for running the extensible SDK
78 installer:
79 <literallayout class='monospaced'>
80 $ ./poky-glibc-x86_64-core-image-minimal-core2-64-toolchain-ext-&DISTRO;.sh
81 Poky (Yocto Project Reference Distro) Extensible SDK installer version &DISTRO;
82 ===================================================================================
83 Enter target directory for SDK (default: ~/poky_sdk):
84 You are about to install the SDK to "/home/scottrif/poky_sdk". Proceed[Y/n]? Y
85 Extracting SDK......................................................................done
86 Setting it up...
87 Extracting buildtools...
88 Preparing build system...
89 done
90 SDK has been successfully set up and is ready to be used.
91 Each time you wish to use the SDK in a new shell session, you need to source the environment setup script e.g.
92 $ . /home/scottrif/poky_sdk/environment-setup-core2-64-poky-linux
93 </literallayout>
94 </para></listitem>
95 </itemizedlist>
96 </para>
97
98 <para>
99 After installing the SDK, you need to run the SDK environment setup
100 script.
101 Here is the output from an example run:
102 <literallayout class='monospaced'>
103 $ cd /home/scottrif/poky_sdk
104 $ source environment-setup-core2-64-poky-linux
105 SDK environment now set up; additionally you may now run devtool to perform development tasks.
106 Run devtool --help for further details.
107 </literallayout>
108 Once you run the environment setup script, you have
109 <filename>devtool</filename> available.
110 </para>
111</section>
112
113<section id='using-devtool-in-your-sdk-workflow'>
114 <title>Using <filename>devtool</filename> in Your SDK Workflow</title>
115
116 <para>
117 The cornerstone of the extensible SDK is a command-line tool
118 called <filename>devtool</filename>.
119 This tool provides a number of features that help
120 you build, test and package software within the extensible SDK, and
121 optionally integrate it into an image built by the OpenEmbedded build
122 system.
123 </para>
124
125 <para>
126 The <filename>devtool</filename> command line is organized similarly
127 to
128 <ulink url='&YOCTO_DOCS_DEV_URL;#git'>Git</ulink> in that it has a
129 number of sub-commands for each function.
130 You can run <filename>devtool --help</filename> to see all the
131 commands.
132 <note> 19 <note>
133 See the 20 For a side-by-side comparison of main features supported for an
134 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-devtool-reference'><filename>devtool</filename>&nbsp;Quick Reference</ulink>" 21 extensible SDK as compared to a standard SDK, see the
135 in the Yocto Project Reference Manual for more a 22 "<link linkend='sdk-manual-intro'>Introduction</link>"
136 <filename>devtool</filename> reference. 23 section.
137 </note> 24 </note>
138 </para> 25 </para>
139 26
140 <para> 27 <para>
141 Two <filename>devtool</filename> subcommands that provide 28 You can use an extensible SDK to work on Makefile, Autotools, and
142 entry-points into development are: 29 Eclipse-based projects.
143 <itemizedlist> 30 See the
144 <listitem><para><emphasis><filename>devtool add</filename></emphasis>: 31 "<link linkend='sdk-working-projects'>Working with Different Types of Projects</link>"
145 Assists in adding new software to be built. 32 chapter for more information.
146 </para></listitem>
147 <listitem><para><emphasis><filename>devtool modify</filename></emphasis>:
148 Sets up an environment to enable you to modify the source of
149 an existing component.
150 </para></listitem>
151 </itemizedlist>
152 As with the OpenEmbedded build system, "recipes" represent software
153 packages within <filename>devtool</filename>.
154 When you use <filename>devtool add</filename>, a recipe is
155 automatically created.
156 When you use <filename>devtool modify</filename>, the specified
157 existing recipe is used in order to determine where to get the source
158 code and how to patch it.
159 In both cases, an environment is set up so that when you build the
160 recipe a source tree that is under your control is used in order to
161 allow you to make changes to the source as desired.
162 By default, both new recipes and the source go into a "workspace"
163 directory under the SDK.
164 </para>
165
166 <para>
167 The remainder of this section presents the
168 <filename>devtool add</filename> and
169 <filename>devtool modify</filename> workflows.
170 </para> 33 </para>
171 34
172 <section id='sdk-use-devtool-to-add-an-application'> 35 <section id='sdk-extensible-sdk-intro'>
173 <title>Use <filename>devtool add</filename> to Add an Application</title> 36 <title>Why use the Extensible SDK and What is in It?</title>
174
175 <para>
176 The <filename>devtool add</filename> command generates
177 a new recipe based on existing source code.
178 This command takes advantage of the
179 <ulink url='&YOCTO_DOCS_DEV_URL;#devtool-the-workspace-layer-structure'>workspace</ulink>
180 layer that many <filename>devtool</filename> commands
181 use.
182 The command is flexible enough to allow you to extract source
183 code into both the workspace or a separate local Git repository
184 and to use existing code that does not need to be extracted.
185 </para>
186 37
187 <para> 38 <para>
188 Depending on your particular scenario, the arguments and options 39 The extensible SDK provides a cross-development toolchain and
189 you use with <filename>devtool add</filename> form different 40 libraries tailored to the contents of a specific image.
190 combinations. 41 You would use the Extensible SDK if you want a toolchain experience
191 The following diagram shows common development flows 42 supplemented with the powerful set of <filename>devtool</filename>
192 you would use with the <filename>devtool add</filename> 43 commands tailored for the Yocto Project environment.
193 command:
194 </para> 44 </para>
195 45
196 <para> 46 <para>
197 <imagedata fileref="figures/sdk-devtool-add-flow.png" align="center" /> 47 The installed extensible SDK consists of several files and
198 </para> 48 directories.
199 49 Basically, it contains an SDK environment setup script, some
200 <para> 50 configuration files, an internal build system, and the
201 <orderedlist> 51 <filename>devtool</filename> functionality.
202 <listitem><para><emphasis>Generating the New Recipe</emphasis>:
203 The top part of the flow shows three scenarios by which
204 you could use <filename>devtool add</filename> to
205 generate a recipe based on existing source code.</para>
206
207 <para>In a shared development environment, it is
208 typical where other developers are responsible for
209 various areas of source code.
210 As a developer, you are probably interested in using
211 that source code as part of your development using
212 the Yocto Project.
213 All you need is access to the code, a recipe, and a
214 controlled area in which to do your work.</para>
215
216 <para>Within the diagram, three possible scenarios
217 feed into the <filename>devtool add</filename> workflow:
218 <itemizedlist>
219 <listitem><para><emphasis>Left</emphasis>:
220 The left scenario represents a common situation
221 where the source code does not exist locally
222 and needs to be extracted.
223 In this situation, you just let it get
224 extracted to the default workspace - you do not
225 want it in some specific location outside of the
226 workspace.
227 Thus, everything you need will be located in the
228 workspace:
229 <literallayout class='monospaced'>
230 $ devtool add <replaceable>recipe fetchuri</replaceable>
231 </literallayout>
232 With this command, <filename>devtool</filename>
233 creates a recipe and an append file in the
234 workspace as well as extracts the upstream
235 source files into a local Git repository also
236 within the <filename>sources</filename> folder.
237 </para></listitem>
238 <listitem><para><emphasis>Middle</emphasis>:
239 The middle scenario also represents a situation where
240 the source code does not exist locally.
241 In this case, the code is again upstream
242 and needs to be extracted to some
243 local area - this time outside of the default
244 workspace.
245 If required, <filename>devtool</filename>
246 always creates
247 a Git repository locally during the extraction.
248 Furthermore, the first positional argument
249 <replaceable>srctree</replaceable> in this case
250 identifies where the
251 <filename>devtool add</filename> command
252 will locate the extracted code outside of the
253 workspace:
254 <literallayout class='monospaced'>
255 $ devtool add <replaceable>recipe srctree fetchuri</replaceable>
256 </literallayout>
257 In summary, the source code is pulled from
258 <replaceable>fetchuri</replaceable> and extracted
259 into the location defined by
260 <replaceable>srctree</replaceable> as a local
261 Git repository.</para>
262
263 <para>Within workspace, <filename>devtool</filename>
264 creates both the recipe and an append file
265 for the recipe.
266 </para></listitem>
267 <listitem><para><emphasis>Right</emphasis>:
268 The right scenario represents a situation
269 where the source tree (srctree) has been
270 previously prepared outside of the
271 <filename>devtool</filename> workspace.
272 </para>
273
274 <para>The following command names the recipe
275 and identifies where the existing source tree
276 is located:
277 <literallayout class='monospaced'>
278 $ devtool add <replaceable>recipe srctree</replaceable>
279 </literallayout>
280 The command examines the source code and creates
281 a recipe for it placing the recipe into the
282 workspace.</para>
283
284 <para>Because the extracted source code already exists,
285 <filename>devtool</filename> does not try to
286 relocate it into the workspace - just the new
287 the recipe is placed in the workspace.</para>
288
289 <para>Aside from a recipe folder, the command
290 also creates an append folder and places an initial
291 <filename>*.bbappend</filename> within.
292 </para></listitem>
293 </itemizedlist>
294 </para></listitem>
295 <listitem><para><emphasis>Edit the Recipe</emphasis>:
296 At this point, you can use <filename>devtool edit-recipe</filename>
297 to open up the editor as defined by the
298 <filename>$EDITOR</filename> environment variable
299 and modify the file:
300 <literallayout class='monospaced'>
301 $ devtool edit-recipe <replaceable>recipe</replaceable>
302 </literallayout>
303 From within the editor, you can make modifications to the
304 recipe that take affect when you build it later.
305 </para></listitem>
306 <listitem><para><emphasis>Build the Recipe or Rebuild the Image</emphasis>:
307 At this point in the flow, the next step you
308 take depends on what you are going to do with
309 the new code.</para>
310 <para>If you need to take the build output and eventually
311 move it to the target hardware, you would use
312 <filename>devtool build</filename>:
313 <literallayout class='monospaced'>
314 $ devtool build <replaceable>recipe</replaceable>
315 </literallayout></para>
316 <para>On the other hand, if you want an image to
317 contain the recipe's packages for immediate deployment
318 onto a device (e.g. for testing purposes), you can use
319 the <filename>devtool build-image</filename> command:
320 <literallayout class='monospaced'>
321 $ devtool build-image <replaceable>image</replaceable>
322 </literallayout>
323 </para></listitem>
324 <listitem><para><emphasis>Deploy the Build Output</emphasis>:
325 When you use the <filename>devtool build</filename>
326 command to build out your recipe, you probably want to
327 see if the resulting build output works as expected on target
328 hardware.
329 <note>
330 This step assumes you have a previously built
331 image that is already either running in QEMU or
332 running on actual hardware.
333 Also, it is assumed that for deployment of the image
334 to the target, SSH is installed in the image and if
335 the image is running on real hardware that you have
336 network access to and from your development machine.
337 </note>
338 You can deploy your build output to that target hardware by
339 using the <filename>devtool deploy-target</filename> command:
340 <literallayout class='monospaced'>
341 $ devtool deploy-target <replaceable>recipe target</replaceable>
342 </literallayout>
343 The <replaceable>target</replaceable> is a live target machine
344 running as an SSH server.</para>
345
346 <para>You can, of course, also deploy the image you build
347 using the <filename>devtool build-image</filename> command
348 to actual hardware.
349 However, <filename>devtool</filename> does not provide a
350 specific command that allows you to do this.
351 </para></listitem>
352 <listitem><para>
353 <emphasis>Finish Your Work With the Recipe</emphasis>:
354 The <filename>devtool finish</filename> command creates
355 any patches corresponding to commits in the local
356 Git repository, moves the new recipe to a more permanent
357 layer, and then resets the recipe so that the recipe is
358 built normally rather than from the workspace.
359 <literallayout class='monospaced'>
360 $ devtool finish <replaceable>recipe layer</replaceable>
361 </literallayout>
362 <note>
363 Any changes you want to turn into patches must be
364 committed to the Git repository in the source tree.
365 </note></para>
366
367 <para>As mentioned, the <filename>devtool finish</filename>
368 command moves the final recipe to its permanent layer.
369 </para>
370
371 <para>As a final process of the
372 <filename>devtool finish</filename> command, the state
373 of the standard layers and the upstream source is
374 restored so that you can build the recipe from those
375 areas rather than the workspace.
376 <note>
377 You can use the <filename>devtool reset</filename>
378 command to put things back should you decide you
379 do not want to proceed with your work.
380 If you do use this command, realize that the source
381 tree is preserved.
382 </note>
383 </para></listitem>
384 </orderedlist>
385 </para> 52 </para>
386 </section> 53 </section>
387 54
388 <section id='sdk-devtool-use-devtool-modify-to-modify-the-source-of-an-existing-component'> 55 <section id='sdk-setting-up-to-use-the-extensible-sdk'>
389 <title>Use <filename>devtool modify</filename> to Modify the Source of an Existing Component</title> 56 <title>Setting Up to Use the Extensible SDK</title>
390 57
391 <para> 58 <para>
392 The <filename>devtool modify</filename> command prepares the 59 The first thing you need to do is install the SDK on your host
393 way to work on existing code that already has a recipe in 60 development machine by running the <filename>*.sh</filename>
394 place. 61 installation script.
395 The command is flexible enough to allow you to extract code,
396 specify the existing recipe, and keep track of and gather any
397 patch files from other developers that are
398 associated with the code.
399 </para> 62 </para>
400 63
401 <para> 64 <para>
402 Depending on your particular scenario, the arguments and options 65 You can download a tarball installer, which includes the
403 you use with <filename>devtool modify</filename> form different 66 pre-built toolchain, the <filename>runqemu</filename>
404 combinations. 67 script, the internal build system, <filename>devtool</filename>,
405 The following diagram shows common development flows 68 and support files from the appropriate directory under
406 you would use with the <filename>devtool modify</filename> 69 <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'></ulink>.
407 command: 70 Toolchains are available for 32-bit and 64-bit x86 development
71 systems from the <filename>i686</filename> and
72 <filename>x86_64</filename> directories, respectively.
73 The toolchains the Yocto Project provides are based off the
74 <filename>core-image-sato</filename> image and contain
75 libraries appropriate for developing against that image.
76 Each type of development system supports five or more target
77 architectures.
408 </para> 78 </para>
409 79
410 <para> 80 <para>
411 <imagedata fileref="figures/sdk-devtool-modify-flow.png" align="center" /> 81 The names of the tarball installer scripts are such that a
412 </para> 82 string representing the host system appears first in the
83 filename and then is immediately followed by a string
84 representing the target architecture.
85 An extensible SDK has the string "-ext" as part of the name.
86 <literallayout class='monospaced'>
87 poky-glibc-<replaceable>host_system</replaceable>-<replaceable>image_type</replaceable>-<replaceable>arch</replaceable>-toolchain-ext-<replaceable>release_version</replaceable>.sh
413 88
414 <para> 89 Where:
415 <orderedlist> 90 <replaceable>host_system</replaceable> is a string representing your development system:
416 <listitem><para><emphasis>Preparing to Modify the Code</emphasis>:
417 The top part of the flow shows three scenarios by which
418 you could use <filename>devtool modify</filename> to
419 prepare to work on source files.
420 Each scenario assumes the following:
421 <itemizedlist>
422 <listitem><para>The recipe exists in some layer external
423 to the <filename>devtool</filename> workspace.
424 </para></listitem>
425 <listitem><para>The source files exist upstream in an
426 un-extracted state or locally in a previously
427 extracted state.
428 </para></listitem>
429 </itemizedlist>
430 The typical situation is where another developer has
431 created some layer for use with the Yocto Project and
432 their recipe already resides in that layer.
433 Furthermore, their source code is readily available
434 either upstream or locally.
435 <itemizedlist>
436 <listitem><para><emphasis>Left</emphasis>:
437 The left scenario represents a common situation
438 where the source code does not exist locally
439 and needs to be extracted.
440 In this situation, the source is extracted
441 into the default workspace location.
442 The recipe, in this scenario, is in its own
443 layer outside the workspace
444 (i.e.
445 <filename>meta-</filename><replaceable>layername</replaceable>).
446 </para>
447
448 <para>The following command identifies the recipe
449 and by default extracts the source files:
450 <literallayout class='monospaced'>
451 $ devtool modify <replaceable>recipe</replaceable>
452 </literallayout>
453 Once <filename>devtool</filename>locates the recipe,
454 it uses the
455 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
456 variable to locate the source code and
457 any local patch files from other developers are
458 located.
459 <note>
460 You cannot provide an URL for
461 <replaceable>srctree</replaceable> when using the
462 <filename>devtool modify</filename> command.
463 </note>
464 With this scenario, however, since no
465 <replaceable>srctree</replaceable> argument exists, the
466 <filename>devtool modify</filename> command by default
467 extracts the source files to a Git structure.
468 Furthermore, the location for the extracted source is the
469 default area within the workspace.
470 The result is that the command sets up both the source
471 code and an append file within the workspace with the
472 recipe remaining in its original location.
473 </para></listitem>
474 <listitem><para><emphasis>Middle</emphasis>:
475 The middle scenario represents a situation where
476 the source code also does not exist locally.
477 In this case, the code is again upstream
478 and needs to be extracted to some
479 local area as a Git repository.
480 The recipe, in this scenario, is again in its own
481 layer outside the workspace.</para>
482
483 <para>The following command tells
484 <filename>devtool</filename> what recipe with
485 which to work and, in this case, identifies a local
486 area for the extracted source files that is outside
487 of the default workspace:
488 <literallayout class='monospaced'>
489 $ devtool modify <replaceable>recipe srctree</replaceable>
490 </literallayout>
491 As with all extractions, the command uses
492 the recipe's <filename>SRC_URI</filename> to locate the
493 source files.
494 Once the files are located, the command by default
495 extracts them.
496 Providing the <replaceable>srctree</replaceable>
497 argument instructs <filename>devtool</filename> where
498 place the extracted source.</para>
499
500 <para>Within workspace, <filename>devtool</filename>
501 creates an append file for the recipe.
502 The recipe remains in its original location but
503 the source files are extracted to the location you
504 provided with <replaceable>srctree</replaceable>.
505 </para></listitem>
506 <listitem><para><emphasis>Right</emphasis>:
507 The right scenario represents a situation
508 where the source tree
509 (<replaceable>srctree</replaceable>) exists as a
510 previously extracted Git structure outside of
511 the <filename>devtool</filename> workspace.
512 In this example, the recipe also exists
513 elsewhere in its own layer.
514 </para>
515
516 <para>The following command tells
517 <filename>devtool</filename> the recipe
518 with which to work, uses the "-n" option to indicate
519 source does not need to be extracted, and uses
520 <replaceable>srctree</replaceable> to point to the
521 previously extracted source files:
522 <literallayout class='monospaced'>
523 $ devtool modify -n <replaceable>recipe srctree</replaceable>
524 </literallayout>
525 </para>
526 91
527 <para>Once the command finishes, it creates only 92 i686 or x86_64.
528 an append file for the recipe in the workspace.
529 The recipe and the source code remain in their
530 original locations.
531 </para></listitem>
532 </itemizedlist>
533 </para></listitem>
534 <listitem><para><emphasis>Edit the Source</emphasis>:
535 Once you have used the <filename>devtool modify</filename>
536 command, you are free to make changes to the source
537 files.
538 You can use any editor you like to make and save
539 your source code modifications.
540 </para></listitem>
541 <listitem><para><emphasis>Build the Recipe</emphasis>:
542 Once you have updated the source files, you can build
543 the recipe.
544 </para></listitem>
545 <listitem><para><emphasis>Deploy the Build Output</emphasis>:
546 When you use the <filename>devtool build</filename>
547 command to build out your recipe, you probably want to see
548 if the resulting build output works as expected on target
549 hardware.
550 <note>
551 This step assumes you have a previously built
552 image that is already either running in QEMU or
553 running on actual hardware.
554 Also, it is assumed that for deployment of the image
555 to the target, SSH is installed in the image and if
556 the image is running on real hardware that you have
557 network access to and from your development machine.
558 </note>
559 You can deploy your build output to that target hardware by
560 using the <filename>devtool deploy-target</filename> command:
561 <literallayout class='monospaced'>
562 $ devtool deploy-target <replaceable>recipe target</replaceable>
563 </literallayout>
564 The <replaceable>target</replaceable> is a live target machine
565 running as an SSH server.</para>
566
567 <para>You can, of course, also deploy the image you build
568 using the <filename>devtool build-image</filename> command
569 to actual hardware.
570 However, <filename>devtool</filename> does not provide a
571 specific command that allows you to do this.
572 </para></listitem>
573 <listitem><para>
574 <emphasis>Finish Your Work With the Recipe</emphasis>:
575 The <filename>devtool finish</filename> command creates
576 any patches corresponding to commits in the local
577 Git repository, updates the recipe to point to them
578 (or creates a <filename>.bbappend</filename> file to do
579 so, depending on the specified destination layer), and
580 then resets the recipe so that the recipe is built normally
581 rather than from the workspace.
582 <literallayout class='monospaced'>
583 $ devtool finish <replaceable>recipe layer</replaceable>
584 </literallayout>
585 <note>
586 Any changes you want to turn into patches must be
587 committed to the Git repository in the source tree.
588 </note></para>
589
590 <para>Because there is no need to move the recipe,
591 <filename>devtool finish</filename> either updates the
592 original recipe in the original layer or the command
593 creates a <filename>.bbappend</filename> in a different
594 layer as provided by <replaceable>layer</replaceable>.
595 </para>
596
597 <para>As a final process of the
598 <filename>devtool finish</filename> command, the state
599 of the standard layers and the upstream source is
600 restored so that you can build the recipe from those
601 areas rather than the workspace.
602 <note>
603 You can use the <filename>devtool reset</filename>
604 command to put things back should you decide you
605 do not want to proceed with your work.
606 If you do use this command, realize that the source
607 tree is preserved.
608 </note>
609 </para></listitem>
610 </orderedlist>
611 </para>
612 </section>
613 93
614 <section id='sdk-devtool-use-devtool-upgrade-to-create-a-version-of-the-recipe-that-supports-a-newer-version-of-the-software'> 94 <replaceable>image_type</replaceable> is the image for which the SDK was built.
615 <title>Use <filename>devtool upgrade</filename> to Create a Version of the Recipe that Supports a Newer Version of the Software</title>
616 95
617 <para> 96 <replaceable>arch</replaceable> is a string representing the tuned target architecture:
618 The <filename>devtool upgrade</filename> command updates
619 an existing recipe so that you can build it for an updated
620 set of source files.
621 The command is flexible enough to allow you to specify
622 source code revision and versioning schemes, extract code into
623 or out of the <filename>devtool</filename> workspace, and
624 work with any source file forms that the fetchers support.
625 </para>
626 97
627 <para> 98 i586, x86_64, powerpc, mips, armv7a or armv5te
628 Depending on your particular scenario, the arguments and options 99
629 you use with <filename>devtool upgrade</filename> form different 100 <replaceable>release_version</replaceable> is a string representing the release number of the
630 combinations. 101 Yocto Project:
631 The following diagram shows a common development flow 102
632 you would use with the <filename>devtool modify</filename> 103 &DISTRO;, &DISTRO;+snapshot
633 command: 104 </literallayout>
105 For example, the following toolchain installer is for a 64-bit
106 development host system and a i586-tuned target architecture
107 based off the SDK for <filename>core-image-sato</filename> and
108 using the current &DISTRO; snapshot:
109 <literallayout class='monospaced'>
110 poky-glibc-x86_64-core-image-sato-i586-toolchain-ext-&DISTRO;.sh
111 </literallayout>
112 <note>
113 As an alternative to downloading an SDK, you can build the
114 toolchain installer.
115 For information on building the installer, see the
116 "<link linkend='sdk-building-an-sdk-installer'>Building an SDK Installer</link>"
117 section.
118 Another helpful resource for building an installer is the
119 <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>Cookbook guide to Making an Eclipse Debug Capable Image</ulink>
120 wiki page.
121 This wiki page focuses on development when using the Eclipse
122 IDE.
123 </note>
634 </para> 124 </para>
635 125
636 <para> 126 <para>
637 <imagedata fileref="figures/sdk-devtool-upgrade-flow.png" align="center" /> 127 The SDK and toolchains are self-contained and by default are
128 installed into the <filename>poky_sdk</filename> folder in your
129 home directory.
130 You can choose to install the extensible SDK in any location when
131 you run the installer.
132 However, the location you choose needs to be writable for whichever
133 users need to use the SDK, since files will need to be written
134 under that directory during the normal course of operation.
638 </para> 135 </para>
639 136
640 <para> 137 <para>
641 <orderedlist> 138 The following command shows how to run the installer given a
642 <listitem><para><emphasis>Initiate the Upgrade</emphasis>: 139 toolchain tarball for a 64-bit x86 development host system and
643 The top part of the flow shows a typical scenario by which 140 a 64-bit x86 target architecture.
644 you could use <filename>devtool upgrade</filename>. 141 The example assumes the toolchain installer is located in
645 The following conditions exist: 142 <filename>~/Downloads/</filename>.
646 <itemizedlist> 143 <note>
647 <listitem><para>The recipe exists in some layer external 144 If you do not have write permissions for the directory
648 to the <filename>devtool</filename> workspace. 145 into which you are installing the SDK, the installer
649 </para></listitem> 146 notifies you and exits.
650 <listitem><para>The source files for the new release 147 Be sure you have write permissions in the directory and
651 exist adjacent to the same location pointed to by 148 run the installer again.
652 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> 149 </note>
653 in the recipe (e.g. a tarball with the new version 150 <literallayout class='monospaced'>
654 number in the name, or as a different revision in 151 $ ./poky-glibc-x86_64-core-image-minimal-core2-64-toolchain-ext-&DISTRO;.sh
655 the upstream Git repository). 152 Poky (Yocto Project Reference Distro) Extensible SDK installer version &DISTRO;
656 </para></listitem> 153 ===================================================================================
657 </itemizedlist> 154 Enter target directory for SDK (default: ~/poky_sdk):
658 A common situation is where third-party software has 155 You are about to install the SDK to "/home/scottrif/poky_sdk". Proceed[Y/n]? Y
659 undergone a revision so that it has been upgraded. 156 Extracting SDK......................................................................done
660 The recipe you have access to is likely in your own layer. 157 Setting it up...
661 Thus, you need to upgrade the recipe to use the 158 Extracting buildtools...
662 newer version of the software: 159 Preparing build system...
663 <literallayout class='monospaced'> 160 done
664 $ devtool upgrade -V <replaceable>version recipe</replaceable> 161 SDK has been successfully set up and is ready to be used.
665 </literallayout> 162 Each time you wish to use the SDK in a new shell session, you need to source the environment setup script e.g.
666 By default, the <filename>devtool upgrade</filename> command 163 $ . /home/scottrif/poky_sdk/environment-setup-core2-64-poky-linux
667 extracts source code into the <filename>sources</filename> 164 </literallayout>
668 directory in the workspace.
669 If you want the code extracted to any other location, you
670 need to provide the <replaceable>srctree</replaceable>
671 positional argument with the command as follows:
672 <literallayout class='monospaced'>
673 $ devtool upgrade -V <replaceable>version recipe srctree</replaceable>
674 </literallayout>
675 Also, in this example, the "-V" option is used to specify
676 the new version.
677 If the source files pointed to by the
678 <filename>SRC_URI</filename> statement in the recipe are
679 in a Git repository, you must provide the "-S" option and
680 specify a revision for the software.</para>
681
682 <para>Once <filename>devtool</filename> locates the recipe,
683 it uses the <filename>SRC_URI</filename> variable to locate
684 the source code and any local patch files from other
685 developers are located.
686 The result is that the command sets up the source
687 code, the new version of the recipe, and an append file
688 all within the workspace.
689 </para></listitem>
690 <listitem><para><emphasis>Resolve any Conflicts created by the Upgrade</emphasis>:
691 At this point, there could be some conflicts due to the
692 software being upgraded to a new version.
693 This would occur if your recipe specifies some patch files in
694 <filename>SRC_URI</filename> that conflict with changes
695 made in the new version of the software.
696 If this is the case, you need to resolve the conflicts
697 by editing the source and following the normal
698 <filename>git rebase</filename> conflict resolution
699 process.</para>
700 <para>Before moving onto the next step, be sure to resolve any
701 such conflicts created through use of a newer or different
702 version of the software.
703 </para></listitem>
704 <listitem><para><emphasis>Build the Recipe</emphasis>:
705 Once you have your recipe in order, you can build it.
706 You can either use <filename>devtool build</filename> or
707 <filename>bitbake</filename>.
708 Either method produces build output that is stored
709 in
710 <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>.
711 </para></listitem>
712 <listitem><para><emphasis>Deploy the Build Output</emphasis>:
713 When you use the <filename>devtool build</filename>
714 command or <filename>bitbake</filename> to build out your
715 recipe, you probably want to see if the resulting build
716 output works as expected on target hardware.
717 <note>
718 This step assumes you have a previously built
719 image that is already either running in QEMU or
720 running on actual hardware.
721 Also, it is assumed that for deployment of the image
722 to the target, SSH is installed in the image and if
723 the image is running on real hardware that you have
724 network access to and from your development machine.
725 </note>
726 You can deploy your build output to that target hardware by
727 using the <filename>devtool deploy-target</filename> command:
728 <literallayout class='monospaced'>
729 $ devtool deploy-target <replaceable>recipe target</replaceable>
730 </literallayout>
731 The <replaceable>target</replaceable> is a live target machine
732 running as an SSH server.</para>
733 <para>You can, of course, also deploy the image you build
734 using the <filename>devtool build-image</filename> command
735 to actual hardware.
736 However, <filename>devtool</filename> does not provide a
737 specific command that allows you to do this.
738 </para></listitem>
739 <listitem><para>
740 <emphasis>Finish Your Work With the Recipe</emphasis>:
741 The <filename>devtool finish</filename> command creates
742 any patches corresponding to commits in the local
743 Git repository, updates the recipe to point to them
744 (or creates a <filename>.bbappend</filename> file to do
745 so, depending on the specified destination layer), and
746 then resets the recipe so that the recipe is built normally
747 rather than from the workspace.
748 <literallayout class='monospaced'>
749 $ devtool finish <replaceable>recipe layer</replaceable>
750 </literallayout>
751 <note>
752 Any changes you want to turn into patches must be
753 committed to the Git repository in the source tree.
754 </note></para>
755 <para>Because there is no need to move the recipe,
756 <filename>devtool finish</filename> either updates the
757 original recipe in the original layer or the command
758 creates a <filename>.bbappend</filename> in a different
759 layer as provided by <replaceable>layer</replaceable>.
760 </para>
761 <para>As a final process of the
762 <filename>devtool finish</filename> command, the state
763 of the standard layers and the upstream source is
764 restored so that you can build the recipe from those
765 areas rather than the workspace.
766 <note>
767 You can use the <filename>devtool reset</filename>
768 command to put things back should you decide you
769 do not want to proceed with your work.
770 If you do use this command, realize that the source
771 tree is preserved.
772 </note>
773 </para></listitem>
774 </orderedlist>
775 </para> 165 </para>
776 </section> 166 </section>
777</section>
778
779<section id='sdk-a-closer-look-at-devtool-add'>
780 <title>A Closer Look at <filename>devtool add</filename></title>
781 167
782 <para> 168 <section id='sdk-running-the-extensible-sdk-environment-setup-script'>
783 The <filename>devtool add</filename> command automatically creates a 169 <title>Running the Extensible SDK Environment Setup Script</title>
784 recipe based on the source tree with which you provide it.
785 Currently, the command has support for the following:
786 <itemizedlist>
787 <listitem><para>
788 Autotools (<filename>autoconf</filename> and
789 <filename>automake</filename>)
790 </para></listitem>
791 <listitem><para>
792 CMake
793 </para></listitem>
794 <listitem><para>
795 Scons
796 </para></listitem>
797 <listitem><para>
798 <filename>qmake</filename>
799 </para></listitem>
800 <listitem><para>
801 Plain <filename>Makefile</filename>
802 </para></listitem>
803 <listitem><para>
804 Out-of-tree kernel module
805 </para></listitem>
806 <listitem><para>
807 Binary package (i.e. "-b" option)
808 </para></listitem>
809 <listitem><para>
810 Node.js module
811 </para></listitem>
812 <listitem><para>
813 Python modules that use <filename>setuptools</filename>
814 or <filename>distutils</filename>
815 </para></listitem>
816 </itemizedlist>
817 </para>
818
819 <para>
820 Apart from binary packages, the determination of how a source tree
821 should be treated is automatic based on the files present within
822 that source tree.
823 For example, if a <filename>CMakeLists.txt</filename> file is found,
824 then the source tree is assumed to be using
825 CMake and is treated accordingly.
826 <note>
827 In most cases, you need to edit the automatically generated
828 recipe in order to make it build properly.
829 Typically, you would go through several edit and build cycles
830 until you can build the recipe.
831 Once the recipe can be built, you could use possible further
832 iterations to test the recipe on the target device.
833 </note>
834 </para>
835
836 <para>
837 The remainder of this section covers specifics regarding how parts
838 of the recipe are generated.
839 </para>
840
841 <section id='sdk-name-and-version'>
842 <title>Name and Version</title>
843 170
844 <para> 171 <para>
845 If you do not specify a name and version on the command 172 Once you have the SDK installed, you must run the SDK environment
846 line, <filename>devtool add</filename> attempts to determine 173 setup script before you can actually use it.
847 the name and version of the software being built from 174 This setup script resides in the directory you chose when you
848 various metadata within the source tree. 175 installed the SDK, which is either the default
849 Furthermore, the command sets the name of the created recipe 176 <filename>poky_sdk</filename> directory or the directory you
850 file accordingly. 177 chose during installation.
851 If the name or version cannot be determined, the
852 <filename>devtool add</filename> command prints an error and
853 you must re-run the command with both the name and version
854 or just the name or version specified.
855 </para> 178 </para>
856 179
857 <para> 180 <para>
858 Sometimes the name or version determined from the source tree 181 Before running the script, be sure it is the one that matches the
859 might be incorrect. 182 architecture for which you are developing.
860 For such a case, you must reset the recipe: 183 Environment setup scripts begin with the string
184 "<filename>environment-setup</filename>" and include as part of
185 their name the tuned target architecture.
186 As an example, the following commands set the working directory
187 to where the SDK was installed and then source the environment
188 setup script.
189 In this example, the setup script is for an IA-based
190 target machine using i586 tuning:
861 <literallayout class='monospaced'> 191 <literallayout class='monospaced'>
862 $ devtool reset -n <replaceable>recipename</replaceable> 192 $ cd /home/scottrif/poky_sdk
193 $ source environment-setup-core2-64-poky-linux
194 SDK environment now set up; additionally you may now run devtool to perform development tasks.
195 Run devtool --help for further details.
196 </literallayout>
197 When you run the setup script, many environment variables are
198 defined:
199 <literallayout class='monospaced'>
200 <ulink url='&YOCTO_DOCS_REF_URL;#var-SDKTARGETSYSROOT'><filename>SDKTARGETSYSROOT</filename></ulink> - The path to the sysroot used for cross-compilation
201 <ulink url='&YOCTO_DOCS_REF_URL;#var-PKG_CONFIG_PATH'><filename>PKG_CONFIG_PATH</filename></ulink> - The path to the target pkg-config files
202 <ulink url='&YOCTO_DOCS_REF_URL;#var-CONFIG_SITE'><filename>CONFIG_SITE</filename></ulink> - A GNU autoconf site file preconfigured for the target
203 <ulink url='&YOCTO_DOCS_REF_URL;#var-CC'><filename>CC</filename></ulink> - The minimal command and arguments to run the C compiler
204 <ulink url='&YOCTO_DOCS_REF_URL;#var-CXX'><filename>CXX</filename></ulink> - The minimal command and arguments to run the C++ compiler
205 <ulink url='&YOCTO_DOCS_REF_URL;#var-CPP'><filename>CPP</filename></ulink> - The minimal command and arguments to run the C preprocessor
206 <ulink url='&YOCTO_DOCS_REF_URL;#var-AS'><filename>AS</filename></ulink> - The minimal command and arguments to run the assembler
207 <ulink url='&YOCTO_DOCS_REF_URL;#var-LD'><filename>LD</filename></ulink> - The minimal command and arguments to run the linker
208 <ulink url='&YOCTO_DOCS_REF_URL;#var-GDB'><filename>GDB</filename></ulink> - The minimal command and arguments to run the GNU Debugger
209 <ulink url='&YOCTO_DOCS_REF_URL;#var-STRIP'><filename>STRIP</filename></ulink> - The minimal command and arguments to run 'strip', which strips symbols
210 <ulink url='&YOCTO_DOCS_REF_URL;#var-RANLIB'><filename>RANLIB</filename></ulink> - The minimal command and arguments to run 'ranlib'
211 <ulink url='&YOCTO_DOCS_REF_URL;#var-OBJCOPY'><filename>OBJCOPY</filename></ulink> - The minimal command and arguments to run 'objcopy'
212 <ulink url='&YOCTO_DOCS_REF_URL;#var-OBJDUMP'><filename>OBJDUMP</filename></ulink> - The minimal command and arguments to run 'objdump'
213 <ulink url='&YOCTO_DOCS_REF_URL;#var-AR'><filename>AR</filename></ulink> - The minimal command and arguments to run 'ar'
214 <ulink url='&YOCTO_DOCS_REF_URL;#var-NM'><filename>NM</filename></ulink> - The minimal command and arguments to run 'nm'
215 <ulink url='&YOCTO_DOCS_REF_URL;#var-TARGET_PREFIX'><filename>TARGET_PREFIX</filename></ulink> - The toolchain binary prefix for the target tools
216 <ulink url='&YOCTO_DOCS_REF_URL;#var-CROSS_COMPILE'><filename>CROSS_COMPILE</filename></ulink> - The toolchain binary prefix for the target tools
217 <ulink url='&YOCTO_DOCS_REF_URL;#var-CONFIGURE_FLAGS'><filename>CONFIGURE_FLAGS</filename></ulink> - The minimal arguments for GNU configure
218 <ulink url='&YOCTO_DOCS_REF_URL;#var-CFLAGS'><filename>CFLAGS</filename></ulink> - Suggested C flags
219 <ulink url='&YOCTO_DOCS_REF_URL;#var-CXXFLAGS'><filename>CXXFLAGS</filename></ulink> - Suggested C++ flags
220 <ulink url='&YOCTO_DOCS_REF_URL;#var-LDFLAGS'><filename>LDFLAGS</filename></ulink> - Suggested linker flags when you use CC to link
221 <ulink url='&YOCTO_DOCS_REF_URL;#var-CPPFLAGS'><filename>CPPFLAGS</filename></ulink> - Suggested preprocessor flags
863 </literallayout> 222 </literallayout>
864 After running the <filename>devtool reset</filename> command,
865 you need to run <filename>devtool add</filename> again and
866 provide the name or the version.
867 </para> 223 </para>
868 </section> 224 </section>
869 225
870 <section id='sdk-dependency-detection-and-mapping'> 226 <section id='using-devtool-in-your-sdk-workflow'>
871 <title>Dependency Detection and Mapping</title> 227 <title>Using <filename>devtool</filename> in Your SDK Workflow</title>
872 228
873 <para> 229 <para>
874 The <filename>devtool add</filename> command attempts to 230 The cornerstone of the extensible SDK is a command-line tool
875 detect build-time dependencies and map them to other recipes 231 called <filename>devtool</filename>.
876 in the system. 232 This tool provides a number of features that help
877 During this mapping, the command fills in the names of those 233 you build, test and package software within the extensible SDK, and
878 recipes in the 234 optionally integrate it into an image built by the OpenEmbedded build
879 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink> 235 system.
880 value within the recipe.
881 If a dependency cannot be mapped, then a comment is placed in
882 the recipe indicating such.
883 The inability to map a dependency might be caused because the
884 naming is not recognized or because the dependency simply is
885 not available.
886 For cases where the dependency is not available, you must use
887 the <filename>devtool add</filename> command to add an
888 additional recipe to satisfy the dependency and then come
889 back to the first recipe and add its name to
890 <filename>DEPENDS</filename>.
891 </para> 236 </para>
892 237
893 <para> 238 <para>
894 If you need to add runtime dependencies, you can do so by 239 The <filename>devtool</filename> command line is organized similarly
895 adding the following to your recipe: 240 to
896 <literallayout class='monospaced'> 241 <ulink url='&YOCTO_DOCS_DEV_URL;#git'>Git</ulink> in that it has a
897 RDEPENDS_${PN} += "dependency1 dependency2 ..." 242 number of sub-commands for each function.
898 </literallayout> 243 You can run <filename>devtool --help</filename> to see all the
244 commands.
899 <note> 245 <note>
900 The <filename>devtool add</filename> command often cannot 246 See the
901 distinguish between mandatory and optional dependencies. 247 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-devtool-reference'><filename>devtool</filename>&nbsp;Quick Reference</ulink>"
902 Consequently, some of the detected dependencies might 248 in the Yocto Project Reference Manual for more a
903 in fact be optional. 249 <filename>devtool</filename> reference.
904 When in doubt, consult the documentation or the configure
905 script for the software the recipe is building for further
906 details.
907 In some cases, you might find you can substitute the
908 dependency for an option to disable the associated
909 functionality passed to the configure script.
910 </note> 250 </note>
911 </para> 251 </para>
912 </section>
913
914 <section id='sdk-license-detection'>
915 <title>License Detection</title>
916 252
917 <para> 253 <para>
918 The <filename>devtool add</filename> command attempts to 254 Two <filename>devtool</filename> subcommands that provide
919 determine if the software you are adding is able to be 255 entry-points into development are:
920 distributed under a common open-source license and sets the 256 <itemizedlist>
921 <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE'><filename>LICENSE</filename></ulink> 257 <listitem><para><emphasis><filename>devtool add</filename></emphasis>:
922 value accordingly. 258 Assists in adding new software to be built.
923 You should double-check this value against the documentation 259 </para></listitem>
924 or source files for the software you are building and update 260 <listitem><para><emphasis><filename>devtool modify</filename></emphasis>:
925 that <filename>LICENSE</filename> value if necessary. 261 Sets up an environment to enable you to modify the source of
262 an existing component.
263 </para></listitem>
264 </itemizedlist>
265 As with the OpenEmbedded build system, "recipes" represent software
266 packages within <filename>devtool</filename>.
267 When you use <filename>devtool add</filename>, a recipe is
268 automatically created.
269 When you use <filename>devtool modify</filename>, the specified
270 existing recipe is used in order to determine where to get the source
271 code and how to patch it.
272 In both cases, an environment is set up so that when you build the
273 recipe a source tree that is under your control is used in order to
274 allow you to make changes to the source as desired.
275 By default, both new recipes and the source go into a "workspace"
276 directory under the SDK.
926 </para> 277 </para>
927 278
928 <para> 279 <para>
929 The <filename>devtool add</filename> command also sets the 280 The remainder of this section presents the
930 <ulink url='&YOCTO_DOCS_REF_URL;#var-LIC_FILES_CHKSUM'><filename>LIC_FILES_CHKSUM</filename></ulink> 281 <filename>devtool add</filename> and
931 value to point to all files that appear to be license-related. 282 <filename>devtool modify</filename> workflows.
932 However, license statements often appear in comments at the top
933 of source files or within documentation.
934 Consequently, you might need to amend the
935 <filename>LIC_FILES_CHKSUM</filename> variable to point to one
936 or more of those comments if present.
937 Setting <filename>LIC_FILES_CHKSUM</filename> is particularly
938 important for third-party software.
939 The mechanism attempts to ensure correct licensing should you
940 upgrade the recipe to a newer upstream version in future.
941 Any change in licensing is detected and you receive an error
942 prompting you to check the license text again.
943 </para> 283 </para>
944 284
945 <para> 285 <section id='sdk-use-devtool-to-add-an-application'>
946 If the <filename>devtool add</filename> command cannot 286 <title>Use <filename>devtool add</filename> to Add an Application</title>
947 determine licensing information, the 287
948 <filename>LICENSE</filename> value is set to "CLOSED" and the 288 <para>
949 <filename>LIC_FILES_CHKSUM</filename> value remains unset. 289 The <filename>devtool add</filename> command generates
950 This behavior allows you to continue with development but is 290 a new recipe based on existing source code.
951 unlikely to be correct in all cases. 291 This command takes advantage of the
952 Consequently, you should check the documentation or source 292 <ulink url='&YOCTO_DOCS_DEV_URL;#devtool-the-workspace-layer-structure'>workspace</ulink>
953 files for the software you are building to determine the actual 293 layer that many <filename>devtool</filename> commands
954 license. 294 use.
955 </para> 295 The command is flexible enough to allow you to extract source
296 code into both the workspace or a separate local Git repository
297 and to use existing code that does not need to be extracted.
298 </para>
299
300 <para>
301 Depending on your particular scenario, the arguments and options
302 you use with <filename>devtool add</filename> form different
303 combinations.
304 The following diagram shows common development flows
305 you would use with the <filename>devtool add</filename>
306 command:
307 </para>
308
309 <para>
310 <imagedata fileref="figures/sdk-devtool-add-flow.png" align="center" />
311 </para>
312
313 <para>
314 <orderedlist>
315 <listitem><para><emphasis>Generating the New Recipe</emphasis>:
316 The top part of the flow shows three scenarios by which
317 you could use <filename>devtool add</filename> to
318 generate a recipe based on existing source code.</para>
319
320 <para>In a shared development environment, it is
321 typical where other developers are responsible for
322 various areas of source code.
323 As a developer, you are probably interested in using
324 that source code as part of your development using
325 the Yocto Project.
326 All you need is access to the code, a recipe, and a
327 controlled area in which to do your work.</para>
328
329 <para>Within the diagram, three possible scenarios
330 feed into the <filename>devtool add</filename> workflow:
331 <itemizedlist>
332 <listitem><para><emphasis>Left</emphasis>:
333 The left scenario represents a common situation
334 where the source code does not exist locally
335 and needs to be extracted.
336 In this situation, you just let it get
337 extracted to the default workspace - you do not
338 want it in some specific location outside of the
339 workspace.
340 Thus, everything you need will be located in the
341 workspace:
342 <literallayout class='monospaced'>
343 $ devtool add <replaceable>recipe fetchuri</replaceable>
344 </literallayout>
345 With this command, <filename>devtool</filename>
346 creates a recipe and an append file in the
347 workspace as well as extracts the upstream
348 source files into a local Git repository also
349 within the <filename>sources</filename> folder.
350 </para></listitem>
351 <listitem><para><emphasis>Middle</emphasis>:
352 The middle scenario also represents a situation where
353 the source code does not exist locally.
354 In this case, the code is again upstream
355 and needs to be extracted to some
356 local area - this time outside of the default
357 workspace.
358 If required, <filename>devtool</filename>
359 always creates
360 a Git repository locally during the extraction.
361 Furthermore, the first positional argument
362 <replaceable>srctree</replaceable> in this case
363 identifies where the
364 <filename>devtool add</filename> command
365 will locate the extracted code outside of the
366 workspace:
367 <literallayout class='monospaced'>
368 $ devtool add <replaceable>recipe srctree fetchuri</replaceable>
369 </literallayout>
370 In summary, the source code is pulled from
371 <replaceable>fetchuri</replaceable> and extracted
372 into the location defined by
373 <replaceable>srctree</replaceable> as a local
374 Git repository.</para>
375
376 <para>Within workspace, <filename>devtool</filename>
377 creates both the recipe and an append file
378 for the recipe.
379 </para></listitem>
380 <listitem><para><emphasis>Right</emphasis>:
381 The right scenario represents a situation
382 where the source tree (srctree) has been
383 previously prepared outside of the
384 <filename>devtool</filename> workspace.
385 </para>
386
387 <para>The following command names the recipe
388 and identifies where the existing source tree
389 is located:
390 <literallayout class='monospaced'>
391 $ devtool add <replaceable>recipe srctree</replaceable>
392 </literallayout>
393 The command examines the source code and creates
394 a recipe for it placing the recipe into the
395 workspace.</para>
396
397 <para>Because the extracted source code already exists,
398 <filename>devtool</filename> does not try to
399 relocate it into the workspace - just the new
400 the recipe is placed in the workspace.</para>
401
402 <para>Aside from a recipe folder, the command
403 also creates an append folder and places an initial
404 <filename>*.bbappend</filename> within.
405 </para></listitem>
406 </itemizedlist>
407 </para></listitem>
408 <listitem><para><emphasis>Edit the Recipe</emphasis>:
409 At this point, you can use <filename>devtool edit-recipe</filename>
410 to open up the editor as defined by the
411 <filename>$EDITOR</filename> environment variable
412 and modify the file:
413 <literallayout class='monospaced'>
414 $ devtool edit-recipe <replaceable>recipe</replaceable>
415 </literallayout>
416 From within the editor, you can make modifications to the
417 recipe that take affect when you build it later.
418 </para></listitem>
419 <listitem><para><emphasis>Build the Recipe or Rebuild the Image</emphasis>:
420 At this point in the flow, the next step you
421 take depends on what you are going to do with
422 the new code.</para>
423 <para>If you need to take the build output and eventually
424 move it to the target hardware, you would use
425 <filename>devtool build</filename>:
426 <literallayout class='monospaced'>
427 $ devtool build <replaceable>recipe</replaceable>
428 </literallayout></para>
429 <para>On the other hand, if you want an image to
430 contain the recipe's packages for immediate deployment
431 onto a device (e.g. for testing purposes), you can use
432 the <filename>devtool build-image</filename> command:
433 <literallayout class='monospaced'>
434 $ devtool build-image <replaceable>image</replaceable>
435 </literallayout>
436 </para></listitem>
437 <listitem><para><emphasis>Deploy the Build Output</emphasis>:
438 When you use the <filename>devtool build</filename>
439 command to build out your recipe, you probably want to
440 see if the resulting build output works as expected on target
441 hardware.
442 <note>
443 This step assumes you have a previously built
444 image that is already either running in QEMU or
445 running on actual hardware.
446 Also, it is assumed that for deployment of the image
447 to the target, SSH is installed in the image and if
448 the image is running on real hardware that you have
449 network access to and from your development machine.
450 </note>
451 You can deploy your build output to that target hardware by
452 using the <filename>devtool deploy-target</filename> command:
453 <literallayout class='monospaced'>
454 $ devtool deploy-target <replaceable>recipe target</replaceable>
455 </literallayout>
456 The <replaceable>target</replaceable> is a live target machine
457 running as an SSH server.</para>
458
459 <para>You can, of course, also deploy the image you build
460 using the <filename>devtool build-image</filename> command
461 to actual hardware.
462 However, <filename>devtool</filename> does not provide a
463 specific command that allows you to do this.
464 </para></listitem>
465 <listitem><para>
466 <emphasis>Finish Your Work With the Recipe</emphasis>:
467 The <filename>devtool finish</filename> command creates
468 any patches corresponding to commits in the local
469 Git repository, moves the new recipe to a more permanent
470 layer, and then resets the recipe so that the recipe is
471 built normally rather than from the workspace.
472 <literallayout class='monospaced'>
473 $ devtool finish <replaceable>recipe layer</replaceable>
474 </literallayout>
475 <note>
476 Any changes you want to turn into patches must be
477 committed to the Git repository in the source tree.
478 </note></para>
479
480 <para>As mentioned, the <filename>devtool finish</filename>
481 command moves the final recipe to its permanent layer.
482 </para>
483
484 <para>As a final process of the
485 <filename>devtool finish</filename> command, the state
486 of the standard layers and the upstream source is
487 restored so that you can build the recipe from those
488 areas rather than the workspace.
489 <note>
490 You can use the <filename>devtool reset</filename>
491 command to put things back should you decide you
492 do not want to proceed with your work.
493 If you do use this command, realize that the source
494 tree is preserved.
495 </note>
496 </para></listitem>
497 </orderedlist>
498 </para>
499 </section>
500
501 <section id='sdk-devtool-use-devtool-modify-to-modify-the-source-of-an-existing-component'>
502 <title>Use <filename>devtool modify</filename> to Modify the Source of an Existing Component</title>
503
504 <para>
505 The <filename>devtool modify</filename> command prepares the
506 way to work on existing code that already has a recipe in
507 place.
508 The command is flexible enough to allow you to extract code,
509 specify the existing recipe, and keep track of and gather any
510 patch files from other developers that are
511 associated with the code.
512 </para>
513
514 <para>
515 Depending on your particular scenario, the arguments and options
516 you use with <filename>devtool modify</filename> form different
517 combinations.
518 The following diagram shows common development flows
519 you would use with the <filename>devtool modify</filename>
520 command:
521 </para>
522
523 <para>
524 <imagedata fileref="figures/sdk-devtool-modify-flow.png" align="center" />
525 </para>
526
527 <para>
528 <orderedlist>
529 <listitem><para><emphasis>Preparing to Modify the Code</emphasis>:
530 The top part of the flow shows three scenarios by which
531 you could use <filename>devtool modify</filename> to
532 prepare to work on source files.
533 Each scenario assumes the following:
534 <itemizedlist>
535 <listitem><para>The recipe exists in some layer external
536 to the <filename>devtool</filename> workspace.
537 </para></listitem>
538 <listitem><para>The source files exist upstream in an
539 un-extracted state or locally in a previously
540 extracted state.
541 </para></listitem>
542 </itemizedlist>
543 The typical situation is where another developer has
544 created some layer for use with the Yocto Project and
545 their recipe already resides in that layer.
546 Furthermore, their source code is readily available
547 either upstream or locally.
548 <itemizedlist>
549 <listitem><para><emphasis>Left</emphasis>:
550 The left scenario represents a common situation
551 where the source code does not exist locally
552 and needs to be extracted.
553 In this situation, the source is extracted
554 into the default workspace location.
555 The recipe, in this scenario, is in its own
556 layer outside the workspace
557 (i.e.
558 <filename>meta-</filename><replaceable>layername</replaceable>).
559 </para>
560
561 <para>The following command identifies the recipe
562 and by default extracts the source files:
563 <literallayout class='monospaced'>
564 $ devtool modify <replaceable>recipe</replaceable>
565 </literallayout>
566 Once <filename>devtool</filename>locates the recipe,
567 it uses the
568 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
569 variable to locate the source code and
570 any local patch files from other developers are
571 located.
572 <note>
573 You cannot provide an URL for
574 <replaceable>srctree</replaceable> when using the
575 <filename>devtool modify</filename> command.
576 </note>
577 With this scenario, however, since no
578 <replaceable>srctree</replaceable> argument exists, the
579 <filename>devtool modify</filename> command by default
580 extracts the source files to a Git structure.
581 Furthermore, the location for the extracted source is the
582 default area within the workspace.
583 The result is that the command sets up both the source
584 code and an append file within the workspace with the
585 recipe remaining in its original location.
586 </para></listitem>
587 <listitem><para><emphasis>Middle</emphasis>:
588 The middle scenario represents a situation where
589 the source code also does not exist locally.
590 In this case, the code is again upstream
591 and needs to be extracted to some
592 local area as a Git repository.
593 The recipe, in this scenario, is again in its own
594 layer outside the workspace.</para>
595
596 <para>The following command tells
597 <filename>devtool</filename> what recipe with
598 which to work and, in this case, identifies a local
599 area for the extracted source files that is outside
600 of the default workspace:
601 <literallayout class='monospaced'>
602 $ devtool modify <replaceable>recipe srctree</replaceable>
603 </literallayout>
604 As with all extractions, the command uses
605 the recipe's <filename>SRC_URI</filename> to locate the
606 source files.
607 Once the files are located, the command by default
608 extracts them.
609 Providing the <replaceable>srctree</replaceable>
610 argument instructs <filename>devtool</filename> where
611 place the extracted source.</para>
612
613 <para>Within workspace, <filename>devtool</filename>
614 creates an append file for the recipe.
615 The recipe remains in its original location but
616 the source files are extracted to the location you
617 provided with <replaceable>srctree</replaceable>.
618 </para></listitem>
619 <listitem><para><emphasis>Right</emphasis>:
620 The right scenario represents a situation
621 where the source tree
622 (<replaceable>srctree</replaceable>) exists as a
623 previously extracted Git structure outside of
624 the <filename>devtool</filename> workspace.
625 In this example, the recipe also exists
626 elsewhere in its own layer.
627 </para>
628
629 <para>The following command tells
630 <filename>devtool</filename> the recipe
631 with which to work, uses the "-n" option to indicate
632 source does not need to be extracted, and uses
633 <replaceable>srctree</replaceable> to point to the
634 previously extracted source files:
635 <literallayout class='monospaced'>
636 $ devtool modify -n <replaceable>recipe srctree</replaceable>
637 </literallayout>
638 </para>
639
640 <para>Once the command finishes, it creates only
641 an append file for the recipe in the workspace.
642 The recipe and the source code remain in their
643 original locations.
644 </para></listitem>
645 </itemizedlist>
646 </para></listitem>
647 <listitem><para><emphasis>Edit the Source</emphasis>:
648 Once you have used the <filename>devtool modify</filename>
649 command, you are free to make changes to the source
650 files.
651 You can use any editor you like to make and save
652 your source code modifications.
653 </para></listitem>
654 <listitem><para><emphasis>Build the Recipe</emphasis>:
655 Once you have updated the source files, you can build
656 the recipe.
657 </para></listitem>
658 <listitem><para><emphasis>Deploy the Build Output</emphasis>:
659 When you use the <filename>devtool build</filename>
660 command to build out your recipe, you probably want to see
661 if the resulting build output works as expected on target
662 hardware.
663 <note>
664 This step assumes you have a previously built
665 image that is already either running in QEMU or
666 running on actual hardware.
667 Also, it is assumed that for deployment of the image
668 to the target, SSH is installed in the image and if
669 the image is running on real hardware that you have
670 network access to and from your development machine.
671 </note>
672 You can deploy your build output to that target hardware by
673 using the <filename>devtool deploy-target</filename> command:
674 <literallayout class='monospaced'>
675 $ devtool deploy-target <replaceable>recipe target</replaceable>
676 </literallayout>
677 The <replaceable>target</replaceable> is a live target machine
678 running as an SSH server.</para>
679
680 <para>You can, of course, also deploy the image you build
681 using the <filename>devtool build-image</filename> command
682 to actual hardware.
683 However, <filename>devtool</filename> does not provide a
684 specific command that allows you to do this.
685 </para></listitem>
686 <listitem><para>
687 <emphasis>Finish Your Work With the Recipe</emphasis>:
688 The <filename>devtool finish</filename> command creates
689 any patches corresponding to commits in the local
690 Git repository, updates the recipe to point to them
691 (or creates a <filename>.bbappend</filename> file to do
692 so, depending on the specified destination layer), and
693 then resets the recipe so that the recipe is built normally
694 rather than from the workspace.
695 <literallayout class='monospaced'>
696 $ devtool finish <replaceable>recipe layer</replaceable>
697 </literallayout>
698 <note>
699 Any changes you want to turn into patches must be
700 committed to the Git repository in the source tree.
701 </note></para>
702
703 <para>Because there is no need to move the recipe,
704 <filename>devtool finish</filename> either updates the
705 original recipe in the original layer or the command
706 creates a <filename>.bbappend</filename> in a different
707 layer as provided by <replaceable>layer</replaceable>.
708 </para>
709
710 <para>As a final process of the
711 <filename>devtool finish</filename> command, the state
712 of the standard layers and the upstream source is
713 restored so that you can build the recipe from those
714 areas rather than the workspace.
715 <note>
716 You can use the <filename>devtool reset</filename>
717 command to put things back should you decide you
718 do not want to proceed with your work.
719 If you do use this command, realize that the source
720 tree is preserved.
721 </note>
722 </para></listitem>
723 </orderedlist>
724 </para>
725 </section>
726
727 <section id='sdk-devtool-use-devtool-upgrade-to-create-a-version-of-the-recipe-that-supports-a-newer-version-of-the-software'>
728 <title>Use <filename>devtool upgrade</filename> to Create a Version of the Recipe that Supports a Newer Version of the Software</title>
729
730 <para>
731 The <filename>devtool upgrade</filename> command updates
732 an existing recipe so that you can build it for an updated
733 set of source files.
734 The command is flexible enough to allow you to specify
735 source code revision and versioning schemes, extract code into
736 or out of the <filename>devtool</filename> workspace, and
737 work with any source file forms that the fetchers support.
738 </para>
739
740 <para>
741 Depending on your particular scenario, the arguments and options
742 you use with <filename>devtool upgrade</filename> form different
743 combinations.
744 The following diagram shows a common development flow
745 you would use with the <filename>devtool modify</filename>
746 command:
747 </para>
748
749 <para>
750 <imagedata fileref="figures/sdk-devtool-upgrade-flow.png" align="center" />
751 </para>
752
753 <para>
754 <orderedlist>
755 <listitem><para><emphasis>Initiate the Upgrade</emphasis>:
756 The top part of the flow shows a typical scenario by which
757 you could use <filename>devtool upgrade</filename>.
758 The following conditions exist:
759 <itemizedlist>
760 <listitem><para>The recipe exists in some layer external
761 to the <filename>devtool</filename> workspace.
762 </para></listitem>
763 <listitem><para>The source files for the new release
764 exist adjacent to the same location pointed to by
765 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
766 in the recipe (e.g. a tarball with the new version
767 number in the name, or as a different revision in
768 the upstream Git repository).
769 </para></listitem>
770 </itemizedlist>
771 A common situation is where third-party software has
772 undergone a revision so that it has been upgraded.
773 The recipe you have access to is likely in your own layer.
774 Thus, you need to upgrade the recipe to use the
775 newer version of the software:
776 <literallayout class='monospaced'>
777 $ devtool upgrade -V <replaceable>version recipe</replaceable>
778 </literallayout>
779 By default, the <filename>devtool upgrade</filename> command
780 extracts source code into the <filename>sources</filename>
781 directory in the workspace.
782 If you want the code extracted to any other location, you
783 need to provide the <replaceable>srctree</replaceable>
784 positional argument with the command as follows:
785 <literallayout class='monospaced'>
786 $ devtool upgrade -V <replaceable>version recipe srctree</replaceable>
787 </literallayout>
788 Also, in this example, the "-V" option is used to specify
789 the new version.
790 If the source files pointed to by the
791 <filename>SRC_URI</filename> statement in the recipe are
792 in a Git repository, you must provide the "-S" option and
793 specify a revision for the software.</para>
794
795 <para>Once <filename>devtool</filename> locates the recipe,
796 it uses the <filename>SRC_URI</filename> variable to locate
797 the source code and any local patch files from other
798 developers are located.
799 The result is that the command sets up the source
800 code, the new version of the recipe, and an append file
801 all within the workspace.
802 </para></listitem>
803 <listitem><para><emphasis>Resolve any Conflicts created by the Upgrade</emphasis>:
804 At this point, there could be some conflicts due to the
805 software being upgraded to a new version.
806 This would occur if your recipe specifies some patch files in
807 <filename>SRC_URI</filename> that conflict with changes
808 made in the new version of the software.
809 If this is the case, you need to resolve the conflicts
810 by editing the source and following the normal
811 <filename>git rebase</filename> conflict resolution
812 process.</para>
813 <para>Before moving onto the next step, be sure to resolve any
814 such conflicts created through use of a newer or different
815 version of the software.
816 </para></listitem>
817 <listitem><para><emphasis>Build the Recipe</emphasis>:
818 Once you have your recipe in order, you can build it.
819 You can either use <filename>devtool build</filename> or
820 <filename>bitbake</filename>.
821 Either method produces build output that is stored
822 in
823 <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>.
824 </para></listitem>
825 <listitem><para><emphasis>Deploy the Build Output</emphasis>:
826 When you use the <filename>devtool build</filename>
827 command or <filename>bitbake</filename> to build out your
828 recipe, you probably want to see if the resulting build
829 output works as expected on target hardware.
830 <note>
831 This step assumes you have a previously built
832 image that is already either running in QEMU or
833 running on actual hardware.
834 Also, it is assumed that for deployment of the image
835 to the target, SSH is installed in the image and if
836 the image is running on real hardware that you have
837 network access to and from your development machine.
838 </note>
839 You can deploy your build output to that target hardware by
840 using the <filename>devtool deploy-target</filename> command:
841 <literallayout class='monospaced'>
842 $ devtool deploy-target <replaceable>recipe target</replaceable>
843 </literallayout>
844 The <replaceable>target</replaceable> is a live target machine
845 running as an SSH server.</para>
846 <para>You can, of course, also deploy the image you build
847 using the <filename>devtool build-image</filename> command
848 to actual hardware.
849 However, <filename>devtool</filename> does not provide a
850 specific command that allows you to do this.
851 </para></listitem>
852 <listitem><para>
853 <emphasis>Finish Your Work With the Recipe</emphasis>:
854 The <filename>devtool finish</filename> command creates
855 any patches corresponding to commits in the local
856 Git repository, updates the recipe to point to them
857 (or creates a <filename>.bbappend</filename> file to do
858 so, depending on the specified destination layer), and
859 then resets the recipe so that the recipe is built normally
860 rather than from the workspace.
861 <literallayout class='monospaced'>
862 $ devtool finish <replaceable>recipe layer</replaceable>
863 </literallayout>
864 <note>
865 Any changes you want to turn into patches must be
866 committed to the Git repository in the source tree.
867 </note></para>
868 <para>Because there is no need to move the recipe,
869 <filename>devtool finish</filename> either updates the
870 original recipe in the original layer or the command
871 creates a <filename>.bbappend</filename> in a different
872 layer as provided by <replaceable>layer</replaceable>.
873 </para>
874 <para>As a final process of the
875 <filename>devtool finish</filename> command, the state
876 of the standard layers and the upstream source is
877 restored so that you can build the recipe from those
878 areas rather than the workspace.
879 <note>
880 You can use the <filename>devtool reset</filename>
881 command to put things back should you decide you
882 do not want to proceed with your work.
883 If you do use this command, realize that the source
884 tree is preserved.
885 </note>
886 </para></listitem>
887 </orderedlist>
888 </para>
889 </section>
956 </section> 890 </section>
957 891
958 <section id='sdk-adding-makefile-only-software'> 892 <section id='sdk-a-closer-look-at-devtool-add'>
959 <title>Adding Makefile-Only Software</title> 893 <title>A Closer Look at <filename>devtool add</filename></title>
960
961 <para>
962 The use of <filename>make</filename> by itself is very common
963 in both proprietary and open source software.
964 Unfortunately, Makefiles are often not written with
965 cross-compilation in mind.
966 Thus, <filename>devtool add</filename> often cannot do very
967 much to ensure that these Makefiles build correctly.
968 It is very common, for example, to explicitly call
969 <filename>gcc</filename> instead of using the
970 <ulink url='&YOCTO_DOCS_REF_URL;#var-CC'><filename>CC</filename></ulink>
971 variable.
972 Usually, in a cross-compilation environment,
973 <filename>gcc</filename> is the compiler for the build host
974 and the cross-compiler is named something similar to
975 <filename>arm-poky-linux-gnueabi-gcc</filename> and might
976 require some arguments (e.g. to point to the associated sysroot
977 for the target machine).
978 </para>
979 894
980 <para> 895 <para>
981 When writing a recipe for Makefile-only software, keep the 896 The <filename>devtool add</filename> command automatically creates a
982 following in mind: 897 recipe based on the source tree with which you provide it.
898 Currently, the command has support for the following:
983 <itemizedlist> 899 <itemizedlist>
984 <listitem><para> 900 <listitem><para>
985 You probably need to patch the Makefile to use 901 Autotools (<filename>autoconf</filename> and
986 variables instead of hardcoding tools within the 902 <filename>automake</filename>)
987 toolchain such as <filename>gcc</filename> and
988 <filename>g++</filename>.
989 </para></listitem> 903 </para></listitem>
990 <listitem><para> 904 <listitem><para>
991 The environment in which <filename>make</filename> runs 905 CMake
992 is set up with various standard variables for
993 compilation (e.g. <filename>CC</filename>,
994 <filename>CXX</filename>, and so forth) in a similar
995 manner to the environment set up by the SDK's
996 environment setup script.
997 One easy way to see these variables is to run the
998 <filename>devtool build</filename> command on the
999 recipe and then look in
1000 <filename>oe-logs/run.do_compile</filename>.
1001 Towards the top of this file you will see a list of
1002 environment variables that are being set.
1003 You can take advantage of these variables within the
1004 Makefile.
1005 </para></listitem> 906 </para></listitem>
1006 <listitem><para> 907 <listitem><para>
1007 If the Makefile sets a default for a variable using "=", 908 Scons
1008 that default overrides the value set in the environment,
1009 which is usually not desirable.
1010 In this situation, you can either patch the Makefile
1011 so it sets the default using the "?=" operator, or
1012 you can alternatively force the value on the
1013 <filename>make</filename> command line.
1014 To force the value on the command line, add the
1015 variable setting to
1016 <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OEMAKE'><filename>EXTRA_OEMAKE</filename></ulink>
1017 or
1018 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGECONFIG_CONFARGS'><filename>PACKAGECONFIG_CONFARGS</filename></ulink>
1019 within the recipe.
1020 Here is an example using <filename>EXTRA_OEMAKE</filename>:
1021 <literallayout class='monospaced'>
1022 EXTRA_OEMAKE += "'CC=${CC}' 'CXX=${CXX}'"
1023 </literallayout>
1024 In the above example, single quotes are used around the
1025 variable settings as the values are likely to contain
1026 spaces because required default options are passed to
1027 the compiler.
1028 </para></listitem> 909 </para></listitem>
1029 <listitem><para> 910 <listitem><para>
1030 Hardcoding paths inside Makefiles is often problematic 911 <filename>qmake</filename>
1031 in a cross-compilation environment.
1032 This is particularly true because those hardcoded paths
1033 often point to locations on the build host and thus
1034 will either be read-only or will introduce
1035 contamination into the cross-compilation by virtue of
1036 being specific to the build host rather than the target.
1037 Patching the Makefile to use prefix variables or other
1038 path variables is usually the way to handle this.
1039 </para></listitem> 912 </para></listitem>
1040 <listitem><para> 913 <listitem><para>
1041 Sometimes a Makefile runs target-specific commands such 914 Plain <filename>Makefile</filename>
1042 as <filename>ldconfig</filename>. 915 </para></listitem>
1043 For such cases, you might be able to simply apply 916 <listitem><para>
1044 patches that remove these commands from the Makefile. 917 Out-of-tree kernel module
918 </para></listitem>
919 <listitem><para>
920 Binary package (i.e. "-b" option)
1045 </para></listitem> 921 </para></listitem>
1046 </itemizedlist>
1047 </para>
1048 </section>
1049
1050 <section id='sdk-adding-native-tools'>
1051 <title>Adding Native Tools</title>
1052
1053 <para>
1054 Often, you need to build additional tools that run on the
1055 build host system as opposed to the target.
1056 You should indicate this using one of the following methods
1057 when you run <filename>devtool add</filename>:
1058 <itemizedlist>
1059 <listitem><para> 922 <listitem><para>
1060 Specify the name of the recipe such that it ends 923 Node.js module
1061 with "-native".
1062 Specifying the name like this produces a recipe that
1063 only builds for the build host.
1064 </para></listitem> 924 </para></listitem>
1065 <listitem><para> 925 <listitem><para>
1066 Specify the "&dash;&dash;also-native" option with the 926 Python modules that use <filename>setuptools</filename>
1067 <filename>devtool add</filename> command. 927 or <filename>distutils</filename>
1068 Specifying this option creates a recipe file that still
1069 builds for the target but also creates a variant with
1070 a "-native" suffix that builds for the build host.
1071 </para></listitem> 928 </para></listitem>
1072 </itemizedlist> 929 </itemizedlist>
930 </para>
931
932 <para>
933 Apart from binary packages, the determination of how a source tree
934 should be treated is automatic based on the files present within
935 that source tree.
936 For example, if a <filename>CMakeLists.txt</filename> file is found,
937 then the source tree is assumed to be using
938 CMake and is treated accordingly.
1073 <note> 939 <note>
1074 If you need to add a tool that is shipped as part of a 940 In most cases, you need to edit the automatically generated
1075 source tree that builds code for the target, you can 941 recipe in order to make it build properly.
1076 typically accomplish this by building the native and target 942 Typically, you would go through several edit and build cycles
1077 parts separately rather than within the same compilation 943 until you can build the recipe.
1078 process. 944 Once the recipe can be built, you could use possible further
1079 Realize though that with the "&dash;&dash;also-native" option, you 945 iterations to test the recipe on the target device.
1080 can add the tool using just one recipe file.
1081 </note> 946 </note>
1082 </para> 947 </para>
1083 </section>
1084
1085 <section id='sdk-adding-node-js-modules'>
1086 <title>Adding Node.js Modules</title>
1087 948
1088 <para> 949 <para>
1089 You can use the <filename>devtool add</filename> command two 950 The remainder of this section covers specifics regarding how parts
1090 different ways to add Node.js modules: 1) Through 951 of the recipe are generated.
1091 <filename>npm</filename> and, 2) from a repository or local
1092 source.
1093 </para> 952 </para>
1094 953
1095 <para> 954 <section id='sdk-name-and-version'>
1096 Use the following form to add Node.js modules through 955 <title>Name and Version</title>
1097 <filename>npm</filename>: 956
1098 <literallayout class='monospaced'> 957 <para>
1099 $ devtool add "npm://registry.npmjs.org;name=forever;version=0.15.1" 958 If you do not specify a name and version on the command
1100 </literallayout> 959 line, <filename>devtool add</filename> attempts to determine
1101 The name and version parameters are mandatory. 960 the name and version of the software being built from
1102 Lockdown and shrinkwrap files are generated and pointed to by 961 various metadata within the source tree.
1103 the recipe in order to freeze the version that is fetched for 962 Furthermore, the command sets the name of the created recipe
1104 the dependencies according to the first time. 963 file accordingly.
1105 This also saves checksums that are verified on future fetches. 964 If the name or version cannot be determined, the
1106 Together, these behaviors ensure the reproducibility and 965 <filename>devtool add</filename> command prints an error and
1107 integrity of the build. 966 you must re-run the command with both the name and version
1108 <note><title>Notes</title> 967 or just the name or version specified.
968 </para>
969
970 <para>
971 Sometimes the name or version determined from the source tree
972 might be incorrect.
973 For such a case, you must reset the recipe:
974 <literallayout class='monospaced'>
975 $ devtool reset -n <replaceable>recipename</replaceable>
976 </literallayout>
977 After running the <filename>devtool reset</filename> command,
978 you need to run <filename>devtool add</filename> again and
979 provide the name or the version.
980 </para>
981 </section>
982
983 <section id='sdk-dependency-detection-and-mapping'>
984 <title>Dependency Detection and Mapping</title>
985
986 <para>
987 The <filename>devtool add</filename> command attempts to
988 detect build-time dependencies and map them to other recipes
989 in the system.
990 During this mapping, the command fills in the names of those
991 recipes in the
992 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink>
993 value within the recipe.
994 If a dependency cannot be mapped, then a comment is placed in
995 the recipe indicating such.
996 The inability to map a dependency might be caused because the
997 naming is not recognized or because the dependency simply is
998 not available.
999 For cases where the dependency is not available, you must use
1000 the <filename>devtool add</filename> command to add an
1001 additional recipe to satisfy the dependency and then come
1002 back to the first recipe and add its name to
1003 <filename>DEPENDS</filename>.
1004 </para>
1005
1006 <para>
1007 If you need to add runtime dependencies, you can do so by
1008 adding the following to your recipe:
1009 <literallayout class='monospaced'>
1010 RDEPENDS_${PN} += "dependency1 dependency2 ..."
1011 </literallayout>
1012 <note>
1013 The <filename>devtool add</filename> command often cannot
1014 distinguish between mandatory and optional dependencies.
1015 Consequently, some of the detected dependencies might
1016 in fact be optional.
1017 When in doubt, consult the documentation or the configure
1018 script for the software the recipe is building for further
1019 details.
1020 In some cases, you might find you can substitute the
1021 dependency for an option to disable the associated
1022 functionality passed to the configure script.
1023 </note>
1024 </para>
1025 </section>
1026
1027 <section id='sdk-license-detection'>
1028 <title>License Detection</title>
1029
1030 <para>
1031 The <filename>devtool add</filename> command attempts to
1032 determine if the software you are adding is able to be
1033 distributed under a common open-source license and sets the
1034 <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE'><filename>LICENSE</filename></ulink>
1035 value accordingly.
1036 You should double-check this value against the documentation
1037 or source files for the software you are building and update
1038 that <filename>LICENSE</filename> value if necessary.
1039 </para>
1040
1041 <para>
1042 The <filename>devtool add</filename> command also sets the
1043 <ulink url='&YOCTO_DOCS_REF_URL;#var-LIC_FILES_CHKSUM'><filename>LIC_FILES_CHKSUM</filename></ulink>
1044 value to point to all files that appear to be license-related.
1045 However, license statements often appear in comments at the top
1046 of source files or within documentation.
1047 Consequently, you might need to amend the
1048 <filename>LIC_FILES_CHKSUM</filename> variable to point to one
1049 or more of those comments if present.
1050 Setting <filename>LIC_FILES_CHKSUM</filename> is particularly
1051 important for third-party software.
1052 The mechanism attempts to ensure correct licensing should you
1053 upgrade the recipe to a newer upstream version in future.
1054 Any change in licensing is detected and you receive an error
1055 prompting you to check the license text again.
1056 </para>
1057
1058 <para>
1059 If the <filename>devtool add</filename> command cannot
1060 determine licensing information, the
1061 <filename>LICENSE</filename> value is set to "CLOSED" and the
1062 <filename>LIC_FILES_CHKSUM</filename> value remains unset.
1063 This behavior allows you to continue with development but is
1064 unlikely to be correct in all cases.
1065 Consequently, you should check the documentation or source
1066 files for the software you are building to determine the actual
1067 license.
1068 </para>
1069 </section>
1070
1071 <section id='sdk-adding-makefile-only-software'>
1072 <title>Adding Makefile-Only Software</title>
1073
1074 <para>
1075 The use of <filename>make</filename> by itself is very common
1076 in both proprietary and open source software.
1077 Unfortunately, Makefiles are often not written with
1078 cross-compilation in mind.
1079 Thus, <filename>devtool add</filename> often cannot do very
1080 much to ensure that these Makefiles build correctly.
1081 It is very common, for example, to explicitly call
1082 <filename>gcc</filename> instead of using the
1083 <ulink url='&YOCTO_DOCS_REF_URL;#var-CC'><filename>CC</filename></ulink>
1084 variable.
1085 Usually, in a cross-compilation environment,
1086 <filename>gcc</filename> is the compiler for the build host
1087 and the cross-compiler is named something similar to
1088 <filename>arm-poky-linux-gnueabi-gcc</filename> and might
1089 require some arguments (e.g. to point to the associated sysroot
1090 for the target machine).
1091 </para>
1092
1093 <para>
1094 When writing a recipe for Makefile-only software, keep the
1095 following in mind:
1109 <itemizedlist> 1096 <itemizedlist>
1110 <listitem><para> 1097 <listitem><para>
1111 You must use quotes around the URL. 1098 You probably need to patch the Makefile to use
1112 The <filename>devtool add</filename> does not require 1099 variables instead of hardcoding tools within the
1113 the quotes, but the shell considers ";" as a splitter 1100 toolchain such as <filename>gcc</filename> and
1114 between multiple commands. 1101 <filename>g++</filename>.
1115 Thus, without the quotes,
1116 <filename>devtool add</filename> does not receive the
1117 other parts, which results in several "command not
1118 found" errors.
1119 </para></listitem> 1102 </para></listitem>
1120 <listitem><para> 1103 <listitem><para>
1121 In order to support adding 1104 The environment in which <filename>make</filename> runs
1122 Node.js modules, a 1105 is set up with various standard variables for
1123 <filename>nodejs</filename> recipe must be part of your 1106 compilation (e.g. <filename>CC</filename>,
1124 SDK in order to provide Node.js 1107 <filename>CXX</filename>, and so forth) in a similar
1125 itself. 1108 manner to the environment set up by the SDK's
1109 environment setup script.
1110 One easy way to see these variables is to run the
1111 <filename>devtool build</filename> command on the
1112 recipe and then look in
1113 <filename>oe-logs/run.do_compile</filename>.
1114 Towards the top of this file you will see a list of
1115 environment variables that are being set.
1116 You can take advantage of these variables within the
1117 Makefile.
1118 </para></listitem>
1119 <listitem><para>
1120 If the Makefile sets a default for a variable using "=",
1121 that default overrides the value set in the environment,
1122 which is usually not desirable.
1123 In this situation, you can either patch the Makefile
1124 so it sets the default using the "?=" operator, or
1125 you can alternatively force the value on the
1126 <filename>make</filename> command line.
1127 To force the value on the command line, add the
1128 variable setting to
1129 <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OEMAKE'><filename>EXTRA_OEMAKE</filename></ulink>
1130 or
1131 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGECONFIG_CONFARGS'><filename>PACKAGECONFIG_CONFARGS</filename></ulink>
1132 within the recipe.
1133 Here is an example using <filename>EXTRA_OEMAKE</filename>:
1134 <literallayout class='monospaced'>
1135 EXTRA_OEMAKE += "'CC=${CC}' 'CXX=${CXX}'"
1136 </literallayout>
1137 In the above example, single quotes are used around the
1138 variable settings as the values are likely to contain
1139 spaces because required default options are passed to
1140 the compiler.
1141 </para></listitem>
1142 <listitem><para>
1143 Hardcoding paths inside Makefiles is often problematic
1144 in a cross-compilation environment.
1145 This is particularly true because those hardcoded paths
1146 often point to locations on the build host and thus
1147 will either be read-only or will introduce
1148 contamination into the cross-compilation by virtue of
1149 being specific to the build host rather than the target.
1150 Patching the Makefile to use prefix variables or other
1151 path variables is usually the way to handle this.
1152 </para></listitem>
1153 <listitem><para>
1154 Sometimes a Makefile runs target-specific commands such
1155 as <filename>ldconfig</filename>.
1156 For such cases, you might be able to simply apply
1157 patches that remove these commands from the Makefile.
1126 </para></listitem> 1158 </para></listitem>
1127 </itemizedlist> 1159 </itemizedlist>
1128 </note> 1160 </para>
1129 </para> 1161 </section>
1130 1162
1131 <para> 1163 <section id='sdk-adding-native-tools'>
1132 As mentioned earlier, you can also add Node.js modules 1164 <title>Adding Native Tools</title>
1133 directly from a repository or local source tree.
1134 To add modules this way, use <filename>devtool add</filename> in
1135 the following form:
1136 <literallayout class='monospaced'>
1137 $ devtool add https://github.com/diversario/node-ssdp
1138 </literallayout>
1139 In this example, <filename>devtool</filename> fetches the specified
1140 Git repository, detects that the code is Node.js code, fetches
1141 dependencies using <filename>npm</filename>, and sets
1142 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
1143 accordingly.
1144 </para>
1145 </section>
1146</section>
1147 1165
1148<section id='sdk-working-with-recipes'> 1166 <para>
1149 <title>Working With Recipes</title> 1167 Often, you need to build additional tools that run on the
1150 1168 build host system as opposed to the target.
1151 <para> 1169 You should indicate this using one of the following methods
1152 When building a recipe with <filename>devtool build</filename> the 1170 when you run <filename>devtool add</filename>:
1153 typical build progression is as follows: 1171 <itemizedlist>
1154 <orderedlist> 1172 <listitem><para>
1155 <listitem><para> 1173 Specify the name of the recipe such that it ends
1156 Fetch the source 1174 with "-native".
1157 </para></listitem> 1175 Specifying the name like this produces a recipe that
1158 <listitem><para> 1176 only builds for the build host.
1159 Unpack the source 1177 </para></listitem>
1160 </para></listitem> 1178 <listitem><para>
1161 <listitem><para> 1179 Specify the "&dash;&dash;also-native" option with the
1162 Configure the source 1180 <filename>devtool add</filename> command.
1163 </para></listitem> 1181 Specifying this option creates a recipe file that still
1164 <listitem><para> 1182 builds for the target but also creates a variant with
1165 Compiling the source 1183 a "-native" suffix that builds for the build host.
1166 </para></listitem> 1184 </para></listitem>
1167 <listitem><para> 1185 </itemizedlist>
1168 Install the build output 1186 <note>
1169 </para></listitem> 1187 If you need to add a tool that is shipped as part of a
1170 <listitem><para> 1188 source tree that builds code for the target, you can
1171 Package the installed output 1189 typically accomplish this by building the native and target
1172 </para></listitem> 1190 parts separately rather than within the same compilation
1173 </orderedlist> 1191 process.
1174 For recipes in the workspace, fetching and unpacking is disabled 1192 Realize though that with the "&dash;&dash;also-native" option, you
1175 as the source tree has already been prepared and is persistent. 1193 can add the tool using just one recipe file.
1176 Each of these build steps is defined as a function, usually with a 1194 </note>
1177 "do_" prefix. 1195 </para>
1178 These functions are typically shell scripts but can instead be written 1196 </section>
1179 in Python. 1197
1180 </para> 1198 <section id='sdk-adding-node-js-modules'>
1181 1199 <title>Adding Node.js Modules</title>
1182 <para> 1200
1183 If you look at the contents of a recipe, you will see that the 1201 <para>
1184 recipe does not include complete instructions for building the 1202 You can use the <filename>devtool add</filename> command two
1185 software. 1203 different ways to add Node.js modules: 1) Through
1186 Instead, common functionality is encapsulated in classes inherited 1204 <filename>npm</filename> and, 2) from a repository or local
1187 with the <filename>inherit</filename> directive, leaving the recipe 1205 source.
1188 to describe just the things that are specific to the software to be 1206 </para>
1189 built. 1207
1190 A <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-base'><filename>base</filename></ulink> 1208 <para>
1191 class exists that is implicitly inherited by all recipes and provides 1209 Use the following form to add Node.js modules through
1192 the functionality that most typical recipes need. 1210 <filename>npm</filename>:
1193 </para> 1211 <literallayout class='monospaced'>
1194 1212 $ devtool add "npm://registry.npmjs.org;name=forever;version=0.15.1"
1195 <para> 1213 </literallayout>
1196 The remainder of this section presents information useful when 1214 The name and version parameters are mandatory.
1197 working with recipes. 1215 Lockdown and shrinkwrap files are generated and pointed to by
1198 </para> 1216 the recipe in order to freeze the version that is fetched for
1217 the dependencies according to the first time.
1218 This also saves checksums that are verified on future fetches.
1219 Together, these behaviors ensure the reproducibility and
1220 integrity of the build.
1221 <note><title>Notes</title>
1222 <itemizedlist>
1223 <listitem><para>
1224 You must use quotes around the URL.
1225 The <filename>devtool add</filename> does not require
1226 the quotes, but the shell considers ";" as a splitter
1227 between multiple commands.
1228 Thus, without the quotes,
1229 <filename>devtool add</filename> does not receive the
1230 other parts, which results in several "command not
1231 found" errors.
1232 </para></listitem>
1233 <listitem><para>
1234 In order to support adding
1235 Node.js modules, a
1236 <filename>nodejs</filename> recipe must be part of your
1237 SDK in order to provide Node.js
1238 itself.
1239 </para></listitem>
1240 </itemizedlist>
1241 </note>
1242 </para>
1199 1243
1200 <section id='sdk-finding-logs-and-work-files'> 1244 <para>
1201 <title>Finding Logs and Work Files</title> 1245 As mentioned earlier, you can also add Node.js modules
1246 directly from a repository or local source tree.
1247 To add modules this way, use <filename>devtool add</filename> in
1248 the following form:
1249 <literallayout class='monospaced'>
1250 $ devtool add https://github.com/diversario/node-ssdp
1251 </literallayout>
1252 In this example, <filename>devtool</filename> fetches the specified
1253 Git repository, detects that the code is Node.js code, fetches
1254 dependencies using <filename>npm</filename>, and sets
1255 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
1256 accordingly.
1257 </para>
1258 </section>
1259 </section>
1202 1260
1203 <para> 1261 <section id='sdk-working-with-recipes'>
1204 When you are debugging a recipe that you previously created using 1262 <title>Working With Recipes</title>
1205 <filename>devtool add</filename> or whose source you are modifying
1206 by using the <filename>devtool modify</filename> command, after
1207 the first run of <filename>devtool build</filename>, you will
1208 find some symbolic links created within the source tree:
1209 <filename>oe-logs</filename>, which points to the directory in
1210 which log files and run scripts for each build step are created
1211 and <filename>oe-workdir</filename>, which points to the temporary
1212 work area for the recipe.
1213 You can use these links to get more information on what is
1214 happening at each build step.
1215 </para>
1216 1263
1217 <para> 1264 <para>
1218 These locations under <filename>oe-workdir</filename> are 1265 When building a recipe with <filename>devtool build</filename> the
1219 particularly useful: 1266 typical build progression is as follows:
1220 <itemizedlist> 1267 <orderedlist>
1221 <listitem><para><filename>image/</filename>: 1268 <listitem><para>
1222 Contains all of the files installed at the 1269 Fetch the source
1223 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-install'><filename>do_install</filename></ulink>
1224 stage.
1225 Within a recipe, this directory is referred to by the
1226 expression
1227 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-D'><filename>D</filename></ulink><filename>}</filename>.
1228 </para></listitem> 1270 </para></listitem>
1229 <listitem><para><filename>sysroot-destdir/</filename>: 1271 <listitem><para>
1230 Contains a subset of files installed within 1272 Unpack the source
1231 <filename>do_install</filename> that have been put into the
1232 shared sysroot.
1233 For more information, see the
1234 "<link linkend='sdk-sharing-files-between-recipes'>Sharing Files Between Recipes</link>"
1235 section.
1236 </para></listitem> 1273 </para></listitem>
1237 <listitem><para><filename>packages-split/</filename>: 1274 <listitem><para>
1238 Contains subdirectories for each package produced by the 1275 Configure the source
1239 recipe.
1240 For more information, see the
1241 "<link linkend='sdk-packaging'>Packaging</link>" section.
1242 </para></listitem> 1276 </para></listitem>
1243 </itemizedlist> 1277 <listitem><para>
1244 </para> 1278 Compiling the source
1245 </section> 1279 </para></listitem>
1246 1280 <listitem><para>
1247 <section id='sdk-setting-configure-arguments'> 1281 Install the build output
1248 <title>Setting Configure Arguments</title> 1282 </para></listitem>
1249 1283 <listitem><para>
1250 <para> 1284 Package the installed output
1251 If the software your recipe is building uses GNU autoconf, 1285 </para></listitem>
1252 then a fixed set of arguments is passed to it to enable 1286 </orderedlist>
1253 cross-compilation plus any extras specified by 1287 For recipes in the workspace, fetching and unpacking is disabled
1254 <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></ulink> 1288 as the source tree has already been prepared and is persistent.
1255 or 1289 Each of these build steps is defined as a function, usually with a
1256 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGECONFIG_CONFARGS'><filename>PACKAGECONFIG_CONFARGS</filename></ulink> 1290 "do_" prefix.
1257 set within the recipe. 1291 These functions are typically shell scripts but can instead be written
1258 If you wish to pass additional options, add them to 1292 in Python.
1259 <filename>EXTRA_OECONF</filename> or
1260 <filename>PACKAGECONFIG_CONFARGS</filename>.
1261 Other supported build tools have similar variables
1262 (e.g.
1263 <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OECMAKE'><filename>EXTRA_OECMAKE</filename></ulink>
1264 for CMake,
1265 <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OESCONS'><filename>EXTRA_OESCONS</filename></ulink>
1266 for Scons, and so forth).
1267 If you need to pass anything on the <filename>make</filename>
1268 command line, you can use <filename>EXTRA_OEMAKE</filename> or the
1269 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGECONFIG_CONFARGS'><filename>PACKAGECONFIG_CONFARGS</filename></ulink>
1270 variables to do so.
1271 </para> 1293 </para>
1272 1294
1273 <para> 1295 <para>
1274 You can use the <filename>devtool configure-help</filename> command 1296 If you look at the contents of a recipe, you will see that the
1275 to help you set the arguments listed in the previous paragraph. 1297 recipe does not include complete instructions for building the
1276 The command determines the exact options being passed, and shows 1298 software.
1277 them to you along with any custom arguments specified through 1299 Instead, common functionality is encapsulated in classes inherited
1278 <filename>EXTRA_OECONF</filename> or 1300 with the <filename>inherit</filename> directive, leaving the recipe
1279 <filename>PACKAGECONFIG_CONFARGS</filename>. 1301 to describe just the things that are specific to the software to be
1280 If applicable, the command also shows you the output of the 1302 built.
1281 configure script's "&dash;&dash;help" option as a reference. 1303 A <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-base'><filename>base</filename></ulink>
1304 class exists that is implicitly inherited by all recipes and provides
1305 the functionality that most typical recipes need.
1282 </para> 1306 </para>
1283 </section>
1284
1285 <section id='sdk-sharing-files-between-recipes'>
1286 <title>Sharing Files Between Recipes</title>
1287 1307
1288 <para> 1308 <para>
1289 Recipes often need to use files provided by other recipes on 1309 The remainder of this section presents information useful when
1290 the build host. 1310 working with recipes.
1291 For example, an application linking to a common library needs
1292 access to the library itself and its associated headers.
1293 The way this access is accomplished within the extensible SDK is
1294 through the sysroot.
1295 One sysroot exists per "machine" for which the SDK is being built.
1296 In practical terms, this means a sysroot exists for the target
1297 machine, and a sysroot exists for the build host.
1298 </para> 1311 </para>
1299 1312
1300 <para> 1313 <section id='sdk-finding-logs-and-work-files'>
1301 Recipes should never write files directly into the sysroot. 1314 <title>Finding Logs and Work Files</title>
1302 Instead, files should be installed into standard locations 1315
1303 during the 1316 <para>
1304 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-install'><filename>do_install</filename></ulink> 1317 When you are debugging a recipe that you previously created using
1305 task within the 1318 <filename>devtool add</filename> or whose source you are modifying
1306 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-D'><filename>D</filename></ulink><filename>}</filename> 1319 by using the <filename>devtool modify</filename> command, after
1307 directory. 1320 the first run of <filename>devtool build</filename>, you will
1308 A subset of these files automatically go into the sysroot. 1321 find some symbolic links created within the source tree:
1309 The reason for this limitation is that almost all files that go 1322 <filename>oe-logs</filename>, which points to the directory in
1310 into the sysroot are cataloged in manifests in order to ensure 1323 which log files and run scripts for each build step are created
1311 they can be removed later when a recipe is modified or removed. 1324 and <filename>oe-workdir</filename>, which points to the temporary
1312 Thus, the sysroot is able to remain free from stale files. 1325 work area for the recipe.
1313 </para> 1326 You can use these links to get more information on what is
1327 happening at each build step.
1328 </para>
1329
1330 <para>
1331 These locations under <filename>oe-workdir</filename> are
1332 particularly useful:
1333 <itemizedlist>
1334 <listitem><para><filename>image/</filename>:
1335 Contains all of the files installed at the
1336 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-install'><filename>do_install</filename></ulink>
1337 stage.
1338 Within a recipe, this directory is referred to by the
1339 expression
1340 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-D'><filename>D</filename></ulink><filename>}</filename>.
1341 </para></listitem>
1342 <listitem><para><filename>sysroot-destdir/</filename>:
1343 Contains a subset of files installed within
1344 <filename>do_install</filename> that have been put into the
1345 shared sysroot.
1346 For more information, see the
1347 "<link linkend='sdk-sharing-files-between-recipes'>Sharing Files Between Recipes</link>"
1348 section.
1349 </para></listitem>
1350 <listitem><para><filename>packages-split/</filename>:
1351 Contains subdirectories for each package produced by the
1352 recipe.
1353 For more information, see the
1354 "<link linkend='sdk-packaging'>Packaging</link>" section.
1355 </para></listitem>
1356 </itemizedlist>
1357 </para>
1358 </section>
1359
1360 <section id='sdk-setting-configure-arguments'>
1361 <title>Setting Configure Arguments</title>
1362
1363 <para>
1364 If the software your recipe is building uses GNU autoconf,
1365 then a fixed set of arguments is passed to it to enable
1366 cross-compilation plus any extras specified by
1367 <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></ulink>
1368 or
1369 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGECONFIG_CONFARGS'><filename>PACKAGECONFIG_CONFARGS</filename></ulink>
1370 set within the recipe.
1371 If you wish to pass additional options, add them to
1372 <filename>EXTRA_OECONF</filename> or
1373 <filename>PACKAGECONFIG_CONFARGS</filename>.
1374 Other supported build tools have similar variables
1375 (e.g.
1376 <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OECMAKE'><filename>EXTRA_OECMAKE</filename></ulink>
1377 for CMake,
1378 <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OESCONS'><filename>EXTRA_OESCONS</filename></ulink>
1379 for Scons, and so forth).
1380 If you need to pass anything on the <filename>make</filename>
1381 command line, you can use <filename>EXTRA_OEMAKE</filename> or the
1382 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGECONFIG_CONFARGS'><filename>PACKAGECONFIG_CONFARGS</filename></ulink>
1383 variables to do so.
1384 </para>
1385
1386 <para>
1387 You can use the <filename>devtool configure-help</filename> command
1388 to help you set the arguments listed in the previous paragraph.
1389 The command determines the exact options being passed, and shows
1390 them to you along with any custom arguments specified through
1391 <filename>EXTRA_OECONF</filename> or
1392 <filename>PACKAGECONFIG_CONFARGS</filename>.
1393 If applicable, the command also shows you the output of the
1394 configure script's "&dash;&dash;help" option as a reference.
1395 </para>
1396 </section>
1397
1398 <section id='sdk-sharing-files-between-recipes'>
1399 <title>Sharing Files Between Recipes</title>
1400
1401 <para>
1402 Recipes often need to use files provided by other recipes on
1403 the build host.
1404 For example, an application linking to a common library needs
1405 access to the library itself and its associated headers.
1406 The way this access is accomplished within the extensible SDK is
1407 through the sysroot.
1408 One sysroot exists per "machine" for which the SDK is being built.
1409 In practical terms, this means a sysroot exists for the target
1410 machine, and a sysroot exists for the build host.
1411 </para>
1412
1413 <para>
1414 Recipes should never write files directly into the sysroot.
1415 Instead, files should be installed into standard locations
1416 during the
1417 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-install'><filename>do_install</filename></ulink>
1418 task within the
1419 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-D'><filename>D</filename></ulink><filename>}</filename>
1420 directory.
1421 A subset of these files automatically go into the sysroot.
1422 The reason for this limitation is that almost all files that go
1423 into the sysroot are cataloged in manifests in order to ensure
1424 they can be removed later when a recipe is modified or removed.
1425 Thus, the sysroot is able to remain free from stale files.
1426 </para>
1427 </section>
1428
1429 <section id='sdk-packaging'>
1430 <title>Packaging</title>
1431
1432 <para>
1433 Packaging is not always particularly relevant within the
1434 extensible SDK.
1435 However, if you examine how build output gets into the final image
1436 on the target device, it is important to understand packaging
1437 because the contents of the image are expressed in terms of
1438 packages and not recipes.
1439 </para>
1440
1441 <para>
1442 During the
1443 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package'><filename>do_package</filename></ulink>
1444 task, files installed during the
1445 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-install'><filename>do_install</filename></ulink>
1446 task are split into one main package, which is almost always named
1447 the same as the recipe, and several other packages.
1448 This separation is done because not all of those installed files
1449 are always useful in every image.
1450 For example, you probably do not need any of the documentation
1451 installed in a production image.
1452 Consequently, for each recipe the documentation files are separated
1453 into a <filename>-doc</filename> package.
1454 Recipes that package software that has optional modules or
1455 plugins might do additional package splitting as well.
1456 </para>
1457
1458 <para>
1459 After building a recipe you can see where files have gone by
1460 looking in the <filename>oe-workdir/packages-split</filename>
1461 directory, which contains a subdirectory for each package.
1462 Apart from some advanced cases, the
1463 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'><filename>PACKAGES</filename></ulink>
1464 and
1465 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILES'><filename>FILES</filename></ulink>
1466 variables controls splitting.
1467 The <filename>PACKAGES</filename> variable lists all of the
1468 packages to be produced, while the <filename>FILES</filename>
1469 variable specifies which files to include in each package,
1470 using an override to specify the package.
1471 For example, <filename>FILES_${PN}</filename> specifies the files
1472 to go into the main package (i.e. the main package is named the
1473 same as the recipe and
1474 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink><filename>}</filename>
1475 evaluates to the recipe name).
1476 The order of the <filename>PACKAGES</filename> value is significant.
1477 For each installed file, the first package whose
1478 <filename>FILES</filename> value matches the file is the package
1479 into which the file goes.
1480 Defaults exist for both the <filename>PACKAGES</filename> and
1481 <filename>FILES</filename> variables.
1482 Consequently, you might find you do not even need to set these
1483 variables in your recipe unless the software the recipe is
1484 building installs files into non-standard locations.
1485 </para>
1486 </section>
1314 </section> 1487 </section>
1315 1488
1316 <section id='sdk-packaging'> 1489 <section id='sdk-restoring-the-target-device-to-its-original-state'>
1317 <title>Packaging</title> 1490 <title>Restoring the Target Device to its Original State</title>
1318 1491
1319 <para> 1492 <para>
1320 Packaging is not always particularly relevant within the 1493 If you use the <filename>devtool deploy-target</filename>
1321 extensible SDK. 1494 command to write a recipe's build output to the target, and
1322 However, if you examine how build output gets into the final image 1495 you are working on an existing component of the system, then you
1323 on the target device, it is important to understand packaging 1496 might find yourself in a situation where you need to restore the
1324 because the contents of the image are expressed in terms of 1497 original files that existed prior to running the
1325 packages and not recipes. 1498 <filename>devtool deploy-target</filename> command.
1326 </para> 1499 Because the <filename>devtool deploy-target</filename> command
1327 1500 backs up any files it overwrites, you can use the
1328 <para> 1501 <filename>devtool undeploy-target</filename> to restore those files
1329 During the 1502 and remove any other files the recipe deployed.
1330 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package'><filename>do_package</filename></ulink> 1503 Consider the following example:
1331 task, files installed during the 1504 <literallayout class='monospaced'>
1332 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-install'><filename>do_install</filename></ulink>
1333 task are split into one main package, which is almost always named
1334 the same as the recipe, and several other packages.
1335 This separation is done because not all of those installed files
1336 are always useful in every image.
1337 For example, you probably do not need any of the documentation
1338 installed in a production image.
1339 Consequently, for each recipe the documentation files are separated
1340 into a <filename>-doc</filename> package.
1341 Recipes that package software that has optional modules or
1342 plugins might do additional package splitting as well.
1343 </para>
1344
1345 <para>
1346 After building a recipe you can see where files have gone by
1347 looking in the <filename>oe-workdir/packages-split</filename>
1348 directory, which contains a subdirectory for each package.
1349 Apart from some advanced cases, the
1350 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'><filename>PACKAGES</filename></ulink>
1351 and
1352 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILES'><filename>FILES</filename></ulink>
1353 variables controls splitting.
1354 The <filename>PACKAGES</filename> variable lists all of the
1355 packages to be produced, while the <filename>FILES</filename>
1356 variable specifies which files to include in each package,
1357 using an override to specify the package.
1358 For example, <filename>FILES_${PN}</filename> specifies the files
1359 to go into the main package (i.e. the main package is named the
1360 same as the recipe and
1361 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink><filename>}</filename>
1362 evaluates to the recipe name).
1363 The order of the <filename>PACKAGES</filename> value is significant.
1364 For each installed file, the first package whose
1365 <filename>FILES</filename> value matches the file is the package
1366 into which the file goes.
1367 Defaults exist for both the <filename>PACKAGES</filename> and
1368 <filename>FILES</filename> variables.
1369 Consequently, you might find you do not even need to set these
1370 variables in your recipe unless the software the recipe is
1371 building installs files into non-standard locations.
1372 </para>
1373 </section>
1374</section>
1375
1376<section id='sdk-restoring-the-target-device-to-its-original-state'>
1377 <title>Restoring the Target Device to its Original State</title>
1378
1379 <para>
1380 If you use the <filename>devtool deploy-target</filename>
1381 command to write a recipe's build output to the target, and
1382 you are working on an existing component of the system, then you
1383 might find yourself in a situation where you need to restore the
1384 original files that existed prior to running the
1385 <filename>devtool deploy-target</filename> command.
1386 Because the <filename>devtool deploy-target</filename> command
1387 backs up any files it overwrites, you can use the
1388 <filename>devtool undeploy-target</filename> to restore those files
1389 and remove any other files the recipe deployed.
1390 Consider the following example:
1391 <literallayout class='monospaced'>
1392 $ devtool undeploy-target lighttpd root@192.168.7.2 1505 $ devtool undeploy-target lighttpd root@192.168.7.2
1393 </literallayout> 1506 </literallayout>
1394 If you have deployed multiple applications, you can remove them 1507 If you have deployed multiple applications, you can remove them
1395 all at once thus restoring the target device back to its 1508 all at once thus restoring the target device back to its
1396 original state: 1509 original state:
1397 <literallayout class='monospaced'> 1510 <literallayout class='monospaced'>
1398 $ devtool undeploy-target -a root@192.168.7.2 1511 $ devtool undeploy-target -a root@192.168.7.2
1399 </literallayout> 1512 </literallayout>
1400 Information about files deployed to the target as well as any 1513 Information about files deployed to the target as well as any
1401 backed up files are stored on the target itself. 1514 backed up files are stored on the target itself.
1402 This storage of course requires some additional space 1515 This storage of course requires some additional space
1403 on the target machine. 1516 on the target machine.
1404 <note> 1517 <note>
1405 The <filename>devtool deploy-target</filename> and 1518 The <filename>devtool deploy-target</filename> and
1406 <filename>devtool undeploy-target</filename> command do not 1519 <filename>devtool undeploy-target</filename> command do not
1407 currently interact with any package management system on the 1520 currently interact with any package management system on the
1408 target device (e.g. RPM or OPKG). 1521 target device (e.g. RPM or OPKG).
1409 Consequently, you should not intermingle operations 1522 Consequently, you should not intermingle operations
1410 <filename>devtool deploy-target</filename> and the package 1523 <filename>devtool deploy-target</filename> and the package
1411 manager operations on the target device. 1524 manager operations on the target device.
1412 Doing so could result in a conflicting set of files. 1525 Doing so could result in a conflicting set of files.
1413 </note> 1526 </note>
1414 </para> 1527 </para>
1415</section> 1528 </section>
1416 1529
1417<section id='sdk-installing-additional-items-into-the-extensible-sdk'> 1530 <section id='sdk-installing-additional-items-into-the-extensible-sdk'>
1418 <title>Installing Additional Items Into the Extensible SDK</title> 1531 <title>Installing Additional Items Into the Extensible SDK</title>
1419 1532
1420 <para> 1533 <para>
1421 The extensible SDK typically only comes with a small number of tools 1534 The extensible SDK typically only comes with a small number of tools
1422 and libraries out of the box. 1535 and libraries out of the box.
1423 If you have a minimal SDK, then it starts mostly empty and is 1536 If you have a minimal SDK, then it starts mostly empty and is
1424 populated on-demand. 1537 populated on-demand.
1425 However, sometimes you will need to explicitly install extra items 1538 However, sometimes you will need to explicitly install extra items
1426 into the SDK. 1539 into the SDK.
1427 If you need these extra items, you can first search for the items 1540 If you need these extra items, you can first search for the items
1428 using the <filename>devtool search</filename> command. 1541 using the <filename>devtool search</filename> command.
1429 For example, suppose you need to link to libGL but you are not sure 1542 For example, suppose you need to link to libGL but you are not sure
1430 which recipe provides it. 1543 which recipe provides it.
1431 You can use the following command to find out: 1544 You can use the following command to find out:
1432 <literallayout class='monospaced'> 1545 <literallayout class='monospaced'>
1433 $ devtool search libGL 1546 $ devtool search libGL
1434 mesa A free implementation of the OpenGL API 1547 mesa A free implementation of the OpenGL API
1435 </literallayout> 1548 </literallayout>
1436 Once you know the recipe (i.e. <filename>mesa</filename> in this 1549 Once you know the recipe (i.e. <filename>mesa</filename> in this
1437 example), you can install it: 1550 example), you can install it:
1438 <literallayout class='monospaced'> 1551 <literallayout class='monospaced'>
1439 $ devtool sdk-install mesa 1552 $ devtool sdk-install mesa
1440 </literallayout> 1553 </literallayout>
1441 By default, the <filename>devtool sdk-install</filename> assumes the 1554 By default, the <filename>devtool sdk-install</filename> assumes the
1442 item is available in pre-built form from your SDK provider. 1555 item is available in pre-built form from your SDK provider.
1443 If the item is not available and it is acceptable to build the item 1556 If the item is not available and it is acceptable to build the item
1444 from source, you can add the "-s" option as follows: 1557 from source, you can add the "-s" option as follows:
1445 <literallayout class='monospaced'> 1558 <literallayout class='monospaced'>
1446 $ devtool sdk-install -s mesa 1559 $ devtool sdk-install -s mesa
1447 </literallayout> 1560 </literallayout>
1448 It is important to remember that building the item from source takes 1561 It is important to remember that building the item from source takes
1449 significantly longer than installing the pre-built artifact. 1562 significantly longer than installing the pre-built artifact.
1450 Also, if no recipe exists for the item you want to add to the SDK, you 1563 Also, if no recipe exists for the item you want to add to the SDK, you
1451 must instead add it using the <filename>devtool add</filename> command. 1564 must instead add it using the <filename>devtool add</filename> command.
1452 </para> 1565 </para>
1453</section> 1566 </section>
1454 1567
1455<section id='sdk-updating-the-extensible-sdk'> 1568 <section id='sdk-updating-the-extensible-sdk'>
1456 <title>Updating the Extensible SDK</title> 1569 <title>Updating the Extensible SDK</title>
1457 1570
1458 <para> 1571 <para>
1459 If you are working with an extensible SDK that gets occasionally 1572 If you are working with an extensible SDK that gets occasionally
1460 updated (e.g. typically when that SDK has been provided to you by 1573 updated (e.g. typically when that SDK has been provided to you by
1461 another party), then you will need to manually pull down those 1574 another party), then you will need to manually pull down those
1462 updates to your installed SDK. 1575 updates to your installed SDK.
1463 </para> 1576 </para>
1464 1577
1465 <para> 1578 <para>
1466 To update your installed SDK, run the following: 1579 To update your installed SDK, run the following:
1467 <literallayout class='monospaced'> 1580 <literallayout class='monospaced'>
1468 $ devtool sdk-update 1581 $ devtool sdk-update
1469 </literallayout> 1582 </literallayout>
1470 The previous command assumes your SDK provider has set the default 1583 The previous command assumes your SDK provider has set the default
1471 update URL for you. 1584 update URL for you.
1472 If that URL has not been set, you need to specify it yourself as 1585 If that URL has not been set, you need to specify it yourself as
1473 follows: 1586 follows:
1474 <literallayout class='monospaced'> 1587 <literallayout class='monospaced'>
1475 $ devtool sdk-update <replaceable>path_to_update_directory</replaceable> 1588 $ devtool sdk-update <replaceable>path_to_update_directory</replaceable>
1476 </literallayout> 1589 </literallayout>
1477 <note> 1590 <note>
1478 The URL needs to point specifically to a published SDK and not an 1591 The URL needs to point specifically to a published SDK and not an
1479 SDK installer that you would download and install. 1592 SDK installer that you would download and install.
1480 </note> 1593 </note>
1481 </para> 1594 </para>
1482</section> 1595 </section>
1483
1484<section id='sdk-creating-a-derivative-sdk-with-additional-components'>
1485 <title>Creating a Derivative SDK With Additional Components</title>
1486 1596
1487 <para> 1597 <section id='sdk-creating-a-derivative-sdk-with-additional-components'>
1488 You might need to produce an SDK that contains your own custom 1598 <title>Creating a Derivative SDK With Additional Components</title>
1489 libraries for sending to a third party (e.g., if you are a vendor with
1490 customers needing to build their own software for the target platform).
1491 If that is the case, then you can produce a derivative SDK based on
1492 the currently installed SDK fairly easily.
1493 Use these steps:
1494 <orderedlist>
1495 <listitem><para>If necessary, install an extensible SDK that
1496 you want to use as a base for your derivative SDK.
1497 </para></listitem>
1498 <listitem><para>Source the environment script for the SDK.
1499 </para></listitem>
1500 <listitem><para>Add the extra libraries or other components
1501 you want by using the <filename>devtool add</filename>
1502 command.
1503 </para></listitem>
1504 <listitem><para>Run the <filename>devtool build-sdk</filename>
1505 command.
1506 </para></listitem>
1507 </orderedlist>
1508 The above procedure takes the recipes added to the workspace and
1509 constructs a new SDK installer containing those recipes and the
1510 resulting binary artifacts.
1511 The recipes go into their own separate layer in the constructed
1512 derivative SDK, leaving the workspace clean and ready for users
1513 to add their own recipes.
1514 </para>
1515</section>
1516 1599
1600 <para>
1601 You might need to produce an SDK that contains your own custom
1602 libraries for sending to a third party (e.g., if you are a vendor with
1603 customers needing to build their own software for the target platform).
1604 If that is the case, then you can produce a derivative SDK based on
1605 the currently installed SDK fairly easily.
1606 Use these steps:
1607 <orderedlist>
1608 <listitem><para>If necessary, install an extensible SDK that
1609 you want to use as a base for your derivative SDK.
1610 </para></listitem>
1611 <listitem><para>Source the environment script for the SDK.
1612 </para></listitem>
1613 <listitem><para>Add the extra libraries or other components
1614 you want by using the <filename>devtool add</filename>
1615 command.
1616 </para></listitem>
1617 <listitem><para>Run the <filename>devtool build-sdk</filename>
1618 command.
1619 </para></listitem>
1620 </orderedlist>
1621 The above procedure takes the recipes added to the workspace and
1622 constructs a new SDK installer containing those recipes and the
1623 resulting binary artifacts.
1624 The recipes go into their own separate layer in the constructed
1625 derivative SDK, leaving the workspace clean and ready for users
1626 to add their own recipes.
1627 </para>
1628 </section>
1517</chapter> 1629</chapter>
1518<!-- 1630<!--
1519vim: expandtab tw=80 ts=4 1631vim: expandtab tw=80 ts=4
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2025-01-12 19:19:59 +0000