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