blob: 5075f0c224ec7553ced154ec5a8821d08a557694 [file] [log] [blame]
Andrew Geisslerf0343792020-11-18 10:42:21 -06001.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002
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
Andrew Geissler09209ee2020-12-13 08:44:15 -060014SDK, see the ":doc:`/sdk-manual/extensible`" chapter in the Yocto
Andrew Geisslerc9f78652020-09-18 14:11:35 -050015Project 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
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500134.. code-block:: none
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500135
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
Andrew Geissler09209ee2020-12-13 08:44:15 -0600196 ":ref:`ref-manual/devtool-reference:deploying your software on the target machine`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500197 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
Andrew Geisslerd1e89492021-02-12 15:35:20 -0600207 $ devtool add --srcbranch &DISTRO_NAME_NO_CAP; jackson /home/user/sources/jackson
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500208
Andrew Geisslerd1e89492021-02-12 15:35:20 -0600209 In the previous example, you are checking out the &DISTRO_NAME_NO_CAP;
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500210 branch.
211
212- To specify a specific tag or commit hash, use the ``--srcrev``
213 option:
214 ::
215
Andrew Geisslerd1e89492021-02-12 15:35:20 -0600216 $ devtool add --srcrev &DISTRO_REL_TAG; jackson /home/user/sources/jackson
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500217 $ devtool add --srcrev some_commit_hash /home/user/sources/jackson
218
219 The previous examples check out the
Andrew Geisslerd1e89492021-02-12 15:35:20 -0600220 &DISTRO_REL_TAG; tag and the commit associated with the
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500221 some_commit_hash hash.
222
223.. note::
224
225 If you prefer to use the latest revision every time the recipe is
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500226 built, use the options ``--autorev`` or ``-a``.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500227
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
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500264:ref:`add <devtool-adding-a-new-recipe-to-the-workspace>` command
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500265except 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
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500306:ref:`devtool modify <devtool-modifying-a-recipe>` command to extract
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500307the 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
Andrew Geissler09209ee2020-12-13 08:44:15 -0600352 :yocto_git:`maintainers.inc </poky/tree/meta/conf/distro/include/maintainers.inc>`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500353 file.
354
Andrew Geissler09209ee2020-12-13 08:44:15 -0600355 - If the recipe is using the :ref:`bitbake:bitbake-user-manual/bitbake-user-manual-fetching:git fetcher (\`\`git://\`\`)`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500356 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
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500389 written into the recipe using the ``RECIPE_NO_UPDATE_REASON``
390 variable. See the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600391 :yocto_git:`base-passwd.bb </poky/tree/meta/recipes-core/base-passwd/base-passwd_3.5.29.bb>`
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500392 recipe for an example.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500393
394::
395
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500396 $ devtool check-upgrade-status
397 ...
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500398 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
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500400 NOTE: u-boot-tools 2018.11 2019.01 Marek Vasut <marek.vasut@gmail.com> d3689267f92c5956e09cc7d1baa4700141662bff
401 .
402 .
403 .
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500404 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
Andrew Geissler09209ee2020-12-13 08:44:15 -0600416upgrade recipes. You can read about them in the ":ref:`dev-manual/common-tasks:upgrading recipes`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500417section 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
Andrew Geissler09209ee2020-12-13 08:44:15 -0600441":ref:`sdk-manual/extensible:use \`\`devtool upgrade\`\` to create a version of the recipe that supports a newer version of the software`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500442section in the Yocto Project Application Development and the Extensible
443Software Development Kit (eSDK) manual. You can also see an example of
Andrew Geissler09209ee2020-12-13 08:44:15 -0600444how to use ``devtool upgrade`` in the ":ref:`dev-manual/common-tasks:using \`\`devtool upgrade\`\``"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500445section 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
Andrew Geissler09209ee2020-12-13 08:44:15 -0600564":ref:`devtool deploy-target <ref-manual/devtool-reference:deploying your software on the target machine>`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500565command.
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
Andrew Geissler09209ee2020-12-13 08:44:15 -0600612:ref:`devtool add <ref-manual/devtool-reference:adding a new recipe to the workspace layer>`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500613to create and add the ``mtr_0.86.bb`` recipe to the ``workspace`` directory:
614::
615
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500616 $ devtool status
617 mtr:/home/scottrif/poky/build/workspace/sources/mtr (/home/scottrif/poky/build/workspace/recipes/mtr/mtr_0.86.bb)
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500618 $
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.