Lesson

Using devtool in Yocto

How to use devtool to create, modify, build, test, and finish Yocto recipe changes

Practical Yocto Project DevelopmentDevelopment and DebuggingLesson 18 of 26

devtool is a helper for day-to-day Yocto recipe development.

You can write recipes by hand, and you should do that to understand what they contain. But when you are actively changing sources, testing patches, or creating a new recipe from an application tree, devtool can make the loop much shorter.

The basic idea is simple: devtool creates a workspace, points BitBake at this workspace version of the recipe or source, and gives you commands for building, deploying, and syncing the result back into a real layer.

Where devtool Fits

A normal Yocto workflow often looks like this:

1. edit source or metadata
2. run BitBake
3. inspect the result
4. create patches or recipe updates
5. commit changes to a layer

devtool does not replace this workflow. It gives you a more convenient working area for the middle of it.

For example, when modifying an existing recipe, devtool can:

• unpack or clone the source into a workspace directory
• create workspace metadata so BitBake uses that source tree
• let you edit the recipe
• build just that recipe
• deploy the built output to a running target
• generate patches from your local commits
• bring the changes back into your own layer

BitBake still performs the actual recipe tasks. devtool is the development front-end around those tasks.

The Workspace Layer

When you use devtool, it creates a workspace, usually under:

build/workspace/

That workspace behaves like an extra layer in the build. It normally contains:

sources/

Editable source trees for recipes being developed with devtool.

recipes/

Workspace recipe metadata and appends used to redirect BitBake to the workspace source.

conf/layer.conf

The layer configuration that makes the workspace visible to BitBake.

You can inspect the workspace layer like any other layer:

bitbake-layers show-layers

While a recipe is in the workspace, the workspace layer normally has a high priority. That is useful while developing, but it also means you should reset or finish workspace work when you are done or it will continue to use it for your subsequent builds.

Common Commands

These are the devtool commands you will use most often.

devtool add

Create a new recipe from an existing source tree, archive, or repository.

devtool modify

Prepare an editable workspace source tree for an existing recipe.

devtool edit-recipe

Open the workspace recipe or append for editing.

devtool build

Build the recipe using the workspace source and metadata.

devtool deploy-target

Copy built output to a running target for quick testing.

devtool reset

Remove a recipe from the workspace so normal layer metadata is used again.

devtool finish

Move finished workspace changes into a chosen layer.

devtool update-recipe

Update recipe metadata from workspace source changes, usually by generating or refreshing patches.

Complete Worked Example

This example uses one of the simple Hello World applications from the simple recipes lesson. It shows one useful devtool capability: creating an initial recipe from existing source code.

Create the recipe

Create the initial recipe with:

devtool add \              
    --src-subdir meta-hello-worlds/recipes-hello/hello-make/files \
    hello-devtool \
    'git://github.com/ming4real/meta-hello-worlds.git;protocol=https;branch=main'

This inspects the source and tries to work out a recipe for you, putting it in build/workspace/recipes/ and clones the source to build/workspace/sources/

Build it

devtool build hello-devtool

You can also use BitBake directly:

bitbake hello-devtool

That is an important point: the recipe is now integrated with BitBake. devtool has adjusted the workspace metadata, but the normal build engine still runs the recipe tasks.

Test on a Target

If you have a running target with SSH access, deploy the built files:

devtool deploy-target hello-devtool root@192.168.7.2

Then run it on the target:

ssh root@192.168.7.2 hello-devtool

This is useful for fast application testing because you do not have to rebuild and reflash a complete image for every small change.

Integrate it into your project

When the recipe is ready to keep, finish it into your software layer:

devtool finish hello-devtool meta-my-software

This creates the recipe directory in meta-my-software, copies the generated metadata into place, and removes the recipe from the active workspace state.

To include it in an image, add the package as usual:

IMAGE_INSTALL:append = " hello-devtool"

Modifying an Existing Recipe

Use devtool modify when the recipe already exists.

For example:

devtool modify hello-recipe

This prepares an editable source tree under the workspace. You can find it with:

devtool status

Make your source changes in the workspace source directory. Commit the changes with Git:

git add .
git commit -m "Fix hello output"

Build the workspace version:

devtool build hello-recipe

If you need to adjust recipe metadata, open the workspace recipe or append:

devtool edit-recipe hello-recipe

When the changes are ready, write them back to your layer:

devtool finish hello-recipe ../meta-my-software

devtool finish updates the recipe and any generated patches into the destination layer, then removes the recipe from the workspace. You will see that it has created the patch file with a name based on the commit message and added that to the SRC_URI for you.

