blob: 11f7399c5a8f085578b4be219c99009e311630d3 [file] [log] [blame]
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
<chapter id='ref-devtool-reference'>
<title><filename>devtool</filename> Quick Reference</title>
<para>
The <filename>devtool</filename> command-line tool provides a number
of features that help you build, test, and package software.
This command is available alongside the <filename>bitbake</filename>
command.
Additionally, the <filename>devtool</filename> command is a key
part of the extensible SDK.
</para>
<para>
This chapter provides a Quick Reference for the
<filename>devtool</filename> command.
For more information on how to apply the command when using the
extensible SDK, see the
"<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-extensible'>Using the Extensible SDK</ulink>"
chapter in the Yocto Project Application Development and the
Extensible Software Development Kit (eSDK) manual.
</para>
<section id='devtool-getting-help'>
<title>Getting Help</title>
<para>
The <filename>devtool</filename> command line is organized
similarly to Git in that it has a number of sub-commands for
each function.
You can run <filename>devtool --help</filename> to see all
the commands:
<literallayout class='monospaced'>
$ devtool -h
NOTE: Starting bitbake server...
usage: devtool [--basepath BASEPATH] [--bbpath BBPATH] [-d] [-q]
[--color COLOR] [-h]
&lt;subcommand&gt; ...
OpenEmbedded development tool
options:
--basepath BASEPATH Base directory of SDK / build directory
--bbpath BBPATH Explicitly specify the BBPATH, rather than getting it
from the metadata
-d, --debug Enable debug output
-q, --quiet Print only errors
--color COLOR Colorize output (where COLOR is auto, always, never)
-h, --help show this help message and exit
subcommands:
Beginning work on a recipe:
add Add a new recipe
modify Modify the source for an existing recipe
upgrade Upgrade an existing recipe
Getting information:
status Show workspace status
search Search available recipes
latest-version Report the latest version of an existing recipe
check-upgrade-status Report upgradability for multiple (or all) recipes
Working on a recipe in the workspace:
build Build a recipe
rename Rename a recipe file in the workspace
edit-recipe Edit a recipe file
find-recipe Find a recipe file
configure-help Get help on configure script options
update-recipe Apply changes from external source tree to recipe
reset Remove a recipe from your workspace
finish Finish working on a recipe in your workspace
Testing changes on target:
deploy-target Deploy recipe output files to live target machine
undeploy-target Undeploy recipe output files in live target machine
build-image Build image including workspace recipe packages
Advanced:
create-workspace Set up workspace in an alternative location
export Export workspace into a tar archive
import Import exported tar archive into workspace
extract Extract the source for an existing recipe
sync Synchronize the source tree for an existing recipe
Use devtool &lt;subcommand&gt; --help to get help on a specific command
</literallayout>
As directed in the general help output, you can get more syntax
on a specific command by providing the command name and using
"--help":
<literallayout class='monospaced'>
$ devtool add --help
NOTE: Starting bitbake server...
usage: devtool add [-h] [--same-dir | --no-same-dir] [--fetch URI]
[--fetch-dev] [--version VERSION] [--no-git]
[--srcrev SRCREV | --autorev] [--srcbranch SRCBRANCH]
[--binary] [--also-native] [--src-subdir SUBDIR]
[--mirrors] [--provides PROVIDES]
[recipename] [srctree] [fetchuri]
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.
arguments:
recipename Name for new recipe to add (just name - no version,
path or extension). If not specified, will attempt to
auto-detect it.
srctree Path to external source tree. If not specified, a
subdirectory of
/home/scottrif/poky/build/workspace/sources will be
used.
fetchuri Fetch the specified URI and extract it to create the
source tree
options:
-h, --help show this help message and exit
--same-dir, -s Build in same directory as source
--no-same-dir Force build in a separate build directory
--fetch URI, -f URI Fetch the specified URI and extract it to create the
source tree (deprecated - pass as positional argument
instead)
--fetch-dev For npm, also fetch devDependencies
--version VERSION, -V VERSION
Version to use within recipe (PV)
--no-git, -g If fetching source, do not set up source tree as a git
repository
--srcrev SRCREV, -S SRCREV
Source revision to fetch if fetching from an SCM such
as git (default latest)
--autorev, -a When fetching from a git repository, set SRCREV in the
recipe to a floating revision instead of fixed
--srcbranch SRCBRANCH, -B SRCBRANCH
Branch in source repository if fetching from an SCM
such as git (default master)
--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.
--also-native Also add native variant (i.e. support building recipe
for the build host as well as the target machine)
--src-subdir SUBDIR Specify subdirectory within source tree to use
--mirrors Enable PREMIRRORS and MIRRORS for source tree fetching
(disable by default).
--provides PROVIDES, -p PROVIDES
Specify an alias for the item provided by the recipe.
E.g. virtual/libgl
</literallayout>
</para>
</section>
<section id='devtool-the-workspace-layer-structure'>
<title>The Workspace Layer Structure</title>
<para>
<filename>devtool</filename> uses a "Workspace" layer
in which to accomplish builds.
This layer is not specific to any single
<filename>devtool</filename> command but is rather a common
working area used across the tool.
</para>
<para>
The following figure shows the workspace structure:
</para>
<para>
<imagedata fileref="figures/build-workspace-directory.png"
width="6in" depth="5in" align="left" scale="70" />
</para>
<para>
<literallayout class='monospaced'>
attic - A directory created if devtool believes it must preserve
anything when you run "devtool reset". For example, if you
run "devtool add", make changes to the recipe, and then
run "devtool reset", devtool takes notice that the file has
been changed and moves it into the attic should you still
want the recipe.
README - Provides information on what is in workspace layer and how to
manage it.
.devtool_md5 - A checksum file used by devtool.
appends - A directory that contains *.bbappend files, which point to
external source.
conf - A configuration directory that contains the layer.conf file.
recipes - A directory containing recipes. This directory contains a
folder for each directory added whose name matches that of the
added recipe. devtool places the <replaceable>recipe</replaceable>.bb file
within that sub-directory.
sources - A directory containing a working copy of the source files used
when building the recipe. This is the default directory used
as the location of the source tree when you do not provide a
source tree path. This directory contains a folder for each
set of source files matched to a corresponding recipe.
</literallayout>
</para>
</section>
<section id='devtool-adding-a-new-recipe-to-the-workspace'>
<title>Adding a New Recipe to the Workspace Layer</title>
<para>
Use the <filename>devtool add</filename> command to add a new recipe
to the workspace layer.
The recipe you add should not exist -
<filename>devtool</filename> creates it for you.
The source files the recipe uses should exist in an external
area.
</para>
<para>
The following example creates and adds a new recipe named
<filename>jackson</filename> to a workspace layer the tool creates.
The source code built by the recipes resides in
<filename>/home/<replaceable>user</replaceable>/sources/jackson</filename>:
<literallayout class='monospaced'>
$ devtool add jackson /home/<replaceable>user</replaceable>/sources/jackson
</literallayout>
</para>
<para>
If you add a recipe and the workspace layer does not exist,
the command creates the layer and populates it as
described in
"<link linkend='devtool-the-workspace-layer-structure'>The Workspace Layer Structure</link>"
section.
</para>
<para>
Running <filename>devtool add</filename> when the
workspace layer exists causes the tool to add the recipe,
append files, and source files into the existing workspace layer.
The <filename>.bbappend</filename> file is created to point
to the external source tree.
<note>
If your recipe has runtime dependencies defined, you must be sure
that these packages exist on the target hardware before attempting
to run your application.
If dependent packages (e.g. libraries) do not exist on the target,
your application, when run, will fail to find those functions.
For more information, see the
"<link linkend='devtool-deploying-your-software-on-the-target-machine'>Deploying Your Software on the Target Machine</link>"
section.
</note>
</para>
<para>
By default, <filename>devtool add</filename> uses the latest
revision (i.e. master) when unpacking files from a remote URI.
In some cases, you might want to specify a source revision by
branch, tag, or commit hash. You can specify these options when
using the <filename>devtool add</filename> command:
<itemizedlist>
<listitem><para>
To specify a source branch, use the
<filename>--srcbranch</filename> option:
<literallayout class='monospaced'>
$ devtool add --srcbranch &DISTRO_NAME_NO_CAP; jackson /home/<replaceable>user</replaceable>/sources/jackson
</literallayout>
In the previous example, you are checking out the
&DISTRO_NAME_NO_CAP; branch.
</para></listitem>
<listitem><para>
To specify a specific tag or commit hash, use the
<filename>--srcrev</filename> option:
<literallayout class='monospaced'>
$ devtool add --srcrev &DISTRO_REL_TAG; jackson /home/<replaceable>user</replaceable>/sources/jackson
$ devtool add --srcrev <replaceable>some_commit_hash</replaceable> /home/<replaceable>user</replaceable>/sources/jackson
</literallayout>
The previous examples check out the &DISTRO_REL_TAG; tag
and the commit associated with the
<replaceable>some_commit_hash</replaceable> hash.
</para></listitem>
</itemizedlist>
<note>
If you prefer to use the latest revision every time the recipe is
built, use the options <filename>--autorev</filename>
or <filename>-a</filename>.
</note>
</para>
</section>
<section id='devtool-extracting-the-source-for-an-existing-recipe'>
<title>Extracting the Source for an Existing Recipe</title>
<para>
Use the <filename>devtool extract</filename> command to
extract the source for an existing recipe.
When you use this command, you must supply the root name
of the recipe (i.e. no version, paths, or extensions), and
you must supply the directory to which you want the source
extracted.
</para>
<para>
Additional command options let you control the name of a
development branch into which you can checkout the source
and whether or not to keep a temporary directory, which is
useful for debugging.
</para>
</section>
<section id='devtool-synchronizing-a-recipes-extracted-source-tree'>
<title>Synchronizing a Recipe's Extracted Source Tree</title>
<para>
Use the <filename>devtool sync</filename> command to
synchronize a previously extracted source tree for an
existing recipe.
When you use this command, you must supply the root name
of the recipe (i.e. no version, paths, or extensions), and
you must supply the directory to which you want the source
extracted.
</para>
<para>
Additional command options let you control the name of a
development branch into which you can checkout the source
and whether or not to keep a temporary directory, which is
useful for debugging.
</para>
</section>
<section id='devtool-modifying-a-recipe'>
<title>Modifying an Existing Recipe</title>
<para>
Use the <filename>devtool modify</filename> command to begin
modifying the source of an existing recipe.
This command is very similar to the
<link linkend='devtool-adding-a-new-recipe-to-the-workspace'><filename>add</filename></link>
command except that it does not physically create the
recipe in the workspace layer because the recipe already
exists in an another layer.
</para>
<para>
The <filename>devtool modify</filename> command extracts the
source for a recipe, sets it up as a Git repository if the
source had not already been fetched from Git, checks out a
branch for development, and applies any patches from the recipe
as commits on top.
You can use the following command to checkout the source
files:
<literallayout class='monospaced'>
$ devtool modify <replaceable>recipe</replaceable>
</literallayout>
Using the above command form, <filename>devtool</filename> uses
the existing recipe's
<link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
statement to locate the upstream source, extracts the source
into the default sources location in the workspace.
The default development branch used is "devtool".
</para>
</section>
<section id='devtool-edit-an-existing-recipe'>
<title>Edit an Existing Recipe</title>
<para>
Use the <filename>devtool edit-recipe</filename> command
to run the default editor, which is identified using the
<filename>EDITOR</filename> variable, on the specified recipe.
</para>
<para>
When you use the <filename>devtool edit-recipe</filename>
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 <filename>devtool add</filename> or
<filename>devtool upgrade</filename> 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.
</para>
</section>
<section id='devtool-updating-a-recipe'>
<title>Updating a Recipe</title>
<para>
Use the <filename>devtool update-recipe</filename> command to
update your recipe with patches that reflect changes you make
to the source files.
For example, if you know you are going to work on some
code, you could first use the
<link linkend='devtool-modifying-a-recipe'><filename>devtool modify</filename></link>
command to extract the code and set up the workspace.
After which, you could modify, compile, and test the code.
</para>
<para>
When you are satisfied with the results and you have committed
your changes to the Git repository, you can then
run the <filename>devtool update-recipe</filename> to create the
patches and update the recipe:
<literallayout class='monospaced'>
$ devtool update-recipe <replaceable>recipe</replaceable>
</literallayout>
If you run the <filename>devtool update-recipe</filename>
without committing your changes, the command ignores the
changes.
</para>
<para>
Often, you might want to apply customizations made to your
software in your own layer rather than apply them to the
original recipe.
If so, you can use the
<filename>-a</filename> or <filename>--append</filename>
option with the <filename>devtool update-recipe</filename>
command.
These options allow you to specify the layer into which to
write an append file:
<literallayout class='monospaced'>
$ devtool update-recipe <replaceable>recipe</replaceable> -a <replaceable>base-layer-directory</replaceable>
</literallayout>
The <filename>*.bbappend</filename> file is created at the
appropriate path within the specified layer directory, which
may or may not be in your <filename>bblayers.conf</filename>
file.
If an append file already exists, the command updates it
appropriately.
</para>
</section>
<section id='devtool-checking-on-the-upgrade-status-of-a-recipe'>
<title>Checking on the Upgrade Status of a Recipe</title>
<para>
Upstream recipes change over time.
Consequently, you might find that you need to determine if you
can upgrade a recipe to a newer version.
</para>
<para>
To check on the upgrade status of a recipe, use the
<filename>devtool check-upgrade-status</filename> 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.
<note><title>NOTES:</title>
<itemizedlist>
<listitem><para>
For the <filename>oe-core</filename> layer, recipe
maintainers come from the
<ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/poky/tree/meta/conf/distro/include/maintainers.inc'><filename>maintainers.inc</filename></ulink>
file.
</para></listitem>
<listitem><para>
If the recipe is using the
<ulink url='&YOCTO_DOCS_BB_URL;#git-fetcher'>Git fetcher</ulink>
rather than a tarball, the commit hash points to the
commit that matches the recipe's latest version tag.
</para></listitem>
</itemizedlist>
</note>
</para>
<para>
As with all <filename>devtool</filename> commands, you can get
help on the individual command:
<literallayout class='monospaced'>
$ devtool check-upgrade-status -h
NOTE: Starting bitbake server...
usage: devtool check-upgrade-status [-h] [--all] [recipe [recipe ...]]
Prints a table of recipes together with versions currently provided by
recipes, and latest upstream versions, when there is a later version available
arguments:
recipe Name of the recipe to report (omit to report upgrade info for
all recipes)
options:
-h, --help show this help message and exit
--all, -a Show all recipes, not just recipes needing upgrade
</literallayout>
</para>
<para>
Unless you provide a specific recipe name on the command line,
the command checks all recipes in all configured layers.
</para>
<para>
Following is a partial example table that reports on all the
recipes.
Notice the reported reason for not upgrading the
<filename>base-passwd</filename> recipe.
In this example, while a new version is available upstream,
you do not want to use it because the dependency on
<filename>cdebconf</filename> is not easily satisfied.
<note>
When a reason for not upgrading displays, the reason is
usually written into the recipe using the
<filename>RECIPE_NO_UPDATE_REASON</filename> variable.
See the
<ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/poky/tree/meta/recipes-core/base-passwd/base-passwd_3.5.29.bb'><filename>base-passwd.bb</filename></ulink>
recipe for an example.
</note>
<literallayout class='monospaced'>
$ devtool check-upgrade-status
...
NOTE: acpid 2.0.30 2.0.31
Ross Burton &lt;ross.burton@intel.com&gt;
NOTE: u-boot-fw-utils 2018.11 2019.01
Marek Vasut &lt;marek.vasut@gmail.com&gt;
d3689267f92c5956e09cc7d1baa4700141662bff
NOTE: u-boot-tools 2018.11 2019.01
Marek Vasut &lt;marek.vasut@gmail.com&gt;
d3689267f92c5956e09cc7d1baa4700141662bff
.
.
.
NOTE: base-passwd 3.5.29 3.5.45
Anuj Mittal &lt;anuj.mittal@intel.com&gt; 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 &lt;andrej.valek@siemens.com&gt;
NOTE: dbus-test 1.12.10 1.12.12
Chen Qi &lt;Qi.Chen@windriver.com&gt;
</literallayout>
</para>
</section>
<section id='devtool-upgrading-a-recipe'>
<title>Upgrading a Recipe</title>
<para>
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
"<ulink url='&YOCTO_DOCS_DEV_URL;#gs-upgrading-recipes'>Upgrading Recipes</ulink>"
section of the Yocto Project Development Tasks Manual.
This section overviews the <filename>devtool upgrade</filename>
command.
<note>
Before you upgrade a recipe, you can check on its upgrade
status.
See the
"<link linkend='devtool-checking-on-the-upgrade-status-of-a-recipe'>Checking on the Upgrade Status of a Recipe</link>"
for more information.
</note>
</para>
<para>
The <filename>devtool upgrade</filename> command
upgrades an existing recipe to a more recent version of the
recipe upstream.
The command puts the upgraded recipe file along with any associated
files into a "workspace" and, if necessary, extracts the source
tree to a specified location.
During the upgrade, patches associated with the recipe are
rebased or added as needed.
</para>
<para>
When you use the <filename>devtool upgrade</filename> command,
you must supply the root name of the recipe (i.e. no version,
paths, or extensions), and you must supply the directory
to which you want the source extracted.
Additional command options let you control things such as
the version number to which you want to upgrade (i.e. the
<link linkend='var-PV'><filename>PV</filename></link>),
the source revision to which you want to upgrade (i.e. the
<link linkend='var-SRCREV'><filename>SRCREV</filename></link>),
whether or not to apply patches, and so forth.
</para>
<para>
You can read more on the <filename>devtool upgrade</filename>
workflow in the
"<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-devtool-use-devtool-upgrade-to-create-a-version-of-the-recipe-that-supports-a-newer-version-of-the-software'>Use <filename>devtool upgrade</filename> to Create a Version of the Recipe that Supports a Newer Version of the Software</ulink>"
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
<filename>devtool upgrade</filename> in the
"<ulink url='&YOCTO_DOCS_DEV_URL;#gs-using-devtool-upgrade'>Using <filename>devtool upgrade</filename></ulink>"
section in the Yocto Project Development Tasks Manual.
</para>
</section>
<section id='devtool-resetting-a-recipe'>
<title>Resetting a Recipe</title>
<para>
Use the <filename>devtool reset</filename> command to remove a
recipe and its configuration (e.g. the corresponding
<filename>.bbappend</filename> file) from the workspace layer.
Realize that this command deletes the recipe and the
append file.
The command does not physically move them for you.
Consequently, you must be sure to physically relocate your
updated recipe and the append file outside of the workspace
layer before running the <filename>devtool reset</filename>
command.
</para>
<para>
If the <filename>devtool reset</filename> command detects that
the recipe or the append files have been modified, the
command preserves the modified files in a separate "attic"
subdirectory under the workspace layer.
</para>
<para>
Here is an example that resets the workspace directory that
contains the <filename>mtr</filename> recipe:
<literallayout class='monospaced'>
$ devtool reset mtr
NOTE: Cleaning sysroot for recipe mtr...
NOTE: Leaving source tree /home/scottrif/poky/build/workspace/sources/mtr as-is; if you no
longer need it then please delete it manually
$
</literallayout>
</para>
</section>
<section id='devtool-building-your-recipe'>
<title>Building Your Recipe</title>
<para>
Use the <filename>devtool build</filename> command to build your
recipe.
The <filename>devtool build</filename> command is equivalent to
the <filename>bitbake -c populate_sysroot</filename> command.
</para>
<para>
When you use the <filename>devtool build</filename> 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 disable parallel makes during the build.
Here is an example:
<literallayout class='monospaced'>
$ devtool build <replaceable>recipe</replaceable>
</literallayout>
</para>
</section>
<section id='devtool-building-your-image'>
<title>Building Your Image</title>
<para>
Use the <filename>devtool build-image</filename> command
to build an image, extending it to include packages from
recipes in the workspace.
Using this command is useful when you want an image that
ready for immediate deployment onto a device for testing.
For proper integration into a final image, you need to
edit your custom image recipe appropriately.
</para>
<para>
When you use the <filename>devtool build-image</filename>
command, you must supply the name of the image.
This command has no command line options:
<literallayout class='monospaced'>
$ devtool build-image <replaceable>image</replaceable>
</literallayout>
</para>
</section>
<section id='devtool-deploying-your-software-on-the-target-machine'>
<title>Deploying Your Software on the Target Machine</title>
<para>
Use the <filename>devtool deploy-target</filename> command to
deploy the recipe's build output to the live target machine:
<literallayout class='monospaced'>
$ devtool deploy-target <replaceable>recipe</replaceable>&nbsp;<replaceable>target</replaceable>
</literallayout>
The <replaceable>target</replaceable> is the address of the
target machine, which must be running an SSH server (i.e.
<filename>user@hostname[:destdir]</filename>).
</para>
<para>
This command deploys all files installed during the
<link linkend='ref-tasks-install'><filename>do_install</filename></link>
task.
Furthermore, you do not need to have package management enabled
within the target machine.
If you do, the package manager is bypassed.
<note><title>Notes</title>
<para>
The <filename>deploy-target</filename>
functionality is for development only.
You should never use it to update an image that will be
used in production.
</para>
</note>
</para>
<para>
Some conditions exist that could prevent a deployed application
from behaving as expected.
When both of the following conditions exist, your application has
the potential to not behave correctly when run on the target:
<itemizedlist>
<listitem><para>
You are deploying a new application to the target and
the recipe you used to build the application had
correctly defined runtime dependencies.
</para></listitem>
<listitem><para>
The target does not physically have the packages on which
the application depends installed.
</para></listitem>
</itemizedlist>
If both of these conditions exist, your application will not
behave as expected.
The reason for this misbehavior is because the
<filename>devtool deploy-target</filename> command does not deploy
the packages (e.g. libraries) on which your new application
depends.
The assumption is that the packages are already on the target.
Consequently, when a runtime call is made in the application
for a dependent function (e.g. a library call), the function
cannot be found.
</para>
<para>
To be sure you have all the dependencies local to the target, you
need to be sure that the packages are pre-deployed (installed)
on the target before attempting to run your application.
</para>
</section>
<section id='devtool-removing-your-software-from-the-target-machine'>
<title>Removing Your Software from the Target Machine</title>
<para>
Use the <filename>devtool undeploy-target</filename> command to
remove deployed build output from the target machine.
For the <filename>devtool undeploy-target</filename> command to
work, you must have previously used the
<link linkend='devtool-deploying-your-software-on-the-target-machine'><filename>devtool deploy-target</filename></link>
command.
<literallayout class='monospaced'>
$ devtool undeploy-target <replaceable>recipe</replaceable>&nbsp;<replaceable>target</replaceable>
</literallayout>
The <replaceable>target</replaceable> is the address of the
target machine, which must be running an SSH server (i.e.
<filename>user@hostname</filename>).
</para>
</section>
<section id='devtool-creating-the-workspace'>
<title>Creating the Workspace Layer in an Alternative Location</title>
<para>
Use the <filename>devtool create-workspace</filename> command to
create a new workspace layer in your
<link linkend='build-directory'>Build Directory</link>.
When you create a new workspace layer, it is populated with the
<filename>README</filename> file and the
<filename>conf</filename> directory only.
</para>
<para>
The following example creates a new workspace layer in your
current working and by default names the workspace layer
"workspace":
<literallayout class='monospaced'>
$ devtool create-workspace
</literallayout>
</para>
<para>
You can create a workspace layer anywhere by supplying
a pathname with the command.
The following command creates a new workspace layer named
"new-workspace":
<literallayout class='monospaced'>
$ devtool create-workspace /home/scottrif/new-workspace
</literallayout>
</para>
</section>
<section id='devtool-get-the-status-of-the-recipes-in-your-workspace'>
<title>Get the Status of the Recipes in Your Workspace</title>
<para>
Use the <filename>devtool status</filename> command to
list the recipes currently in your workspace.
Information includes the paths to their respective
external source trees.
</para>
<para>
The <filename>devtool status</filename> command has no
command-line options:
<literallayout class='monospaced'>
$ devtool status
</literallayout>
Following is sample output after using
<link linkend='devtool-adding-a-new-recipe-to-the-workspace'><filename>devtool add</filename></link>
to create and add the <filename>mtr_0.86.bb</filename> recipe
to the <filename>workspace</filename> directory:
<literallayout class='monospaced'>
$ devtool status
mtr: /home/scottrif/poky/build/workspace/sources/mtr (/home/scottrif/poky/build/workspace/recipes/mtr/mtr_0.86.bb)
$
</literallayout>
</para>
</section>
<section id='devtool-search-for-available-target-recipes'>
<title>Search for Available Target Recipes</title>
<para>
Use the <filename>devtool search</filename> command to
search for available target recipes.
The command matches the recipe name, package name,
description, and installed files.
The command displays the recipe name as a result of a
match.
</para>
<para>
When you use the <filename>devtool search</filename> command,
you must supply a <replaceable>keyword</replaceable>.
The command uses the <replaceable>keyword</replaceable> when
searching for a match.
</para>
</section>
</chapter>
<!--
vim: expandtab tw=80 ts=4
-->