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 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.. code-block:: none 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/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:ref:`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:ref:`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 :yocto_git:`maintainers.inc </poky/tree/meta/conf/distro/include/maintainers.inc>` 353 file. 354 355 - If the recipe is using the :ref:`bitbake:bitbake-user-manual/bitbake-user-manual-fetching:git fetcher (\`\`git://\`\`)` 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 391 :yocto_git:`base-passwd.bb </poky/tree/meta/recipes-core/base-passwd/base-passwd_3.5.29.bb>` 392 recipe for an example. 393 394:: 395 396 $ devtool check-upgrade-status 397 ... 398 NOTE: acpid 2.0.30 2.0.31 Ross Burton <ross.burton@intel.com> 399 NOTE: u-boot-fw-utils 2018.11 2019.01 Marek Vasut <marek.vasut@gmail.com> d3689267f92c5956e09cc7d1baa4700141662bff 400 NOTE: u-boot-tools 2018.11 2019.01 Marek Vasut <marek.vasut@gmail.com> d3689267f92c5956e09cc7d1baa4700141662bff 401 . 402 . 403 . 404 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 405 NOTE: busybox 1.29.2 1.30.0 Andrej Valek <andrej.valek@siemens.com> 406 NOTE: dbus-test 1.12.10 1.12.12 Chen Qi <Qi.Chen@windriver.com> 407 408.. _devtool-upgrading-a-recipe: 409 410Upgrading a Recipe 411================== 412 413As software matures, upstream recipes are upgraded to newer versions. As 414a developer, you need to keep your local recipes up-to-date with the 415upstream version releases. Several methods exist by which you can 416upgrade recipes. You can read about them in the ":ref:`dev-manual/common-tasks:upgrading recipes`" 417section of the Yocto Project Development Tasks Manual. This section 418overviews the ``devtool upgrade`` command. 419 420Before you upgrade a recipe, you can check on its upgrade status. See 421the ":ref:`devtool-checking-on-the-upgrade-status-of-a-recipe`" section 422for more information. 423 424The ``devtool upgrade`` command upgrades an existing recipe to a more 425recent version of the recipe upstream. The command puts the upgraded 426recipe file along with any associated files into a "workspace" and, if 427necessary, extracts the source tree to a specified location. During the 428upgrade, patches associated with the recipe are rebased or added as 429needed. 430 431When you use the ``devtool upgrade`` command, you must supply the root 432name of the recipe (i.e. no version, paths, or extensions), and you must 433supply the directory to which you want the source extracted. Additional 434command options let you control things such as the version number to 435which you want to upgrade (i.e. the :term:`PV`), the source 436revision to which you want to upgrade (i.e. the 437:term:`SRCREV`), whether or not to apply patches, and so 438forth. 439 440You can read more on the ``devtool upgrade`` workflow in the 441":ref:`sdk-manual/extensible:use \`\`devtool upgrade\`\` to create a version of the recipe that supports a newer version of the software`" 442section in the Yocto Project Application Development and the Extensible 443Software Development Kit (eSDK) manual. You can also see an example of 444how to use ``devtool upgrade`` in the ":ref:`dev-manual/common-tasks:using \`\`devtool upgrade\`\``" 445section in the Yocto Project Development Tasks Manual. 446 447.. _devtool-resetting-a-recipe: 448 449Resetting a Recipe 450================== 451 452Use the ``devtool reset`` command to remove a recipe and its 453configuration (e.g. the corresponding ``.bbappend`` file) from the 454workspace layer. Realize that this command deletes the recipe and the 455append file. The command does not physically move them for you. 456Consequently, you must be sure to physically relocate your updated 457recipe and the append file outside of the workspace layer before running 458the ``devtool reset`` command. 459 460If the ``devtool reset`` command detects that the recipe or the append 461files have been modified, the command preserves the modified files in a 462separate "attic" subdirectory under the workspace layer. 463 464Here is an example that resets the workspace directory that contains the 465``mtr`` recipe: 466:: 467 468 $ devtool reset mtr 469 NOTE: Cleaning sysroot for recipe mtr... 470 NOTE: Leaving source tree /home/scottrif/poky/build/workspace/sources/mtr as-is; if you no longer need it then please delete it manually 471 $ 472 473.. _devtool-building-your-recipe: 474 475Building Your Recipe 476==================== 477 478Use the ``devtool build`` command to build your recipe. The 479``devtool build`` command is equivalent to the 480``bitbake -c populate_sysroot`` command. 481 482When you use the ``devtool build`` command, you must supply the root 483name of the recipe (i.e. do not provide versions, paths, or extensions). 484You can use either the "-s" or the "--disable-parallel-make" options to 485disable parallel makes during the build. Here is an example: 486:: 487 488 $ devtool build recipe 489 490.. _devtool-building-your-image: 491 492Building Your Image 493=================== 494 495Use the ``devtool build-image`` command to build an image, extending it 496to include packages from recipes in the workspace. Using this command is 497useful when you want an image that ready for immediate deployment onto a 498device for testing. For proper integration into a final image, you need 499to edit your custom image recipe appropriately. 500 501When you use the ``devtool build-image`` command, you must supply the 502name of the image. This command has no command line options: 503:: 504 505 $ devtool build-image image 506 507.. _devtool-deploying-your-software-on-the-target-machine: 508 509Deploying Your Software on the Target Machine 510============================================= 511 512Use the ``devtool deploy-target`` command to deploy the recipe's build 513output to the live target machine: 514:: 515 516 $ devtool deploy-target recipe target 517 518The target is the address of the target machine, which must be running 519an SSH server (i.e. ``user@hostname[:destdir]``). 520 521This command deploys all files installed during the 522:ref:`ref-tasks-install` task. Furthermore, you do not 523need to have package management enabled within the target machine. If 524you do, the package manager is bypassed. 525 526.. note:: 527 528 The ``deploy-target`` functionality is for development only. You 529 should never use it to update an image that will be used in 530 production. 531 532Some conditions exist that could prevent a deployed application from 533behaving as expected. When both of the following conditions exist, your 534application has the potential to not behave correctly when run on the 535target: 536 537- You are deploying a new application to the target and the recipe you 538 used to build the application had correctly defined runtime 539 dependencies. 540 541- The target does not physically have the packages on which the 542 application depends installed. 543 544If both of these conditions exist, your application will not behave as 545expected. The reason for this misbehavior is because the 546``devtool deploy-target`` command does not deploy the packages (e.g. 547libraries) on which your new application depends. The assumption is that 548the packages are already on the target. Consequently, when a runtime 549call is made in the application for a dependent function (e.g. a library 550call), the function cannot be found. 551 552To be sure you have all the dependencies local to the target, you need 553to be sure that the packages are pre-deployed (installed) on the target 554before attempting to run your application. 555 556.. _devtool-removing-your-software-from-the-target-machine: 557 558Removing Your Software from the Target Machine 559============================================== 560 561Use the ``devtool undeploy-target`` command to remove deployed build 562output from the target machine. For the ``devtool undeploy-target`` 563command to work, you must have previously used the 564":ref:`devtool deploy-target <ref-manual/devtool-reference:deploying your software on the target machine>`" 565command. 566:: 567 568 $ devtool undeploy-target recipe target 569 570The target is the 571address of the target machine, which must be running an SSH server (i.e. 572``user@hostname``). 573 574.. _devtool-creating-the-workspace: 575 576Creating the Workspace Layer in an Alternative Location 577======================================================= 578 579Use the ``devtool create-workspace`` command to create a new workspace 580layer in your :term:`Build Directory`. When you create a 581new workspace layer, it is populated with the ``README`` file and the 582``conf`` directory only. 583 584The following example creates a new workspace layer in your current 585working and by default names the workspace layer "workspace": 586:: 587 588 $ devtool create-workspace 589 590You can create a workspace layer anywhere by supplying a pathname with 591the command. The following command creates a new workspace layer named 592"new-workspace": 593:: 594 595 $ devtool create-workspace /home/scottrif/new-workspace 596 597.. _devtool-get-the-status-of-the-recipes-in-your-workspace: 598 599Get the Status of the Recipes in Your Workspace 600=============================================== 601 602Use the ``devtool status`` command to list the recipes currently in your 603workspace. Information includes the paths to their respective external 604source trees. 605 606The ``devtool status`` command has no command-line options: 607:: 608 609 $ devtool status 610 611Following is sample output after using 612:ref:`devtool add <ref-manual/devtool-reference:adding a new recipe to the workspace layer>` 613to create and add the ``mtr_0.86.bb`` recipe to the ``workspace`` directory: 614:: 615 616 $ devtool status 617 mtr:/home/scottrif/poky/build/workspace/sources/mtr (/home/scottrif/poky/build/workspace/recipes/mtr/mtr_0.86.bb) 618 $ 619 620.. _devtool-search-for-available-target-recipes: 621 622Search for Available Target Recipes 623=================================== 624 625Use the ``devtool search`` command to search for available target 626recipes. The command matches the recipe name, package name, description, 627and installed files. The command displays the recipe name as a result of 628a match. 629 630When you use the ``devtool search`` command, you must supply a keyword. 631The command uses the keyword when searching for a match. 632
