aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorJamie Lenehan <lenehan@twibble.org>2007-05-02 09:48:24 +0000
committerJamie Lenehan <lenehan@twibble.org>2007-05-02 09:48:24 +0000
commita35403110d02609e837e2c9835566825a5c75574 (patch)
tree5842efff15563de5658790bf14adcca5fd5af9f6
parent61459e55980ecc0aa5cbd94cfa8e5ef658150ec0 (diff)
downloadopenembedded-a35403110d02609e837e2c9835566825a5c75574.tar.gz
openembedded-a35403110d02609e837e2c9835566825a5c75574.tar.bz2
openembedded-a35403110d02609e837e2c9835566825a5c75574.zip
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.
-rw-r--r--usermanual/chapters/usage.xml903
-rw-r--r--usermanual/usermanual.xml3
2 files changed, 805 insertions, 101 deletions
diff --git a/usermanual/chapters/usage.xml b/usermanual/chapters/usage.xml
index 2e1f887d38..f2031b3346 100644
--- a/usermanual/chapters/usage.xml
+++ b/usermanual/chapters/usage.xml
@@ -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%&gt; 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>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>strace-4.5.14 This is the directory created by the extracted source
- code. (Refered to by the S variable in the recipes). </para>
-
- <para>temp Scripts to perform the various stages (configure, compile, etc)
- and the logs containing the output of those scripts. </para>
- </section>
+ <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>%&gt; 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>
- <section id="usage_tempdir" xreflabel="tempdir">
- <title>Temp dir</title>
+ <para>The various top level directories under tmp include:</para>
- <para>The temp directory contains the scripts to perform various actions
- and the log files generated by those actions:</para>
- </section>
+ <variablelist>
+ <varlistentry>
+ <term>stamps</term>
+
+ <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>
+
+ <varlistentry>
+ <term>cross</term>
+
+ <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>
- <section id="usage_installdir" xreflabel="installdir">
- <title>Install dir</title>
+ <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>
- <para>The install directory contains one subdirectory per package to be
- generated, each containing the files to be included in that package, and
- some package control files:</para>
+ <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>~%&gt; 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>~%&gt; 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>%&gt; 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>&lt;name&gt;-&lt;version&gt;</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>~%&gt; 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 bug... unknown
+checking whether ccache sh4-linux-gcc -ml -m4 accepts -fstrict-aliasing... yes
+checking the alignment of the assembler... 0
+checking whether to build assembler versions... no
+configure: creating ./config.status
+config.status: creating Makefile
+config.status: creating examples/Makefile
+config.status: creating include/Makefile
+config.status: creating ltest/Makefile
+config.status: creating minilzo/Makefile
+config.status: creating src/Makefile
+config.status: creating tests/Makefile
+config.status: creating config.h
+config.status: executing depfiles commands</screen></para>
+
+ <para>Or perhaps you want to see which files were included in each of
+ the generated packages:<screen>~%&gt; find tmp/work/lzo-1.08-r14/install
+tmp/work/lzo-1.08-r14/install
+tmp/work/lzo-1.08-r14/install/lzo-doc
+tmp/work/lzo-1.08-r14/install/lzo-dbg
+tmp/work/lzo-1.08-r14/install/lzo-dbg/usr
+tmp/work/lzo-1.08-r14/install/lzo-dbg/usr/lib
+tmp/work/lzo-1.08-r14/install/lzo-dbg/usr/lib/.debug
+tmp/work/lzo-1.08-r14/install/lzo-dbg/usr/lib/.debug/liblzo.so.1.0.0
+tmp/work/lzo-1.08-r14/install/lzo-dev
+tmp/work/lzo-1.08-r14/install/lzo-dev/usr
+tmp/work/lzo-1.08-r14/install/lzo-dev/usr/include
+tmp/work/lzo-1.08-r14/install/lzo-dev/usr/include/lzo2a.h
+tmp/work/lzo-1.08-r14/install/lzo-dev/usr/include/lzo1y.h
+tmp/work/lzo-1.08-r14/install/lzo-dev/usr/include/lzo1.h
+tmp/work/lzo-1.08-r14/install/lzo-dev/usr/include/lzo1b.h
+tmp/work/lzo-1.08-r14/install/lzo-dev/usr/include/lzo1f.h
+tmp/work/lzo-1.08-r14/install/lzo-dev/usr/include/lzoconf.h
+tmp/work/lzo-1.08-r14/install/lzo-dev/usr/include/lzo1x.h
+tmp/work/lzo-1.08-r14/install/lzo-dev/usr/include/lzo16bit.h
+tmp/work/lzo-1.08-r14/install/lzo-dev/usr/include/lzo1a.h
+tmp/work/lzo-1.08-r14/install/lzo-dev/usr/include/lzo1z.h
+tmp/work/lzo-1.08-r14/install/lzo-dev/usr/include/lzoutil.h
+tmp/work/lzo-1.08-r14/install/lzo-dev/usr/include/lzo1c.h
+tmp/work/lzo-1.08-r14/install/lzo-dev/usr/lib
+tmp/work/lzo-1.08-r14/install/lzo-dev/usr/lib/liblzo.a
+tmp/work/lzo-1.08-r14/install/lzo-dev/usr/lib/liblzo.so
+tmp/work/lzo-1.08-r14/install/lzo-dev/usr/lib/liblzo.la
+tmp/work/lzo-1.08-r14/install/lzo.shlibdeps
+tmp/work/lzo-1.08-r14/install/lzo-locale
+tmp/work/lzo-1.08-r14/install/lzo
+tmp/work/lzo-1.08-r14/install/lzo/usr
+tmp/work/lzo-1.08-r14/install/lzo/usr/lib
+tmp/work/lzo-1.08-r14/install/lzo/usr/lib/liblzo.so.1
+tmp/work/lzo-1.08-r14/install/lzo/usr/lib/liblzo.so.1.0.0</screen></para>
+ </section>
</section>
- <section id="usage_deploydir" xreflabel="deploydir">
- <title>Deploy dir</title>
+ <section id="usage_tasks" xreflabel="tasks">
+ <title>Tasks</title>
+
+ <para>When you build a software package you generally perform a number of
+ steps or tasks. These would include things like "download the source
+ code", "unpack the source code", "run the configure script", "build the
+ software", "install the software" etc. OpenEmbedded builds software in a
+ similar way - by performing a set of tasks. Understanding these tasks is
+ critical to understanding how things get done in OpenEmbedded.</para>
+
+ <para></para>
+
+ <para>The following is a list of the most commonly seen tasks:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>fetch</term>
+
+ <listitem>
+ <para>The fetch task is responsible for fetching any source code
+ that is required. This means things such as downloading files and
+ checking out from svn or git repositories for example.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>unpack</term>
+
+ <listitem>
+ <para>The unpack task is responsible for extracting files from
+ archives, such as .tar.gz, into the working area and copying any
+ additional files into the working area.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>patch</term>
+
+ <listitem>
+ <para>The patch task is responsible for applying any patches to the
+ unpacked source code</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>configure</term>
+
+ <listitem>
+ <para>The configure task takes care of the configuration of the
+ package. Running a configure script ("./configure &lt;options&gt;")
+ is probably the form of configuration that is most recognised but
+ it's not the only configuration system that exists.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>compile</term>
- <para>The deploy directory is where the final packaged files (typically
- .ipk files) and and flash images or nfs images etc end up. For our strace
- example we end up with just two .ipk files, one for the application and
- one for the documentation.</para>
+ <listitem>
+ <para>The compile task actually compiles the software. This could be
+ as simple as running "make".</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>populate_staging (stage)</term>
+
+ <listitem>
+ <para>The populate_staging task (stage is an alternate, easier to
+ type name, that can be used to refer to this task) is responsible
+ for making available libraries and headers (if any) that may be
+ required by other packages to build. For example if you compile zlib
+ then it's headers and the library need to be made available for
+ other applications to include and link against.</para>
+
+ <para>NOTE that this is different to the install (and packaging)
+ related tasks in that this is making available things for use during
+ build on the development host while the installed files are being
+ made available for use on the target device.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term></term>
+
+ <listitem>
+ <para></para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>install</term>
+
+ <listitem>
+ <para>The install task is responsible for actually installing the
+ software. Now this needs to install the software into the
+ destination directory (${D}) but once package the destination
+ directory will be removed from all the files. In other words if you
+ install something into ${D}/bin then it will end up in the /bin
+ directory in the package and therefore on the target.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>package</term>
+
+ <listitem>
+ <para>The package task takes the installed files and splits them
+ into separate directories under the ${WORKDIR}/install directory,
+ one per package. It moves the files for the destination directory,
+ ${D}, that they were installed in into the appropriate packages
+ subdirectory. Usually there will be a main package a separate
+ documentation (-doc), development (-dev) and debugging packages
+ (-dbg) for example.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>package_write</term>
+
+ <listitem>
+ <para>The package_write task is responsible for taking each packages
+ subdirectory and creating any actual installation package, such as
+ .ipk, .deb or .rpm.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term></term>
+
+ <listitem>
+ <para></para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para></para>
+
+ <para>Note that these are not the only possible set of tasks. There are
+ various methods available to insert additional tasks in between existing
+ tasks if needed. As an example the insane.bbclass, which performs various
+ QA checks, does these checks by inserting a new task, qa_configure,
+ between the configure and compile tasks to check on the result of
+ configuration and another new tasks, qa_staging, between populate_staging
+ and build to validate the files that have been staged.</para>
+
+ <para></para>
+
+ <para>You can see a list of all the tasks available for a specific recipe
+ by explicitly calling bitbake on the recipe and asking it for a list of
+ tasks:</para>
+
+ <para><screen>~%&gt; bitbake -b packages/perl/perl_5.8.8.bb -c listtasks
+NOTE: package perl-5.8.8: started
+NOTE: package perl-5.8.8-r11: task do_listtasks: started
+do_fetchall
+do_listtasks
+do_rebuild
+do_compile
+do_build
+do_populate_staging
+do_mrproper
+do_fetch
+do_configure
+do_clean
+do_package
+do_unpack
+do_install
+do_package_write
+do_distribute_sources
+do_showdata
+do_qa_configure
+do_qa_staging
+do_patch
+NOTE: package perl-5.8.8-r11: task do_listtasks: completed
+NOTE: package perl-5.8.8: completed
+~%&gt; </screen></para>
+
+ <para>Note that <emphasis>do_</emphasis> prefixed to the tasks - the
+ <emphasis>do_&lt;task&gt;</emphasis> is the name of the method that
+ implements the required functionality for
+ <emphasis>&lt;task&gt;</emphasis>, so the above is actually listing the
+ methods that implement the available tasks. It's sometimes a but confusing
+ but just remember that the do_ is the method name (with a definition
+ usually found in the of the .bbclass files in the classes
+ directory.)</para>
</section>
- <section id="usage_singlepkg" xreflabel="singlepkg">
+ <section id="usage_workwithsinglepackage"
+ xreflabel="working with a single package">
<title>Working with a single package</title>
<para>When working on fixing and/or creating a single recipe you can ask
- bitbake to deal with a single .bb file only. The -b &lt;bb-file&gt; option
- asks bitbake to only process the named file. So to clean and rebuild a
- single package you can do: %&gt; bitbake -b &lt;bb-file&gt; -c clean %&gt;
- bitbake -D -b &lt;bb-file&gt; The various options that are useful here
- are: -b &lt;bb-file&gt; Specify which recipe to process -c &lt;action&gt;
- Specify which action to perform (see below) -D Enable debugging output.
- This gives you a lot more output during the operation. -f Force on
- operation. This is useful in getting bitbake to perform some operation it
- normally wouldn't do. For example, if you try and compile twice ina row
- then bitbake will not do anything on the second attempt since it has
- already gone through the compile stage. By adding -f forces it the action
- to take place. The most common actions (used with -c) are: fetch Will
- download any files that need to be fetched. unpack Extracts the source
- code into the working directory, but does not apply any patches. patch
- Applies patches into the source in the working directory. configure Runs
- the configuration task for the recipe. compile Actually compile
- everything. stage Copy required files into the staging area. install
- Install files that are going to be package. package Package files.
- Normally this means creating the .ipkg files. clean Clean the package -
- this deletes the entire working directory for the package, so on the next
- build the source will be extracted, patches applied etc. Note that each
- action will run any preceeding actions that have not yet been performed.
- So starting with compile will also peform the fetch, unpack, patch and
- configure actions. A typically development session would involve editing
- files in the working directory and running: %&gt; bitbake -f
- packages/testapp/testapp_4.3.bb -c compile (Try and compile) look at logs,
- edit some files in working area %&gt; bitbake -f
- packages/testapp/testapp_4.3.bb -c compile -f (Force re-compile) and then
- once appropriate patches have been made and the recipe updated: %&gt;
- bitbake -f packages/testapp/testapp_4.3.bb -c clean (Remove working files)
- %&gt; bitbake -f packages/testapp/testapp_4.3.bb (Try everything from
- scratch) A full list of available tasks for a specific package can be
- obtained with the listtasks task: %&gt; bitbake -f
- packages/testapp/testapp_4.3.bb -c listtasks </para>
+ bitbake to deal directly with a single .bb file only. The <emphasis>-b
+ &lt;bb-file&gt;</emphasis> option asks bitbake to only process the named
+ file. Note that this ignores any dependencies that are in the recipe, so
+ these must have already been handled.</para>
+
+ <para>A typically example of this is to clean and then rebuild a package
+ with some debugging information:</para>
+
+ <para><screen>%&gt; bitbake -b &lt;bb-file&gt; -c clean
+%&gt; bitbake -b &lt;bb-file&gt; -D</screen></para>
+
+ <para>The various options to bitbake that are useful here are:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>-b &lt;bb-file&gt;</term>
+
+ <listitem>
+ <para>Specify which recipe to process;</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>-c &lt;action&gt;</term>
+
+ <listitem>
+ <para>Specify which action to perform, typically the name of one of
+ the tasks supported by the recipe;</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>-D</term>
+
+ <listitem>
+ <para>Display debugging information, use two <emphasis
+ role="bold">-D</emphasis>'s for additional debugging.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>-f</term>
+
+ <listitem>
+ <para>Force an operation. This is useful in getting bitbake to
+ perform some operation it normally wouldn't do. For example, if you
+ try and compile twice in a row then bitbake will not do anything on
+ the second attempt since it has already performed the compile task.
+ By adding <emphasis role="bold">-f</emphasis> it will force it to
+ perform the action regardless of if it thinks it's been done
+ previously.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>The most common actions (used with -c) are:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>fetch</term>
+
+ <listitem>
+ <para>Try to download all of the required source files, but don't do
+ anything else with them.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>unpack</term>
+
+ <listitem>
+ <para>Unpack the source file but don't apply the patches yet.
+ Sometimes you may want to look at the extracted, but not patched
+ source code and that's what just unpacking will give you (some
+ time's handy to get diffs generated against the original
+ source).</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>patch</term>
+
+ <listitem>
+ <para>Apply any patches.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>configure</term>
+
+ <listitem>
+ <para>Performs and configuration that is required for the
+ software.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>compile</term>
+
+ <listitem>
+ <para>Perform the actual compilation steps of the software.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>stage</term>
+
+ <listitem>
+ <para>If any files, such as header and libraries, will be required
+ by other packages then they need to be installed into the staging
+ area and that's what this task takes care of.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>install</term>
+
+ <listitem>
+ <para>Install the software in preparation for packaging.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>package</term>
+
+ <listitem>
+ <para>Package the software. Remember that this moves the files from
+ the installation directory, D, into the packing install area. So to
+ re-package you also need to re-install first.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>clean</term>
+
+ <listitem>
+ <para>Delete the entire directory for this version of the software.
+ Usually done to allow a test build with no chance of old files or
+ changes being left behind.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>Note that each of the actions that corresponds to task's will run
+ any preceding tasks that have not yet been performed. So starting with
+ compile will also perform the fetch, unpack, patch and configure
+ actions.</para>
+
+ <para>A typically development session might involve editing files in the
+ working directory and recompiling until it all works:<screen>[... test ...]
+%&gt; bitbake -b packages/testapp/testapp_4.3.bb -c compile -D
+
+[... save a copy of main.c and make some changes ...]
+%&gt; vi tmp/work/testapp-4.3-r0/main.c
+%&gt; bitbake -b packages/testapp/testapp_4.3.bb -c compile -D -f
+
+[... create a patch and add it to the recipe ...]
+%&gt; vi packages/testapp/testapp_4.3.bb
+
+[... test from clean ...]
+%&gt; bitbake -b packages/testapp/testapp_4.3.bb -c clean
+%&gt; bitbake -b packages/testapp/testapp_4.3.bb
+
+[... NOTE: How to create the patch is not covered at this point ...]</screen></para>
+
+ <para>Here's another example showing how you might go about fixing up the
+ packaging in your recipe:<screen>%&gt; bitbake -b packages/testapp/testapp_4.3.bb -c install -f
+%&gt; bitbake -b packages/testapp/testapp_4.3.bb -c stage -f
+%&gt; find tmp/work/testapp_4.3/install
+...
+%&gt; vi packages/testapp/testapp_4.3.bb</screen>At this stage you play with
+ the <emphasis role="bold">PACKAGE_</emphasis> and <emphasis
+ role="bold">FILES_</emphasis> variables and then repeat the above
+ sequence.</para>
+
+ <para>Note how we install and then stage. This is one of those things
+ where understanding the tasks helps a lot! Remember that stage moves the
+ files from where they were installed (${D}) into the various
+ subdirectories (under <emphasis role="bold">${WORKDIR}/instal</emphasis>l)
+ for each package. So if you try and run a stage task without a prior
+ install there won't be any files there to stage! Note also that the stage
+ tasks clears all the subdirectories in <emphasis
+ role="bold">${WORKDIR}/install</emphasis> so you won't get any left over
+ files. But beware, the install task doesn't clear <emphasis
+ role="bold">${D}</emphasis> directory, so any left over files from a
+ previous packing attempt will be left behind (which is ok if all you care
+ about it staging).</para>
</section>
- <section id="usage_bbinteractive" xreflabel="bbinteractive">
+ <section id="usage_interactive_bitbake" xreflabel="interactive bitbake">
<title>Interactive bitbake</title>
- <para>To interactively test things use: %&gt; bitbake -i this will open
- the bitbake shell. From here there are a lot of commands available (try
- help). First thing you will want to do is parse all of the recipes.
- BB&gt;&gt; parse You can now build a specific recipe: BB&gt;&gt; build
- net-snmp If it fails you may want to clean the build before trying again:
- BB&gt;&gt; clean net-snmp If you update the recipe by editing the .bb file
- (to fix some issues) then you will want to clean the package, reparse the
- modified recipe, and the build again: BB&gt;&gt; clean net-snmp BB&gt;&gt;
- reparse net-snmp BB&gt;&gt; build net-snmp Note that you can use wildcards
- in the bitbake shell as well: BB&gt;&gt; build t* The interacive mode was
- most useful with bitbake versions prior to 1.4 where the entire set of
- recipes had to be reparsed each time bitbake was run. Since bitbake 1.4
- the parseing is cached between runs and so it is no where near as painful
- to run individual bitbake commands and therefore the interactive mode is
- no longer as important as it once was. [edit] </para>
+ <para>To interactively test things use:<screen>%&gt; bitbake -i</screen>this
+ will open the bitbake shell. From here there are a lot of commands
+ available (try help).</para>
+
+ <para>First thing you will want to do is parse all of the recipes (recent
+ bitbake version do this automatically when needed, so you don't need to
+ manually do this anymore):<screen>BB&gt;&gt; parse</screen>You can now
+ build a specific recipe:<screen>BB&gt;&gt; build net-snmp</screen>If it
+ fails you may want to clean the build before trying again:<screen>BB&gt;&gt; clean net-snmp</screen>If
+ you update the recipe by editing the .bb file (to fix some issues) then
+ you will want to clean the package, reparse the modified recipe, and the
+ build again:<screen>BB&gt;&gt; clean net-snmp
+BB&gt;&gt; reparse net-snmp
+BB&gt;&gt; build net-snmp</screen>Note that you can use wildcards in the
+ bitbake shell as well:<screen>BB&gt;&gt; build t*</screen></para>
+
+ <para></para>
</section>
<section id="usage_devshell" xreflabel="devshell">
<title>Devshell</title>
- <para></para>
+ <para>[To be done]</para>
</section>
- <section id="usage_workflow" xreflabel="workflow">
- <title>Workflow</title>
+ <section id="usage_patches" xreflabel="patching">
+ <title>Patching and patch management</title>
- <para>fetch Will download any files that need to be fetched. unpack
- Extracts the source code into the working directory, but does not apply
- any patches. patch Applies patches into the source in the working
- directory. configure Runs the configuration task for the recipe. compile
- Actually compile everything. stage Copy required files into the staging
- area. install Install files that are going to be package. package Package
- files. Normally this means creating the .ipkg files. </para>
+ <para>[To be done]</para>
</section>
</chapter> \ No newline at end of file
diff --git a/usermanual/usermanual.xml b/usermanual/usermanual.xml
index e978dd50cc..88d8a408b8 100644
--- a/usermanual/usermanual.xml
+++ b/usermanual/usermanual.xml
@@ -5,6 +5,7 @@
-->
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
+<!ENTITY chapter-usage SYSTEM "chapters/usage.xml">
<!ENTITY chapter-recipes SYSTEM "chapters/recipes.xml">
<!ENTITY class-autotools SYSTEM "reference/class_autotools.xml">
<!ENTITY class-binconfig SYSTEM "reference/class_binconfig.xml">
@@ -833,7 +834,7 @@ NOTE: Couldn't find shared library provider for libm.so.6
<!-- Bitbake usage chapter -->
- <!-- &chapter-usage; - this is not ready yet -->
+ <!-- &chapter-usage; - this is not ready yet -->
<!-- Bitbake recipies chapter -->