# Using Poky

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.

## Poky Overview

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

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.

### Metadata (Recipes)

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.

### Classes

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.

### Configuration

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).

## Running a Build

First the Poky build environment needs to be set up using the following command:

    $ source poky-init-build-env

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.

## Installing and Using the Result

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.

### USB Networking

Devices commonly have USB connectivity. To connect to the usbnet interface, on the host machine run:

    modprobe usbnet
    ifconfig usb0 192.168.0.200
    route add 192.168.0.202 usb0

### QEMU/USB networking with IP masquerading

On Ubuntu, Debian or similar distributions you can have the network automatically configured. You can also enable masquerading between the QEMU system and the rest of your network. To do this you need to edit `/etc/network/interfaces` to include:

    allow-hotplug tap0
    iface tap0 inet static
            address 192.168.7.200
            netmask 255.255.255.0
            network 192.168.7.0
            post-up iptables -A POSTROUTING -t nat -j MASQUERADE -s 192.168.7.0/24
            post-up echo 1 > /proc/sys/net/ipv4/ip_forward
            post-up iptables -P FORWARD ACCEPT

This ensures the tap0 interface will be up everytime you run QEMU and it will have network/internet access.

Under emulation there are two steps to configure for internet access via tap0. The first step is to configure routing:

    route add default gw 192.168.7.200 tap0

The second is to configure name resolution which is configured in the `/etc/resolv.conf` file. The simplest solution is to copy its content from the host machine.

USB connections to devices can be set up and automated in a similar way. First add the following to `/etc/network/interfaces`:

    allow-hotplug usb0
    iface usb0 inet static
            address 192.168.0.200
            netmask 255.255.255.0
            network 192.168.0.0
            post-up iptables -A POSTROUTING -t nat -j MASQUERADE -s 192.168.0.0/24
            post-up echo 1 > /proc/sys/net/ipv4/ip_forward
            post-up iptables -P FORWARD ACCEPT

and then to configure routing on the device you would use:

    route add default gw 192.168.0.202 usb0

## Debugging Build Failures

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:

### Task Failures

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.

### Running specific tasks

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`.

### Dependency Graphs

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.

### General Bitbake Problems

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.

### Building with no dependencies

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.

### Variables

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.

### Other Tips

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).