summaryrefslogtreecommitdiffstats
path: root/documentation/ref-manual/ref-devtool-reference.rst
diff options
context:
space:
mode:
authorRichard Purdie <richard.purdie@linuxfoundation.org>2020-09-14 22:48:44 +0200
committerRichard Purdie <richard.purdie@linuxfoundation.org>2020-09-17 10:09:35 +0100
commit292598164a304a3da3288e6fb8963f13045d1e7f (patch)
treeefedbbdc16cb2e0978a4d40e6a6294e32b0e496f /documentation/ref-manual/ref-devtool-reference.rst
parentd313d972bf592de77f2af13cb3fc4226247cb1a1 (diff)
downloadpoky-292598164a304a3da3288e6fb8963f13045d1e7f.tar.gz
sphinx: ref-manual links fixes and many other cleanups to import
(From yocto-docs rev: d079e418d5a81610e1f06a7a6ca45dd040c1402e) Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/ref-manual/ref-devtool-reference.rst')
-rw-r--r--documentation/ref-manual/ref-devtool-reference.rst404
1 files changed, 245 insertions, 159 deletions
diff --git a/documentation/ref-manual/ref-devtool-reference.rst b/documentation/ref-manual/ref-devtool-reference.rst
index ca1d7fd0cb..eaca45ae25 100644
--- a/documentation/ref-manual/ref-devtool-reference.rst
+++ b/documentation/ref-manual/ref-devtool-reference.rst
@@ -11,8 +11,7 @@ is a key part of the extensible SDK.
11 11
12This chapter provides a Quick Reference for the ``devtool`` command. For 12This chapter provides a Quick Reference for the ``devtool`` command. For
13more information on how to apply the command when using the extensible 13more information on how to apply the command when using the extensible
14SDK, see the "`Using the Extensible 14SDK, see the ":doc:`../sdk-manual/sdk-extensible`" chapter in the Yocto
15SDK <&YOCTO_DOCS_SDK_URL;#sdk-extensible>`__" chapter in the Yocto
16Project Application Development and the Extensible Software Development 15Project Application Development and the Extensible Software Development
17Kit (eSDK) manual. 16Kit (eSDK) manual.
18 17
@@ -23,66 +22,99 @@ Getting Help
23 22
24The ``devtool`` command line is organized similarly to Git in that it 23The ``devtool`` command line is organized similarly to Git in that it
25has a number of sub-commands for each function. You can run 24has a number of sub-commands for each function. You can run
26``devtool --help`` to see all the commands: $ devtool -h NOTE: Starting 25``devtool --help`` to see all the commands:
27bitbake server... usage: devtool [--basepath BASEPATH] [--bbpath BBPATH] 26::
28[-d] [-q] [--color COLOR] [-h] <subcommand> ... OpenEmbedded development 27
29tool options: --basepath BASEPATH Base directory of SDK / build 28 $ devtool -h
30directory --bbpath BBPATH Explicitly specify the BBPATH, rather than 29 NOTE: Starting bitbake server...
31getting it from the metadata -d, --debug Enable debug output -q, --quiet 30 usage: devtool [--basepath BASEPATH] [--bbpath BBPATH] [-d] [-q] [--color COLOR] [-h] <subcommand> ...
32Print only errors --color COLOR Colorize output (where COLOR is auto, 31
33always, never) -h, --help show this help message and exit subcommands: 32 OpenEmbedded development tool
34Beginning work on a recipe: add Add a new recipe modify Modify the 33
35source for an existing recipe upgrade Upgrade an existing recipe Getting 34 options:
36information: status Show workspace status search Search available 35 --basepath BASEPATH Base directory of SDK / build directory
37recipes latest-version Report the latest version of an existing recipe 36 --bbpath BBPATH Explicitly specify the BBPATH, rather than getting it from the metadata
38check-upgrade-status Report upgradability for multiple (or all) recipes 37 -d, --debug Enable debug output
39Working on a recipe in the workspace: build Build a recipe rename Rename 38 -q, --quiet Print only errors
40a recipe file in the workspace edit-recipe Edit a recipe file 39 --color COLOR Colorize output (where COLOR is auto, always, never)
41find-recipe Find a recipe file configure-help Get help on configure 40 -h, --help show this help message and exit
42script options update-recipe Apply changes from external source tree to 41
43recipe reset Remove a recipe from your workspace finish Finish working 42 subcommands:
44on a recipe in your workspace Testing changes on target: deploy-target 43 Beginning work on a recipe:
45Deploy recipe output files to live target machine undeploy-target 44 add Add a new recipe
46Undeploy recipe output files in live target machine build-image Build 45 modify Modify the source for an existing recipe
47image including workspace recipe packages Advanced: create-workspace Set 46 upgrade Upgrade an existing recipe
48up workspace in an alternative location export Export workspace into a 47 Getting information:
49tar archive import Import exported tar archive into workspace extract 48 status Show workspace status
50Extract the source for an existing recipe sync Synchronize the source 49 latest-version Report the latest version of an existing recipe
51tree for an existing recipe Use devtool <subcommand> --help to get help 50 check-upgrade-status Report upgradability for multiple (or all) recipes
52on a specific command As directed in the general help output, you can 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
53get more syntax on a specific command by providing the command name and 81get more syntax on a specific command by providing the command name and
54using "--help": $ devtool add --help NOTE: Starting bitbake server... 82using "--help":
55usage: devtool add [-h] [--same-dir \| --no-same-dir] [--fetch URI] 83::
56[--fetch-dev] [--version VERSION] [--no-git] [--srcrev SRCREV \| 84
57--autorev] [--srcbranch SRCBRANCH] [--binary] [--also-native] 85 $ devtool add --help
58[--src-subdir SUBDIR] [--mirrors] [--provides PROVIDES] [recipename] 86 NOTE: Starting bitbake server...
59[srctree] [fetchuri] Adds a new recipe to the workspace to build a 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]
60specified source tree. Can optionally fetch a remote URI and unpack it 88 [--provides PROVIDES]
61to create the source tree. arguments: recipename Name for new recipe to 89 [recipename] [srctree] [fetchuri]
62add (just name - no version, path or extension). If not specified, will 90
63attempt to auto-detect it. srctree Path to external source tree. If not 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.
64specified, a subdirectory of /home/scottrif/poky/build/workspace/sources 92
65will be used. fetchuri Fetch the specified URI and extract it to create 93 arguments:
66the source tree options: -h, --help show this help message and exit 94 recipename Name for new recipe to add (just name - no version, path or extension). If not specified, will attempt to auto-detect it.
67--same-dir, -s Build in same directory as source --no-same-dir Force 95 srctree Path to external source tree. If not specified, a subdirectory of /media/build1/poky/build/workspace/sources will be used.
68build in a separate build directory --fetch URI, -f URI Fetch the 96 fetchuri Fetch the specified URI and extract it to create the source tree
69specified URI and extract it to create the source tree (deprecated - 97
70pass as positional argument instead) --fetch-dev For npm, also fetch 98 options:
71devDependencies --version VERSION, -V VERSION Version to use within 99 -h, --help show this help message and exit
72recipe (PV) --no-git, -g If fetching source, do not set up source tree 100 --same-dir, -s Build in same directory as source
73as a git repository --srcrev SRCREV, -S SRCREV Source revision to fetch 101 --no-same-dir Force build in a separate build directory
74if fetching from an SCM such as git (default latest) --autorev, -a When 102 --fetch URI, -f URI Fetch the specified URI and extract it to create the source tree (deprecated - pass as positional argument instead)
75fetching from a git repository, set SRCREV in the recipe to a floating 103 --npm-dev For npm, also fetch devDependencies
76revision instead of fixed --srcbranch SRCBRANCH, -B SRCBRANCH Branch in 104 --version VERSION, -V VERSION
77source repository if fetching from an SCM such as git (default master) 105 Version to use within recipe (PV)
78--binary, -b Treat the source tree as something that should be installed 106 --no-git, -g If fetching source, do not set up source tree as a git repository
79verbatim (no compilation, same directory structure). Useful with binary 107 --srcrev SRCREV, -S SRCREV
80packages e.g. RPMs. --also-native Also add native variant (i.e. support 108 Source revision to fetch if fetching from an SCM such as git (default latest)
81building recipe for the build host as well as the target machine) 109 --autorev, -a When fetching from a git repository, set SRCREV in the recipe to a floating revision instead of fixed
82--src-subdir SUBDIR Specify subdirectory within source tree to use 110 --srcbranch SRCBRANCH, -B SRCBRANCH
83--mirrors Enable PREMIRRORS and MIRRORS for source tree fetching 111 Branch in source repository if fetching from an SCM such as git (default master)
84(disable by default). --provides PROVIDES, -p PROVIDES Specify an alias 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.
85for the item provided by the recipe. E.g. virtual/libgl 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
86 118
87.. _devtool-the-workspace-layer-structure: 119.. _devtool-the-workspace-layer-structure:
88 120
@@ -99,22 +131,35 @@ The following figure shows the workspace structure:
99 :align: center 131 :align: center
100 :scale: 70% 132 :scale: 70%
101 133
102attic - A directory created if devtool believes it must preserve 134::
103anything when you run "devtool reset". For example, if you run "devtool 135
104add", make changes to the recipe, and then run "devtool reset", devtool 136 attic - A directory created if devtool believes it must preserve
105takes notice that the file has been changed and moves it into the attic 137 anything when you run "devtool reset". For example, if you
106should you still want the recipe. README - Provides information on what 138 run "devtool add", make changes to the recipe, and then
107is in workspace layer and how to manage it. .devtool_md5 - A checksum 139 run "devtool reset", devtool takes notice that the file has
108file used by devtool. appends - A directory that contains \*.bbappend 140 been changed and moves it into the attic should you still
109files, which point to external source. conf - A configuration directory 141 want the recipe.
110that contains the layer.conf file. recipes - A directory containing 142
111recipes. This directory contains a folder for each directory added whose 143 README - Provides information on what is in workspace layer and how to
112name matches that of the added recipe. devtool places the recipe.bb file 144 manage it.
113within that sub-directory. sources - A directory containing a working 145
114copy of the source files used when building the recipe. This is the 146 .devtool_md5 - A checksum file used by devtool.
115default directory used as the location of the source tree when you do 147
116not provide a source tree path. This directory contains a folder for 148 appends - A directory that contains *.bbappend files, which point to
117each set of source files matched to a corresponding recipe. 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.
118 163
119.. _devtool-adding-a-new-recipe-to-the-workspace: 164.. _devtool-adding-a-new-recipe-to-the-workspace:
120 165
@@ -127,8 +172,10 @@ you. The source files the recipe uses should exist in an external area.
127 172
128The following example creates and adds a new recipe named ``jackson`` to 173The following example creates and adds a new recipe named ``jackson`` to
129a workspace layer the tool creates. The source code built by the recipes 174a workspace layer the tool creates. The source code built by the recipes
130resides in ``/home/user/sources/jackson``: $ devtool add jackson 175resides in ``/home/user/sources/jackson``:
131/home/user/sources/jackson 176::
177
178 $ devtool add jackson /home/user/sources/jackson
132 179
133If you add a recipe and the workspace layer does not exist, the command 180If you add a recipe and the workspace layer does not exist, the command
134creates the layer and populates it as described in "`The Workspace Layer 181creates the layer and populates it as described in "`The Workspace Layer
@@ -145,35 +192,38 @@ external source tree.
145 that these packages exist on the target hardware before attempting to 192 that these packages exist on the target hardware before attempting to
146 run your application. If dependent packages (e.g. libraries) do not 193 run your application. If dependent packages (e.g. libraries) do not
147 exist on the target, your application, when run, will fail to find 194 exist on the target, your application, when run, will fail to find
148 those functions. For more information, see the " 195 those functions. For more information, see the
149 Deploying Your Software on the Target Machine 196 ":ref:`ref-manual/ref-devtool-reference:deploying your software on the target machine`"
150 " section. 197 section.
151 198
152By default, ``devtool add`` uses the latest revision (i.e. master) when 199By default, ``devtool add`` uses the latest revision (i.e. master) when
153unpacking files from a remote URI. In some cases, you might want to 200unpacking files from a remote URI. In some cases, you might want to
154specify a source revision by branch, tag, or commit hash. You can 201specify a source revision by branch, tag, or commit hash. You can
155specify these options when using the ``devtool add`` command: 202specify these options when using the ``devtool add`` command:
156 203
157- To specify a source branch, use the ``--srcbranch`` option: $ devtool 204- To specify a source branch, use the ``--srcbranch`` option:
158 add --srcbranch DISTRO_NAME_NO_CAP jackson /home/user/sources/jackson 205 ::
206
207 $ devtool add --srcbranch DISTRO_NAME_NO_CAP jackson /home/user/sources/jackson
208
159 In the previous example, you are checking out the DISTRO_NAME_NO_CAP 209 In the previous example, you are checking out the DISTRO_NAME_NO_CAP
160 branch. 210 branch.
161 211
162- To specify a specific tag or commit hash, use the ``--srcrev`` 212- To specify a specific tag or commit hash, use the ``--srcrev``
163 option: $ devtool add --srcrev DISTRO_REL_TAG jackson 213 option:
164 /home/user/sources/jackson $ devtool add --srcrev some_commit_hash 214 ::
165 /home/user/sources/jackson The previous examples check out the 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
166 DISTRO_REL_TAG tag and the commit associated with the 220 DISTRO_REL_TAG tag and the commit associated with the
167 some_commit_hash hash. 221 some_commit_hash hash.
168 222
169.. note:: 223.. note::
170 224
171 If you prefer to use the latest revision every time the recipe is 225 If you prefer to use the latest revision every time the recipe is
172 built, use the options 226 built, use the options --autorev or -a.
173 --autorev
174 or
175 -a
176 .
177 227
178.. _devtool-extracting-the-source-for-an-existing-recipe: 228.. _devtool-extracting-the-source-for-an-existing-recipe:
179 229
@@ -219,8 +269,12 @@ The ``devtool modify`` command extracts the source for a recipe, sets it
219up as a Git repository if the source had not already been fetched from 269up as a Git repository if the source had not already been fetched from
220Git, checks out a branch for development, and applies any patches from 270Git, checks out a branch for development, and applies any patches from
221the recipe as commits on top. You can use the following command to 271the recipe as commits on top. You can use the following command to
222checkout the source files: $ devtool modify recipe Using the above 272checkout the source files:
223command form, ``devtool`` uses the existing recipe's 273::
274
275 $ devtool modify recipe
276
277Using the above command form, ``devtool`` uses the existing recipe's
224:term:`SRC_URI` statement to locate the upstream source, 278:term:`SRC_URI` statement to locate the upstream source,
225extracts the source into the default sources location in the workspace. 279extracts the source into the default sources location in the workspace.
226The default development branch used is "devtool". 280The default development branch used is "devtool".
@@ -255,16 +309,24 @@ compile, and test the code.
255 309
256When you are satisfied with the results and you have committed your 310When you are satisfied with the results and you have committed your
257changes to the Git repository, you can then run the 311changes to the Git repository, you can then run the
258``devtool update-recipe`` to create the patches and update the recipe: $ 312``devtool update-recipe`` to create the patches and update the recipe:
259devtool update-recipe recipe If you run the ``devtool update-recipe`` 313::
314
315 $ devtool update-recipe recipe
316
317If you run the ``devtool update-recipe``
260without committing your changes, the command ignores the changes. 318without committing your changes, the command ignores the changes.
261 319
262Often, you might want to apply customizations made to your software in 320Often, you might want to apply customizations made to your software in
263your own layer rather than apply them to the original recipe. If so, you 321your own layer rather than apply them to the original recipe. If so, you
264can use the ``-a`` or ``--append`` option with the 322can use the ``-a`` or ``--append`` option with the
265``devtool update-recipe`` command. These options allow you to specify 323``devtool update-recipe`` command. These options allow you to specify
266the layer into which to write an append file: $ devtool update-recipe 324the layer into which to write an append file:
267recipe -a base-layer-directory The ``*.bbappend`` file is created at the 325::
326
327 $ devtool update-recipe recipe -a base-layer-directory
328
329The ``*.bbappend`` file is created at the
268appropriate path within the specified layer directory, which may or may 330appropriate path within the specified layer directory, which may or may
269not be in your ``bblayers.conf`` file. If an append file already exists, 331not be in your ``bblayers.conf`` file. If an append file already exists,
270the command updates it appropriately. 332the command updates it appropriately.
@@ -287,7 +349,7 @@ particular recipe.
287.. note:: 349.. note::
288 350
289 - For the ``oe-core`` layer, recipe maintainers come from the 351 - For the ``oe-core`` layer, recipe maintainers come from the
290 ```maintainers.inc`http://git.yoctoproject.org/cgit/cgit.cgi/poky/tree/meta/conf/distro/include/maintainers.inc 352 `maintainers.inc <http://git.yoctoproject.org/cgit/cgit.cgi/poky/tree/meta/conf/distro/include/maintainers.inc>`_
291 file. 353 file.
292 354
293 - If the recipe is using the :ref:`bitbake:git-fetcher` 355 - If the recipe is using the :ref:`bitbake:git-fetcher`
@@ -296,14 +358,21 @@ particular recipe.
296 recipe's latest version tag. 358 recipe's latest version tag.
297 359
298As with all ``devtool`` commands, you can get help on the individual 360As with all ``devtool`` commands, you can get help on the individual
299command: $ devtool check-upgrade-status -h NOTE: Starting bitbake 361command:
300server... usage: devtool check-upgrade-status [-h] [--all] [recipe 362::
301[recipe ...]] Prints a table of recipes together with versions currently 363
302provided by recipes, and latest upstream versions, when there is a later 364 $ devtool check-upgrade-status -h
303version available arguments: recipe Name of the recipe to report (omit 365 NOTE: Starting bitbake server...
304to report upgrade info for all recipes) options: -h, --help show this 366 usage: devtool check-upgrade-status [-h] [--all] [recipe [recipe ...]]
305help message and exit --all, -a Show all recipes, not just recipes 367
306needing upgrade 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
307 376
308Unless you provide a specific recipe name on the command line, the 377Unless you provide a specific recipe name on the command line, the
309command checks all recipes in all configured layers. 378command checks all recipes in all configured layers.
@@ -317,21 +386,18 @@ satisfied.
317.. note:: 386.. note::
318 387
319 When a reason for not upgrading displays, the reason is usually 388 When a reason for not upgrading displays, the reason is usually
320 written into the recipe using the 389 written into the recipe using the RECIPE_NO_UPDATE_REASON
321 RECIPE_NO_UPDATE_REASON 390 variable. See the base-passwd.bb recipe for an example.
322 variable. See the 391
323 base-passwd.bb 392::
324 recipe for an example. 393
325 394 $ devtool check-upgrade-status ...
326$ devtool check-upgrade-status ... NOTE: acpid 2.0.30 2.0.31 Ross Burton 395 NOTE: acpid 2.0.30 2.0.31 Ross Burton <ross.burton@intel.com>
327<ross.burton@intel.com> NOTE: u-boot-fw-utils 2018.11 2019.01 Marek 396 NOTE: u-boot-fw-utils 2018.11 2019.01 Marek Vasut <marek.vasut@gmail.com> d3689267f92c5956e09cc7d1baa4700141662bff
328Vasut <marek.vasut@gmail.com> d3689267f92c5956e09cc7d1baa4700141662bff 397 NOTE: u-boot-tools 2018.11 2019.01 Marek Vasut <marek.vasut@gmail.com> d3689267f92c5956e09cc7d1baa4700141662bff . . .
329NOTE: u-boot-tools 2018.11 2019.01 Marek Vasut <marek.vasut@gmail.com> 398 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
330d3689267f92c5956e09cc7d1baa4700141662bff . . . NOTE: base-passwd 3.5.29 399 NOTE: busybox 1.29.2 1.30.0 Andrej Valek <andrej.valek@siemens.com>
3313.5.45 Anuj Mittal <anuj.mittal@intel.com> cannot be updated due to: 400 NOTE: dbus-test 1.12.10 1.12.12 Chen Qi <Qi.Chen@windriver.com>
332Version 3.5.38 requires cdebconf for update-passwd utility NOTE: busybox
3331.29.2 1.30.0 Andrej Valek <andrej.valek@siemens.com> NOTE: dbus-test
3341.12.10 1.12.12 Chen Qi <Qi.Chen@windriver.com>
335 401
336.. _devtool-upgrading-a-recipe: 402.. _devtool-upgrading-a-recipe:
337 403
@@ -341,17 +407,13 @@ Upgrading a Recipe
341As software matures, upstream recipes are upgraded to newer versions. As 407As software matures, upstream recipes are upgraded to newer versions. As
342a developer, you need to keep your local recipes up-to-date with the 408a developer, you need to keep your local recipes up-to-date with the
343upstream version releases. Several methods exist by which you can 409upstream version releases. Several methods exist by which you can
344upgrade recipes. You can read about them in the "`Upgrading 410upgrade recipes. You can read about them in the ":ref:`gs-upgrading-recipes`"
345Recipes <&YOCTO_DOCS_DEV_URL;#gs-upgrading-recipes>`__" section of the 411section of the Yocto Project Development Tasks Manual. This section
346Yocto Project Development Tasks Manual. This section overviews the 412overviews the ``devtool upgrade`` command.
347``devtool upgrade`` command.
348 413
349.. note:: 414Before you upgrade a recipe, you can check on its upgrade status. See
350 415the ":ref:`devtool-checking-on-the-upgrade-status-of-a-recipe`" section
351 Before you upgrade a recipe, you can check on its upgrade status. See 416for more information.
352 the "
353 Checking on the Upgrade Status of a Recipe
354 " for more information.
355 417
356The ``devtool upgrade`` command upgrades an existing recipe to a more 418The ``devtool upgrade`` command upgrades an existing recipe to a more
357recent version of the recipe upstream. The command puts the upgraded 419recent version of the recipe upstream. The command puts the upgraded
@@ -369,14 +431,11 @@ revision to which you want to upgrade (i.e. the
369:term:`SRCREV`), whether or not to apply patches, and so 431:term:`SRCREV`), whether or not to apply patches, and so
370forth. 432forth.
371 433
372You can read more on the ``devtool upgrade`` workflow in the "`Use 434You can read more on the ``devtool upgrade`` workflow in the
373``devtool upgrade`` to Create a Version of the Recipe that Supports a 435":ref:`sdk-devtool-use-devtool-upgrade-to-create-a-version-of-the-recipe-that-supports-a-newer-version-of-the-software`"
374Newer Version of the
375Software <&YOCTO_DOCS_SDK_URL;#sdk-devtool-use-devtool-upgrade-to-create-a-version-of-the-recipe-that-supports-a-newer-version-of-the-software>`__"
376section in the Yocto Project Application Development and the Extensible 436section in the Yocto Project Application Development and the Extensible
377Software Development Kit (eSDK) manual. You can also see an example of 437Software Development Kit (eSDK) manual. You can also see an example of
378how to use ``devtool upgrade`` in the "`Using 438how to use ``devtool upgrade`` in the ":ref:`gs-using-devtool-upgrade`"
379``devtool upgrade`` <&YOCTO_DOCS_DEV_URL;#gs-using-devtool-upgrade>`__"
380section in the Yocto Project Development Tasks Manual. 439section in the Yocto Project Development Tasks Manual.
381 440
382.. _devtool-resetting-a-recipe: 441.. _devtool-resetting-a-recipe:
@@ -397,10 +456,13 @@ files have been modified, the command preserves the modified files in a
397separate "attic" subdirectory under the workspace layer. 456separate "attic" subdirectory under the workspace layer.
398 457
399Here is an example that resets the workspace directory that contains the 458Here is an example that resets the workspace directory that contains the
400``mtr`` recipe: $ devtool reset mtr NOTE: Cleaning sysroot for recipe 459``mtr`` recipe:
401mtr... NOTE: Leaving source tree 460::
402/home/scottrif/poky/build/workspace/sources/mtr as-is; if you no longer 461
403need it then please delete it manually $ 462 $ devtool reset mtr
463 NOTE: Cleaning sysroot for recipe mtr...
464 NOTE: Leaving source tree /home/scottrif/poky/build/workspace/sources/mtr as-is; if you no longer need it then please delete it manually
465 $
404 466
405.. _devtool-building-your-recipe: 467.. _devtool-building-your-recipe:
406 468
@@ -414,8 +476,10 @@ Use the ``devtool build`` command to build your recipe. The
414When you use the ``devtool build`` command, you must supply the root 476When you use the ``devtool build`` command, you must supply the root
415name of the recipe (i.e. do not provide versions, paths, or extensions). 477name of the recipe (i.e. do not provide versions, paths, or extensions).
416You can use either the "-s" or the "--disable-parallel-make" options to 478You can use either the "-s" or the "--disable-parallel-make" options to
417disable parallel makes during the build. Here is an example: $ devtool 479disable parallel makes during the build. Here is an example:
418build recipe 480::
481
482 $ devtool build recipe
419 483
420.. _devtool-building-your-image: 484.. _devtool-building-your-image:
421 485
@@ -429,8 +493,10 @@ device for testing. For proper integration into a final image, you need
429to edit your custom image recipe appropriately. 493to edit your custom image recipe appropriately.
430 494
431When you use the ``devtool build-image`` command, you must supply the 495When you use the ``devtool build-image`` command, you must supply the
432name of the image. This command has no command line options: $ devtool 496name of the image. This command has no command line options:
433build-image image 497::
498
499 $ devtool build-image image
434 500
435.. _devtool-deploying-your-software-on-the-target-machine: 501.. _devtool-deploying-your-software-on-the-target-machine:
436 502
@@ -438,7 +504,11 @@ Deploying Your Software on the Target Machine
438============================================= 504=============================================
439 505
440Use the ``devtool deploy-target`` command to deploy the recipe's build 506Use the ``devtool deploy-target`` command to deploy the recipe's build
441output to the live target machine: $ devtool deploy-target recipe target 507output to the live target machine:
508::
509
510 $ devtool deploy-target recipe target
511
442The target is the address of the target machine, which must be running 512The target is the address of the target machine, which must be running
443an SSH server (i.e. ``user@hostname[:destdir]``). 513an SSH server (i.e. ``user@hostname[:destdir]``).
444 514
@@ -485,8 +555,13 @@ Removing Your Software from the Target Machine
485Use the ``devtool undeploy-target`` command to remove deployed build 555Use the ``devtool undeploy-target`` command to remove deployed build
486output from the target machine. For the ``devtool undeploy-target`` 556output from the target machine. For the ``devtool undeploy-target``
487command to work, you must have previously used the 557command to work, you must have previously used the
488```devtool deploy-target`` <#devtool-deploying-your-software-on-the-target-machine>`__ 558":ref:`devtool deploy-target <ref-manual/ref-devtool-reference:deploying your software on the target machine>`"
489command. $ devtool undeploy-target recipe target The target is the 559command.
560::
561
562 $ devtool undeploy-target recipe target
563
564The target is the
490address of the target machine, which must be running an SSH server (i.e. 565address of the target machine, which must be running an SSH server (i.e.
491``user@hostname``). 566``user@hostname``).
492 567
@@ -501,12 +576,17 @@ new workspace layer, it is populated with the ``README`` file and the
501``conf`` directory only. 576``conf`` directory only.
502 577
503The following example creates a new workspace layer in your current 578The following example creates a new workspace layer in your current
504working and by default names the workspace layer "workspace": $ devtool 579working and by default names the workspace layer "workspace":
505create-workspace 580::
581
582 $ devtool create-workspace
506 583
507You can create a workspace layer anywhere by supplying a pathname with 584You can create a workspace layer anywhere by supplying a pathname with
508the command. The following command creates a new workspace layer named 585the command. The following command creates a new workspace layer named
509"new-workspace": $ devtool create-workspace /home/scottrif/new-workspace 586"new-workspace":
587::
588
589 $ devtool create-workspace /home/scottrif/new-workspace
510 590
511.. _devtool-get-the-status-of-the-recipes-in-your-workspace: 591.. _devtool-get-the-status-of-the-recipes-in-your-workspace:
512 592
@@ -517,13 +597,19 @@ Use the ``devtool status`` command to list the recipes currently in your
517workspace. Information includes the paths to their respective external 597workspace. Information includes the paths to their respective external
518source trees. 598source trees.
519 599
520The ``devtool status`` command has no command-line options: $ devtool 600The ``devtool status`` command has no command-line options:
521status Following is sample output after using 601::
522```devtool add`` <#devtool-adding-a-new-recipe-to-the-workspace>`__ to 602
523create and add the ``mtr_0.86.bb`` recipe to the ``workspace`` 603 $ devtool status
524directory: $ devtool status mtr: 604
525/home/scottrif/poky/build/workspace/sources/mtr 605Following is sample output after using
526(/home/scottrif/poky/build/workspace/recipes/mtr/mtr_0.86.bb) $ 606:ref:`devtool add <ref-manual/ref-devtool-reference:adding a new recipe to the workspace layer>`
607to create and add the ``mtr_0.86.bb`` recipe to the ``workspace`` directory:
608::
609
610 $ devtool status mtr
611 :/home/scottrif/poky/build/workspace/sources/mtr (/home/scottrif/poky/build/workspace/recipes/mtr/mtr_0.86.bb)
612 $
527 613
528.. _devtool-search-for-available-target-recipes: 614.. _devtool-search-for-available-target-recipes:
529 615