diff options
Diffstat (limited to 'documentation/poky-ref-manual/usingpoky.xml')
| -rw-r--r-- | documentation/poky-ref-manual/usingpoky.xml | 348 |
1 files changed, 0 insertions, 348 deletions
diff --git a/documentation/poky-ref-manual/usingpoky.xml b/documentation/poky-ref-manual/usingpoky.xml deleted file mode 100644 index fc4fbdc6c..000000000 --- a/documentation/poky-ref-manual/usingpoky.xml +++ /dev/null @@ -1,348 +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 - followed by information about running poky builds and dealing with any - problems that may arise. - </para> - -<section id='usingpoky-components'> - <title>Poky Overview</title> - - <para> - The BitBake task executor together with various types of configuration files form the core of Poky. - This section overviews the BitBake task executor and the - configuration files by describing what they are used for and they they interact. - </para> - - <para> - BitBake handles the parsing and execution of the data files. - The data itself is of various types: - <itemizedlist> - <listitem><para>Recipes: Provides details about particular pieces of software</para></listitem> - <listitem><para>Class Data: An abstraction of common build information (e.g. how to build a - Linux kernel).</para></listitem> - <listitem><para>Configuration Data: Defines machine-specific settings, policy decisions, etc. - Configuration data acts a the glue to bind everything together.</para></listitem> - </itemizedlist> - </para> - - <para> - BitBake knows how to combine multiple data sources together and refers to each data source - as a <link linkend='usingpoky-changes-layers'>'layer'</link>. - </para> - - <para> - Following are some brief details on these core components. - For more detailed information on these components see the - <link linkend='ref-structure'>'Reference: Directory Structure'</link> - appendix. - </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 BitBake - supports look at 'bitbake --help'. - </para> - - <para> - The most common usage for BitBake is <filename>bitbake <packagename></filename>, where - packagename is the name of the package you want to build (referred to as the 'target' - in this manual). - The target often equates to the first part of a <filename>.bb</filename> filename. - So, to run the <filename>matchbox-desktop_1.2.3.bb</filename> file, you - might type the following: - <literallayout class='monospaced'> - $ bitbake matchbox-desktop - </literallayout> - Several different versions of <filename>matchbox-desktop</filename> might exist. - BitBake chooses the one selected by the distribution configuration. - You can get more details about how BitBake chooses between different versions - and providers in the <link linkend='ref-bitbake-providers'> - 'Preferences and Providers'</link> section. - </para> - <para> - BitBake also tries to execute any dependent tasks first. - So for example, before building <filename>matchbox-desktop</filename> BitBake - would build a cross compiler and glibc if they had not already been built. - </para> - - </section> - - <section id='usingpoky-components-metadata'> - <title>Metadata (Recipes)</title> - - <para> - The <filename>.bb</filename> files are usually referred to as 'recipes'. - In general, a recipe contains information about a single piece of software such - as from where to download the source patches (if any are needed), which special - configuration options to apply, how to compile the source files, and how to - package the compiled output. - </para> - - <para> - The term 'package' can also be used to describe recipes. - However, since the same word is used for the packaged output from Poky (i.e. .ipk or .deb - files), this document avoids it. - </para> - - </section> - - <section id='usingpoky-components-classes'> - <title>Classes</title> - - <para> - Class files (<filename>.bbclass</filename>) contain information that is useful to share - between metadata files. - An example is the autotools class, which contains - common settings for any application that autotools uses. - The <link linkend='ref-classes'>Reference: Classes</link> appendix provides details - about common classes and how to use them. - </para> - </section> - - <section id='usingpoky-components-configuration'> - <title>Configuration</title> - - <para> - The configuration files (<filename>.conf</filename>) define various configuration variables - that govern what Poky does. - These files are split into several areas that define machine configuration options, - distribution configuration options, compiler tuning options, general common configuration - options and user configuration options (<filename>local.conf</filename>). - </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 build's object files. The default - build dir is poky-dir/build. A different build_dir can be used for each of the targets. - For example, ~/build/x86 for a qemux86 target, and ~/build/arm for a qemuarm target. - Please refer to <link linkend="structure-core-script">poky-init-build-env</link> - for more detailed information. - </para> - <para> - Once the Poky build environment is set up, a target can 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>meta/recipes-core/images</filename>, - <filename>/meta/recipes-sato/images</filename>, etc. - Or, the target can be the name of a recipe for a specific piece of software such as - <application>busybox</application>. - For more details about the standard images available, see the - <link linkend="ref-images">'Reference: Images'</link> appendix. - </para> - <note> - Building an image without GNU Public License Version 3 (GPLv3) components is - only supported for minimal and base images. - See <link linkend='ref-images'>'Reference: Images'</link> for more information. - </note> - <note> - When building an image using GPL components you need to maintain your original - settings and not switch back and forth applying different versions of the GNU - Public License. If you rebuild using different versions of GPL you can get - dependency errors due to some components not being rebuilt. - </note> -</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 described in the - 'Using Pre-Built Binaries and QEMU' section of the Yocto Project Quick Start. - See <ulink url="http://www.yoctoproject.org//docs/yocto-quick-start/yocto-project-qs.html"/> - for the guide. - For information about how to install these images, see the documentation for your - particular board/machine. - </para> - -</section> - -<section id='usingpoky-debugging'> - <title>Debugging Build Failures</title> - - <para> - The exact method for debugging Poky depends on the nature of the - problem and on the system's area from which the bug originates. - Standard debugging practices such as comparison against the last - known working version with examination of the changes and the re-application of steps - to identify the one causing the problem are - valid for Poky just as they are for any other system. - Even though it is impossible to detail every possible potential failure, - here are some general tips to aid in 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 example, the "compile" task of busybox 1.01 on the ARM spitz machine might be - <filename>tmp/work/armv5te-poky-linux-gnueabi/busybox-1.01/temp/log.do_compile.1234</filename>. - To see what BitBake runs to generate that log, look at the corresponding - <filename>run.do_taskname.pid </filename> file located in the same directory. - </para> - - <para> - Presently, the output from python tasks is sent directly to the console. - </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 on which it depends build first - hence, - the standard BitBake behaviour. - Some tasks exist, such as devshell, that are not part of the default build chain. - If you wish to run a task that is not part of the default build chain you can use the - "-c" option in BitBake as follows: - <literallayout class='monospaced'> - $ bitbake matchbox-desktop -c devshell - </literallayout> - </para> - - <para> - If you wish to rerun a task use the force option "-f". - For example, the following sequence forces recompilation after changing files in the - working directory. - </para> - - <para> - <literallayout class='monospaced'> - $ bitbake matchbox-desktop - [make some changes to the source code in the WORKDIR] - $ bitbake matchbox-desktop -c compile -f - $ bitbake matchbox-desktop - </literallayout> - </para> - - <para> - This sequence first builds <filename>matchbox-desktop</filename> and then recompiles it. - The last command reruns all tasks, basically the packaging tasks, after the compile. - BitBake recognizes that the "compile" task was rerun and therefore understands that the other - tasks also need to be run again. - </para> - - <para> - You can view a list of tasks in a given package by running the "listtasks" task. - For example: - <literallayout class='monospaced'> - $ bitbake matchbox-desktop -c - </literallayout> - The results are in the file <filename>${WORKDIR}/temp/log.do_listtasks</filename>. - </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. - The <filename>bitbake -g targetname</filename> command creates the <filename>depends.dot</filename> and - <filename>task-depends.dot</filename> files in the current directory. - These files show the package and task dependencies and are useful for debugging problems. - You can use the <filename>bitbake -g -u depexp targetname</filename> command to display the results - in a more human-readable form. - </para> - </section> - - <section id='usingpoky-debugging-bitbake'> - <title>General BitBake Problems</title> - - <para> - You can see debug output from BitBake by using the "-D" option. - The debug output gives more information about what BitBake - is doing and the reason behind it. - Each "-D" option you use increases the logging level. - The most common usage is <filename>-DDD</filename>. - </para> - - <para> - The output from <filename>bitbake -DDD -v targetname</filename> can reveal why - BitBake chose a certain version of a package or why BitBake - picked a certain provider. - This command could also help you in a situation where you think BitBake did something - unexpected. - </para> - </section> - - <section id='usingpoky-debugging-buildfile'> - <title>Building with No Dependencies</title> - <para> - If you really want to build a specific <filename>.bb</filename> file, you can use - the command form <filename>bitbake -b somepath/somefile.bb</filename>. - This command form does not check for dependencies so you should use it - only when you know its dependencies already exist. - You can also specify fragments of the filename and BitBake checks for a unique match. - </para> - </section> - - <section id='usingpoky-debugging-variables'> - <title>Variables</title> - <para> - The "-e" option dumps 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 watching for undesireable items making their way - into compiler command lines. - For example, you do not want references to local system files like - <filename>/usr/lib/</filename> or <filename>/usr/include/</filename>. - </para> - </tip> - <tip> - <para> - If you want to remove the psplash boot splashscreen, add "psplash=false" - to the kernel command line. - Doing so prevents psplash from loading thus allowing you to see the console. - It is also possible to switch out of the splashscreen by - switching the virtual console (e.g. Fn+Left or Fn+Right on a Zaurus). - </para> - </tip> - </section> -</section> - -</chapter> -<!-- -vim: expandtab tw=80 ts=4 ---> |