Andrew Geissler | f034379 | 2020-11-18 10:42:21 -0600 | [diff] [blame] | 1 | .. SPDX-License-Identifier: CC-BY-SA-2.0-UK |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 2 | |
| 3 | *************************** |
| 4 | ``devtool`` Quick Reference |
| 5 | *************************** |
| 6 | |
| 7 | The ``devtool`` command-line tool provides a number of features that |
| 8 | help you build, test, and package software. This command is available |
| 9 | alongside the ``bitbake`` command. Additionally, the ``devtool`` command |
| 10 | is a key part of the extensible SDK. |
| 11 | |
| 12 | This chapter provides a Quick Reference for the ``devtool`` command. For |
| 13 | more information on how to apply the command when using the extensible |
Andrew Geissler | 09209ee | 2020-12-13 08:44:15 -0600 | [diff] [blame] | 14 | SDK, see the ":doc:`/sdk-manual/extensible`" chapter in the Yocto |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 15 | Project Application Development and the Extensible Software Development |
| 16 | Kit (eSDK) manual. |
| 17 | |
| 18 | .. _devtool-getting-help: |
| 19 | |
| 20 | Getting Help |
| 21 | ============ |
| 22 | |
| 23 | The ``devtool`` command line is organized similarly to Git in that it |
| 24 | has a number of sub-commands for each function. You can run |
Andrew Geissler | c926e17 | 2021-05-07 16:11:35 -0500 | [diff] [blame] | 25 | ``devtool --help`` to see all the commands:: |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 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 | |
| 79 | As directed in the general help output, you can |
| 80 | get more syntax on a specific command by providing the command name and |
Andrew Geissler | 5199d83 | 2021-09-24 16:47:35 -0500 | [diff] [blame] | 81 | using ``--help``:: |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 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 | |
| 119 | The Workspace Layer Structure |
| 120 | ============================= |
| 121 | |
| 122 | ``devtool`` uses a "Workspace" layer in which to accomplish builds. This |
| 123 | layer is not specific to any single ``devtool`` command but is rather a |
| 124 | common working area used across the tool. |
| 125 | |
| 126 | The following figure shows the workspace structure: |
| 127 | |
| 128 | .. image:: figures/build-workspace-directory.png |
Andrew Geissler | d583833 | 2022-05-27 11:33:10 -0500 | [diff] [blame] | 129 | :scale: 100% |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 130 | |
Andrew Geissler | 4c19ea1 | 2020-10-27 13:52:24 -0500 | [diff] [blame] | 131 | .. code-block:: none |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 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 | |
| 163 | Adding a New Recipe to the Workspace Layer |
| 164 | ========================================== |
| 165 | |
| 166 | Use the ``devtool add`` command to add a new recipe to the workspace |
Andrew Geissler | 615f2f1 | 2022-07-15 14:00:58 -0500 | [diff] [blame] | 167 | layer. The recipe you add should not exist --- ``devtool`` creates it for |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 168 | you. The source files the recipe uses should exist in an external area. |
| 169 | |
| 170 | The following example creates and adds a new recipe named ``jackson`` to |
| 171 | a workspace layer the tool creates. The source code built by the recipes |
Andrew Geissler | c926e17 | 2021-05-07 16:11:35 -0500 | [diff] [blame] | 172 | resides in ``/home/user/sources/jackson``:: |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 173 | |
| 174 | $ devtool add jackson /home/user/sources/jackson |
| 175 | |
| 176 | If you add a recipe and the workspace layer does not exist, the command |
Andrew Geissler | 3b8a17c | 2021-04-15 15:55:55 -0500 | [diff] [blame] | 177 | creates the layer and populates it as described in |
| 178 | ":ref:`devtool-the-workspace-layer-structure`" section. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 179 | |
| 180 | Running ``devtool add`` when the workspace layer exists causes the tool |
| 181 | to add the recipe, append files, and source files into the existing |
| 182 | workspace layer. The ``.bbappend`` file is created to point to the |
| 183 | external 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 |
Andrew Geissler | 09209ee | 2020-12-13 08:44:15 -0600 | [diff] [blame] | 192 | ":ref:`ref-manual/devtool-reference:deploying your software on the target machine`" |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 193 | section. |
| 194 | |
| 195 | By default, ``devtool add`` uses the latest revision (i.e. master) when |
| 196 | unpacking files from a remote URI. In some cases, you might want to |
| 197 | specify a source revision by branch, tag, or commit hash. You can |
| 198 | specify these options when using the ``devtool add`` command: |
| 199 | |
Andrew Geissler | c926e17 | 2021-05-07 16:11:35 -0500 | [diff] [blame] | 200 | - To specify a source branch, use the ``--srcbranch`` option:: |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 201 | |
Andrew Geissler | d1e8949 | 2021-02-12 15:35:20 -0600 | [diff] [blame] | 202 | $ devtool add --srcbranch &DISTRO_NAME_NO_CAP; jackson /home/user/sources/jackson |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 203 | |
Andrew Geissler | d1e8949 | 2021-02-12 15:35:20 -0600 | [diff] [blame] | 204 | In the previous example, you are checking out the &DISTRO_NAME_NO_CAP; |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 205 | branch. |
| 206 | |
| 207 | - To specify a specific tag or commit hash, use the ``--srcrev`` |
Andrew Geissler | c926e17 | 2021-05-07 16:11:35 -0500 | [diff] [blame] | 208 | option:: |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 209 | |
Andrew Geissler | d1e8949 | 2021-02-12 15:35:20 -0600 | [diff] [blame] | 210 | $ devtool add --srcrev &DISTRO_REL_TAG; jackson /home/user/sources/jackson |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 211 | $ devtool add --srcrev some_commit_hash /home/user/sources/jackson |
| 212 | |
| 213 | The previous examples check out the |
Andrew Geissler | d1e8949 | 2021-02-12 15:35:20 -0600 | [diff] [blame] | 214 | &DISTRO_REL_TAG; tag and the commit associated with the |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 215 | some_commit_hash hash. |
| 216 | |
| 217 | .. note:: |
| 218 | |
| 219 | If you prefer to use the latest revision every time the recipe is |
Andrew Geissler | 4c19ea1 | 2020-10-27 13:52:24 -0500 | [diff] [blame] | 220 | built, use the options ``--autorev`` or ``-a``. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 221 | |
| 222 | .. _devtool-extracting-the-source-for-an-existing-recipe: |
| 223 | |
| 224 | Extracting the Source for an Existing Recipe |
| 225 | ============================================ |
| 226 | |
| 227 | Use the ``devtool extract`` command to extract the source for an |
| 228 | existing recipe. When you use this command, you must supply the root |
| 229 | name of the recipe (i.e. no version, paths, or extensions), and you must |
| 230 | supply the directory to which you want the source extracted. |
| 231 | |
| 232 | Additional command options let you control the name of a development |
| 233 | branch into which you can checkout the source and whether or not to keep |
| 234 | a temporary directory, which is useful for debugging. |
| 235 | |
| 236 | .. _devtool-synchronizing-a-recipes-extracted-source-tree: |
| 237 | |
| 238 | Synchronizing a Recipe's Extracted Source Tree |
| 239 | ============================================== |
| 240 | |
| 241 | Use the ``devtool sync`` command to synchronize a previously extracted |
| 242 | source tree for an existing recipe. When you use this command, you must |
| 243 | supply the root name of the recipe (i.e. no version, paths, or |
| 244 | extensions), and you must supply the directory to which you want the |
| 245 | source extracted. |
| 246 | |
| 247 | Additional command options let you control the name of a development |
| 248 | branch into which you can checkout the source and whether or not to keep |
| 249 | a temporary directory, which is useful for debugging. |
| 250 | |
| 251 | .. _devtool-modifying-a-recipe: |
| 252 | |
| 253 | Modifying an Existing Recipe |
| 254 | ============================ |
| 255 | |
| 256 | Use the ``devtool modify`` command to begin modifying the source of an |
| 257 | existing recipe. This command is very similar to the |
Andrew Geissler | 4c19ea1 | 2020-10-27 13:52:24 -0500 | [diff] [blame] | 258 | :ref:`add <devtool-adding-a-new-recipe-to-the-workspace>` command |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 259 | except that it does not physically create the recipe in the workspace |
| 260 | layer because the recipe already exists in an another layer. |
| 261 | |
| 262 | The ``devtool modify`` command extracts the source for a recipe, sets it |
| 263 | up as a Git repository if the source had not already been fetched from |
| 264 | Git, checks out a branch for development, and applies any patches from |
| 265 | the recipe as commits on top. You can use the following command to |
Andrew Geissler | c926e17 | 2021-05-07 16:11:35 -0500 | [diff] [blame] | 266 | checkout the source files:: |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 267 | |
| 268 | $ devtool modify recipe |
| 269 | |
| 270 | Using the above command form, ``devtool`` uses the existing recipe's |
| 271 | :term:`SRC_URI` statement to locate the upstream source, |
| 272 | extracts the source into the default sources location in the workspace. |
| 273 | The default development branch used is "devtool". |
| 274 | |
| 275 | .. _devtool-edit-an-existing-recipe: |
| 276 | |
| 277 | Edit an Existing Recipe |
| 278 | ======================= |
| 279 | |
| 280 | Use the ``devtool edit-recipe`` command to run the default editor, which |
| 281 | is identified using the ``EDITOR`` variable, on the specified recipe. |
| 282 | |
| 283 | When you use the ``devtool edit-recipe`` command, you must supply the |
| 284 | root name of the recipe (i.e. no version, paths, or extensions). Also, |
| 285 | the recipe file itself must reside in the workspace as a result of the |
Andrew Geissler | 5199d83 | 2021-09-24 16:47:35 -0500 | [diff] [blame] | 286 | ``devtool add`` or ``devtool upgrade`` commands. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 287 | |
| 288 | .. _devtool-updating-a-recipe: |
| 289 | |
| 290 | Updating a Recipe |
| 291 | ================= |
| 292 | |
| 293 | Use the ``devtool update-recipe`` command to update your recipe with |
| 294 | patches that reflect changes you make to the source files. For example, |
| 295 | if you know you are going to work on some code, you could first use the |
Andrew Geissler | 4c19ea1 | 2020-10-27 13:52:24 -0500 | [diff] [blame] | 296 | :ref:`devtool modify <devtool-modifying-a-recipe>` command to extract |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 297 | the code and set up the workspace. After which, you could modify, |
| 298 | compile, and test the code. |
| 299 | |
| 300 | When you are satisfied with the results and you have committed your |
| 301 | changes to the Git repository, you can then run the |
Andrew Geissler | c926e17 | 2021-05-07 16:11:35 -0500 | [diff] [blame] | 302 | ``devtool update-recipe`` to create the patches and update the recipe:: |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 303 | |
| 304 | $ devtool update-recipe recipe |
| 305 | |
| 306 | If you run the ``devtool update-recipe`` |
| 307 | without committing your changes, the command ignores the changes. |
| 308 | |
| 309 | Often, you might want to apply customizations made to your software in |
| 310 | your own layer rather than apply them to the original recipe. If so, you |
| 311 | can use the ``-a`` or ``--append`` option with the |
| 312 | ``devtool update-recipe`` command. These options allow you to specify |
Andrew Geissler | c926e17 | 2021-05-07 16:11:35 -0500 | [diff] [blame] | 313 | the layer into which to write an append file:: |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 314 | |
| 315 | $ devtool update-recipe recipe -a base-layer-directory |
| 316 | |
| 317 | The ``*.bbappend`` file is created at the |
| 318 | appropriate path within the specified layer directory, which may or may |
| 319 | not be in your ``bblayers.conf`` file. If an append file already exists, |
| 320 | the command updates it appropriately. |
| 321 | |
| 322 | .. _devtool-checking-on-the-upgrade-status-of-a-recipe: |
| 323 | |
| 324 | Checking on the Upgrade Status of a Recipe |
| 325 | ========================================== |
| 326 | |
| 327 | Upstream recipes change over time. Consequently, you might find that you |
| 328 | need to determine if you can upgrade a recipe to a newer version. |
| 329 | |
Andrew Geissler | 5199d83 | 2021-09-24 16:47:35 -0500 | [diff] [blame] | 330 | To check on the upgrade status of a recipe, you can use the |
| 331 | ``devtool latest-version recipe`` command, which quickly shows the current |
| 332 | version and the latest version available upstream. To get a more global |
| 333 | picture, use the ``devtool check-upgrade-status`` command, which takes a |
| 334 | list of recipes as input, or no arguments, in which case it checks all |
| 335 | available recipes. This command will only print the recipes for which |
| 336 | a new upstream version is available. Each such recipe will have its current |
| 337 | version and latest upstream version, as well as the email of the maintainer |
| 338 | and any additional information such as the commit hash or reason for not |
| 339 | being able to upgrade it, displayed in a table. |
| 340 | |
| 341 | This 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` |
| 344 | variables in package recipes. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 345 | |
| 346 | .. note:: |
| 347 | |
Andrew Geissler | 5199d83 | 2021-09-24 16:47:35 -0500 | [diff] [blame] | 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 | |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 352 | - For the ``oe-core`` layer, recipe maintainers come from the |
Andrew Geissler | 09209ee | 2020-12-13 08:44:15 -0600 | [diff] [blame] | 353 | :yocto_git:`maintainers.inc </poky/tree/meta/conf/distro/include/maintainers.inc>` |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 354 | file. |
| 355 | |
Andrew Geissler | fc113ea | 2023-03-31 09:59:46 -0500 | [diff] [blame] | 356 | - If the recipe is using the :ref:`bitbake-user-manual/bitbake-user-manual-fetching:git fetcher (\`\`git://\`\`)` |
Andrew Geissler | 5199d83 | 2021-09-24 16:47:35 -0500 | [diff] [blame] | 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). |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 361 | |
| 362 | As with all ``devtool`` commands, you can get help on the individual |
Andrew Geissler | c926e17 | 2021-05-07 16:11:35 -0500 | [diff] [blame] | 363 | command:: |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 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 | |
| 378 | Unless you provide a specific recipe name on the command line, the |
| 379 | command checks all recipes in all configured layers. |
| 380 | |
Andrew Geissler | 6aa7eec | 2023-03-03 12:41:14 -0600 | [diff] [blame] | 381 | Following is a partial example table that reports on all the recipes:: |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 382 | |
Andrew Geissler | 4c19ea1 | 2020-10-27 13:52:24 -0500 | [diff] [blame] | 383 | $ devtool check-upgrade-status |
| 384 | ... |
Andrew Geissler | 5199d83 | 2021-09-24 16:47:35 -0500 | [diff] [blame] | 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 | |
Andrew Geissler | 6aa7eec | 2023-03-03 12:41:14 -0600 | [diff] [blame] | 392 | Notice the reported reason for not upgrading the ``base-passwd`` recipe. |
| 393 | In this example, while a new version is available upstream, you do not |
| 394 | want to use it because the dependency on ``cdebconf`` is not easily |
| 395 | satisfied. Maintainers can explicit the reason that is shown by adding |
| 396 | the :term:`RECIPE_NO_UPDATE_REASON` variable to the corresponding recipe. |
| 397 | See :yocto_git:`base-passwd.bb </poky/tree/meta/recipes-core/base-passwd/base-passwd_3.5.29.bb?h=kirkstone>` |
| 398 | for an example:: |
| 399 | |
| 400 | RECIPE_NO_UPDATE_REASON = "Version 3.5.38 requires cdebconf for update-passwd utility" |
| 401 | |
Andrew Geissler | 5199d83 | 2021-09-24 16:47:35 -0500 | [diff] [blame] | 402 | Last but not least, you may set :term:`UPSTREAM_VERSION_UNKNOWN` to ``1`` |
| 403 | in a recipe when there's currently no way to determine its latest upstream |
| 404 | version. |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 405 | |
| 406 | .. _devtool-upgrading-a-recipe: |
| 407 | |
| 408 | Upgrading a Recipe |
| 409 | ================== |
| 410 | |
| 411 | As software matures, upstream recipes are upgraded to newer versions. As |
| 412 | a developer, you need to keep your local recipes up-to-date with the |
William A. Kennington III | ac69b48 | 2021-06-02 12:28:27 -0700 | [diff] [blame] | 413 | upstream version releases. There are several ways of upgrading recipes. |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 414 | You can read about them in the ":ref:`dev-manual/upgrading-recipes:upgrading recipes`" |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 415 | section of the Yocto Project Development Tasks Manual. This section |
| 416 | overviews the ``devtool upgrade`` command. |
| 417 | |
| 418 | Before you upgrade a recipe, you can check on its upgrade status. See |
| 419 | the ":ref:`devtool-checking-on-the-upgrade-status-of-a-recipe`" section |
| 420 | for more information. |
| 421 | |
| 422 | The ``devtool upgrade`` command upgrades an existing recipe to a more |
| 423 | recent version of the recipe upstream. The command puts the upgraded |
| 424 | recipe file along with any associated files into a "workspace" and, if |
| 425 | necessary, extracts the source tree to a specified location. During the |
| 426 | upgrade, patches associated with the recipe are rebased or added as |
| 427 | needed. |
| 428 | |
| 429 | When you use the ``devtool upgrade`` command, you must supply the root |
| 430 | name of the recipe (i.e. no version, paths, or extensions), and you must |
| 431 | supply the directory to which you want the source extracted. Additional |
| 432 | command options let you control things such as the version number to |
| 433 | which you want to upgrade (i.e. the :term:`PV`), the source |
| 434 | revision to which you want to upgrade (i.e. the |
| 435 | :term:`SRCREV`), whether or not to apply patches, and so |
| 436 | forth. |
| 437 | |
| 438 | You can read more on the ``devtool upgrade`` workflow in the |
Andrew Geissler | 09209ee | 2020-12-13 08:44:15 -0600 | [diff] [blame] | 439 | ":ref:`sdk-manual/extensible:use \`\`devtool upgrade\`\` to create a version of the recipe that supports a newer version of the software`" |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 440 | section in the Yocto Project Application Development and the Extensible |
| 441 | Software Development Kit (eSDK) manual. You can also see an example of |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 442 | how to use ``devtool upgrade`` in the ":ref:`dev-manual/upgrading-recipes:using \`\`devtool upgrade\`\``" |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 443 | section in the Yocto Project Development Tasks Manual. |
| 444 | |
| 445 | .. _devtool-resetting-a-recipe: |
| 446 | |
| 447 | Resetting a Recipe |
| 448 | ================== |
| 449 | |
| 450 | Use the ``devtool reset`` command to remove a recipe and its |
| 451 | configuration (e.g. the corresponding ``.bbappend`` file) from the |
| 452 | workspace layer. Realize that this command deletes the recipe and the |
| 453 | append file. The command does not physically move them for you. |
| 454 | Consequently, you must be sure to physically relocate your updated |
| 455 | recipe and the append file outside of the workspace layer before running |
| 456 | the ``devtool reset`` command. |
| 457 | |
| 458 | If the ``devtool reset`` command detects that the recipe or the append |
| 459 | files have been modified, the command preserves the modified files in a |
| 460 | separate "attic" subdirectory under the workspace layer. |
| 461 | |
| 462 | Here is an example that resets the workspace directory that contains the |
Andrew Geissler | c926e17 | 2021-05-07 16:11:35 -0500 | [diff] [blame] | 463 | ``mtr`` recipe:: |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 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 | |
| 472 | Building Your Recipe |
| 473 | ==================== |
| 474 | |
| 475 | Use the ``devtool build`` command to build your recipe. The |
| 476 | ``devtool build`` command is equivalent to the |
| 477 | ``bitbake -c populate_sysroot`` command. |
| 478 | |
| 479 | When you use the ``devtool build`` command, you must supply the root |
| 480 | name of the recipe (i.e. do not provide versions, paths, or extensions). |
Andrew Geissler | 5199d83 | 2021-09-24 16:47:35 -0500 | [diff] [blame] | 481 | You can use either the ``-s`` or the ``--disable-parallel-make`` options to |
Andrew Geissler | c926e17 | 2021-05-07 16:11:35 -0500 | [diff] [blame] | 482 | disable parallel makes during the build. Here is an example:: |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 483 | |
| 484 | $ devtool build recipe |
| 485 | |
| 486 | .. _devtool-building-your-image: |
| 487 | |
| 488 | Building Your Image |
| 489 | =================== |
| 490 | |
| 491 | Use the ``devtool build-image`` command to build an image, extending it |
| 492 | to include packages from recipes in the workspace. Using this command is |
| 493 | useful when you want an image that ready for immediate deployment onto a |
| 494 | device for testing. For proper integration into a final image, you need |
| 495 | to edit your custom image recipe appropriately. |
| 496 | |
| 497 | When you use the ``devtool build-image`` command, you must supply the |
Andrew Geissler | c926e17 | 2021-05-07 16:11:35 -0500 | [diff] [blame] | 498 | name of the image. This command has no command line options:: |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 499 | |
| 500 | $ devtool build-image image |
| 501 | |
| 502 | .. _devtool-deploying-your-software-on-the-target-machine: |
| 503 | |
| 504 | Deploying Your Software on the Target Machine |
| 505 | ============================================= |
| 506 | |
| 507 | Use the ``devtool deploy-target`` command to deploy the recipe's build |
Andrew Geissler | c926e17 | 2021-05-07 16:11:35 -0500 | [diff] [blame] | 508 | output to the live target machine:: |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 509 | |
| 510 | $ devtool deploy-target recipe target |
| 511 | |
| 512 | The target is the address of the target machine, which must be running |
| 513 | an SSH server (i.e. ``user@hostname[:destdir]``). |
| 514 | |
| 515 | This command deploys all files installed during the |
| 516 | :ref:`ref-tasks-install` task. Furthermore, you do not |
| 517 | need to have package management enabled within the target machine. If |
| 518 | you 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 | |
William A. Kennington III | ac69b48 | 2021-06-02 12:28:27 -0700 | [diff] [blame] | 526 | Some conditions could prevent a deployed application from |
| 527 | behaving as expected. When both of the following conditions are met, your |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 528 | application has the potential to not behave correctly when run on the |
| 529 | target: |
| 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 | |
William A. Kennington III | ac69b48 | 2021-06-02 12:28:27 -0700 | [diff] [blame] | 538 | If both of these conditions are met, your application will not behave as |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 539 | expected. The reason for this misbehavior is because the |
| 540 | ``devtool deploy-target`` command does not deploy the packages (e.g. |
| 541 | libraries) on which your new application depends. The assumption is that |
| 542 | the packages are already on the target. Consequently, when a runtime |
| 543 | call is made in the application for a dependent function (e.g. a library |
| 544 | call), the function cannot be found. |
| 545 | |
| 546 | To be sure you have all the dependencies local to the target, you need |
| 547 | to be sure that the packages are pre-deployed (installed) on the target |
| 548 | before attempting to run your application. |
| 549 | |
| 550 | .. _devtool-removing-your-software-from-the-target-machine: |
| 551 | |
| 552 | Removing Your Software from the Target Machine |
| 553 | ============================================== |
| 554 | |
| 555 | Use the ``devtool undeploy-target`` command to remove deployed build |
| 556 | output from the target machine. For the ``devtool undeploy-target`` |
| 557 | command to work, you must have previously used the |
Andrew Geissler | 09209ee | 2020-12-13 08:44:15 -0600 | [diff] [blame] | 558 | ":ref:`devtool deploy-target <ref-manual/devtool-reference:deploying your software on the target machine>`" |
Andrew Geissler | 517393d | 2023-01-13 08:55:19 -0600 | [diff] [blame] | 559 | command:: |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 560 | |
| 561 | $ devtool undeploy-target recipe target |
| 562 | |
| 563 | The target is the |
| 564 | address of the target machine, which must be running an SSH server (i.e. |
| 565 | ``user@hostname``). |
| 566 | |
| 567 | .. _devtool-creating-the-workspace: |
| 568 | |
| 569 | Creating the Workspace Layer in an Alternative Location |
| 570 | ======================================================= |
| 571 | |
| 572 | Use the ``devtool create-workspace`` command to create a new workspace |
| 573 | layer in your :term:`Build Directory`. When you create a |
| 574 | new workspace layer, it is populated with the ``README`` file and the |
| 575 | ``conf`` directory only. |
| 576 | |
| 577 | The following example creates a new workspace layer in your current |
Andrew Geissler | c926e17 | 2021-05-07 16:11:35 -0500 | [diff] [blame] | 578 | working and by default names the workspace layer "workspace":: |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 579 | |
| 580 | $ devtool create-workspace |
| 581 | |
| 582 | You can create a workspace layer anywhere by supplying a pathname with |
| 583 | the command. The following command creates a new workspace layer named |
Andrew Geissler | c926e17 | 2021-05-07 16:11:35 -0500 | [diff] [blame] | 584 | "new-workspace":: |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 585 | |
| 586 | $ devtool create-workspace /home/scottrif/new-workspace |
| 587 | |
| 588 | .. _devtool-get-the-status-of-the-recipes-in-your-workspace: |
| 589 | |
| 590 | Get the Status of the Recipes in Your Workspace |
| 591 | =============================================== |
| 592 | |
| 593 | Use the ``devtool status`` command to list the recipes currently in your |
| 594 | workspace. Information includes the paths to their respective external |
| 595 | source trees. |
| 596 | |
Andrew Geissler | c926e17 | 2021-05-07 16:11:35 -0500 | [diff] [blame] | 597 | The ``devtool status`` command has no command-line options:: |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 598 | |
| 599 | $ devtool status |
| 600 | |
| 601 | Following is sample output after using |
Andrew Geissler | 09209ee | 2020-12-13 08:44:15 -0600 | [diff] [blame] | 602 | :ref:`devtool add <ref-manual/devtool-reference:adding a new recipe to the workspace layer>` |
Andrew Geissler | c926e17 | 2021-05-07 16:11:35 -0500 | [diff] [blame] | 603 | to create and add the ``mtr_0.86.bb`` recipe to the ``workspace`` directory:: |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 604 | |
Andrew Geissler | 4c19ea1 | 2020-10-27 13:52:24 -0500 | [diff] [blame] | 605 | $ devtool status |
| 606 | mtr:/home/scottrif/poky/build/workspace/sources/mtr (/home/scottrif/poky/build/workspace/recipes/mtr/mtr_0.86.bb) |
Andrew Geissler | c9f7865 | 2020-09-18 14:11:35 -0500 | [diff] [blame] | 607 | $ |
| 608 | |
| 609 | .. _devtool-search-for-available-target-recipes: |
| 610 | |
| 611 | Search for Available Target Recipes |
| 612 | =================================== |
| 613 | |
| 614 | Use the ``devtool search`` command to search for available target |
| 615 | recipes. The command matches the recipe name, package name, description, |
| 616 | and installed files. The command displays the recipe name as a result of |
| 617 | a match. |
| 618 | |
| 619 | When you use the ``devtool search`` command, you must supply a keyword. |
| 620 | The command uses the keyword when searching for a match. |