handbook: Move into documentation directory

Signed-off-by: Richard Purdie <rpurdie@linux.intel.com>

1 files changed, 316 insertions, 0 deletions

diff --git a/documentation/poky-ref-manual/usingpoky.xml b/documentation/poky-ref-manual/usingpoky.xml
new file mode 100644
index 0000000000..ad6bda2545
--- /dev/null
+++ b/documentation/poky-ref-manual/usingpoky.xml
@@ -0,0 +1,316 @@
+<!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 
+-->