diff options
Diffstat (limited to 'handbook/usingpoky.xml')
-rw-r--r-- | handbook/usingpoky.xml | 316 |
1 files changed, 0 insertions, 316 deletions
diff --git a/handbook/usingpoky.xml b/handbook/usingpoky.xml deleted file mode 100644 index ad6bda254..000000000 --- a/handbook/usingpoky.xml +++ /dev/null @@ -1,316 +0,0 @@ -<!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 <target> -$ 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 ---> |