Lesson

Using devtool in Yocto

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

The Yocto ProjectGetting StartedLesson 10 of 14

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

You can write recipes by hand, and you should understand what they contain. But when you are actively changing source, 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 the 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
• finish 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 version takes priority. That is useful while developing, but it also means you should reset or finish workspace work when you are done.

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 creates a tiny C application outside the layer first, then uses devtool add to generate a recipe for it.

Start inside your build environment after sourcing the Yocto setup script.

Create a small application:

mkdir -p /tmp/hello-devtool
cd /tmp/hello-devtool

Create hello-devtool.c:

#include <stdio.h>

int main(void)
{
    puts("Hello from devtool");
    return 0;
}

Create a simple Makefile:

CC ?= gcc
CFLAGS ?= -O2
LDFLAGS ?=
prefix ?= /usr
bindir ?= $(prefix)/bin

all: hello-devtool

hello-devtool: hello-devtool.c
	$(CC) $(CFLAGS) $(LDFLAGS) -o $@ $<

install: hello-devtool
	install -d $(DESTDIR)$(bindir)
	install -m 0755 hello-devtool $(DESTDIR)$(bindir)/hello-devtool

clean:
	rm -f hello-devtool

Initialise Git so devtool can track changes cleanly:

git init
git add hello-devtool.c Makefile
git commit -m "Initial hello-devtool application"

Now ask devtool to create a recipe:

devtool add hello-devtool /tmp/hello-devtool

This creates workspace metadata and points BitBake at the local source tree. 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.

Modify the Application

Edit hello-devtool.c:

#include <stdio.h>

int main(void)
{
    puts("Hello from devtool after a local change");
    return 0;
}

Commit the source change:

git add hello-devtool.c
git commit -m "Update hello message"

Rebuild and redeploy:

devtool build hello-devtool
devtool deploy-target hello-devtool root@192.168.7.2

This is the tight edit, build, deploy, test loop that devtool is designed to support.

Finish into a Layer

Once the recipe works, move it into your own layer:

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

devtool finish writes the recipe and any generated patches into the destination layer. After that, the layer contains the permanent metadata and the workspace entry for that recipe is removed.

Check what changed:

git status
git diff

Then build through the normal layer path:

bitbake hello-devtool

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

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 mean your destination layer was updated.

Use reset when:

• you finished the change and want the normal layer version to be used
• you tried an experiment and want to discard the workspace override
• BitBake is still using a workspace source tree when you expected normal metadata

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 make recipe development faster by managing a workspace source tree and recipe changesTo replace BitBake as the build engineTo configure disk partition layouts for images

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

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

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 finish <recipe> <layer>``devtool deploy-target <recipe> <target>``devtool edit-recipe <recipe>`

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

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

Check answers