If you are not ready to finish but want to update the recipe metadata from the workspace commits, use:

devtool update-recipe hello-recipe

This is commonly used to generate or refresh patch files listed from the recipe.

Generating Patches

For existing recipes, the cleanest devtool flow is usually:

1. run devtool modify <recipe>
2. edit the workspace source
3. commit each logical change in Git
4. run devtool build <recipe>
5. run devtool update-recipe <recipe> or devtool finish <recipe> <layer>

The Git commits give devtool clear patch boundaries. Good commit messages also become good patch subjects.

If a recipe fetches from Git and your project policy is to update SRCREV instead of carrying patches, check the generated result carefully. Some projects prefer patch files in a product layer; others prefer moving the recipe to a newer upstream revision.

Resetting Workspace State

If you want to abandon workspace changes:

devtool reset hello-recipe

This removes the workspace metadata for that recipe. It does not update your destination layer.

Use reset when:

• you tried an experiment and want to discard the workspace override
• BitBake is still using a workspace source tree when you expected normal metadata
• you manually copied or handled the result and now want to clear the workspace state

Troubleshooting

BitBake Is Still Using the Workspace Version

Run:

devtool status

If the recipe is listed, the workspace is still active for it. Finish or reset it:

devtool finish hello-recipe ../meta-my-software
devtool reset hello-recipe

Use finish when you want to keep the changes. Use reset when you want to stop using the workspace version.

devtool add Creates a Recipe That Does Not Build

devtool add can generate a starting recipe, but it cannot understand every custom build system perfectly.

Check:

• whether the source has a standard build system such as Make, CMake, Meson, or Autotools
• whether the generated recipe inherited the right class
• whether build dependencies need to be added to DEPENDS
• whether install rules respect DESTDIR

Then use:

devtool edit-recipe hello-devtool
devtool build hello-devtool

Deploy to Target Fails

If devtool deploy-target fails, check:

• the target is reachable over the network
• SSH works outside devtool
• the username and address are correct
• the target root filesystem has enough space
• the deployed binary matches the target architecture

Remember that deploy-target is not a substitute for package and image testing. It is a fast development step.

Patches Are Not Generated

If devtool update-recipe or devtool finish does not generate the patch you expected, check:

• the source changes are committed in the workspace Git repository
• you modified the workspace source, not a copy somewhere else
• the destination layer path is correct
• the recipe is still listed by devtool status

Uncommitted changes may be ignored or handled differently depending on the exact command and version, so commit logical changes before asking devtool to produce patches.

The Finished Recipe Is in the Wrong Layer

devtool finish writes to the layer path you provide:

devtool finish hello-recipe ../meta-my-software

If you accidentally finish into the wrong layer, inspect the Git diff before committing. Move the generated recipe, append, or patches into the intended project layer and keep third-party layers clean.

The Image Does Not Include the Application

Building with devtool build proves the recipe builds. It does not select the package for an image.

Add the package to an image or package group:

IMAGE_INSTALL:append = " hello-devtool"

Then build the image:

bitbake my-image

Summary

Use devtool when you are actively developing recipe source or metadata.

The practical flow is:

1. use devtool add for new software or devtool modify for existing recipes
2. edit source in the workspace
3. build with devtool build or bitbake
4. test quickly with devtool deploy-target when a target is available
5. commit source changes so patches can be generated cleanly
6. use devtool update-recipe or devtool finish to sync changes back into a layer
7. use devtool reset when you need to clear workspace state

That keeps experiments fast while still ending with normal, reviewable Yocto metadata in your own layer.

Check your understanding

Quick quiz: devtool

A short review of the devtool workflow.

Question 1What is the main purpose of `devtool`?

To replace BitBake as the build engineTo make recipe development faster by managing a workspace source tree and recipe changesTo configure disk partition layouts for images

Question 2What does `devtool modify <recipe>` normally create?

A new image recipeA deployed root filesystem imageA workspace checkout of the recipe source and an append in the workspace layer

Question 3Which command is commonly used to build a recipe while it is under devtool control?

`devtool build <recipe>``devtool reset <recipe>``devtool finish <recipe> <layer>`

Question 4Which command writes completed recipe changes back into a normal layer?

`devtool deploy-target <recipe> <target>``devtool finish <recipe> <layer>``devtool edit-recipe <recipe>`

Question 5After finishing or abandoning workspace work, why use `devtool reset <recipe>`?

To delete the final image from `tmp/deploy/images`To force BitBake to ignore all patchesTo remove the recipe from the devtool workspace so future builds use normal layer metadata again

Check answers