This section gives an overview of the components that make up Poky following by information about running poky builds and dealing with any problems that may arise.

At the core of Poky is the bitbake task executor together with various types of configuration files. This section gives an overview of bitbake and the configuration files, in particular what they are used for, and how they interact. Bitbake handles the parsing and execution of the data files. The data itself is of various types; recipes which give details about particular pieces of software, class data which is an abstraction of common build information (e.g. how to build a Linux kernel) and configuration data for machines, policy decisions, etc., which acts as a glue and binds everything together. Bitbake knows how to combine multiple data sources together, each data source being referred to as a 'layer'. The directory structure walkthrough section gives details on the meaning of specific directories but some brief details on the core components follows:

Bitbake is the tool at the heart of Poky and is responsible for parsing the metadata, generating a list of tasks from it and then executing them. To see a list of the options it supports look at bitbake --help. The most common usage is bitbake packagename where packagename is the name of the package you wish to build (from now on called the target). This often equates to the first part of a .bb filename, so to run the matchbox-desktop_1.2.3.bb file, you might type bitbake matchbox-desktop. Several different versions of matchbox-desktop might exist and bitbake will choose the one selected by the distribution configuration (more details about how bitbake chooses between different versions and providers is available in the 'Preferences and Providers' section). Bitbake will also try to execute any dependent tasks first so before building matchbox-desktop it would build a cross compiler and glibc if not already built.

The .bb files are usually referred to as 'recipes'. In general, a recipe contains information about a single piece of software such as where to download the source, any patches that are needed, any special configuration options, how to compile the source files and how to package the compiled output. 'package' can also be used to describe recipes but since the same word is used for the packaged output from Poky (i.e. .ipk or .deb files), this document will avoid it.

Class (.bbclass) files contain information which is useful to share between metadata files. An example is the autotools class which contains the common settings that any application using autotools would use. The classes reference section gives details on common classes and how to use them.

The configuration (.conf) files define various configuration variables which govern what Poky does. These are split into several areas, such as machine configuration options, distribution configuration options, compiler tuning options, general common configuration and user configuration (local.conf).

First the Poky build environment needs to be set up using the following command: $ source poky-init-build-env [build_dir] The build_dir is the dir containing all the building object files. The default build dir is poky-dir/build. Multiple build_dir can be used for different targets. For example, ~/build/x86 for qemux86 target, and ~/build/arm for qemuarm target. Please refer to poky-init-build-env for detail info Once the Poky build environment is set up, a target can now be built using: $ bitbake <target> The target is the name of the recipe you want to build. Common targets are the images (in meta/packages/images/) or the name of a recipe for a specific piece of software like busybox. More details about the standard images are available in the image reference section.

Once an image has been built it often needs to be installed. The images/kernels built by Poky are placed in the tmp/deploy/images directory. Running qemux86 and qemuarm images is covered in the Running an Image section. See your board/machine documentation for information about how to install these images.

The exact method for debugging Poky depends on the nature of the bug(s) and which part of the system they might be from. Standard debugging practises such as comparing to the last known working version and examining the changes, reapplying the changes in steps to identify the one causing the problem etc. are valid for Poky just like any other system. It's impossible to detail every possible potential failure here but there are some general tips to aid debugging:

The log file for shell tasks is available in ${WORKDIR}/temp/log.do_taskname.pid. For the compile task of busybox 1.01 on the ARM spitz machine, this might be tmp/work/armv5te-poky-linux-gnueabi/busybox-1.01/temp/log.do_compile.1234 for example. To see what bitbake ran to generate that log, look at the run.do_taskname.pid file in the same directory. The output from python tasks is sent directly to the console at present.

Any given package consists of a set of tasks, in most cases the series is fetch, unpack, patch, configure, compile, install, package, package_write and build. The default task is "build" and any tasks this depends on are built first hence the standard bitbake behaviour. There are some tasks such as devshell which are not part of the default build chain. If you wish to run such a task you can use the "-c" option to bitbake e.g. bitbake matchbox-desktop -c devshell. If you wish to rerun a task you can use the force option "-f". A typical usage session might look like: % bitbake matchbox-desktop [change some source in the WORKDIR for example] % bitbake matchbox-desktop -c compile -f % bitbake matchbox-desktop which would build matchbox-desktop, then recompile it. The final command reruns all tasks after the compile (basically the packaging tasks) since bitbake will notice that the compile has been rerun and hence the other tasks also need to run again. You can view a list of tasks in a given package by running the listtasks task e.g. bitbake matchbox-desktop -c listtasks, and the result is in file ${WORKDIR}/temp/log.do_listtasks.

Sometimes it can be hard to see why bitbake wants to build some other packages before a given package you've specified. bitbake -g targetname will create depends.dot and task-depends.dot files in the current directory. They show which packages and tasks depend on which other packages and tasks and are useful for debugging purposes. "bitbake -g -u depexp targetname" will show result in more human-readable GUI style.

Debug output from bitbake can be seen with the "-D" option. The debug output gives more information about what bitbake is doing and/or why. Each -D option increases the logging level, the most common usage being "-DDD". The output from bitbake -DDD -v targetname can reveal why a certain version of a package might be chosen, why bitbake picked a certain provider or help in other situations where bitbake does something you're not expecting.

If you really want to build a specific .bb file, you can use the form bitbake -b somepath/somefile.bb. Note that this will not check the dependencies so this option should only be used when you know its dependencies already exist. You can specify fragments of the filename and bitbake will see if it can find a unique match.

The "-e" option will dump the resulting environment for either the configuration (no package specified) or for a specific package when specified with the "-b" option.

When adding new packages it is worth keeping an eye open for bad things creeping into compiler commandlines such as references to local system files (/usr/lib/ or /usr/include/ etc.). If you want to remove the psplash boot splashscreen, add "psplash=false" to the kernel commandline and psplash won't load allowing you to see the console. It's also possible to switch out of the splashscreen by switching virtual console (Fn+Left or Fn+Right on a Zaurus).