[oe-commits] org.oe.documentation usermanual: Work some more on the using bitbake/OE chapter. Enable it -
lenehan commit
openembedded-commits at lists.openembedded.org
Fri May 4 07:58:08 UTC 2007
usermanual: Work some more on the using bitbake/OE chapter. Enable it -
while it's not great but I think there is probably a few useful items in
there for new users now.
Author: lenehan at openembedded.org
Branch: org.openembedded.documentation
Revision: 1d471462a7877e50349aa37c5eae7f29e0bf45bc
ViewMTN: http://monotone.openembedded.org/revision.psp?id=1d471462a7877e50349aa37c5eae7f29e0bf45bc
Files:
1
usermanual/chapters/recipes.xml
usermanual/chapters/usage.xml
usermanual/usermanual.xml
Diffs:
#
# mt diff -r67b9d3a1b37c967bf0e6f356980db8176dca3264 -r1d471462a7877e50349aa37c5eae7f29e0bf45bc
#
#
#
# patch "usermanual/chapters/recipes.xml"
# from [ab2952651e5ccc69e0a9f7a56093a4c0ef38e1c2]
# to [3334f2cc26495fcea1a82f5488ae571bd7a39222]
#
# patch "usermanual/chapters/usage.xml"
# from [5100699f1578a8d4b4384937e975ad7f2e3ed413]
# to [c1cbce2eb95191aab51f44d1f7973c81c7f1c7da]
#
# patch "usermanual/usermanual.xml"
# from [030cc8dea218beda51a1ac2c1569e422b08ccbd6]
# to [b96632a7efc6aae32145f635933691e597646ad5]
#
============================================================
--- usermanual/chapters/recipes.xml ab2952651e5ccc69e0a9f7a56093a4c0ef38e1c2
+++ usermanual/chapters/recipes.xml 3334f2cc26495fcea1a82f5488ae571bd7a39222
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="UTF-8"?>
-<chapter id="chapter_recipes">
+<chapter id="chapter_recipes" xreflabel="Recipes chapter">
<title>Recipes</title>
<section id="recipes_introduction" xreflabel="introduction">
============================================================
--- usermanual/chapters/usage.xml 5100699f1578a8d4b4384937e975ad7f2e3ed413
+++ usermanual/chapters/usage.xml c1cbce2eb95191aab51f44d1f7973c81c7f1c7da
@@ -7,16 +7,17 @@
<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
+ creating something that you can run on another device. This involves
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>
+ device. The difficulties of cross-compiling and the variety of devices
+ which can be supported lead to a lot more complexity in an OpenEmbedded
+ based distribution than you'd find in a typical desktop distribution
+ (which cross-compiling isn't needed).</para>
<para>A major part of OpenEmbedded deals with compiling source code for
- various projects. For each project OpenEmbedded has to:</para>
+ various projects. For each project this generally requires the same basic
+ set of tasks:</para>
<orderedlist>
<listitem>
@@ -44,43 +45,57 @@
</listitem>
</orderedlist>
- <para>As mentioned this is made for more complex than normal due
- to:</para>
+ <para>There's nothing particular unusual about this process when building
+ on the machine the package is to be installed on. What makes this
+ difficult is:</para>
<orderedlist>
<listitem>
<para>Cross-compiling: cross-compiling is difficult, and lots of
- software has no support for cross-compiling. All packages included in
+ 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>
+ <para>Target and host are different: This means you can't compile up a
+ program and then run it - it's compiled to run on the target system,
+ not on the system compiling it. Lots of software tries to build and
+ run little helper and/or test applications and this won't work when
+ cross-compiling.</para>
</listitem>
+
+ <listitem>
+ <para>Tool chains (compiler, linker etc) are often difficult to
+ compile. Cross tool chains are even more difficult. Typically you'd go
+ out and download a tool chain made by someone else - but not when your
+ using OE. In OE the entire toolchain is built as part of the process.
+ This may make things take longer initially and may make it more
+ difficult to get started but makes it easier to apply patches and test
+ out changes to the tool chain.</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>
+ though. Some of the features that OE supports includes:</para>
<itemizedlist>
<listitem>
- <para>Support for glibc and uclibc;</para>
+ <para>Support for both glibc and uclibc;</para>
</listitem>
<listitem>
- <para>Support for building for multiple targets;</para>
+ <para>Support for building for multiple target devices from the one
+ code base;</para>
</listitem>
<listitem>
- <para>Dependencies - automatically building anything that is required
- for the package your really want;</para>
+ <para>Automatically building anything that is required for the package
+ to compile and/or run (build and run time dependencies);</para>
</listitem>
<listitem>
- <para>Creation of flash and disk images for booting directly on the
+ <para>Creation of flash and disk images of any one of a number of
+ types (jffs2, ext2.gz, squashfs etc) for booting directly on the
target device;</para>
</listitem>
@@ -89,29 +104,36 @@
</listitem>
<listitem>
- <para>Automatically creating all of the cross-compiling tools you'll
+ <para>Automatic building 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>
+ computer and not for the target and used to help during the build
+ process;</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>
+ <para>The rest of this chapter assumes you have mastered the Getting Start
+ guides to OpenEmbedded (see the OpenEmbedded web site for details), and
+ therefore have an appropriately configured setup and that you have managed
+ to actually 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>
+
+ <para>You'll also not a lot of reference to variables that define specific
+ directories or change the behaviour of some part of the build process. You
+ should refer to <xref linkend="chapter_recipes" /> for full details on
+ these variables.</para>
</section>
<section id="usage_workspace" xreflabel="workspace">
<title>Work space</title>
- <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
+ <para>Let's start out by taking a look at a typically working area. Note
+ that this may not be exactly what 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
@@ -240,43 +262,59 @@ tmp/deploy/images</screen></para>
</varlistentry>
</variablelist>
- <para></para>
+ <para>When people refer to the <emphasis>"tmp directory"</emphasis> this
+ is the directory them are talking about.</para>
+ <para>To perform a complete rebuild from script you would usually rename
+ or delete tmp and then restart your build. I recommend keeping one old
+ version of tmp around to use for comparison if something goes wrong with
+ your new build. For example:<screen>%> rm -fr tmp.OLD
+$> mv tmp tmp.OLD
+%> bitbake bootstrap-image</screen></para>
+
<section id="usage_workdir" xreflabel="work directory">
- <title>work directory</title>
+ <title>work directory (tmp/work)</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>The work directory is where all source code is unpacked into,
+ where source is configured, compiled and packaged. In other words this
+ is where all the action happens. Each bitbake recipe will produce a
+ corresponding sub directory in the work directory. The sub directory
+ name will contain the recipe name, version and the release number (as
+ defined by the PR variable within 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
+ <para>Here's an example of a few of the subdirectories under 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/arpwatch-2.1a15-r2</screen>You can see that the first three (of
+ several hundred) recipes here and they are for release 13 of busybox
+ 1.2.1, release 0 or libice 1.1.0.3 and release 2 of arpwatch 2.1a15.
+ It's also possible that you may just have a sub directory for your
+ targets architecture and operating system in which case these
+ directories will be in that additional subdirectory, as shown
+ here:<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
+ <para>The <emphasis role="bold">sh4-linux</emphasis> directory in the
+ above example is a combination of the target architecture (sh4) and
+ operating system (linux). This subdirectory has been added by the use of
+ one of OpenEmbedded's many features. In this case it's 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>
+ for multiple targets within the one work directory and can be enabled on
+ a per distribution basis. This feature enables the sharing of native and
+ architecture neutral packages and building for multiple targets that
+ support the same architecture but require different linux kernels (for
+ example). We'll assume multimachine isn't 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
+ <para>Using lzo 1.08 as an example we'll examine the contents of the
+ working directory 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
@@ -284,17 +322,18 @@ tmp/work/lzo-1.08-r14/image</screen></pa
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>
+ role="bold">tmp/work/lzo-1.08-r14</emphasis>, is know as the
+ <emphasis>"working directory"</emphasis> for the recipe and is specified
+ via the <emphasis role="bold">WORKDIR</emphasis> variable in bitbake.
+ You'll sometimes see recipes refer directly to <emphasis
+ role="bold">WORKDIR</emphasis> and this is the directory they are
+ referencing. The <emphasis role="bold">1.08</emphasis> is the version of
+ lzo and <emphasis role="bold">r14</emphasis> is the release number, as
+ defined by the <emphasis role="bold">PR</emphasis> variable within the
+ recipe.</para>
- <para>Under <emphasis role="bold">WORKDIR</emphasis> there are four
- directories:</para>
+ <para>Under the working directory (<emphasis
+ role="bold">WORKDIR</emphasis>) there are four subdirectories:</para>
<variablelist>
<varlistentry>
@@ -302,7 +341,8 @@ tmp/work/lzo-1.08-r14/image</screen></pa
<listitem>
<para>The temp directories contains logs and in some cases scripts
- that actually implement specific tasks.</para>
+ that actually implement specific tasks (such as a script to
+ configure or compile the source).</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
@@ -324,50 +364,60 @@ tmp/work/lzo-1.08-r14/image</screen></pa
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>
+ <emphasis>"<name>-<version>"</emphasis>. If the source
+ code extracts to somewhere else then that would need to be
+ declared in the recipe by explicitly setting the value of the
+ variable <emphasis role="bold">S</emphasis> to the appropriate
+ directory.</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>install</term>
+ <term>image</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
+ <para>The image 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 installi%s
>>> DIFF TRUNCATED @ 16K
More information about the Openembedded-commits
mailing list