openembedded - Classic OpenEmbedded Development Tree

Age	Commit message (Expand)	Author
2010-04-02	sane-srcrevs: move SRCREVs to recipes	Martin Jansa
2010-03-26	ezx: update ezxd version and ezxd.init script	Antonio Ospite
2010-03-26	ezx: update ezx-boot-usb-native version	Antonio Ospite
2009-11-17	svn recipes: change +svnr${SRCREV} +svnr${SRCPV}	Martin Jansa
2009-08-02	ezxd_svn: Honour LDFLAGS to avoid QA GNU_HASH error.	Stefan Schmidt
2009-06-26	many files: Introduction of virtual/libusb0 provided by libusb or libusb-compat:	Stanislav Brabec
2009-03-17	rename packages/ to recipes/ per earlier agreement	Denys Dmytriyenko

<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <chapter id='usingpoky'> <title>Using Poky</title> <para> 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. </para> <section id='usingpoky-components'> <title>Poky Overview</title> <para> 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. </para> <para> 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 <link linkend='usingpoky-changes-collections'>'collection'</link>. </para> <para> The <link linkend='ref-structure'>directory structure walkthrough</link> section gives details on the meaning of specific directories but some brief details on the core components follows: </para> <section id='usingpoky-components-bitbake'> <title>Bitbake</title> <para> 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 <command>bitbake --help</command>. </para> <para> The most common usage is <command>bitbake packagename</command> 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 <filename>matchbox-desktop_1.2.3.bb</filename> file, you might type <command>bitbake matchbox-desktop</command>. 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 <link linkend='ref-bitbake-providers'> 'Preferences and Providers' section</link>). 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. </para> </section> <section id='usingpoky-components-metadata'> <title>Metadata (Recipes)</title> <para> 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. </para> <para> '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. </para> </section> <section id='usingpoky-components-classes'> <title>Classes</title> <para> 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 <link linkend='ref-classes'>classes reference section</link> gives details on common classes and how to use them. </para> </section> <section id='usingpoky-components-configuration'> <title>Configuration</title> <para> 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). </para> </section> </section> <section id='usingpoky-build'> <title>Running a Build</title> <para> First the Poky build environment needs to be set up using the following command: </para> <para> <literallayout class='monospaced'> $ source poky-init-build-env </literallayout> </para> <para> Once the Poky build environment is set up, a target can now be built using: </para> <para> <literallayout class='monospaced'> $ bitbake <target> </literallayout> </para> <para> The target is the name of the recipe you want to build. Common targets are the images (in <filename class="directory">meta/packages/images/</filename>) or the name of a recipe for a specific piece of software like <application>busybox</application>. More details about the standard images are available in the <link linkend='ref-images'>image reference section</link>. </para> </section> <section id='usingpoky-install'> <title>Installing and Using the Result</title> <para> Once an image has been built it often needs to be installed. The images/kernels built by Poky are placed in the <filename class="directory">tmp/deploy/images</filename> directory. Running qemux86 and qemuarm images is covered in the <link linkend='intro-quickstart-qemu'>Running an Image</link> section. See your board/machine documentation for information about how to install these images. </para> <section id='usingpoky-install-usbnetworking'> <title>USB Networking</title> <para> Devices commonly have USB connectivity. To connect to the usbnet interface, on the host machine run: </para> <para> <programlisting> modprobe usbnet ifconfig usb0 192.168.0.200 route add 192.168.0.202 usb0 </programlisting> </para> </section> <section id='usingpoky-install-qemu-networking'> <title>QEMU/USB networking with IP masquerading</title> <para> 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 <filename>/etc/network/interfaces</filename> to include: </para> <para><programlisting> 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 </programlisting> </para> <para> This ensures the tap0 interface will be up everytime you run QEMU and it will have network/internet access. </para> <para> Under emulation there are two steps to configure for internet access via tap0. The first step is to configure routing: </para> <para><programlisting> route add default gw 192.168.7.200 tap0 </programlisting> </para> <para> The second is to configure name resolution which is configured in the <filename>/etc/resolv.conf</filename> file. The simplest solution is to copy its content from the host machine. </para> <para> USB connections to devices can be set up and automated in a similar way. First add the following to <filename>/etc/network/interfaces</filename>: </para> <para><programlisting> 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 </programlisting> </para> <para> and then to configure routing on the device you would use: </para> <para><programlisting> route add default gw 192.168.0.202 usb0 </programlisting> </para> </section> </section> <section id='usingpoky-debugging'> <title>Debugging Build Failures</title> <para> 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: </para> <section id='usingpoky-debugging-taskfailures'> <title>Task Failures</title> <para>The log file for shell tasks is available in <filename>${WORKDIR}/temp/log.do_taskname.pid</filename>. For the compile task of busybox 1.01 on the ARM spitz machine, this might be <filename>tmp/work/armv5te-poky-linux-gnueabi/busybox-1.01/temp/log.do_compile.1234</filename> for example. To see what bitbake ran to generate that log, look at the <filename>run.do_taskname.pid </filename> file in the same directory. </para> <para>The output from python tasks is sent directly to the console at present.</para> </section> <section id='usingpoky-debugging-taskrunning'> <title>Running specific tasks</title> <para> 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. <command>bitbake matchbox-desktop -c devshell</command>. </para> <para> If you wish to rerun a task you can use the force option "-f". A typical usage session might look like: </para> <para> <literallayout class='monospaced'> % bitbake matchbox-desktop [change some source in the WORKDIR for example] % bitbake matchbox-desktop -c compile -f % bitbake matchbox-desktop</literallayout> </para> <para> 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. </para> <para> You can view a list of tasks in a given package by running the listtasks task e.g. <command>bitbake matchbox-desktop -c listtasks</command>. </para> </section> <section id='usingpoky-debugging-dependencies'> <title>Dependency Graphs</title> <para> Sometimes it can be hard to see why bitbake wants to build some other packages before a given package you've specified. <command>bitbake -g targetname</command> will create <filename>depends.dot</filename> and <filename>task-depends.dot</filename> files in the current directory. They show which packages and tasks depend on which other packages and tasks and are useful for debugging purposes. </para> </section> <section id='usingpoky-debugging-bitbake'> <title>General Bitbake Problems</title> <para> 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". </para> <para> The output from <command>bitbake -DDD -v targetname</command> 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. </para> </section> <section id='usingpoky-debugging-buildfile'> <title>Building with no dependencies</title> <para> If you really want to build a specific .bb file, you can use the form <command>bitbake -b somepath/somefile.bb</command>. 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. </para> </section> <section id='usingpoky-debugging-variables'> <title>Variables</title> <para> 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. </para> </section> <section id='usingpoky-debugging-others'> <title>Other Tips</title> <tip> <para>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 (<filename>/usr/lib/</filename> or <filename>/usr/include/</filename> etc.). </para> </tip> <tip> <para> 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). </para> </tip> </section> </section> </chapter>