diff options
Diffstat (limited to 'documentation/ref-manual/ref-devtool-reference.xml')
-rw-r--r-- | documentation/ref-manual/ref-devtool-reference.xml | 842 |
1 files changed, 0 insertions, 842 deletions
diff --git a/documentation/ref-manual/ref-devtool-reference.xml b/documentation/ref-manual/ref-devtool-reference.xml deleted file mode 100644 index 6c3ccc3034..0000000000 --- a/documentation/ref-manual/ref-devtool-reference.xml +++ /dev/null | |||
@@ -1,842 +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='ref-devtool-reference'> | ||
7 | <title><filename>devtool</filename> Quick Reference</title> | ||
8 | |||
9 | <para> | ||
10 | The <filename>devtool</filename> command-line tool provides a number | ||
11 | of features that help you build, test, and package software. | ||
12 | This command is available alongside the <filename>bitbake</filename> | ||
13 | command. | ||
14 | Additionally, the <filename>devtool</filename> command is a key | ||
15 | part of the extensible SDK. | ||
16 | </para> | ||
17 | |||
18 | <para> | ||
19 | This chapter provides a Quick Reference for the | ||
20 | <filename>devtool</filename> command. | ||
21 | For more information on how to apply the command when using the | ||
22 | extensible SDK, see the | ||
23 | "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-extensible'>Using the Extensible SDK</ulink>" | ||
24 | chapter in the Yocto Project Application Development and the | ||
25 | Extensible Software Development Kit (eSDK) manual. | ||
26 | </para> | ||
27 | |||
28 | <section id='devtool-getting-help'> | ||
29 | <title>Getting Help</title> | ||
30 | |||
31 | <para> | ||
32 | The <filename>devtool</filename> command line is organized | ||
33 | similarly to Git in that it has a number of sub-commands for | ||
34 | each function. | ||
35 | You can run <filename>devtool --help</filename> to see all | ||
36 | the commands: | ||
37 | <literallayout class='monospaced'> | ||
38 | $ devtool -h | ||
39 | NOTE: Starting bitbake server... | ||
40 | usage: devtool [--basepath BASEPATH] [--bbpath BBPATH] [-d] [-q] | ||
41 | [--color COLOR] [-h] | ||
42 | <subcommand> ... | ||
43 | |||
44 | OpenEmbedded development tool | ||
45 | |||
46 | options: | ||
47 | --basepath BASEPATH Base directory of SDK / build directory | ||
48 | --bbpath BBPATH Explicitly specify the BBPATH, rather than getting it | ||
49 | from the metadata | ||
50 | -d, --debug Enable debug output | ||
51 | -q, --quiet Print only errors | ||
52 | --color COLOR Colorize output (where COLOR is auto, always, never) | ||
53 | -h, --help show this help message and exit | ||
54 | |||
55 | subcommands: | ||
56 | Beginning work on a recipe: | ||
57 | add Add a new recipe | ||
58 | modify Modify the source for an existing recipe | ||
59 | upgrade Upgrade an existing recipe | ||
60 | Getting information: | ||
61 | status Show workspace status | ||
62 | search Search available recipes | ||
63 | latest-version Report the latest version of an existing recipe | ||
64 | check-upgrade-status Report upgradability for multiple (or all) recipes | ||
65 | Working on a recipe in the workspace: | ||
66 | build Build a recipe | ||
67 | rename Rename a recipe file in the workspace | ||
68 | edit-recipe Edit a recipe file | ||
69 | find-recipe Find a recipe file | ||
70 | configure-help Get help on configure script options | ||
71 | update-recipe Apply changes from external source tree to recipe | ||
72 | reset Remove a recipe from your workspace | ||
73 | finish Finish working on a recipe in your workspace | ||
74 | Testing changes on target: | ||
75 | deploy-target Deploy recipe output files to live target machine | ||
76 | undeploy-target Undeploy recipe output files in live target machine | ||
77 | build-image Build image including workspace recipe packages | ||
78 | Advanced: | ||
79 | create-workspace Set up workspace in an alternative location | ||
80 | export Export workspace into a tar archive | ||
81 | import Import exported tar archive into workspace | ||
82 | extract Extract the source for an existing recipe | ||
83 | sync Synchronize the source tree for an existing recipe | ||
84 | Use devtool <subcommand> --help to get help on a specific command | ||
85 | </literallayout> | ||
86 | As directed in the general help output, you can get more syntax | ||
87 | on a specific command by providing the command name and using | ||
88 | "--help": | ||
89 | <literallayout class='monospaced'> | ||
90 | $ devtool add --help | ||
91 | NOTE: Starting bitbake server... | ||
92 | usage: devtool add [-h] [--same-dir | --no-same-dir] [--fetch URI] | ||
93 | [--fetch-dev] [--version VERSION] [--no-git] | ||
94 | [--srcrev SRCREV | --autorev] [--srcbranch SRCBRANCH] | ||
95 | [--binary] [--also-native] [--src-subdir SUBDIR] | ||
96 | [--mirrors] [--provides PROVIDES] | ||
97 | [recipename] [srctree] [fetchuri] | ||
98 | |||
99 | Adds a new recipe to the workspace to build a specified source tree. Can | ||
100 | optionally fetch a remote URI and unpack it to create the source tree. | ||
101 | |||
102 | arguments: | ||
103 | recipename Name for new recipe to add (just name - no version, | ||
104 | path or extension). If not specified, will attempt to | ||
105 | auto-detect it. | ||
106 | srctree Path to external source tree. If not specified, a | ||
107 | subdirectory of | ||
108 | /home/scottrif/poky/build/workspace/sources will be | ||
109 | used. | ||
110 | fetchuri Fetch the specified URI and extract it to create the | ||
111 | source tree | ||
112 | |||
113 | options: | ||
114 | -h, --help show this help message and exit | ||
115 | --same-dir, -s Build in same directory as source | ||
116 | --no-same-dir Force build in a separate build directory | ||
117 | --fetch URI, -f URI Fetch the specified URI and extract it to create the | ||
118 | source tree (deprecated - pass as positional argument | ||
119 | instead) | ||
120 | --fetch-dev For npm, also fetch devDependencies | ||
121 | --version VERSION, -V VERSION | ||
122 | Version to use within recipe (PV) | ||
123 | --no-git, -g If fetching source, do not set up source tree as a git | ||
124 | repository | ||
125 | --srcrev SRCREV, -S SRCREV | ||
126 | Source revision to fetch if fetching from an SCM such | ||
127 | as git (default latest) | ||
128 | --autorev, -a When fetching from a git repository, set SRCREV in the | ||
129 | recipe to a floating revision instead of fixed | ||
130 | --srcbranch SRCBRANCH, -B SRCBRANCH | ||
131 | Branch in source repository if fetching from an SCM | ||
132 | such as git (default master) | ||
133 | --binary, -b Treat the source tree as something that should be | ||
134 | installed verbatim (no compilation, same directory | ||
135 | structure). Useful with binary packages e.g. RPMs. | ||
136 | --also-native Also add native variant (i.e. support building recipe | ||
137 | for the build host as well as the target machine) | ||
138 | --src-subdir SUBDIR Specify subdirectory within source tree to use | ||
139 | --mirrors Enable PREMIRRORS and MIRRORS for source tree fetching | ||
140 | (disable by default). | ||
141 | --provides PROVIDES, -p PROVIDES | ||
142 | Specify an alias for the item provided by the recipe. | ||
143 | E.g. virtual/libgl | ||
144 | </literallayout> | ||
145 | </para> | ||
146 | </section> | ||
147 | |||
148 | <section id='devtool-the-workspace-layer-structure'> | ||
149 | <title>The Workspace Layer Structure</title> | ||
150 | |||
151 | <para> | ||
152 | <filename>devtool</filename> uses a "Workspace" layer | ||
153 | in which to accomplish builds. | ||
154 | This layer is not specific to any single | ||
155 | <filename>devtool</filename> command but is rather a common | ||
156 | working area used across the tool. | ||
157 | </para> | ||
158 | |||
159 | <para> | ||
160 | The following figure shows the workspace structure: | ||
161 | </para> | ||
162 | |||
163 | <para> | ||
164 | <imagedata fileref="figures/build-workspace-directory.png" | ||
165 | width="6in" depth="5in" align="left" scale="70" /> | ||
166 | </para> | ||
167 | |||
168 | <para> | ||
169 | <literallayout class='monospaced'> | ||
170 | attic - A directory created if devtool believes it must preserve | ||
171 | anything when you run "devtool reset". For example, if you | ||
172 | run "devtool add", make changes to the recipe, and then | ||
173 | run "devtool reset", devtool takes notice that the file has | ||
174 | been changed and moves it into the attic should you still | ||
175 | want the recipe. | ||
176 | |||
177 | README - Provides information on what is in workspace layer and how to | ||
178 | manage it. | ||
179 | |||
180 | .devtool_md5 - A checksum file used by devtool. | ||
181 | |||
182 | appends - A directory that contains *.bbappend files, which point to | ||
183 | external source. | ||
184 | |||
185 | conf - A configuration directory that contains the layer.conf file. | ||
186 | |||
187 | recipes - A directory containing recipes. This directory contains a | ||
188 | folder for each directory added whose name matches that of the | ||
189 | added recipe. devtool places the <replaceable>recipe</replaceable>.bb file | ||
190 | within that sub-directory. | ||
191 | |||
192 | sources - A directory containing a working copy of the source files used | ||
193 | when building the recipe. This is the default directory used | ||
194 | as the location of the source tree when you do not provide a | ||
195 | source tree path. This directory contains a folder for each | ||
196 | set of source files matched to a corresponding recipe. | ||
197 | </literallayout> | ||
198 | </para> | ||
199 | </section> | ||
200 | |||
201 | <section id='devtool-adding-a-new-recipe-to-the-workspace'> | ||
202 | <title>Adding a New Recipe to the Workspace Layer</title> | ||
203 | |||
204 | <para> | ||
205 | Use the <filename>devtool add</filename> command to add a new recipe | ||
206 | to the workspace layer. | ||
207 | The recipe you add should not exist - | ||
208 | <filename>devtool</filename> creates it for you. | ||
209 | The source files the recipe uses should exist in an external | ||
210 | area. | ||
211 | </para> | ||
212 | |||
213 | <para> | ||
214 | The following example creates and adds a new recipe named | ||
215 | <filename>jackson</filename> to a workspace layer the tool creates. | ||
216 | The source code built by the recipes resides in | ||
217 | <filename>/home/<replaceable>user</replaceable>/sources/jackson</filename>: | ||
218 | <literallayout class='monospaced'> | ||
219 | $ devtool add jackson /home/<replaceable>user</replaceable>/sources/jackson | ||
220 | </literallayout> | ||
221 | </para> | ||
222 | |||
223 | <para> | ||
224 | If you add a recipe and the workspace layer does not exist, | ||
225 | the command creates the layer and populates it as | ||
226 | described in | ||
227 | "<link linkend='devtool-the-workspace-layer-structure'>The Workspace Layer Structure</link>" | ||
228 | section. | ||
229 | </para> | ||
230 | |||
231 | <para> | ||
232 | Running <filename>devtool add</filename> when the | ||
233 | workspace layer exists causes the tool to add the recipe, | ||
234 | append files, and source files into the existing workspace layer. | ||
235 | The <filename>.bbappend</filename> file is created to point | ||
236 | to the external source tree. | ||
237 | <note> | ||
238 | If your recipe has runtime dependencies defined, you must be sure | ||
239 | that these packages exist on the target hardware before attempting | ||
240 | to run your application. | ||
241 | If dependent packages (e.g. libraries) do not exist on the target, | ||
242 | your application, when run, will fail to find those functions. | ||
243 | For more information, see the | ||
244 | "<link linkend='devtool-deploying-your-software-on-the-target-machine'>Deploying Your Software on the Target Machine</link>" | ||
245 | section. | ||
246 | </note> | ||
247 | </para> | ||
248 | |||
249 | <para> | ||
250 | By default, <filename>devtool add</filename> uses the latest | ||
251 | revision (i.e. master) when unpacking files from a remote URI. | ||
252 | In some cases, you might want to specify a source revision by | ||
253 | branch, tag, or commit hash. You can specify these options when | ||
254 | using the <filename>devtool add</filename> command: | ||
255 | <itemizedlist> | ||
256 | <listitem><para> | ||
257 | To specify a source branch, use the | ||
258 | <filename>--srcbranch</filename> option: | ||
259 | <literallayout class='monospaced'> | ||
260 | $ devtool add --srcbranch &DISTRO_NAME_NO_CAP; jackson /home/<replaceable>user</replaceable>/sources/jackson | ||
261 | </literallayout> | ||
262 | In the previous example, you are checking out the | ||
263 | &DISTRO_NAME_NO_CAP; branch. | ||
264 | </para></listitem> | ||
265 | <listitem><para> | ||
266 | To specify a specific tag or commit hash, use the | ||
267 | <filename>--srcrev</filename> option: | ||
268 | <literallayout class='monospaced'> | ||
269 | $ devtool add --srcrev &DISTRO_REL_TAG; jackson /home/<replaceable>user</replaceable>/sources/jackson | ||
270 | $ devtool add --srcrev <replaceable>some_commit_hash</replaceable> /home/<replaceable>user</replaceable>/sources/jackson | ||
271 | </literallayout> | ||
272 | The previous examples check out the &DISTRO_REL_TAG; tag | ||
273 | and the commit associated with the | ||
274 | <replaceable>some_commit_hash</replaceable> hash. | ||
275 | </para></listitem> | ||
276 | </itemizedlist> | ||
277 | <note> | ||
278 | If you prefer to use the latest revision every time the recipe is | ||
279 | built, use the options <filename>--autorev</filename> | ||
280 | or <filename>-a</filename>. | ||
281 | </note> | ||
282 | </para> | ||
283 | </section> | ||
284 | |||
285 | <section id='devtool-extracting-the-source-for-an-existing-recipe'> | ||
286 | <title>Extracting the Source for an Existing Recipe</title> | ||
287 | |||
288 | <para> | ||
289 | Use the <filename>devtool extract</filename> command to | ||
290 | extract the source for an existing recipe. | ||
291 | When you use this command, you must supply the root name | ||
292 | of the recipe (i.e. no version, paths, or extensions), and | ||
293 | you must supply the directory to which you want the source | ||
294 | extracted. | ||
295 | </para> | ||
296 | |||
297 | <para> | ||
298 | Additional command options let you control the name of a | ||
299 | development branch into which you can checkout the source | ||
300 | and whether or not to keep a temporary directory, which is | ||
301 | useful for debugging. | ||
302 | </para> | ||
303 | </section> | ||
304 | |||
305 | <section id='devtool-synchronizing-a-recipes-extracted-source-tree'> | ||
306 | <title>Synchronizing a Recipe's Extracted Source Tree</title> | ||
307 | |||
308 | <para> | ||
309 | Use the <filename>devtool sync</filename> command to | ||
310 | synchronize a previously extracted source tree for an | ||
311 | existing recipe. | ||
312 | When you use this command, you must supply the root name | ||
313 | of the recipe (i.e. no version, paths, or extensions), and | ||
314 | you must supply the directory to which you want the source | ||
315 | extracted. | ||
316 | </para> | ||
317 | |||
318 | <para> | ||
319 | Additional command options let you control the name of a | ||
320 | development branch into which you can checkout the source | ||
321 | and whether or not to keep a temporary directory, which is | ||
322 | useful for debugging. | ||
323 | </para> | ||
324 | </section> | ||
325 | |||
326 | <section id='devtool-modifying-a-recipe'> | ||
327 | <title>Modifying an Existing Recipe</title> | ||
328 | |||
329 | <para> | ||
330 | Use the <filename>devtool modify</filename> command to begin | ||
331 | modifying the source of an existing recipe. | ||
332 | This command is very similar to the | ||
333 | <link linkend='devtool-adding-a-new-recipe-to-the-workspace'><filename>add</filename></link> | ||
334 | command except that it does not physically create the | ||
335 | recipe in the workspace layer because the recipe already | ||
336 | exists in an another layer. | ||
337 | </para> | ||
338 | |||
339 | <para> | ||
340 | The <filename>devtool modify</filename> command extracts the | ||
341 | source for a recipe, sets it up as a Git repository if the | ||
342 | source had not already been fetched from Git, checks out a | ||
343 | branch for development, and applies any patches from the recipe | ||
344 | as commits on top. | ||
345 | You can use the following command to checkout the source | ||
346 | files: | ||
347 | <literallayout class='monospaced'> | ||
348 | $ devtool modify <replaceable>recipe</replaceable> | ||
349 | </literallayout> | ||
350 | Using the above command form, <filename>devtool</filename> uses | ||
351 | the existing recipe's | ||
352 | <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link> | ||
353 | statement to locate the upstream source, extracts the source | ||
354 | into the default sources location in the workspace. | ||
355 | The default development branch used is "devtool". | ||
356 | </para> | ||
357 | </section> | ||
358 | |||
359 | <section id='devtool-edit-an-existing-recipe'> | ||
360 | <title>Edit an Existing Recipe</title> | ||
361 | |||
362 | <para> | ||
363 | Use the <filename>devtool edit-recipe</filename> command | ||
364 | to run the default editor, which is identified using the | ||
365 | <filename>EDITOR</filename> variable, on the specified recipe. | ||
366 | </para> | ||
367 | |||
368 | <para> | ||
369 | When you use the <filename>devtool edit-recipe</filename> | ||
370 | command, you must supply the root name of the recipe | ||
371 | (i.e. no version, paths, or extensions). | ||
372 | Also, the recipe file itself must reside in the workspace | ||
373 | as a result of the <filename>devtool add</filename> or | ||
374 | <filename>devtool upgrade</filename> commands. | ||
375 | However, you can override that requirement by using the | ||
376 | "-a" or "--any-recipe" option. | ||
377 | Using either of these options allows you to edit any recipe | ||
378 | regardless of its location. | ||
379 | </para> | ||
380 | </section> | ||
381 | |||
382 | <section id='devtool-updating-a-recipe'> | ||
383 | <title>Updating a Recipe</title> | ||
384 | |||
385 | <para> | ||
386 | Use the <filename>devtool update-recipe</filename> command to | ||
387 | update your recipe with patches that reflect changes you make | ||
388 | to the source files. | ||
389 | For example, if you know you are going to work on some | ||
390 | code, you could first use the | ||
391 | <link linkend='devtool-modifying-a-recipe'><filename>devtool modify</filename></link> | ||
392 | command to extract the code and set up the workspace. | ||
393 | After which, you could modify, compile, and test the code. | ||
394 | </para> | ||
395 | |||
396 | <para> | ||
397 | When you are satisfied with the results and you have committed | ||
398 | your changes to the Git repository, you can then | ||
399 | run the <filename>devtool update-recipe</filename> to create the | ||
400 | patches and update the recipe: | ||
401 | <literallayout class='monospaced'> | ||
402 | $ devtool update-recipe <replaceable>recipe</replaceable> | ||
403 | </literallayout> | ||
404 | If you run the <filename>devtool update-recipe</filename> | ||
405 | without committing your changes, the command ignores the | ||
406 | changes. | ||
407 | </para> | ||
408 | |||
409 | <para> | ||
410 | Often, you might want to apply customizations made to your | ||
411 | software in your own layer rather than apply them to the | ||
412 | original recipe. | ||
413 | If so, you can use the | ||
414 | <filename>-a</filename> or <filename>--append</filename> | ||
415 | option with the <filename>devtool update-recipe</filename> | ||
416 | command. | ||
417 | These options allow you to specify the layer into which to | ||
418 | write an append file: | ||
419 | <literallayout class='monospaced'> | ||
420 | $ devtool update-recipe <replaceable>recipe</replaceable> -a <replaceable>base-layer-directory</replaceable> | ||
421 | </literallayout> | ||
422 | The <filename>*.bbappend</filename> file is created at the | ||
423 | appropriate path within the specified layer directory, which | ||
424 | may or may not be in your <filename>bblayers.conf</filename> | ||
425 | file. | ||
426 | If an append file already exists, the command updates it | ||
427 | appropriately. | ||
428 | </para> | ||
429 | </section> | ||
430 | |||
431 | <section id='devtool-checking-on-the-upgrade-status-of-a-recipe'> | ||
432 | <title>Checking on the Upgrade Status of a Recipe</title> | ||
433 | |||
434 | <para> | ||
435 | Upstream recipes change over time. | ||
436 | Consequently, you might find that you need to determine if you | ||
437 | can upgrade a recipe to a newer version. | ||
438 | </para> | ||
439 | |||
440 | <para> | ||
441 | To check on the upgrade status of a recipe, use the | ||
442 | <filename>devtool check-upgrade-status</filename> command. | ||
443 | The command displays a table of your current recipe versions, | ||
444 | the latest upstream versions, the email address of the recipe's | ||
445 | maintainer, and any additional information such as commit hash | ||
446 | strings and reasons you might not be able to upgrade a particular | ||
447 | recipe. | ||
448 | <note><title>NOTES:</title> | ||
449 | <itemizedlist> | ||
450 | <listitem><para> | ||
451 | For the <filename>oe-core</filename> layer, recipe | ||
452 | maintainers come from the | ||
453 | <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/poky/tree/meta/conf/distro/include/maintainers.inc'><filename>maintainers.inc</filename></ulink> | ||
454 | file. | ||
455 | </para></listitem> | ||
456 | <listitem><para> | ||
457 | If the recipe is using the | ||
458 | <ulink url='&YOCTO_DOCS_BB_URL;#git-fetcher'>Git fetcher</ulink> | ||
459 | rather than a tarball, the commit hash points to the | ||
460 | commit that matches the recipe's latest version tag. | ||
461 | </para></listitem> | ||
462 | </itemizedlist> | ||
463 | </note> | ||
464 | </para> | ||
465 | |||
466 | <para> | ||
467 | As with all <filename>devtool</filename> commands, you can get | ||
468 | help on the individual command: | ||
469 | <literallayout class='monospaced'> | ||
470 | $ devtool check-upgrade-status -h | ||
471 | NOTE: Starting bitbake server... | ||
472 | usage: devtool check-upgrade-status [-h] [--all] [recipe [recipe ...]] | ||
473 | |||
474 | Prints a table of recipes together with versions currently provided by | ||
475 | recipes, and latest upstream versions, when there is a later version available | ||
476 | |||
477 | arguments: | ||
478 | recipe Name of the recipe to report (omit to report upgrade info for | ||
479 | all recipes) | ||
480 | |||
481 | options: | ||
482 | -h, --help show this help message and exit | ||
483 | --all, -a Show all recipes, not just recipes needing upgrade | ||
484 | </literallayout> | ||
485 | </para> | ||
486 | |||
487 | <para> | ||
488 | Unless you provide a specific recipe name on the command line, | ||
489 | the command checks all recipes in all configured layers. | ||
490 | </para> | ||
491 | |||
492 | <para> | ||
493 | Following is a partial example table that reports on all the | ||
494 | recipes. | ||
495 | Notice the reported reason for not upgrading the | ||
496 | <filename>base-passwd</filename> recipe. | ||
497 | In this example, while a new version is available upstream, | ||
498 | you do not want to use it because the dependency on | ||
499 | <filename>cdebconf</filename> is not easily satisfied. | ||
500 | <note> | ||
501 | When a reason for not upgrading displays, the reason is | ||
502 | usually written into the recipe using the | ||
503 | <filename>RECIPE_NO_UPDATE_REASON</filename> variable. | ||
504 | See the | ||
505 | <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/poky/tree/meta/recipes-core/base-passwd/base-passwd_3.5.29.bb'><filename>base-passwd.bb</filename></ulink> | ||
506 | recipe for an example. | ||
507 | </note> | ||
508 | <literallayout class='monospaced'> | ||
509 | $ devtool check-upgrade-status | ||
510 | ... | ||
511 | NOTE: acpid 2.0.30 2.0.31 | ||
512 | Ross Burton <ross.burton@intel.com> | ||
513 | NOTE: u-boot-fw-utils 2018.11 2019.01 | ||
514 | Marek Vasut <marek.vasut@gmail.com> | ||
515 | d3689267f92c5956e09cc7d1baa4700141662bff | ||
516 | NOTE: u-boot-tools 2018.11 2019.01 | ||
517 | Marek Vasut <marek.vasut@gmail.com> | ||
518 | d3689267f92c5956e09cc7d1baa4700141662bff | ||
519 | . | ||
520 | . | ||
521 | . | ||
522 | NOTE: base-passwd 3.5.29 3.5.45 | ||
523 | Anuj Mittal <anuj.mittal@intel.com> cannot be updated due to: Version | ||
524 | 3.5.38 requires cdebconf for update-passwd utility | ||
525 | NOTE: busybox 1.29.2 1.30.0 | ||
526 | Andrej Valek <andrej.valek@siemens.com> | ||
527 | NOTE: dbus-test 1.12.10 1.12.12 | ||
528 | Chen Qi <Qi.Chen@windriver.com> | ||
529 | </literallayout> | ||
530 | </para> | ||
531 | </section> | ||
532 | |||
533 | <section id='devtool-upgrading-a-recipe'> | ||
534 | <title>Upgrading a Recipe</title> | ||
535 | |||
536 | <para> | ||
537 | As software matures, upstream recipes are upgraded to newer | ||
538 | versions. | ||
539 | As a developer, you need to keep your local recipes up-to-date | ||
540 | with the upstream version releases. | ||
541 | Several methods exist by which you can upgrade recipes. | ||
542 | You can read about them in the | ||
543 | "<ulink url='&YOCTO_DOCS_DEV_URL;#gs-upgrading-recipes'>Upgrading Recipes</ulink>" | ||
544 | section of the Yocto Project Development Tasks Manual. | ||
545 | This section overviews the <filename>devtool upgrade</filename> | ||
546 | command. | ||
547 | <note> | ||
548 | Before you upgrade a recipe, you can check on its upgrade | ||
549 | status. | ||
550 | See the | ||
551 | "<link linkend='devtool-checking-on-the-upgrade-status-of-a-recipe'>Checking on the Upgrade Status of a Recipe</link>" | ||
552 | for more information. | ||
553 | </note> | ||
554 | </para> | ||
555 | |||
556 | <para> | ||
557 | The <filename>devtool upgrade</filename> command | ||
558 | upgrades an existing recipe to a more recent version of the | ||
559 | recipe upstream. | ||
560 | The command puts the upgraded recipe file along with any associated | ||
561 | files into a "workspace" and, if necessary, extracts the source | ||
562 | tree to a specified location. | ||
563 | During the upgrade, patches associated with the recipe are | ||
564 | rebased or added as needed. | ||
565 | </para> | ||
566 | |||
567 | <para> | ||
568 | When you use the <filename>devtool upgrade</filename> command, | ||
569 | you must supply the root name of the recipe (i.e. no version, | ||
570 | paths, or extensions), and you must supply the directory | ||
571 | to which you want the source extracted. | ||
572 | Additional command options let you control things such as | ||
573 | the version number to which you want to upgrade (i.e. the | ||
574 | <link linkend='var-PV'><filename>PV</filename></link>), | ||
575 | the source revision to which you want to upgrade (i.e. the | ||
576 | <link linkend='var-SRCREV'><filename>SRCREV</filename></link>), | ||
577 | whether or not to apply patches, and so forth. | ||
578 | </para> | ||
579 | |||
580 | <para> | ||
581 | You can read more on the <filename>devtool upgrade</filename> | ||
582 | workflow in the | ||
583 | "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-devtool-use-devtool-upgrade-to-create-a-version-of-the-recipe-that-supports-a-newer-version-of-the-software'>Use <filename>devtool upgrade</filename> to Create a Version of the Recipe that Supports a Newer Version of the Software</ulink>" | ||
584 | section in the Yocto Project Application Development and the | ||
585 | Extensible Software Development Kit (eSDK) manual. | ||
586 | You can also see an example of how to use | ||
587 | <filename>devtool upgrade</filename> in the | ||
588 | "<ulink url='&YOCTO_DOCS_DEV_URL;#gs-using-devtool-upgrade'>Using <filename>devtool upgrade</filename></ulink>" | ||
589 | section in the Yocto Project Development Tasks Manual. | ||
590 | </para> | ||
591 | </section> | ||
592 | |||
593 | <section id='devtool-resetting-a-recipe'> | ||
594 | <title>Resetting a Recipe</title> | ||
595 | |||
596 | <para> | ||
597 | Use the <filename>devtool reset</filename> command to remove a | ||
598 | recipe and its configuration (e.g. the corresponding | ||
599 | <filename>.bbappend</filename> file) from the workspace layer. | ||
600 | Realize that this command deletes the recipe and the | ||
601 | append file. | ||
602 | The command does not physically move them for you. | ||
603 | Consequently, you must be sure to physically relocate your | ||
604 | updated recipe and the append file outside of the workspace | ||
605 | layer before running the <filename>devtool reset</filename> | ||
606 | command. | ||
607 | </para> | ||
608 | |||
609 | <para> | ||
610 | If the <filename>devtool reset</filename> command detects that | ||
611 | the recipe or the append files have been modified, the | ||
612 | command preserves the modified files in a separate "attic" | ||
613 | subdirectory under the workspace layer. | ||
614 | </para> | ||
615 | |||
616 | <para> | ||
617 | Here is an example that resets the workspace directory that | ||
618 | contains the <filename>mtr</filename> recipe: | ||
619 | <literallayout class='monospaced'> | ||
620 | $ devtool reset mtr | ||
621 | NOTE: Cleaning sysroot for recipe mtr... | ||
622 | NOTE: Leaving source tree /home/scottrif/poky/build/workspace/sources/mtr as-is; if you no | ||
623 | longer need it then please delete it manually | ||
624 | $ | ||
625 | </literallayout> | ||
626 | </para> | ||
627 | </section> | ||
628 | |||
629 | <section id='devtool-building-your-recipe'> | ||
630 | <title>Building Your Recipe</title> | ||
631 | |||
632 | <para> | ||
633 | Use the <filename>devtool build</filename> command to build your | ||
634 | recipe. | ||
635 | The <filename>devtool build</filename> command is equivalent to | ||
636 | the <filename>bitbake -c populate_sysroot</filename> command. | ||
637 | </para> | ||
638 | |||
639 | <para> | ||
640 | When you use the <filename>devtool build</filename> command, | ||
641 | you must supply the root name of the recipe (i.e. do not provide | ||
642 | versions, paths, or extensions). | ||
643 | You can use either the "-s" or the "--disable-parallel-make" | ||
644 | options to disable parallel makes during the build. | ||
645 | Here is an example: | ||
646 | <literallayout class='monospaced'> | ||
647 | $ devtool build <replaceable>recipe</replaceable> | ||
648 | </literallayout> | ||
649 | </para> | ||
650 | </section> | ||
651 | |||
652 | <section id='devtool-building-your-image'> | ||
653 | <title>Building Your Image</title> | ||
654 | |||
655 | <para> | ||
656 | Use the <filename>devtool build-image</filename> command | ||
657 | to build an image, extending it to include packages from | ||
658 | recipes in the workspace. | ||
659 | Using this command is useful when you want an image that | ||
660 | ready for immediate deployment onto a device for testing. | ||
661 | For proper integration into a final image, you need to | ||
662 | edit your custom image recipe appropriately. | ||
663 | </para> | ||
664 | |||
665 | <para> | ||
666 | When you use the <filename>devtool build-image</filename> | ||
667 | command, you must supply the name of the image. | ||
668 | This command has no command line options: | ||
669 | <literallayout class='monospaced'> | ||
670 | $ devtool build-image <replaceable>image</replaceable> | ||
671 | </literallayout> | ||
672 | </para> | ||
673 | </section> | ||
674 | |||
675 | <section id='devtool-deploying-your-software-on-the-target-machine'> | ||
676 | <title>Deploying Your Software on the Target Machine</title> | ||
677 | |||
678 | <para> | ||
679 | Use the <filename>devtool deploy-target</filename> command to | ||
680 | deploy the recipe's build output to the live target machine: | ||
681 | <literallayout class='monospaced'> | ||
682 | $ devtool deploy-target <replaceable>recipe</replaceable> <replaceable>target</replaceable> | ||
683 | </literallayout> | ||
684 | The <replaceable>target</replaceable> is the address of the | ||
685 | target machine, which must be running an SSH server (i.e. | ||
686 | <filename>user@hostname[:destdir]</filename>). | ||
687 | </para> | ||
688 | |||
689 | <para> | ||
690 | This command deploys all files installed during the | ||
691 | <link linkend='ref-tasks-install'><filename>do_install</filename></link> | ||
692 | task. | ||
693 | Furthermore, you do not need to have package management enabled | ||
694 | within the target machine. | ||
695 | If you do, the package manager is bypassed. | ||
696 | <note><title>Notes</title> | ||
697 | <para> | ||
698 | The <filename>deploy-target</filename> | ||
699 | functionality is for development only. | ||
700 | You should never use it to update an image that will be | ||
701 | used in production. | ||
702 | </para> | ||
703 | </note> | ||
704 | </para> | ||
705 | |||
706 | <para> | ||
707 | Some conditions exist that could prevent a deployed application | ||
708 | from behaving as expected. | ||
709 | When both of the following conditions exist, your application has | ||
710 | the potential to not behave correctly when run on the target: | ||
711 | <itemizedlist> | ||
712 | <listitem><para> | ||
713 | You are deploying a new application to the target and | ||
714 | the recipe you used to build the application had | ||
715 | correctly defined runtime dependencies. | ||
716 | </para></listitem> | ||
717 | <listitem><para> | ||
718 | The target does not physically have the packages on which | ||
719 | the application depends installed. | ||
720 | </para></listitem> | ||
721 | </itemizedlist> | ||
722 | If both of these conditions exist, your application will not | ||
723 | behave as expected. | ||
724 | The reason for this misbehavior is because the | ||
725 | <filename>devtool deploy-target</filename> command does not deploy | ||
726 | the packages (e.g. libraries) on which your new application | ||
727 | depends. | ||
728 | The assumption is that the packages are already on the target. | ||
729 | Consequently, when a runtime call is made in the application | ||
730 | for a dependent function (e.g. a library call), the function | ||
731 | cannot be found. | ||
732 | </para> | ||
733 | |||
734 | <para> | ||
735 | To be sure you have all the dependencies local to the target, you | ||
736 | need to be sure that the packages are pre-deployed (installed) | ||
737 | on the target before attempting to run your application. | ||
738 | </para> | ||
739 | </section> | ||
740 | |||
741 | <section id='devtool-removing-your-software-from-the-target-machine'> | ||
742 | <title>Removing Your Software from the Target Machine</title> | ||
743 | |||
744 | <para> | ||
745 | Use the <filename>devtool undeploy-target</filename> command to | ||
746 | remove deployed build output from the target machine. | ||
747 | For the <filename>devtool undeploy-target</filename> command to | ||
748 | work, you must have previously used the | ||
749 | <link linkend='devtool-deploying-your-software-on-the-target-machine'><filename>devtool deploy-target</filename></link> | ||
750 | command. | ||
751 | <literallayout class='monospaced'> | ||
752 | $ devtool undeploy-target <replaceable>recipe</replaceable> <replaceable>target</replaceable> | ||
753 | </literallayout> | ||
754 | The <replaceable>target</replaceable> is the address of the | ||
755 | target machine, which must be running an SSH server (i.e. | ||
756 | <filename>user@hostname</filename>). | ||
757 | </para> | ||
758 | </section> | ||
759 | |||
760 | <section id='devtool-creating-the-workspace'> | ||
761 | <title>Creating the Workspace Layer in an Alternative Location</title> | ||
762 | |||
763 | <para> | ||
764 | Use the <filename>devtool create-workspace</filename> command to | ||
765 | create a new workspace layer in your | ||
766 | <link linkend='build-directory'>Build Directory</link>. | ||
767 | When you create a new workspace layer, it is populated with the | ||
768 | <filename>README</filename> file and the | ||
769 | <filename>conf</filename> directory only. | ||
770 | </para> | ||
771 | |||
772 | <para> | ||
773 | The following example creates a new workspace layer in your | ||
774 | current working and by default names the workspace layer | ||
775 | "workspace": | ||
776 | <literallayout class='monospaced'> | ||
777 | $ devtool create-workspace | ||
778 | </literallayout> | ||
779 | </para> | ||
780 | |||
781 | <para> | ||
782 | You can create a workspace layer anywhere by supplying | ||
783 | a pathname with the command. | ||
784 | The following command creates a new workspace layer named | ||
785 | "new-workspace": | ||
786 | <literallayout class='monospaced'> | ||
787 | $ devtool create-workspace /home/scottrif/new-workspace | ||
788 | </literallayout> | ||
789 | </para> | ||
790 | </section> | ||
791 | |||
792 | <section id='devtool-get-the-status-of-the-recipes-in-your-workspace'> | ||
793 | <title>Get the Status of the Recipes in Your Workspace</title> | ||
794 | |||
795 | <para> | ||
796 | Use the <filename>devtool status</filename> command to | ||
797 | list the recipes currently in your workspace. | ||
798 | Information includes the paths to their respective | ||
799 | external source trees. | ||
800 | </para> | ||
801 | |||
802 | <para> | ||
803 | The <filename>devtool status</filename> command has no | ||
804 | command-line options: | ||
805 | <literallayout class='monospaced'> | ||
806 | $ devtool status | ||
807 | </literallayout> | ||
808 | Following is sample output after using | ||
809 | <link linkend='devtool-adding-a-new-recipe-to-the-workspace'><filename>devtool add</filename></link> | ||
810 | to create and add the <filename>mtr_0.86.bb</filename> recipe | ||
811 | to the <filename>workspace</filename> directory: | ||
812 | <literallayout class='monospaced'> | ||
813 | $ devtool status | ||
814 | mtr: /home/scottrif/poky/build/workspace/sources/mtr (/home/scottrif/poky/build/workspace/recipes/mtr/mtr_0.86.bb) | ||
815 | $ | ||
816 | </literallayout> | ||
817 | </para> | ||
818 | </section> | ||
819 | |||
820 | <section id='devtool-search-for-available-target-recipes'> | ||
821 | <title>Search for Available Target Recipes</title> | ||
822 | |||
823 | <para> | ||
824 | Use the <filename>devtool search</filename> command to | ||
825 | search for available target recipes. | ||
826 | The command matches the recipe name, package name, | ||
827 | description, and installed files. | ||
828 | The command displays the recipe name as a result of a | ||
829 | match. | ||
830 | </para> | ||
831 | |||
832 | <para> | ||
833 | When you use the <filename>devtool search</filename> command, | ||
834 | you must supply a <replaceable>keyword</replaceable>. | ||
835 | The command uses the <replaceable>keyword</replaceable> when | ||
836 | searching for a match. | ||
837 | </para> | ||
838 | </section> | ||
839 | </chapter> | ||
840 | <!-- | ||
841 | vim: expandtab tw=80 ts=4 | ||
842 | --> | ||