View source for OpenEmbedded - devtool

==Overview==
OpenEmbedded is a build system to generate '''distributions''' via images or to generate a SDK.<br/>
A tool is available on OpenEmbedded to step into development with your OpenEmbedded distribution, this tool is named '''devtool'''.<br/>
This tool allows to:
* add new recipe
* create append on actual recipe by creating bbappend file
* update existing bbappend file
{{Info| Official documentation of devool: {{DocSource | domain=Yocto Project | path=mega-manual/mega-manual.html#using-devtool-in-your-sdk-workflow | text=Using devtool in your sdk workflow (from www.yoctoproject.org)}}}}

Display '''devtool''' help:
<pre>
$ devtool --help
NOTE: Starting bitbake server...
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:
    build                Build a recipe
    rename               Rename a recipe file in the workspace
    edit-recipe          Edit a recipe file in your workspace
    find-recipe          Find a recipe file in your workspace
    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
    import               Import exported tar archive into workspace
    extract              Extract the source for an existing recipe
    sync                 Synchronize the source tree for an existing recipe
    export               Export workspace into a tar archive
Use devtool <subcommand> --help to get help on a specific command
</pre>

==Examples==
===Add a new application or a new library===
====Goal====
The goal is to integrate a new application or a new library on your OpenEmbedded build setup. <br/>
The application or library doesn't have any recipe available on any layer referenced by your OpenEmbedded build setup.<br/>
Devtool can help you to generate recipe in your OpenEmbedded build setup and more specifically in a layer you manage.
{{Info|Devtool is able to detect some mandatory things to help you to integrate application or library like type of configuration (cmake, autotools) but not to define the parameters to pass for configuration. At least you must manually adapt the recipe to your needs :<br/>- by populating correctly SRC_URI, <br/>- by surcharging configure, compile, install command, <br/>- by specifying the list of files to install on target, <br/>- ...}}

====Way of working (step-by-step)====
1. Create a source directory if does not exist (example 'mysources' in build dir) <br/>
 $> mkdir mysources/myapp
2. Get the source of application (git clone, extract tarball, ...) and put it in the source directory<br/>
3. Add the application to the workspace<br/>
 $> devtool add myapp mysources/myapp
 {{Grey|(devtool create on workspace a recipe for myapp, see description of command [[#devtool add |devtool add]].)}}
4. Build it:<br/>
 $> devtool build myapp
5. Deploy to the target device build output (via network access)<br/>
 $> devtool deploy-target myapp root@<ip of board>
6. Edit source code & repeat 4-5 as necessary<br/>
7. Populate the layer with your new recipe<br/>

{{InternalInfo|To save your development, we need to update our specific ST layers.<br/>
According to your development, select the right internal layer:
:- BSP layer such as meta-st-stm32mp if you are dealing with specific machine related configuration
:- FRAMEWORK layer such as meta-st-openstlinux if you are dealing with userland configuration
If you select '''meta-st-openstlinux''' layer, so just do:
 $> mkdir ../meta-st/meta-st-openstlinux/recipes-custom/myapp
 $> cp workspace/recipes/myapp/myapp.bb ../meta-st-openstlinux/recipes-custom/myapp
}}
First, make sure to create/enable your custom layer '''meta-my-custo-layer'''. For that you can refer to [[How to create a new open embedded layer]] article.
 $> mkdir ../meta-st/meta-my-custo-layer/recipes-custom/myapp
 $> cp workspace/recipes/myapp/myapp.bb ../meta-st/meta-my-custo-layer/recipes-custom/myapp
 $> mkdir ../meta-st/meta-my-custo-layer/recipes-custom/myapp/myapp
 $> cp mysources/myapp/* ../meta-st/meta-my-custo-layer/recipes-custom/myapp/myapp
 $> cp <appropriated license file> ../meta-st/meta-my-custo-layer/recipes-custom/myapp/myapp
Note that all copied files into folder ../meta-st/meta-my-custo-layer/recipes-custom/myapp/myapp '''must be added in SRC_URI field of myapp.bb''' <br>
Then the new recipe (myapp.bb) must be added inside the custom image you compile <br>
 $> cd meta-st/meta-my-custo-layer/recipes-samples/images/
Open my-custom-image.bb and add this line : IMAGE_INSTALL += "myapp"<br>

====Material====
* content of recipe file
 $> cat workspace/recipes/myapp/myapp.bb
 # Recipe created by recipetool
 # This is the basis of a recipe and may need further editing in order to be fully functional.
 # (Feel free to remove these comments when editing.)
 #
 # WARNING: the following LICENSE and LIC_FILES_CHKSUM values are best guesses - it is
 # your responsibility to verify that the values are complete and correct.
 LICENSE = "{{Highlight|Unknown}}"
 LIC_FILES_CHKSUM = "{{Highlight|file://LICENSE;md5{{=}}6dc31330b6fcb6a82dea131bf3d33d33}}"
 # No information for SRC_URI yet (only an external source tree was specified)
 SRC_URI = ""
 {{Highlight|DEPENDS +{{=}} “wayland”}} <br/>
 {{Highlight|inherit cmake}}
 # Specify any options you want to pass to cmake using EXTRA_OECMAKE:
 {{Highlight|EXTRA_OECMAKE {{=}} "" }}
{{Highlight|Red text}}: information detected automatically by devtool. 

* workspace tree
 $> tree workspace/ mysources/
 workspace/
 |-- appends
 | `-- myapp.bbappend
 |-- conf
 | `-- layer.conf
 |-- README
 `-- recipes
 `-- myapp
 `-- myapp.bb
 mysources/
 `-- myapp

===modify an existing application or library managed by a recipe on which you have the ownership===
{{Warning| devtool is based on external source (externalsrc) and is not able to work on recipes which are already using external source}}
====Goal====
The goal is to update a recipe owned by you.<br/>

On the following example, we take the library '''libsmaf''' on which we would like to apply some modifications.
====Way of working (step-by-step)====
1. Create a source directory (example 'mysources' in build dir) <br/>
 $> mkdir mysources
2. Extract source <br/>
 $> devtool modify -x libsmaf mysources/libsmaf
 {{Grey|(option '''-x''': request to devtool to extract the source code and patch it following <br/> the rules available on libsmaf recipe.)}}
3. Edit the code and/or commit your changes on local git repository <br/>
4. Build it:<br/>
 $> devtool build libsmaf
5. Deploy to the target device build output (via network access) <br/>
 $> devtool deploy-target libsmaf root@<ip of board>
6. Edit source code & repeat 3-5 as necessary <br/>
7. Write as patches on top of recipe <br/>
{{InternalInfo|To save your development, we need to update our specific ST layers.<br/>
The libsmaf recipe is only available under '''meta-st-openstlinux''', so just do:
 $> devtool update-recipe libsmaf
This will populate your patches into meta-st-openstlinux/recipes-security/smaf/.
}}
 $> devtool update-recipe -a ../meta-st/meta-my-custo-layer  libsmaf
First, make sure to create/enable your custom layer '''meta-my-custo-layer'''. For that you can refer to [[How to create a new open embedded layer]] article.<br/>
8. Come back to normal (remove the component from workspace) <br/>
 $> devtool reset libsmaf

====Material====
* modification made by devtool on libsmaf.bb
 $> git diff recipessecurity/smaf/libsmaf.bb
 diff git a/recipessecurity/smaf/libsmaf.bb b/recipessecurity/smaf/libsmaf.bb
 index 78d5882..6c04a2f 100644
  a/recipessecurity/smaf/libsmaf.bb
 +++ b/recipessecurity/smaf/libsmaf.bb
 @@ 8,7 +8,9 @@ PV="1.0+git"
  
  inherit autotools gettext pkgconfig
  
 -SRC_URI = "<nowiki>git://git.linaro.org/people/benjamin.gaignard/libsmaf.git;protocol=http</nowiki>"
 {{Highlight|+SRC_URI {{=}} "<nowiki>git://git.linaro.org/people/benjamin.gaignard/libsmaf.git;protocol=http</nowiki> \}}
 {{Highlight|+           file://0001Someschanges.patch \}}
 +           "
  S = "${WORKDIR}/git"
{{Highlight|Red text:}} information automatically modified by devtool 

 $> ls recipessecurity/smaf/libsmaf
 {{Highlight| 0001Someschanges.patch}}
{{Highlight| Red text:}} patch file added by devtool

===Create/update an append on application or library===
{{Warning| devtool are based on external source (externalsrc) and are not able to work on recipe which are already using external source}}
====Goal====
The goal are to update (or create) an append made for a specific recipe.<br/>

On this example, we take the library '''pixman''' on which we are would like to apply some modification.

====Way of working (step by step)====
1. Create a source directory if not exist (here mysources on build dir) <br/>
 $> mkdir mysources
2. Extract source<br/>
 $> devtool modify -x pixman mysources/pixman
3. Edit the code and/or commit your change on local git repository <br/>
4. Build it: <br/>
 $> devtool build pixman
5. Deploy to target device build output (via network access) <br/>
 $> devtool deploy-target pixman root@<ip of board>
6. Edit source code & repeat 3-5 as necessary <br/>
7. Write as patches on top of recipe append file<br/>
{{InternalInfo|To save your development, we need to update our specific ST layers.<br/>
According to your development, select the right internal layer:
:- BSP layer such as meta-st-stm32mp if you are dealing with specific machine related configuration
:- FRAMEWORK layer such as meta-st-openstlinux if you are dealing with userland configuration
If you select '''meta-st-openstlinux''' layer, so just do:
 $> devtool update-recipe -a ../meta-st/meta-st-openstlinux pixman
This will populate your patches into meta-st-openstlinux/recipes-graphics/xorg-lib/.
}}
 $> devtool update-recipe -a ../meta-st/meta-my-custo-layer  pixman
First, make sure to create/enable your custom layer '''meta-my-custo-layer'''. For that you can refer to [[How to create a new open embedded layer]] article. Then:<br/>
8. Come back to normal (remove the component of workspace) <br/>
 $> devtool reset pixman

====Material====
* content of created append file: pixman.bbapend
 $> cat meta-st/meta-st-framework/recipes-graphics/xorg-lib/pixman_0.32.6.bbappend
 # look for files in the layer first
 FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
 SRC_URI += "file://0001-NV12-format-support.patch \
 {{Highlight| file://0001-Somes-Changes.patch \}}
 "

* tree of append made in your layer
 $> tree meta-st/meta-st-framework/recipes-graphics/xorg-lib
 |-- pixman
 | |-- 0001-NV12-format-support.patch
 | `-- 0001-Somes-Changes.patch
 `-- pixman_0.32.6.bbappend

==List of '''devtool''' commands==
===Beginning to work on a recipe===
====devtool add====
Add a new recipe to the workspace
* Help command:
<pre>
$ 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
                        <WORKSPACE_LAYER_PATH>/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
</pre>
* Example
 $ '''devtool add mylibrary <source path/mylibrary>'''

* Workspace: result of add command
 $ tree workspaceworkspace/
 |-- appends
 | `-- {{Highlight| mylibrary.bbappend}}
 |-- conf
 | `-- layer.conf
 |-- README
 `-- recipes
    `-- mylibrary
       `-- {{Highlight| mylibrary.bb}}

.bb: recipe file of mylibrary automatically filled with the information found in mysource/mylibrary directory <br/>
.bbappend: recipe file for managing source code of mylibrary via externalsrc class.

====devtool modify====
Modify the source for an existing recipe and add to the workspace.
* Help command:
<pre>
$ devtool modify --help
NOTE: Starting bitbake server...
usage: devtool modify [-h] [--wildcard] [--extract | --no-extract]
                      [--same-dir | --no-same-dir] [--branch BRANCH]
                      [--keep-temp]
                      recipename [srctree]

Sets up the build environment to modify the source for an existing recipe. The
default behaviour is to extract the source being fetched by the recipe into a
git tree so you can work on it; alternatively if you already have your own
pre-prepared source tree you can specify -n/--no-extract.

arguments:
  recipename            Name of existing recipe to edit (just name - no
                        version, path or extension)
  srctree               Path to external source tree. If not specified, a
                        subdirectory of
                        <WORKSPACE_LAYER_PATH>//workspace/sources will be used.

options:
  -h, --help            show this help message and exit
  --wildcard, -w        Use wildcard for unversioned bbappend
  --extract, -x         Extract source for recipe (default)
  --no-extract, -n      Do not extract source, expect it to exist
  --same-dir, -s        Build in same directory as source
  --no-same-dir         Force build in a separate build directory
  --branch BRANCH, -b BRANCH
                        Name for development branch to checkout (when not
                        using -n/--no-extract) (default "devtool")
  --keep-temp           Keep temporary directory (for debugging)
</pre>
* Example
 $ '''devtool modify -x mylibrary <source path/mylibrary>'''
 {{Grey|(option '''-x''': request to devtool to extract the source code and patch it on <source path/mylibrary> <br/>following the rule available on mylibrary recipe.}}
* Workspace: 
 $ tree workspace
 workspace/
 |-- appends
 | `-- {{Highlight| mylibrary_<version>.bbappend}}
 |-- conf
 | `-- layer.conf
 |-- README
 `-- recipes

====devtool upgrade====
Upgrade the source of an existing recipe to a new version
* Help command:
<pre>
$ devtool upgrade --help
NOTE: Starting bitbake server...
usage: devtool upgrade [-h] [--version VERSION] [--srcrev SRCREV]
                       [--srcbranch SRCBRANCH] [--branch BRANCH] [--no-patch]
                       [--same-dir | --no-same-dir] [--keep-temp]
                       recipename [srctree]

Upgrades an existing recipe to a new upstream version. Puts the upgraded
recipe file into the workspace along with any associated files, and extracts
the source tree to a specified location (in case patches need rebasing or
adding to as a result of the upgrade).

arguments:
  recipename            Name of recipe to upgrade (just name - no version,
                        path or extension)
  srctree               Path to where to extract the source tree. If not
                        specified, a subdirectory of
                        <WORKSPACE_LAYER_PATH>/workspace/sources will be used.

options:
  -h, --help            show this help message and exit
  --version VERSION, -V VERSION
                        Version to upgrade to (PV)
  --srcrev SRCREV, -S SRCREV
                        Source revision to upgrade to (required if fetching
                        from an SCM such as git)
  --srcbranch SRCBRANCH, -B SRCBRANCH
                        Branch in source repository containing the revision to
                        use (if fetching from an SCM such as git)
  --branch BRANCH, -b BRANCH
                        Name for new development branch to checkout (default
                        "devtool")
  --no-patch            Do not apply patches from the recipe to the new source
                        code
  --same-dir, -s        Build in same directory as source
  --no-same-dir         Force build in a separate build directory
  --keep-temp           Keep temporary directory (for debugging)
</pre>
* Example
 $ '''devtool upgrade mylib --srcrev <NEW SHA1>'''

===Getting information===
====devtool status====
Show workspace status (list of recipe(s) on workspace).
* Help command:
<pre>
$ devtool status --help
NOTE: Starting bitbake server...
usage: devtool status [-h]

Lists recipes currently in your workspace and the paths to their respective
external source trees

options:
  -h, --help  show this help message and exit
</pre>
* Example
 $ '''devtool status'''

====devtool search====
Search available recipes (same as '''bitbake -s''' but with matching pattern).
* Help command:
<pre>
$ devtool search --help
NOTE: Starting bitbake server...
usage: devtool search [-h] keyword

Searches for available target recipes. Matches on recipe name, package name,
description and installed files, and prints the recipe name on match.

arguments:
  keyword     Keyword to search for (regular expression syntax allowed)

options:
  -h, --help  show this help message and exit
</pre>
* Example
 $ '''devtool search weston'''
 glibc                 GLIBC (GNU C Library)
 weston                Weston, a Wayland compositor
 libgcc                GNU cc and gcc C compilers
 gcc-runtime           Runtime libraries from GCC
 weston-init           Startup script and systemd unit file for the Weston Wayland compositor

===Working on a recipe in the workspace===
====devtool build====
Build a recipe, request to devtool to perform do_configure, do_compile and do_install for a specific package managed in the workspace.
* Help command:
<pre>
$ devtool build --help
NOTE: Starting bitbake server...
usage: devtool build [-h] [-s] recipename

Builds the specified recipe using bitbake (up to and including
do_populate_sysroot, do_packagedata)

arguments:
  recipename            Recipe to build

options:
  -h, --help            show this help message and exit
  -s, --disable-parallel-make
                        Disable make parallelism
</pre>
* Example
 $ '''devtool build myapp'''

====devtool rename====
Rename the recipe file name with a new name.
* Help command:
<pre>
$ devtool rename --help
NOTE: Starting bitbake server...
usage: devtool rename [-h] [--version VERSION] [--no-srctree]
                      recipename [newname]

Renames the recipe file for a recipe in the workspace, changing the name or
version part or both, ensuring that all references within the workspace are
updated at the same time. Only works when the recipe file itself is in the
workspace, e.g. after devtool add. Particularly useful when devtool add did
not automatically determine the correct name.

arguments:
  recipename            Current name of recipe to rename
  newname               New name for recipe (optional, not needed if you only
                        want to change the version)

options:
  -h, --help            show this help message and exit
  --version VERSION, -V VERSION
                        Change the version (NOTE: this does not change the
                        version fetched by the recipe, just the version in the
                        recipe file name)
  --no-srctree, -s      Do not rename the source tree directory (if the
                        default source tree path has been used) - keeping the
                        old name may be desirable if there are internal/other
                        external references to this path
</pre>
* Example
 $ '''devtool rename mylib mylib_newname'''
{{warning| This commands only works after usage of 'devtool add' or 'devtool upgrade' command as it needs the recipe file itself to be in the workspace.}}

====devtool edit-recipe====
Edit recipe file in the configured editor
* Help command:
<pre>
$ devtool edit-recipe --help
NOTE: Starting bitbake server...
usage: devtool edit-recipe [-h] [--any-recipe] recipename

Runs the default editor (as specified by the EDITOR variable) on the specified
recipe. Note that the recipe file itself must be in the workspace (i.e. as a
result of "devtool add" or "devtool upgrade"); you can override this with the
-a/--any-recipe option.

arguments:
  recipename        Recipe to edit

options:
  -h, --help        show this help message and exit
  --any-recipe, -a  Edit any recipe, not just where the recipe file itself is
                    in the workspace
</pre>
* Example
 $ '''devtool edit-recipe mylib'''

====devtool find-recipe====
Find any recipe file
* Help command:
<pre>
$ devtool find-recipe --help
NOTE: Starting bitbake server...
usage: devtool find-recipe [-h] [--any-recipe] recipename

By default, this will find a recipe file in your workspace; you can override
this with the -a/--any-recipe option.

arguments:
  recipename        Recipe to find

options:
  -h, --help        show this help message and exit
  --any-recipe, -a  Find any recipe, not just where the recipe file itself is
                    in the workspace
</pre>
* Example
 $ '''devtool find-recipe mylib'''

====devtool configure-help====
Display the configure help for a recipe using such script.
* Help command:
<pre>
$ devtool configure-help --help
NOTE: Starting bitbake server...
usage: devtool configure-help [options] recipename [--arg ...]

Displays the help for the configure script for the specified recipe (i.e. runs
./configure --help) prefaced by a header describing the current options being
specified. Output is piped through less (or whatever PAGER is set to, if set)
for easy browsing.

arguments:
  recipename       Recipe to show configure help for

options:
  -h, --help       show this help message and exit
  -p, --no-pager   Disable paged output
  -n, --no-header  Disable explanatory header text
  --arg ...        Pass remaining arguments to the configure script instead of
                   --help (useful if the script has additional help options)
</pre>
* Example
 $ '''devtool configure-help mylib'''

====devtool update-recipe====
Apply changes from external source tree to recipe:<br/>
- by updating bb file<br/>
- by updating or creating bbappend file<br/>
<br/>
* Help command:
<pre>
$ devtool update-recipe --help
NOTE: Starting bitbake server...
usage: devtool update-recipe [-h] [--mode MODE] [--initial-rev INITIAL_REV]
                             [--append LAYERDIR] [--wildcard-version]
                             [--no-remove]
                             recipename

Applies changes from external source tree to a recipe
(updating/adding/removing patches as necessary, or by updating SRCREV). Note
that these changes need to have been committed to the git repository in order
to be recognised.

arguments:
  recipename            Name of recipe to update

options:
  -h, --help            show this help message and exit
  --mode MODE, -m MODE  Update mode (where MODE is patch, srcrev, auto;
                        default is auto)
  --initial-rev INITIAL_REV
                        Override starting revision for patches
  --append LAYERDIR, -a LAYERDIR
                        Write changes to a bbappend in the specified layer
                        instead of the recipe
  --wildcard-version, -w
                        In conjunction with -a/--append, use a wildcard to
                        make the bbappend apply to any recipe version
  --no-remove, -n       Don't remove patches, only add or update
</pre>
* Example
Create a bbappend for a specific recipe, here pixman
 $ '''devtool update-recipe -a ../meta-st/meta-st-framework pixman'''
Update the recipe libsmaf
 $ '''devtool update-recipe libsmaf'''

====devtool reset====
Remove a recipe from your workspace (only on workspace).
* Help command:
<pre>
$ devtool reset --help
NOTE: Starting bitbake server...
usage: devtool reset [-h] [--all] [--no-clean] [recipename [recipename ...]]

Removes the specified recipe(s) from your workspace (resetting its state back
to that defined by the metadata).

arguments:
  recipename      Recipe to reset

options:
  -h, --help      show this help message and exit
  --all, -a       Reset all recipes (clear workspace)
  --no-clean, -n  Don't clean the sysroot to remove recipe output
</pre>
* Example
 $ '''devtool reset myapp'''

====devtool finish====
Allow to complete the development done through devtool by updating layer(s) with the work done.
* Help command:
<pre>
$ devtool finish --help
NOTE: Starting bitbake server...
usage: devtool finish [-h] [--mode MODE] [--initial-rev INITIAL_REV]
                      recipename destination

Pushes any committed changes to the specified recipe to the specified layer
and removes it from your workspace. Roughly equivalent to an update-recipe
followed by reset, except the update-recipe step will do the "right thing"
depending on the recipe and the destination layer specified.

arguments:
  recipename            Recipe to finish
  destination           Layer/path to put recipe into. Can be the name of a
                        layer configured in your bblayers.conf, the path to
                        the base of a layer, or a partial path inside a layer.
                        devtool finish will attempt to complete the path based
                        on the layer's structure.

options:
  -h, --help            show this help message and exit
  --mode MODE, -m MODE  Update mode (where MODE is patch, srcrev, auto;
                        default is auto)
  --initial-rev INITIAL_REV
                        Override starting revision for patches
</pre>
* Example
 $ '''devtool finish mylib Layer/path'''

===Testing changes on target===
====devtool deploy-target====
Deploy recipe output files to live target machine.
* Help command:
<pre>
$ devtool deploy-target --help
NOTE: Starting bitbake server...
usage: devtool deploy-target [-h] [-c] [-s] [-n] [-p] [--no-check-space]
                             [-P PORT] [-S | --no-strip]
                             recipename target

Deploys a recipe's build output (i.e. the output of the do_install task) to a
live target machine over ssh. By default, any existing files will be preserved
instead of being overwritten and will be restored if you run devtool undeploy-
target. Note: this only deploys the recipe itself and not any runtime
dependencies, so it is assumed that those have been installed on the target
beforehand.

arguments:
  recipename            Recipe to deploy
  target                Live target machine running an ssh server:
                        user@hostname[:destdir]

options:
  -h, --help            show this help message and exit
  -c, --no-host-check   Disable ssh host key checking
  -s, --show-status     Show progress/status output
  -n, --dry-run         List files to be deployed only
  -p, --no-preserve     Do not preserve existing files
  --no-check-space      Do not check for available space before deploying
  -P PORT, --port PORT  Port to use for connection to the target
  -S, --strip           Strip executables prior to deploying (default: False).
                        The default value of this option can be controlled by
                        setting the strip option in the [Deploy] section to
                        True or False.
  --no-strip            Do not strip executables prior to deploy
</pre>
* Example
 $ '''devtool deploy-target myapp root@<ip of board>'''
{{warning| If your package depends on an other package on runtime (RDEPENDS), it will not force the installation of the dependent package in your rootfs. Therefore you will need to use "devtool build-image" to make sure your rootfs is updated.}}

{{warning| 'deploy-target' copies {{DocSource | domain=Yocto Project | path=mega-manual/mega-manual.html#var-D | text='D'}} directory. It contains all files generated by the recipe. So its content depends on which recipe packages are installed on the target. However {{DocSource | domain=Yocto Project | path=mega-manual/mega-manual.html#var-D | text='D'}} could contain files that do not need to be installed on target. <br>This is the case in particular for virtual/kernel recipe that generates the file 'vmlinux' which is not installed on target. So by doing a 'deploy-target' with kernel recipe, it could generate some 'no space left' errors (that can be solved by manually removing 'vmlinux' before launching the deploy command)}}

====devtool  undeploy-target====
Remove recipe output files from live target machine.
* Help command:
<pre>
$ devtool undeploy-target --help
NOTE: Starting bitbake server...
usage: devtool undeploy-target [-h] [-c] [-s] [-a] [-n] [-P PORT]
                               [recipename] target

Un-deploys recipe output files previously deployed to a live target machine by
devtool deploy-target.

arguments:
  recipename            Recipe to undeploy (if not using -a/--all)
  target                Live target machine running an ssh server:
                        user@hostname

options:
  -h, --help            show this help message and exit
  -c, --no-host-check   Disable ssh host key checking
  -s, --show-status     Show progress/status output
  -a, --all             Undeploy all recipes deployed on the target
  -n, --dry-run         List files to be undeployed only
  -P PORT, --port PORT  Port to use for connection to the target
</pre>
* Example
 $ '''devtool undeploy-target myapp root@<ip of board>'''
{{Warning| this command may permanently remove the files from the live target machine}}

====devtool  build-image====
Build image including workspace recipe packages.
* Help command:
<pre>
$ devtool build-image --help
NOTE: Starting bitbake server...
usage: devtool build-image [-h] [-p PACKAGES] [imagename]

Builds an image, extending it to include packages from recipes in the
workspace

arguments:
  imagename             Image recipe to build

options:
  -h, --help            show this help message and exit
  -p PACKAGES, --add-packages PACKAGES
                        Instead of adding packages for the entire workspace,
                        specify packages to be added to the image (separate
                        multiple packages by commas)
</pre>
* Example
 $ '''devtool build-image st-image-weston'''

===Advanced===
====devtool create-workspace====
Create a specific workspace folder instead of the default one
* Help command:
<pre>
$ devtool create-workspace --help
NOTE: Starting bitbake server...
usage: devtool create-workspace [-h] [--create-only] [layerpath]

Sets up a new workspace. NOTE: other devtool subcommands will create a
workspace automatically as needed, so you only need to use devtool create-
workspace if you want to specify where the workspace should be located.

arguments:
  layerpath      Path in which the workspace layer should be created

options:
  -h, --help     show this help message and exit
  --create-only  Only create the workspace layer, do not alter configuration
</pre>
* Example
 $ '''devtool create-workspace NewWorkspace/path'''

====devtool import====
Import any exported workspace into the workspace.
* Help command:
<pre>
$ devtool import --help
NOTE: Starting bitbake server...
usage: devtool import [-h] [--overwrite] FILE

Import tar archive previously created by "devtool export" into workspace

arguments:
  FILE             Name of the tar archive to import

options:
  -h, --help       show this help message and exit
  --overwrite, -o  Overwrite files when extracting
</pre>
* Example
 $ '''devtool import ExportedWorkspaceFileName'''

====devtool extract====
Extract the source for an existing recipe:<br/>
- extract of source code (do_unpack).<br/>
- patch it (do_patch).<br/>
<br/>
* Help command:
<pre>
$ devtool extract --help
NOTE: Starting bitbake server...
usage: devtool extract [-h] [--branch BRANCH] [--keep-temp] recipename srctree

Extracts the source for an existing recipe

arguments:
  recipename            Name of recipe to extract the source for
  srctree               Path to where to extract the source tree

options:
  -h, --help            show this help message and exit
  --branch BRANCH, -b BRANCH
                        Name for development branch to checkout (default
                        "devtool")
  --keep-temp           Keep temporary directory (for debugging)
</pre>
* Example
 $ '''devtool extract pixman <source path/pixman>'''

====devtool sync====
Synchronize extracted sources
* Help command:
<pre>
$ devtool sync --help
NOTE: Starting bitbake server...
usage: devtool sync [-h] [--branch BRANCH] [--keep-temp] recipename srctree

Synchronize the previously extracted source tree for an existing recipe

arguments:
  recipename            Name of recipe to sync the source for
  srctree               Path to the source tree

options:
  -h, --help            show this help message and exit
  --branch BRANCH, -b BRANCH
                        Name for development branch to checkout (default:
                        devtool)
  --keep-temp           Keep temporary directory (for debugging) (default:
                        False)
</pre>
* Example
 $ '''devtool sync libsmaf mysources/libsmaf'''

====devtool export====
Export the workspace as tarball.
* Help command:
<pre>
$ devtool export --help
NOTE: Starting bitbake server...
usage: devtool export [-h] [--file FILE] [--overwrite]
                      [--include INCLUDE [INCLUDE ...] | --exclude EXCLUDE
                      [EXCLUDE ...]]

Export one or more recipes from current workspace into a tar archive

options:
  -h, --help            show this help message and exit
  --file FILE, -f FILE  Output archive file name
  --overwrite, -o       Overwrite previous export tar archive
  --include INCLUDE [INCLUDE ...], -i INCLUDE [INCLUDE ...]
                        Include recipes into the tar archive
  --exclude EXCLUDE [EXCLUDE ...], -e EXCLUDE [EXCLUDE ...]
                        Exclude recipes into the tar archive
</pre>
* Example
 $ '''devtool export ExportWokspaceFileName'''

<noinclude>
[[Category:System build]]
{{PublicationRequestId | 9336 | 2018-10-22 | BrunoB}}
</noinclude>