path: root/documentation/poky-ref-manual/usingpoky.xml

<!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-layers'>'layer'</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 [build_dir]
</literallayout>
    </para>
    <para>
        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 <link linkend="structure-core-script">poky-init-build-env</link>
        for detail info
    </para>
    <para>
        Once the Poky build environment is set up, a target can now be built using:
    </para>
    <para>
        <literallayout class='monospaced'>
$ bitbake &lt;target&gt;
$ bitbake qemu-native
</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>.
        The qemu-native target will build the poky customized qemu, and will be used
        by runqemu script later.
    </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>

<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>, and the result is in file ${WORKDIR}/temp/log.do_listtasks.pid.
        </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.
            <command>"bitbake -g -u depexp targetname"</command> will show result
            in more human-readable GUI style.
        </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>
<!-- 
vim: expandtab tw=80 ts=4 
-->