[oe-commits] org.oe.documentation usermanual: Clean up the using bitbake/oe chapter to the point where it's
lenehan commit
openembedded-commits at lists.openembedded.org
Wed May 2 10:00:56 UTC 2007
usermanual: Clean up the using bitbake/oe chapter to the point where it's
almost useable. Still not included in user manual yet, probably needs a bit
more work before that hppens.
Author: lenehan at openembedded.org
Branch: org.openembedded.documentation
Revision: 76b9cce3001c5c6f955a6a5d0df273dd118313cb
ViewMTN: http://monotone.openembedded.org/revision.psp?id=76b9cce3001c5c6f955a6a5d0df273dd118313cb
Files:
1
usermanual/chapters/usage.xml
usermanual/usermanual.xml
Diffs:
#
# mt diff -r7d6083f8e8e86dbb2282f774302260e2ff5e4396 -r76b9cce3001c5c6f955a6a5d0df273dd118313cb
#
#
#
# patch "usermanual/chapters/usage.xml"
# from [1933682a44a115545405785b571ae17f3d4d7d57]
# to [5100699f1578a8d4b4384937e975ad7f2e3ed413]
#
# patch "usermanual/usermanual.xml"
# from [458f867995291930203c19c57de54afa008d6c7d]
# to [4a9323c7357d8b5a246acae93eb0ad6260b6491d]
#
============================================================
--- usermanual/chapters/usage.xml 1933682a44a115545405785b571ae17f3d4d7d57
+++ usermanual/chapters/usage.xml 5100699f1578a8d4b4384937e975ad7f2e3ed413
@@ -1,138 +1,841 @@
<?xml version="1.0" encoding="UTF-8"?>
-<chapter>
- <title>Usage</title>
+<chapter id="chapter_using_bitbake_and_oe">
+ <title>Using bitbake and OE</title>
<section id="usage_introduction" xreflabel="introduction">
<title>Introduction</title>
- <para>Using bitbake</para>
+ <para>If your reading this manual you probably already have some idea of
+ what OpenEmbedded is all about, which is taking a lot of software and
+ creating something that you can run on another device. Its all about
+ downloading some source code, compiling it, creating packages (like .deb
+ or .rpm) and/or creating boot images that can written to flash on the
+ device. The complexities of cross-compiling and the variety of devices to
+ be supported lead to a lot more complexity in on OpenEmbedded based
+ distribution than you'd find in a typical desktop distribution (which
+ doesn't get cross-compiled).</para>
+
+ <para>A major part of OpenEmbedded deals with compiling source code for
+ various projects. For each project OpenEmbedded has to:</para>
+
+ <orderedlist>
+ <listitem>
+ <para>Download the source code, and any supporting files (such as
+ initscripts);</para>
+ </listitem>
+
+ <listitem>
+ <para>Extract the source code and apply any patches that might be
+ wanted;</para>
+ </listitem>
+
+ <listitem>
+ <para>Configure the software if needed (such as is done by running the
+ configure script);</para>
+ </listitem>
+
+ <listitem>
+ <para>Compile everything;</para>
+ </listitem>
+
+ <listitem>
+ <para>Package up all the files into some package format, like .deb or
+ .rpm or .ipk, ready for installation.</para>
+ </listitem>
+ </orderedlist>
+
+ <para>As mentioned this is made for more complex than normal due
+ to:</para>
+
+ <orderedlist>
+ <listitem>
+ <para>Cross-compiling: cross-compiling is difficult, and lots of
+ software has no support for cross-compiling. All packages included in
+ OE are cross-compiled;</para>
+ </listitem>
+
+ <listitem>
+ <para>Due to cross-compiling the executable's that are created cannot
+ normally be run, so any software that tries to run things as part of
+ it's build process need to have changes made to handle this some other
+ way</para>
+ </listitem>
+ </orderedlist>
+
+ <para>Of course there's a lot more to OE then just compiling packages
+ though. Just some of the things that OE can handle:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Support for glibc and uclibc;</para>
+ </listitem>
+
+ <listitem>
+ <para>Support for building for multiple targets;</para>
+ </listitem>
+
+ <listitem>
+ <para>Dependencies - automatically building anything that is required
+ for the package your really want;</para>
+ </listitem>
+
+ <listitem>
+ <para>Creation of flash and disk images for booting directly on the
+ target device;</para>
+ </listitem>
+
+ <listitem>
+ <para>Support for various packaging formats;</para>
+ </listitem>
+
+ <listitem>
+ <para>Automatically creating all of the cross-compiling tools you'll
+ need;</para>
+ </listitem>
+
+ <listitem>
+ <para>Support for "native" packages that are built for the host
+ computer and not for the target;</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>This chapter assumes you have master the Getting Start guides to
+ OpenEmbedded (see the OpenEmbedded web site for details), and therefore
+ have an appropriately configured setup and have managed to build the
+ cross-compilers for your target. This section talks you through some of
+ the background on what is happening with the aim of helping you understand
+ how to debug and develop within OpenEmbedded.</para>
</section>
<section id="usage_workspace" xreflabel="workspace">
<title>Work space</title>
- <para>The work directory (the working area) is where all of the source is
- extracted, patched and built: ~/devel/oe/build/titan-glibc-25%> ls
- tmp/work/strace-4.5.14-r1 image/ install/ strace-4.5.14/ temp/ The
- subdirectories in the working area are: image When the install is being
- run for the package it's files are installed into this directory. They are
- moved out when being placed into individual packages and so only the
- directores it created should remain. Any other that remain have not been
- packaged. </para>
+ <para>Let's start out by taking a look at a typically working area OE.
+ Note that this isn't exactly what you'll see - there are a lot of options that
+ can effect exactly how things are done, but it gives us a pretty good idea
+ of whats going on. What we are looking at here is the tmp directory (as
+ specified by TMPDIR in your local.conf):<screen>%> find tmp -maxdepth 2 -type d
+tmp
+tmp/stamps
+tmp/cross
+tmp/cross/bin
+tmp/cross/libexec
+tmp/cross/lib
+tmp/cross/share
+tmp/cross/sh4-linux
+tmp/cache
+tmp/cache/titan
+tmp/work
+tmp/work/busybox-1.2.1-r13
+tmp/work/libice-1_1.0.3-r0
+tmp/work/arpwatch-2.1a15-r2
+...
+tmp/rootfs
+tmp/rootfs/bin
+tmp/rootfs/usr
+tmp/rootfs/media
+tmp/rootfs/dev
+tmp/rootfs/var
+tmp/rootfs/lib
+tmp/rootfs/sbin
+tmp/rootfs/mnt
+tmp/rootfs/boot
+tmp/rootfs/sys
+tmp/rootfs/proc
+tmp/rootfs/etc
+tmp/rootfs/home
+tmp/rootfs/tmp
+tmp/staging
+tmp/staging/man
+tmp/staging/x86_64-linux
+tmp/staging/pkgdata
+tmp/staging/pkgmaps
+tmp/staging/var
+tmp/staging/sh4-linux
+tmp/staging/local
+tmp/staging/etc
+tmp/deploy
+tmp/deploy/addons
+tmp/deploy/ipk
+tmp/deploy/sources
+tmp/deploy/images</screen></para>
- <para>install The install directory contains a subdirectory per package to
- be created with the appropriate files located under each package (moved
- from the image directory) and some files related to processing of the
- packages. </para>
+ <para>The various top level directories under tmp include:</para>
- <para>strace-4.5.14 This is the directory created by the extracted source
- code. (Refered to by the S variable in the recipes). </para>
+ <variablelist>
+ <varlistentry>
+ <term>stamps</term>
- <para>temp Scripts to perform the various stages (configure, compile, etc)
- and the logs containing the output of those scripts. </para>
- </section>
+ <listitem>
+ <para>Nothing of interest to users in here. These time stamps are
+ used by bitbake to keep track of what tasks it has completed and
+ what tasks it still has outstanding. This is how it knows that
+ certain actions have been completed and it doesn't need to do them
+ again.</para>
+ </listitem>
+ </varlistentry>
- <section id="usage_tempdir" xreflabel="tempdir">
- <title>Temp dir</title>
+ <varlistentry>
+ <term>cross</term>
- <para>The temp directory contains the scripts to perform various actions
- and the log files generated by those actions:</para>
+ <listitem>
+ <para>Contains the cross-compiler toolchain. That is the gcc and
+ binutils that run on the host system but produce output for the
+ target system.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>cache</term>
+
+ <listitem>
+ <para>Nothing of interest to users in here. This contains the
+ bitbake parse cache and is used to avoid the need to parse all of
+ the recipes each time bitbake is run. This makes bitbake a lot
+ faster on the 2nd and subsequent runs.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>work</term>
+
+ <listitem>
+ <para>The work directory. This is the directory in which all
+ packages are built - this is where the source code is extract,
+ patches applied, software configure, compiled, installed and
+ package. This is where you'll spend most of you time looking when
+ working in OE.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>rootfs</term>
+
+ <listitem>
+ <para>The generated root filesystem image for your target device.
+ This is the contents of the root filesystem (NOTE: fakeroot means it
+ doesn't have the correct device special nodes and permissions to use
+ directly).</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>staging</term>
+
+ <listitem>
+ <para>Contains the staging area, which is used to stored natively
+ compiled tools and and libraries and headers for the target that are
+ required for building other software.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>deploy</term>
+
+ <listitem>
+ <para>Contains the final output from OE. This includes the
+ installation packages (typically .ipkg packages) and flash and/or
+ disk images. This is where you go to get the final product.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para></para>
+
+ <section id="usage_workdir" xreflabel="work directory">
+ <title>work directory</title>
+
+ <para>The working directory is where all files are extracted and
+ everything is configured, compiled and packaged. In other words this is
+ where all the action happens. Each bitbake recipe will produce a
+ corresponding directory in the working area, with the name containing
+ the recipe name, version and the release number (as defined by the PR
+ variable in the recipe).</para>
+
+ <para>In the following example we show some of the directories that are
+ created and in this case they are created directly in the work
+ directory:<screen>~%> find tmp/work -maxdepth 1 -type d | head -4
+tmp/work
+tmp/work/busybox-1.2.1-r13
+tmp/work/libice-1_1.0.3-r0
+tmp/work/arpwatch-2.1a15-r2</screen>Depending on your distribution settings
+ you may have an additional subdirectory present:<screen>~%> find tmp/work -maxdepth 2 -type d | head -4
+tmp/work
+tmp/work/sh4-linux
+tmp/work/sh4-linux/busybox-1.2.1-r13
+tmp/work/sh4-linux/libice-1_1.0.3-r0
+tmp/work/sh4-linux/arpwatch-2.1a15-r2</screen></para>
+
+ <para>where are additional directory corresponding to the target
+ architecture and OS has been inserted. This is added by the use of the
+ <emphasis>multimachine</emphasis> feature which is used to allow builds
+ for multiple targets within the one work directory (which in turn
+ enables the sharing of native functionality and a reduction in the time
+ taken to build for multiple machines). We'll assume multimachine is not
+ being used for the rest of this chapter, just remember to add the extra
+ directory if your distribution is using it.</para>
+
+ <para>Using lzo 1.08 as an example we'll examine the working directory
+ and see what it contain for a typical recipe:<screen>%> find tmp/work/lzo-1.08-r14 -maxdepth 1
+tmp/work/lzo-1.08-r14
+tmp/work/lzo-1.08-r14/temp
+tmp/work/lzo-1.08-r14/lzo-1.08
+tmp/work/lzo-1.08-r14/install
+tmp/work/lzo-1.08-r14/image</screen></para>
+
+ <para>The directory, <emphasis
+ role="bold">tmp/work/lzo-1.08-r14</emphasis>, is know as the working
+ directory for the recipe is held in the <emphasis
+ role="bold">WORKDIR</emphasis> variable in bitbake. You'll sometimes see
+ recipes refer directly to <emphasis role="bold">WORKDIR</emphasis> and
+ if so this is the directory they are referring to. The <emphasis
+ role="bold">1.08</emphasis> is the version of lzo and the <emphasis
+ role="bold">r14</emphasis> is the release number, as defined by the
+ <emphasis role="bold">PR</emphasis> variable in the recipe.</para>
+
+ <para>Under <emphasis role="bold">WORKDIR</emphasis> there are four
+ directories:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>temp</term>
+
+ <listitem>
+ <para>The temp directories contains logs and in some cases scripts
+ that actually implement specific tasks.</para>
+
+ <para>You can look at the logs in this directory to get more
+ information into what happened (or didn't happen). This is usually
+ the first thing to look at when things are going wrong and these
+ usually need to be included when reporting bugs.</para>
+
+ <para>The scripts can be used to see what a particular task, such
+ as configure or compile, is trying to do.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>lzo-1.08</term>
+
+ <listitem>
+ <para>This is the unpacked source code directory, which was
+ created when the lzo source code was extracted in this directory.
+ The name and format of this directory is therefore dependent on
+ the actual source code packaging. Within recipes this directory is
+ referred to as <emphasis role="bold">S</emphasis> and is usually
+ expected to be named like this, that is
+ <emphasis><name>-<version></emphasis>. If the source
+ code extracts to somewhere else you would need to manually specify
+ the value of <emphasis role="bold">S</emphasis> in your
+ recipe.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>install</term>
+
+ <listitem>
+ <para>The installation directory (or destination directory) is
+ where the software needs to be installed into in order to be
+ packaged. This directory is referred to as <emphasis
+ role="bold">D</emphasis> in recipes. So instead of installing into
+ <emphasis role="bold">/usr/bin</emphasis> and <emphasis
+ role="bold">/usr/lib</emphasis> for example you would need to
+ install into <emphasis role="bold">${D}/usr/bin</emphasis> and
+ <emphasis role="bold">${D}/usr/lib</emphasis> in order for the
+ packaging system to work.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>image</term>
+
+ <listitem>
+ <para>The image directory is used to split the installed files
+ into separate packages. One subdirectory is created per package to
+ be generated and the files and moved from the install directory
+ (<emphasis role="bold">D</emphasis>) over to this directory as
+ each packaging instruction is processed. Typically there will be
+ separate documentation (<emphasis>-doc</emphasis>), debugging
+ (<emphasis>-dbg</emphasis>) and development
+ (<emphasis>-dev</emphasis>) packages automatically created.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>The various variables that can be used in a recipe are described
+ in detail in the recipes chapter of this manual.</para>
+
+ <para>What can you do with this information? How about checking out what
+ happened during the configuration of lzo:<screen>~%> less tmp/work/lzo-1.08-r14/temp/log.do_configure.*
+...
+checking whether ccache sh4-linux-gcc -ml -m4 suffers the -fschedule-insns bug... unknown
+checking whether ccache sh4-linux-gcc -ml -m4 suffers the -fstrength-reduce%s
>>> DIFF TRUNCATED @ 16K
More information about the Openembedded-commits
mailing list