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