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 :scale: 100% 130 131.. code-block:: none 132 133 attic - A directory created if devtool believes it must preserve 134 anything when you run "devtool reset". For example, if you 135 run "devtool add", make changes to the recipe, and then 136 run "devtool reset", devtool takes notice that the file has 137 been changed and moves it into the attic should you still 138 want the recipe. 139 140 README - Provides information on what is in workspace layer and how to 141 manage it. 142 143 .devtool_md5 - A checksum file used by devtool. 144 145 appends - A directory that contains *.bbappend files, which point to 146 external source. 147 148 conf - A configuration directory that contains the layer.conf file. 149 150 recipes - A directory containing recipes. This directory contains a 151 folder for each directory added whose name matches that of the 152 added recipe. devtool places the recipe.bb file 153 within that sub-directory. 154 155 sources - A directory containing a working copy of the source files used 156 when building the recipe. This is the default directory used 157 as the location of the source tree when you do not provide a 158 source tree path. This directory contains a folder for each 159 set of source files matched to a corresponding recipe. 160 161.. _devtool-adding-a-new-recipe-to-the-workspace: 162 163Adding a New Recipe to the Workspace Layer 164========================================== 165 166Use the ``devtool add`` command to add a new recipe to the workspace 167layer. The recipe you add should not exist --- ``devtool`` creates it for 168you. The source files the recipe uses should exist in an external area. 169 170The following example creates and adds a new recipe named ``jackson`` to 171a workspace layer the tool creates. The source code built by the recipes 172resides in ``/home/user/sources/jackson``:: 173 174 $ devtool add jackson /home/user/sources/jackson 175 176If you add a recipe and the workspace layer does not exist, the command 177creates the layer and populates it as described in 178":ref:`devtool-the-workspace-layer-structure`" section. 179 180Running ``devtool add`` when the workspace layer exists causes the tool 181to add the recipe, append files, and source files into the existing 182workspace layer. The ``.bbappend`` file is created to point to the 183external source tree. 184 185.. note:: 186 187 If your recipe has runtime dependencies defined, you must be sure 188 that these packages exist on the target hardware before attempting to 189 run your application. If dependent packages (e.g. libraries) do not 190 exist on the target, your application, when run, will fail to find 191 those functions. For more information, see the 192 ":ref:`ref-manual/devtool-reference:deploying your software on the target machine`" 193 section. 194 195By default, ``devtool add`` uses the latest revision (i.e. master) when 196unpacking files from a remote URI. In some cases, you might want to 197specify a source revision by branch, tag, or commit hash. You can 198specify these options when using the ``devtool add`` command: 199 200- To specify a source branch, use the ``--srcbranch`` option:: 201 202 $ devtool add --srcbranch &DISTRO_NAME_NO_CAP; jackson /home/user/sources/jackson 203 204 In the previous example, you are checking out the &DISTRO_NAME_NO_CAP; 205 branch. 206 207- To specify a specific tag or commit hash, use the ``--srcrev`` 208 option:: 209 210 $ devtool add --srcrev &DISTRO_REL_TAG; jackson /home/user/sources/jackson 211 $ devtool add --srcrev some_commit_hash /home/user/sources/jackson 212 213 The previous examples check out the 214 &DISTRO_REL_TAG; tag and the commit associated with the 215 some_commit_hash hash. 216 217.. note:: 218 219 If you prefer to use the latest revision every time the recipe is 220 built, use the options ``--autorev`` or ``-a``. 221 222.. _devtool-extracting-the-source-for-an-existing-recipe: 223 224Extracting the Source for an Existing Recipe 225============================================ 226 227Use the ``devtool extract`` command to extract the source for an 228existing recipe. When you use this command, you must supply the root 229name of the recipe (i.e. no version, paths, or extensions), and you must 230supply the directory to which you want the source extracted. 231 232Additional command options let you control the name of a development 233branch into which you can checkout the source and whether or not to keep 234a temporary directory, which is useful for debugging. 235 236.. _devtool-synchronizing-a-recipes-extracted-source-tree: 237 238Synchronizing a Recipe's Extracted Source Tree 239============================================== 240 241Use the ``devtool sync`` command to synchronize a previously extracted 242source tree for an existing recipe. When you use this command, you must 243supply the root name of the recipe (i.e. no version, paths, or 244extensions), and you must supply the directory to which you want the 245source extracted. 246 247Additional command options let you control the name of a development 248branch into which you can checkout the source and whether or not to keep 249a temporary directory, which is useful for debugging. 250 251.. _devtool-modifying-a-recipe: 252 253Modifying an Existing Recipe 254============================ 255 256Use the ``devtool modify`` command to begin modifying the source of an 257existing recipe. This command is very similar to the 258:ref:`add <devtool-adding-a-new-recipe-to-the-workspace>` command 259except that it does not physically create the recipe in the workspace 260layer because the recipe already exists in an another layer. 261 262The ``devtool modify`` command extracts the source for a recipe, sets it 263up as a Git repository if the source had not already been fetched from 264Git, checks out a branch for development, and applies any patches from 265the recipe as commits on top. You can use the following command to 266checkout the source files:: 267 268 $ devtool modify recipe 269 270Using the above command form, ``devtool`` uses the existing recipe's 271:term:`SRC_URI` statement to locate the upstream source, 272extracts the source into the default sources location in the workspace. 273The default development branch used is "devtool". 274 275.. _devtool-edit-an-existing-recipe: 276 277Edit an Existing Recipe 278======================= 279 280Use the ``devtool edit-recipe`` command to run the default editor, which 281is identified using the ``EDITOR`` variable, on the specified recipe. 282 283When you use the ``devtool edit-recipe`` command, you must supply the 284root name of the recipe (i.e. no version, paths, or extensions). Also, 285the recipe file itself must reside in the workspace as a result of the 286``devtool add`` or ``devtool upgrade`` commands. 287 288.. _devtool-updating-a-recipe: 289 290Updating a Recipe 291================= 292 293Use the ``devtool update-recipe`` command to update your recipe with 294patches that reflect changes you make to the source files. For example, 295if you know you are going to work on some code, you could first use the 296:ref:`devtool modify <devtool-modifying-a-recipe>` command to extract 297the code and set up the workspace. After which, you could modify, 298compile, and test the code. 299 300When you are satisfied with the results and you have committed your 301changes to the Git repository, you can then run the 302``devtool update-recipe`` to create the patches and update the recipe:: 303 304 $ devtool update-recipe recipe 305 306If you run the ``devtool update-recipe`` 307without committing your changes, the command ignores the changes. 308 309Often, you might want to apply customizations made to your software in 310your own layer rather than apply them to the original recipe. If so, you 311can use the ``-a`` or ``--append`` option with the 312``devtool update-recipe`` command. These options allow you to specify 313the layer into which to write an append file:: 314 315 $ devtool update-recipe recipe -a base-layer-directory 316 317The ``*.bbappend`` file is created at the 318appropriate path within the specified layer directory, which may or may 319not be in your ``bblayers.conf`` file. If an append file already exists, 320the command updates it appropriately. 321 322.. _devtool-checking-on-the-upgrade-status-of-a-recipe: 323 324Checking on the Upgrade Status of a Recipe 325========================================== 326 327Upstream recipes change over time. Consequently, you might find that you 328need to determine if you can upgrade a recipe to a newer version. 329 330To check on the upgrade status of a recipe, you can use the 331``devtool latest-version recipe`` command, which quickly shows the current 332version and the latest version available upstream. To get a more global 333picture, use the ``devtool check-upgrade-status`` command, which takes a 334list of recipes as input, or no arguments, in which case it checks all 335available recipes. This command will only print the recipes for which 336a new upstream version is available. Each such recipe will have its current 337version and latest upstream version, as well as the email of the maintainer 338and any additional information such as the commit hash or reason for not 339being able to upgrade it, displayed in a table. 340 341This upgrade checking mechanism relies on the optional :term:`UPSTREAM_CHECK_URI`, 342:term:`UPSTREAM_CHECK_REGEX`, :term:`UPSTREAM_CHECK_GITTAGREGEX`, 343:term:`UPSTREAM_CHECK_COMMITS` and :term:`UPSTREAM_VERSION_UNKNOWN` 344variables in package recipes. 345 346.. note:: 347 348 - Most of the time, the above variables are unnecessary. They are only 349 required when upstream does something unusual, and default 350 mechanisms cannot find the new upstream versions. 351 352 - For the ``oe-core`` layer, recipe maintainers come from the 353 :yocto_git:`maintainers.inc </poky/tree/meta/conf/distro/include/maintainers.inc>` 354 file. 355 356 - If the recipe is using the :ref:`bitbake-user-manual/bitbake-user-manual-fetching:git fetcher (\`\`git://\`\`)` 357 rather than a tarball, the commit hash points to the commit that matches 358 the recipe's latest version tag, or in the absence of suitable tags, 359 to the latest commit (when :term:`UPSTREAM_CHECK_COMMITS` set to ``1`` 360 in the recipe). 361 362As with all ``devtool`` commands, you can get help on the individual 363command:: 364 365 $ devtool check-upgrade-status -h 366 NOTE: Starting bitbake server... 367 usage: devtool check-upgrade-status [-h] [--all] [recipe [recipe ...]] 368 369 Prints a table of recipes together with versions currently provided by recipes, and latest upstream versions, when there is a later version available 370 371 arguments: 372 recipe Name of the recipe to report (omit to report upgrade info for all recipes) 373 374 options: 375 -h, --help show this help message and exit 376 --all, -a Show all recipes, not just recipes needing upgrade 377 378Unless you provide a specific recipe name on the command line, the 379command checks all recipes in all configured layers. 380 381Here is a partial example table that reports on all the recipes:: 382 383 $ devtool check-upgrade-status 384 ... 385 INFO: bind 9.16.20 9.16.21 Armin Kuster <akuster808@gmail.com> 386 INFO: inetutils 2.1 2.2 Tom Rini <trini@konsulko.com> 387 INFO: iproute2 5.13.0 5.14.0 Changhyeok Bae <changhyeok.bae@gmail.com> 388 INFO: openssl 1.1.1l 3.0.0 Alexander Kanavin <alex.kanavin@gmail.com> 389 INFO: base-passwd 3.5.29 3.5.51 Anuj Mittal <anuj.mittal@intel.com> cannot be updated due to: Version 3.5.38 requires cdebconf for update-passwd utility 390 ... 391 392Notice the reported reason for not upgrading the ``base-passwd`` recipe. 393In this example, while a new version is available upstream, you do not 394want to use it because the dependency on ``cdebconf`` is not easily 395satisfied. Maintainers can explicit the reason that is shown by adding 396the :term:`RECIPE_NO_UPDATE_REASON` variable to the corresponding recipe. 397See :yocto_git:`base-passwd.bb </poky/tree/meta/recipes-core/base-passwd/base-passwd_3.5.29.bb?h=kirkstone>` 398for an example:: 399 400 RECIPE_NO_UPDATE_REASON = "Version 3.5.38 requires cdebconf for update-passwd utility" 401 402Last but not least, you may set :term:`UPSTREAM_VERSION_UNKNOWN` to ``1`` 403in a recipe when there's currently no way to determine its latest upstream 404version. 405 406.. _devtool-upgrading-a-recipe: 407 408Upgrading a Recipe 409================== 410 411As software matures, upstream recipes are upgraded to newer versions. As 412a developer, you need to keep your local recipes up-to-date with the 413upstream version releases. There are several ways of upgrading recipes. 414You can read about them in the ":ref:`dev-manual/upgrading-recipes:upgrading recipes`" 415section of the Yocto Project Development Tasks Manual. This section 416overviews the ``devtool upgrade`` command. 417 418Before you upgrade a recipe, you can check on its upgrade status. See 419the ":ref:`devtool-checking-on-the-upgrade-status-of-a-recipe`" section 420for more information. 421 422The ``devtool upgrade`` command upgrades an existing recipe to a more 423recent version of the recipe upstream. The command puts the upgraded 424recipe file along with any associated files into a "workspace" and, if 425necessary, extracts the source tree to a specified location. During the 426upgrade, patches associated with the recipe are rebased or added as 427needed. 428 429When you use the ``devtool upgrade`` command, you must supply the root 430name of the recipe (i.e. no version, paths, or extensions), and you must 431supply the directory to which you want the source extracted. Additional 432command options let you control things such as the version number to 433which you want to upgrade (i.e. the :term:`PV`), the source 434revision to which you want to upgrade (i.e. the 435:term:`SRCREV`), whether or not to apply patches, and so 436forth. 437 438You can read more on the ``devtool upgrade`` workflow in the 439":ref:`sdk-manual/extensible:use \`\`devtool upgrade\`\` to create a version of the recipe that supports a newer version of the software`" 440section in the Yocto Project Application Development and the Extensible 441Software Development Kit (eSDK) manual. You can also see an example of 442how to use ``devtool upgrade`` in the ":ref:`dev-manual/upgrading-recipes:using \`\`devtool upgrade\`\``" 443section in the Yocto Project Development Tasks Manual. 444 445.. _devtool-resetting-a-recipe: 446 447Resetting a Recipe 448================== 449 450Use the ``devtool reset`` command to remove a recipe and its 451configuration (e.g. the corresponding ``.bbappend`` file) from the 452workspace layer. Realize that this command deletes the recipe and the 453append file. The command does not physically move them for you. 454Consequently, you must be sure to physically relocate your updated 455recipe and the append file outside of the workspace layer before running 456the ``devtool reset`` command. 457 458If the ``devtool reset`` command detects that the recipe or the append 459files have been modified, the command preserves the modified files in a 460separate "attic" subdirectory under the workspace layer. 461 462Here is an example that resets the workspace directory that contains the 463``mtr`` recipe:: 464 465 $ devtool reset mtr 466 NOTE: Cleaning sysroot for recipe mtr... 467 NOTE: Leaving source tree /home/scottrif/poky/build/workspace/sources/mtr as-is; if you no longer need it then please delete it manually 468 $ 469 470.. _devtool-building-your-recipe: 471 472Building Your Recipe 473==================== 474 475Use the ``devtool build`` command to build your recipe. The 476``devtool build`` command is equivalent to the 477``bitbake -c populate_sysroot`` command. 478 479When you use the ``devtool build`` command, you must supply the root 480name of the recipe (i.e. do not provide versions, paths, or extensions). 481You can use either the ``-s`` or the ``--disable-parallel-make`` options to 482disable parallel makes during the build. Here is an example:: 483 484 $ devtool build recipe 485 486.. _devtool-building-your-image: 487 488Building Your Image 489=================== 490 491Use the ``devtool build-image`` command to build an image, extending it 492to include packages from recipes in the workspace. Using this command is 493useful when you want an image that ready for immediate deployment onto a 494device for testing. For proper integration into a final image, you need 495to edit your custom image recipe appropriately. 496 497When you use the ``devtool build-image`` command, you must supply the 498name of the image. This command has no command line options:: 499 500 $ devtool build-image image 501 502.. _devtool-deploying-your-software-on-the-target-machine: 503 504Deploying Your Software on the Target Machine 505============================================= 506 507Use the ``devtool deploy-target`` command to deploy the recipe's build 508output to the live target machine:: 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 could prevent a deployed application from 527behaving as expected. When both of the following conditions are met, 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 are met, 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/devtool-reference:deploying your software on the target machine>`" 559command:: 560 561 $ devtool undeploy-target recipe target 562 563The target is the 564address of the target machine, which must be running an SSH server (i.e. 565``user@hostname``). 566 567.. _devtool-creating-the-workspace: 568 569Creating the Workspace Layer in an Alternative Location 570======================================================= 571 572Use the ``devtool create-workspace`` command to create a new workspace 573layer in your :term:`Build Directory`. When you create a 574new workspace layer, it is populated with the ``README`` file and the 575``conf`` directory only. 576 577The following example creates a new workspace layer in your current 578working and by default names the workspace layer "workspace":: 579 580 $ devtool create-workspace 581 582You can create a workspace layer anywhere by supplying a pathname with 583the command. The following command creates a new workspace layer named 584"new-workspace":: 585 586 $ devtool create-workspace /home/scottrif/new-workspace 587 588.. _devtool-get-the-status-of-the-recipes-in-your-workspace: 589 590Get the Status of the Recipes in Your Workspace 591=============================================== 592 593Use the ``devtool status`` command to list the recipes currently in your 594workspace. Information includes the paths to their respective external 595source trees. 596 597The ``devtool status`` command has no command-line options:: 598 599 $ devtool status 600 601Here is sample output after using 602:ref:`devtool add <ref-manual/devtool-reference:adding a new recipe to the workspace layer>` 603to create and add the ``mtr_0.86.bb`` recipe to the ``workspace`` directory:: 604 605 $ devtool status 606 mtr:/home/scottrif/poky/build/workspace/sources/mtr (/home/scottrif/poky/build/workspace/recipes/mtr/mtr_0.86.bb) 607 $ 608 609.. _devtool-search-for-available-target-recipes: 610 611Search for Available Target Recipes 612=================================== 613 614Use the ``devtool search`` command to search for available target 615recipes. The command matches the recipe name, package name, description, 616and installed files. The command displays the recipe name as a result of 617a match. 618 619When you use the ``devtool search`` command, you must supply a keyword. 620The command uses the keyword when searching for a match. 621
