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