Bitbake: CLI

It’s been tough so far, and I’m not sure that the following will be any easier. Actually, no, come on, yes, in the end, they’re just terminal commands.

bitbake#

When we set up a Yocto project (which we’ll see shortly, I promise) we’ll have access to the bitbake command as well as other more specific commands that will come very handy. For now, let’s talk about bitbake. With bitbake -h we can display an help that allows us to understand what we can do with the command:

user@hostname:/workdir/build$ bitbake -h
usage: bitbake [-s] [-e] [-g] [-u UI] [--version] [-h] [-f] [-c CMD] [-C INVALIDATE_STAMP] [--runall RUNALL] [--runonly RUNONLY] [--no-setscene]
               [--skip-setscene] [--setscene-only] [-n] [-p] [-k] [-P] [-S SIGNATURE_HANDLER] [--revisions-changed] [-b BUILDFILE] [-D] [-l DEBUG_DOMAINS] [-v]
               [-q] [-w WRITEEVENTLOG] [-B BIND] [-T SERVER_TIMEOUT] [--remote-server REMOTE_SERVER] [-m] [--token XMLRPCTOKEN] [--observe-only]
               [--status-only] [--server-only] [-r PREFILE] [-R POSTFILE] [-I EXTRA_ASSUME_PROVIDED]
               [recipename/target ...]

It is assumed there is a conf/bblayers.conf available in cwd or in BBPATH which will provide the layer, BBFILES and other configuration information.

General options:
  recipename/target     Execute the specified task (default is 'build') for these target recipes (.bb files).
  -s, --show-versions   Show current and preferred versions of all recipes.
  -e, --environment     Show the global or per-recipe environment complete with information about where variables were set/changed.
  -g, --graphviz        Save dependency tree information for the specified targets in the dot syntax.
  -u UI, --ui UI        The user interface to use (knotty, ncurses, taskexp_ncurses or teamcity - default knotty).
  --version             Show programs version and exit.
  -h, --help            Show this help message and exit.

Task control options:

There are a ton of options, let’s look at the most common and useful ones.

bitbake -e allows us to view the variables available after bitbake parsing. There are many, many of them.

bitbake <recipe> allows us to build a specific recipe.

bitbake <recipe> -c <task> allows us to execute a specific task from the recipe. If this task has dependencies on other tasks, these will also be executed.

bitbake --runall <task> allows us to execute a specific task on all recipes in the project. This is useful, for instance, to initially perform the fetch on all tasks, so that we don’t have to worry about download faults occurring during the complete build process.

bitbake <recipe> -f allows us to force the construction of a recipe and prevent it from using the sstate-cache. This is useful if we are heavily modifying a recipe and do not want it to use the cache instead of re-running the entire process. You know, it happens.

bitbake <recipe> -f <task> same thing, but referring to a specific task in the recipe.

bitbake -g allows us to generate the files pn-buildlist and task-depends.dot which describe, respectively, all the packages in the build and all the dependencies between the tasks in the build.

common tasks#

Yocto already provides some tasks common to all recipes, such as listtasks, whose job is to display all tasks associated with the recipe:

do_build                              Default task for a recipe - depends on all other normal tasks required to 'build' a recipe
do_checkuri                           Validates the SRC_URI value
do_clean                              Removes all output files for a target
do_cleanall                           Removes all output files, shared state cache, and downloaded source files for a target
do_cleansstate                        Removes all output files and shared state cache for a target
do_collect_spdx_deps                  
do_compile                            Compiles the source in the compilation directory
do_configure                          Configures the source by enabling and disabling any build-time and configuration options for the software being built
do_create_extlinux_config             
do_create_runtime_spdx                
do_create_runtime_spdx_setscene        (setscene version)
do_create_spdx                        
do_create_spdx_setscene                (setscene version)
do_deploy                             Writes deployable output files to the deploy directory
do_deploy_setscene                    Writes deployable output files to the deploy directory (setscene version)
do_deploy_source_date_epoch           
do_deploy_source_date_epoch_setscene   (setscene version)
do_devshell                           Starts a shell with the environment set up for development/debugging
do_diffconfig                         Compares the old and new config files after running do_menuconfig for the kernel
do_fetch                              Fetches the source code
do_install                            Copies files from the compilation directory to a holding area
do_listtasks                          Lists all defined tasks for a target
do_menuconfig                         Runs 'make menuconfig' in the compilation directory
...

The suggestions shown here are provided by the [doc] flag associated with each task.

Other useful tasks include:

• clean removes the workdir of a recipe
• cleansstate cleans the sstate-cache of a recipe
• cleanall removes the workdir, sstate-cache, and downloads of a recipe

oe-pkgdata-util#

Another extremely useful command is oe-pkgdata-util, which allows us to analyze the packages that have been built and understand which recipes contributed to what. For example, to understand which recipe produced the /usr/bin/app.config file in our target’s filesystem.

This and other commands are available in the scripts folder, usually located next to the bitbake and meta folders.

As usual, with oe-pkgdata-util -h we can display an help that allows us to understand what we can do with the command:

user@hostname:/workdir/build$ oe-pkgdata-util -h
usage: oe-pkgdata-util [-h] [-d] [-p PKGDATA_DIR] <subcommand> ...

OpenEmbedded pkgdata tool - queries the pkgdata files written out during do_package

options:
  -h, --help            show this help message and exit
  -d, --debug           Enable debug output
  -p PKGDATA_DIR, --pkgdata-dir PKGDATA_DIR
                        Path to pkgdata directory (determined automatically if not specified)

subcommands:
  lookup-pkg            Translate between recipe-space package names and runtime package names
  list-pkgs             List packages
  list-pkg-files        List files within a package
  lookup-recipe         Find recipe producing one or more packages
  package-info          Show version, recipe and size information for one or more packages
  find-path             Find package providing a target path
  read-value            Read any pkgdata value for one or more packages
  glob                  Expand package name glob expression
Use oe-pkgdata-util <subcommand> --help to get help on a specific command

Among the most interesting subcommands are:

oe-pkgdata-util find-path <path> which allows us to understand which package produced the path in our target filesystem. The path is therefore to be understood as the final one that the target will use at runtime, so something like /usr/bin/app.config.

oe-pkgdata-util lookup-recipe <package> which allows us to understand which recipe produced the package we are interested in. Useful to use in combination with the previous command.

The oe-pkgdata-util command essentially works with what the recipes define in the FILES variable, which indicates where to place certain files in the target filesystem.

runqemu#

This is another interesting command because it allows us to simulate our target within a virtual machine.

more commands