Working with a single recipe

During development you're likely to often find yourself working on a single bitbake recipe - maybe trying to fix something or add a new version or perhaps working on a totally new recipe. Now that you know all about tasks you can use that knowledge to help speed up the development and debugging process.

Bitbake can be instructed to deal directly with a single recipe file by passing it via the -b parameter. This option takes the recipe as a parameter and instructs bitbake to process the named recipe only. Note that this ignores any dependencies that are in the recipe, so these must have already been built previously.

Here's a typically example that cleans up the package (using the clean task) and the rebuilds it with debugging output from bitbake enabled:

~%> bitbake -b  -c clean
~%> bitbake -b  -D

The options to bitbake that are most useful here are:

-b

The recipe to process;

-c

The action to perform, typically the name of one of the tasks supported by the recipe;

-D

Display debugging information, use two -D's for additional debugging;

-f

Force an operation. This is useful in getting bitbake to perform some operation it normally wouldn't do. For example, if you try and call the compile task twice in a row then bitbake will not do anything on the second attempt since it has already performed the task. By adding -f it will force it to perform the action regardless of if it thinks it's been done previously.

The most common actions (used with -c) are:

fetch

Try to download all of the required source files, but don't do anything else with them.

unpack

Unpack the source file but don't apply the patches yet. Sometimes you may want to look at the extracted, but not patched source code and that's what just unpacking will give you (some time's handy to get diffs generated against the original source).

patch

Apply any patches.

configure

Performs and configuration that is required for the software.

compile

Perform the actual compilation steps of the software.

stage

If any files, such as header and libraries, will be required by other packages then they need to be installed into the staging area and that's what this task takes care of.

install

Install the software in preparation for packaging.

package

Package the software. Remember that this moves the files from the installation directory, D, into the packing install area. So to re-package you also need to re-install first.

clean

Delete the entire directory for this version of the software. Usually done to allow a test build with no chance of old files or changes being left behind.

Note that each of the actions that corresponds to task's will run any preceding tasks that have not yet been performed. So starting with compile will also perform the fetch, unpack, patch and configure actions.

A typically development session might involve editing files in the working directory and then recompiling until it all works:

[... test ...]
~%> bitbake -b packages/testapp/testapp_4.3.bb -c compile -D

[... save a copy of main.c and make some changes ...]
~%> vi tmp/work/testapp-4.3-r0/main.c
~%> bitbake -b packages/testapp/testapp_4.3.bb -c compile -D -f

[... create a patch and add it to the recipe ...]
~%> vi packages/testapp/testapp_4.3.bb

[... test from clean ...]
~%> bitbake -b packages/testapp/testapp_4.3.bb -c clean
~%> bitbake -b packages/testapp/testapp_4.3.bb

[... NOTE: How to create the patch is not covered at this point ...]

Here's another example showing how you might go about fixing up the packaging in your recipe:

~%> bitbake -b packages/testapp/testapp_4.3.bb -c install -f
~%> bitbake -b packages/testapp/testapp_4.3.bb -c stage -f
~%> find tmp/work/testapp_4.3/install
...
~%> vi packages/testapp/testapp_4.3.bb

At this stage you play with the PACKAGE_ and FILES_ variables and then repeat the above sequence.

Note how we install and then stage. This is one of those things where understanding the tasks helps a lot! Remember that stage moves the files from where they were installed into the various subdirectories (under ${WORKDIR}/install) for each package. So if you try and run a stage task without a prior install there won't be any files there to stage! Note also that the stage tasks clears all the subdirectories in ${WORKDIR}/install so you won't get any left over files. But beware, the install task doesn't clear ${D} directory, so any left over files from a previous packing attempt will be left behind (which is ok if all you care about it staging).