diff options
Diffstat (limited to 'documentation/ref-manual/devtool-reference.rst')
| -rw-r--r-- | documentation/ref-manual/devtool-reference.rst | 106 |
1 files changed, 56 insertions, 50 deletions
diff --git a/documentation/ref-manual/devtool-reference.rst b/documentation/ref-manual/devtool-reference.rst index 0ce3219831..9319addc3c 100644 --- a/documentation/ref-manual/devtool-reference.rst +++ b/documentation/ref-manual/devtool-reference.rst @@ -78,7 +78,7 @@ has a number of sub-commands for each function. You can run As directed in the general help output, you can get more syntax on a specific command by providing the command name and -using "--help":: +using ``--help``:: $ devtool add --help NOTE: Starting bitbake server... @@ -126,8 +126,7 @@ common working area used across the tool. The following figure shows the workspace structure: .. image:: figures/build-workspace-directory.png - :align: center - :scale: 70% + :scale: 100% .. code-block:: none @@ -165,7 +164,7 @@ Adding a New Recipe to the Workspace Layer ========================================== Use the ``devtool add`` command to add a new recipe to the workspace -layer. The recipe you add should not exist - ``devtool`` creates it for +layer. The recipe you add should not exist --- ``devtool`` creates it for you. The source files the recipe uses should exist in an external area. The following example creates and adds a new recipe named ``jackson`` to @@ -284,10 +283,7 @@ is identified using the ``EDITOR`` variable, on the specified recipe. When you use the ``devtool edit-recipe`` command, you must supply the root name of the recipe (i.e. no version, paths, or extensions). Also, the recipe file itself must reside in the workspace as a result of the -``devtool add`` or ``devtool upgrade`` commands. However, you can -override that requirement by using the "-a" or "--any-recipe" option. -Using either of these options allows you to edit any recipe regardless -of its location. +``devtool add`` or ``devtool upgrade`` commands. .. _devtool-updating-a-recipe: @@ -331,23 +327,37 @@ Checking on the Upgrade Status of a Recipe Upstream recipes change over time. Consequently, you might find that you need to determine if you can upgrade a recipe to a newer version. -To check on the upgrade status of a recipe, use the -``devtool check-upgrade-status`` command. The command displays a table -of your current recipe versions, the latest upstream versions, the email -address of the recipe's maintainer, and any additional information such -as commit hash strings and reasons you might not be able to upgrade a -particular recipe. +To check on the upgrade status of a recipe, you can use the +``devtool latest-version recipe`` command, which quickly shows the current +version and the latest version available upstream. To get a more global +picture, use the ``devtool check-upgrade-status`` command, which takes a +list of recipes as input, or no arguments, in which case it checks all +available recipes. This command will only print the recipes for which +a new upstream version is available. Each such recipe will have its current +version and latest upstream version, as well as the email of the maintainer +and any additional information such as the commit hash or reason for not +being able to upgrade it, displayed in a table. + +This upgrade checking mechanism relies on the optional :term:`UPSTREAM_CHECK_URI`, +:term:`UPSTREAM_CHECK_REGEX`, :term:`UPSTREAM_CHECK_GITTAGREGEX`, +:term:`UPSTREAM_CHECK_COMMITS` and :term:`UPSTREAM_VERSION_UNKNOWN` +variables in package recipes. .. note:: + - Most of the time, the above variables are unnecessary. They are only + required when upstream does something unusual, and default + mechanisms cannot find the new upstream versions. + - For the ``oe-core`` layer, recipe maintainers come from the :yocto_git:`maintainers.inc </poky/tree/meta/conf/distro/include/maintainers.inc>` file. - - If the recipe is using the :ref:`bitbake:bitbake-user-manual/bitbake-user-manual-fetching:git fetcher (\`\`git://\`\`)` - rather than a - tarball, the commit hash points to the commit that matches the - recipe's latest version tag. + - If the recipe is using the :ref:`bitbake-user-manual/bitbake-user-manual-fetching:git fetcher (\`\`git://\`\`)` + rather than a tarball, the commit hash points to the commit that matches + the recipe's latest version tag, or in the absence of suitable tags, + to the latest commit (when :term:`UPSTREAM_CHECK_COMMITS` set to ``1`` + in the recipe). As with all ``devtool`` commands, you can get help on the individual command:: @@ -368,33 +378,30 @@ command:: Unless you provide a specific recipe name on the command line, the command checks all recipes in all configured layers. -Following is a partial example table that reports on all the recipes. +Here is a partial example table that reports on all the recipes:: + + $ devtool check-upgrade-status + ... + INFO: bind 9.16.20 9.16.21 Armin Kuster <akuster808@gmail.com> + INFO: inetutils 2.1 2.2 Tom Rini <trini@konsulko.com> + INFO: iproute2 5.13.0 5.14.0 Changhyeok Bae <changhyeok.bae@gmail.com> + INFO: openssl 1.1.1l 3.0.0 Alexander Kanavin <alex.kanavin@gmail.com> + 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 + ... + Notice the reported reason for not upgrading the ``base-passwd`` recipe. In this example, while a new version is available upstream, you do not want to use it because the dependency on ``cdebconf`` is not easily -satisfied. +satisfied. Maintainers can explicit the reason that is shown by adding +the :term:`RECIPE_NO_UPDATE_REASON` variable to the corresponding recipe. +See :yocto_git:`base-passwd.bb </poky/tree/meta/recipes-core/base-passwd/base-passwd_3.5.29.bb?h=kirkstone>` +for an example:: -.. note:: - - When a reason for not upgrading displays, the reason is usually - written into the recipe using the ``RECIPE_NO_UPDATE_REASON`` - variable. See the - :yocto_git:`base-passwd.bb </poky/tree/meta/recipes-core/base-passwd/base-passwd_3.5.29.bb>` - recipe for an example. - -:: + RECIPE_NO_UPDATE_REASON = "Version 3.5.38 requires cdebconf for update-passwd utility" - $ devtool check-upgrade-status - ... - NOTE: acpid 2.0.30 2.0.31 Ross Burton <ross.burton@intel.com> - NOTE: u-boot-fw-utils 2018.11 2019.01 Marek Vasut <marek.vasut@gmail.com> d3689267f92c5956e09cc7d1baa4700141662bff - NOTE: u-boot-tools 2018.11 2019.01 Marek Vasut <marek.vasut@gmail.com> d3689267f92c5956e09cc7d1baa4700141662bff - . - . - . - 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 - NOTE: busybox 1.29.2 1.30.0 Andrej Valek <andrej.valek@siemens.com> - NOTE: dbus-test 1.12.10 1.12.12 Chen Qi <Qi.Chen@windriver.com> +Last but not least, you may set :term:`UPSTREAM_VERSION_UNKNOWN` to ``1`` +in a recipe when there's currently no way to determine its latest upstream +version. .. _devtool-upgrading-a-recipe: @@ -403,8 +410,8 @@ Upgrading a Recipe As software matures, upstream recipes are upgraded to newer versions. As a developer, you need to keep your local recipes up-to-date with the -upstream version releases. Several methods exist by which you can -upgrade recipes. You can read about them in the ":ref:`dev-manual/common-tasks:upgrading recipes`" +upstream version releases. There are several ways of upgrading recipes. +You can read about them in the ":ref:`dev-manual/upgrading-recipes:upgrading recipes`" section of the Yocto Project Development Tasks Manual. This section overviews the ``devtool upgrade`` command. @@ -432,7 +439,7 @@ You can read more on the ``devtool upgrade`` workflow in the ":ref:`sdk-manual/extensible:use \`\`devtool upgrade\`\` to create a version of the recipe that supports a newer version of the software`" section in the Yocto Project Application Development and the Extensible Software Development Kit (eSDK) manual. You can also see an example of -how to use ``devtool upgrade`` in the ":ref:`dev-manual/common-tasks:using \`\`devtool upgrade\`\``" +how to use ``devtool upgrade`` in the ":ref:`dev-manual/upgrading-recipes:using \`\`devtool upgrade\`\``" section in the Yocto Project Development Tasks Manual. .. _devtool-resetting-a-recipe: @@ -471,7 +478,7 @@ Use the ``devtool build`` command to build your recipe. The When you use the ``devtool build`` command, you must supply the root name of the recipe (i.e. do not provide versions, paths, or extensions). -You can use either the "-s" or the "--disable-parallel-make" options to +You can use either the ``-s`` or the ``--disable-parallel-make`` options to disable parallel makes during the build. Here is an example:: $ devtool build recipe @@ -516,8 +523,8 @@ you do, the package manager is bypassed. should never use it to update an image that will be used in production. -Some conditions exist that could prevent a deployed application from -behaving as expected. When both of the following conditions exist, your +Some conditions could prevent a deployed application from +behaving as expected. When both of the following conditions are met, your application has the potential to not behave correctly when run on the target: @@ -528,7 +535,7 @@ target: - The target does not physically have the packages on which the application depends installed. -If both of these conditions exist, your application will not behave as +If both of these conditions are met, your application will not behave as expected. The reason for this misbehavior is because the ``devtool deploy-target`` command does not deploy the packages (e.g. libraries) on which your new application depends. The assumption is that @@ -549,8 +556,7 @@ Use the ``devtool undeploy-target`` command to remove deployed build output from the target machine. For the ``devtool undeploy-target`` command to work, you must have previously used the ":ref:`devtool deploy-target <ref-manual/devtool-reference:deploying your software on the target machine>`" -command. -:: +command:: $ devtool undeploy-target recipe target @@ -592,7 +598,7 @@ The ``devtool status`` command has no command-line options:: $ devtool status -Following is sample output after using +Here is sample output after using :ref:`devtool add <ref-manual/devtool-reference:adding a new recipe to the workspace layer>` to create and add the ``mtr_0.86.bb`` recipe to the ``workspace`` directory:: |