summaryrefslogtreecommitdiffstats
path: root/documentation/ref-manual/ref-devtool-reference.xml
diff options
context:
space:
mode:
authorNicolas Dechesne <nicolas.dechesne@linaro.org>2020-10-05 16:30:32 +0200
committerRichard Purdie <richard.purdie@linuxfoundation.org>2020-10-06 13:56:17 +0100
commit43d07a285181e64c30d98d10ff93ef50391efe59 (patch)
tree78918fc94d55d44d35e1e3e61c7a6fccc28bca24 /documentation/ref-manual/ref-devtool-reference.xml
parent1fd9c4b2c0ae927df29f7a0d34c3e595bcf48e89 (diff)
downloadpoky-43d07a285181e64c30d98d10ff93ef50391efe59.tar.gz
sphinx: remove DocBook files
The Yocto Project documentation was migrated to Sphinx. Let's remove the deprecated DocBook files. (From yocto-docs rev: 28fb0e63b2fbfd6426b00498bf2682bb53fdd862) Signed-off-by: Nicolas Dechesne <nicolas.dechesne@linaro.org> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/ref-manual/ref-devtool-reference.xml')
-rw-r--r--documentation/ref-manual/ref-devtool-reference.xml842
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 &lt;subcommand&gt; ...
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 &lt;subcommand&gt; --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 &lt;ross.burton@intel.com&gt;
513 NOTE: u-boot-fw-utils 2018.11 2019.01
514 Marek Vasut &lt;marek.vasut@gmail.com&gt;
515 d3689267f92c5956e09cc7d1baa4700141662bff
516 NOTE: u-boot-tools 2018.11 2019.01
517 Marek Vasut &lt;marek.vasut@gmail.com&gt;
518 d3689267f92c5956e09cc7d1baa4700141662bff
519 .
520 .
521 .
522 NOTE: base-passwd 3.5.29 3.5.45
523 Anuj Mittal &lt;anuj.mittal@intel.com&gt; 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 &lt;andrej.valek@siemens.com&gt;
527 NOTE: dbus-test 1.12.10 1.12.12
528 Chen Qi &lt;Qi.Chen@windriver.com&gt;
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>&nbsp;<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>&nbsp;<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<!--
841vim: expandtab tw=80 ts=4
842-->
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2026-08-04 22:48:34 +0000