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