| <!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>" |
| section in the Yocto Project Software Development Kit (SDK) Developer's |
| Guide. |
| </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 --help |
| usage: devtool [--basepath BASEPATH] [--bbpath BBPATH] [-d] [-q] |
| [--color COLOR] [-h] |
| <subcommand> ... |
| |
| 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 |
| Working on a recipe in the workspace: |
| edit-recipe Edit a recipe file in your workspace |
| configure-help Get help on configure script options |
| build Build a recipe |
| 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 |
| extract Extract the source for an existing recipe |
| sync Synchronize the source tree for an existing recipe |
| Use devtool <subcommand> --help to get help on a specific command |
| </literallayout> |
| </para> |
| |
| <para> |
| As directed in the general help output, you can get more |
| syntax on a specific command by providing the command |
| name and using <filename>--help</filename>: |
| <literallayout class='monospaced'> |
| $ devtool add --help |
| usage: devtool add [-h] [--same-dir | --no-same-dir] [--fetch URI] |
| [--version VERSION] [--no-git] [--autorev] [--binary] |
| [--also-native] [--src-subdir SUBDIR] |
| [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) |
| --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 |
| --autorev, -a When fetching from a git repository, set SRCREV in the |
| recipe to a floating revision instead of fixed |
| --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 |
| </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 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/scottrif/sources/jackson</filename>: |
| <literallayout class='monospaced'> |
| $ devtool add jackson /home/scottrif/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. |
| </para> |
| |
| <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> |
| </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 |
| <ulink url='&YOCTO_DOCS_DEV_URL;#devtool-adding-a-new-recipe-to-the-workspace'><filename>add</filename></ulink> |
| 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 |
| <ulink url='&YOCTO_DOCS_DEV_URL;#devtool-modifying-a-recipe'><filename>devtool modify</filename></ulink> |
| 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-upgrading-a-recipe'> |
| <title>Upgrading a Recipe</title> |
| |
| <para> |
| Use the <filename>devtool upgrade</filename> command |
| to upgrade an existing recipe to a new upstream version. |
| The command puts the upgraded recipe file into the |
| workspace along with any associated files, and extracts |
| the source tree to a specified location should patches |
| need rebased or added to as a result of the upgrade. |
| </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> |
| </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 cause the |
| OpenEmbedded build system to build your recipe. |
| The <filename>devtool build</filename> command is equivalent to |
| <filename>bitbake -c populate_sysroot</filename>. |
| </para> |
| |
| <para> |
| When you use the <filename>devtool build</filename> command, |
| you must supply the root name of the recipe (i.e. no version, |
| paths, or extensions). |
| You can use either the "-s" or the "--disable-parallel-make" |
| option 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> <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 |
| <ulink url='&YOCTO_DOCS_DEV_URL;#devtool-deploying-your-software-on-the-target-machine'><filename>devtool deploy-target</filename></ulink> |
| command. |
| <literallayout class='monospaced'> |
| $ devtool undeploy-target <replaceable>recipe</replaceable> <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 |
| <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>. |
| 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 |
| <ulink url='&YOCTO_DOCS_DEV_URL;#devtool-adding-a-new-recipe-to-the-workspace'><filename>devtool add</filename></ulink> |
| 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 |
| --> |