aboutsummaryrefslogtreecommitdiffstats
path: root/usermanual/usermanual.xml
diff options
context:
space:
mode:
Diffstat (limited to 'usermanual/usermanual.xml')
-rw-r--r--usermanual/usermanual.xml790
1 files changed, 15 insertions, 775 deletions
diff --git a/usermanual/usermanual.xml b/usermanual/usermanual.xml
index 06ccf59573..9555a65220 100644
--- a/usermanual/usermanual.xml
+++ b/usermanual/usermanual.xml
@@ -5,6 +5,12 @@
-->
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
+<!ENTITY chapter-introduction SYSTEM "chapters/introduction.xml">
+<!ENTITY chapter-metadata SYSTEM "chapters/metadata.xml">
+<!ENTITY chapter-gettingoe SYSTEM "chapters/getting_oe.xml">
+<!ENTITY chapter-features SYSTEM "chapters/features.xml">
+<!ENTITY chapter-commonusecases SYSTEM "chapters/common_use_cases.xml">
+<!ENTITY chapter-comparing SYSTEM "chapters/comparing.xml">
<!ENTITY chapter-usage SYSTEM "chapters/usage.xml">
<!ENTITY chapter-recipes SYSTEM "chapters/recipes.xml">
<!ENTITY class-autotools SYSTEM "reference/class_autotools.xml">
@@ -47,7 +53,6 @@
<holder>Marcin Juszkiewicz</holder>
<holder>Rolf Leggewie</holder>
-
</copyright>
<legalnotice>
@@ -59,790 +64,25 @@
</legalnotice>
</bookinfo>
- <chapter id="chapter_introduction">
- <title>Introduction</title>
-
- <section id="intro_overview">
- <title>Overview</title>
-
- <para>Like any build tool (make, ant, jam), the OpenEmbedded build tool
- BitBake controls how to build things and the build dependencies. But
- unlike single project tools like <command>make</command> it is not based
- on one makefile or a closed set of inter-dependent makefiles, but
- collects and manages an open set of largely independent build
- descriptions (package recipes) and builds them in proper order.</para>
-
- <para>To be more precise: <ulink
- url="http://www.openembedded.org"><application>OpenEmbedded</application></ulink>
- is a set of metadata used to cross-compile, package and install software
- packages. <application>OpenEmbedded</application> is being used to build
- and maintain a number of embedded Linux distributions, including
- OpenZaurus, Angström, Familiar and SlugOS.</para>
-
- <para>The primary use-case of <application>OpenEmbedded</application>
- are: <itemizedlist>
- <listitem>
- <para>Handle cross-compilation.</para>
- </listitem>
-
- <listitem>
- <para>Handle inter-package dependencies</para>
- </listitem>
-
- <listitem>
- <para>Must be able to emit packages (tar, rpm, ipk)</para>
- </listitem>
-
- <listitem>
- <para>Must be able to create images and feeds from packages</para>
- </listitem>
-
- <listitem>
- <para>Must be highly configurable to support many machines,
- distribution and architectures.</para>
- </listitem>
-
- <listitem>
- <para>Writing of metadata must be easy and reusable</para>
- </listitem>
- </itemizedlist></para>
-
- <para>Together with <ulink
- url="http://bitbake.berlios.de/manual"><application>BitBake</application></ulink>,
- OpenEmbedded satisfies all these and many more. Flexibility and power
- have always been the priorities.</para>
- </section>
-
- <section id="intro_history">
- <title>History</title>
-
- <para>OpenEmbedded was invented and founded by the creators of the
- OpenZaurus project. At this time the project had pushed
- <emphasis>buildroot</emphasis> to its limits. It supported the creation
- of <emphasis>ipk</emphasis> packages, feeds and images and had support
- for more than one machine. But it was impossible to use different
- patches, files for different architectures, machines or distributions.
- To overcome this shortcoming OpenEmbedded was created.</para>
-
- <para>After a few months other projects started using OpenEmbedded and
- contributing back. On 7 December 2004 Chris Larson split the project
- into two parts: BitBake, a generic task executor and OpenEmbedded, the
- metadata for BitBake.</para>
- </section>
- </chapter>
+ <!-- Main chapters-->
- <chapter id="chapter_metadata">
- <title>Metadata</title>
-
- <section id="metadata_file_layout">
- <title>File Layout</title>
-
- <para>OpenEmbedded has six directories three of them hold
- <application>BitBake</application> metadata.</para>
-
- <para>The <emphasis>conf</emphasis> directory is holding the
- bitbake.conf, machine and distribution configuration. bitbake.conf is
- read when <application>BitBake</application> is started and this will
- include among others a local.conf the machine and distribution
- configuration files. These files will be searched in the
- <command>BBPATH</command> environment variable.</para>
-
- <para><emphasis>classes</emphasis> is the directory holding
- <application>BitBake</application> bbclass. These classes can be
- inherited by the <application>BitBake</application> files. BitBake
- automatically inherits the base.bbclass on every parsed file.
- <command>BBPATH</command> is used to find the class.</para>
-
- <para>In <emphasis>packages</emphasis> the
- <application>BitBake</application> files are stored. For each task or
- application we have a directory. These directories store the real
- <application>BitBake</application> files. They are the ones ending with
- <emphasis>.bb</emphasis>. And for each application and version we have
- one.</para>
- </section>
-
- <section id="metadata_syntax">
- <title>Syntax</title>
-
- <para>OpenEmbedded has files ending with <emphasis>.conf</emphasis>,
- <emphasis>.inc</emphasis>, <emphasis>.bb</emphasis>
- and<emphasis>.bbclass</emphasis>. The syntax and semantic of these files
- are best described in the <ulink
- url="http://bitbake.berlios.de/manual"><application>BitBake</application>
- manual</ulink>.</para>
- </section>
-
- <section id="metadata_classes">
- <title>Classes</title>
-
- <para>OpenEmbedded provides special <application>BitBake</application>
- classes to ease compiling, packaging and other things. FIXME.</para>
- </section>
-
- <section id="metadata_writing_data">
- <title>Writing Meta Data (Adding packages)</title>
-
- <para>This page will guide you trough the effort of writing a .bb file
- or <emphasis>recipe</emphasis> in BitBake speak.</para>
-
- <para>Let's start with the easy stuff, like the package description,
- license, etc: <screen>
-DESCRIPTION = "My first application, a really cool app containing lots of foo and bar"
-LICENSE = "GPLv2"
-HOMEPAGE = "http://www.host.com/foo/"
- </screen> The description and license fields are mandatory, so
- better check them twice.</para>
-
- <para>The next step is to specify what the package needs to build and
- run, the so called <emphasis>dependencies</emphasis>: <screen>
-DEPENDS = "gtk+"
-RDEPENDS = "cool-ttf-fonts"
- </screen> The package needs gtk+ to build ('DEPENDS') and
- requires the 'cool-ttf-fonts' package to run ('RDEPENDS'). OE will add
- run-time dependencies on libraries on its own via the so called
- <emphasis>shlibs</emphasis>-code, but you need to specify everything
- other by yourself, which in this case is the 'cool-ttf-fonts'
- package.</para>
-
- <para>After entering all this OE will know what to build before trying
- to build your application, but it doesn't know where to get it yet. So
- let's add the source location: <screen>
-SRC_URI = "http://www.host.com/foo/files/${P}.tar.bz2;md5sum=yoursum"
- </screen> This will tell the fetcher to where to download the
- sources from and it will check the integrity using md5sum if you
- provided the appropriate <emphasis>yoursum</emphasis>. You can make one
- by doing <screen>md5sum foo-1.9.tar.bz2</screen> and replacing
- <emphasis>yoursum</emphasis> with the md5sum on your screen. A typical
- md5sum will look like this: <screen>a6434b0fc8a54c3dec3d6875bf3be8mtn </screen>Notice
- the <emphasis>${P}</emphasis> variable, that one holds the package name,
- <emphasis>${PN}</emphasis> in BitBake speak and the package version,
- <emphasis>${PV}</emphasis> in BitBake speak. It's a short way of writing
- <emphasis>${PN}-${PV}</emphasis>. Using this notation means you can copy
- the recipe when a new version is released without having to alter the
- contents. You do need to check if everything is still correct, because
- new versions mean new bugs.</para>
-
- <para>Before we can move to the actual building we need to find out
- which build system the package is using. If we're lucky, we see a
- <emphasis>configure</emphasis> file in the build tree this is an
- indicator that we can <emphasis>inherit autotools</emphasis> if we see a
- <emphasis>.pro</emphasis> file, it might be qmake, which needs
- <emphasis>inherit qmake</emphasis>. Virtually all gtk apps use
- autotools: <screen>
-inherit autotools pkgconfig
- </screen> We are in luck! The package is a well-behaved
- application using autotools and pkgconfig to configure and build it
- self.</para>
-
- <para>Lets start the build: <screen>
-<command>bitbake</command> foo
- </screen> Depending on what you have built before and the
- speed of your computer this can take a few seconds to a few hours, so be
- prepared.</para>
-
- <para>.... some time goes by .....</para>
-
- <para>Your screen should now have something like this on it: <screen>
-NOTE: package foo-1.9-r0: task do_build: completed
-NOTE: package foo-1.9: completed
-NOTE: build 200605052219: completed
- </screen></para>
-
- <para>All looks well, but wait, let's scroll up: <screen>
-NOTE: the following files where installed but not shipped:
- /usr/weirdpath/importantfile.foo
- </screen> OE has a standard list of paths which need to be
- included, but it can't know everything, so we have to tell OE to include
- that file as well: <screen>
-FILES_${PN} += "/usr/weirdpath/importantfile.foo"
- </screen> It's important to use <emphasis>+=</emphasis> so it
- will get appended to the standard file-list, not replace the standard
- one.</para>
- </section>
- </chapter>
+ &chapter-introduction;
- <chapter id="chapter_getting_oe">
- <title>Getting OpenEmbedded</title>
-
- <section id="gettingoe_getting_bitbake">
- <title>Getting <application>BitBake</application></title>
-
- <para>The required version of <application>BitBake</application> is
- changing rapidly. At the time of writing (30th of June 2007)
- <application>BitBake</application> 1.8.2 was required.</para>
-
- <para>A safe method is to get the <application>BitBake</application> from a
- stable Subversion branch (those with an even minor number). <screen>
-<command>svn</command> co http://svn.berlios.de/svnroot/repos/bitbake/branches/bitbake-1.8
-...
-A bitbake-1.8/classes/base.bbclass
-U bitbake-1.8
-At revision 827.
- </screen> <application>BitBake</application> is checked out now;
- this completes the first and most critical dependency of OpenEmbedded.
- Issuing <command>svn</command> <command>up</command> in the
- <emphasis>bitbake-1.8</emphasis> directory will update
- <application>BitBake</application> to the latest stable version, but
- generally it is a good idea to stick with a specific known working
- version of <application>BitBake</application> until OpenEmbedded asks
- you to upgrade.</para>
- </section>
-
- <section id="gettingoe_getting_oe">
- <title>Getting OpenEmbedded</title>
-
- <para>The OpenEmbedded metadata has a high rate of development, so it's
- a good idea to stay up to date. You'll need monotone 0.28 to get the
- metadata and stay up to date. Monotone is available in most
- distributions and has binaries at <ulink
- url="http://venge.net/monotone/">Monotone homepage</ulink>.</para>
-
- <para>Next step is getting snapshot of database. <screen>
-wget http://openembedded.org/snapshots/OE.mtn.bz2 http://openembedded.org/snapshots/OE.mtn.bz2.md5
-</screen> Or if you have monotone 0.30 or later: <screen>
-wget http://www.openembedded.org/snapshots/OE-this-is-for-mtn-0.30.mtn.bz2
-wget http://www.openembedded.org/snapshots/OE-this-is-for-mtn-0.30.mtn.bz2.md5
-</screen> Then verify integrity of snapshot by checking md5sum. <screen>
-md5sum -c OE.mtn.bz2.md5sum
-</screen> Then unpack database. <screen>
-bunzip OE.mtn.bz2
-</screen> Finally checkout the development branch. <screen>
-mtn --db=OE.mtn co -b org.openembedded.dev
-</screen></para>
- </section>
-
- <section id="gettingoe_configuring_oe">
- <title>Configuring OpenEmbedded</title>
-
- <para>This section is a stub, help us by expanding it</para>
- </section>
-
- <section id="gettingoe_building_software">
- <title>Building Software</title>
-
- <para>This section is a stub, help us by expanding it</para>
- </section>
- </chapter>
+ &chapter-metadata;
- <chapter id="chapter_special_features">
- <title>Special features</title>
-
- <section id="special_debian_naming">
- <title>Debian package naming <anchor id="debian" /></title>
-
- <screen>INHERIT += "debian"</screen>
-
- <para>Placing the above line into your
- <emphasis>${DISTRO}.conf</emphasis> or <emphasis>local.conf</emphasis>
- will trigger renaming of packages if they only ship one library. Imagine
- a package where the package name (<command>PN</command>) is foo and this
- packages ships a file named <command>libfoo.so.1.2.3</command>. Now this
- package will be renamed to <command>libfoo1</command> to follow the
- Debian package naming policy.</para>
- </section>
-
- <section id="special_shlibs">
- <title>Shared Library handling (shlibs) <anchor id="shlibs" /></title>
-
- <para>Run-time Dependencies (<command>RDEPENDS</command>) will be added
- when packaging the software. They should only contain the minimal
- dependencies to run the program. OpenEmbedded will analyze each packaged
- binary and search for <command>SO_NEEDED</command> libraries. The
- libraries are absolutely required by the program then OpenEmbedded is
- searching for packages that installs these libraries. these packages are
- automatically added to the <command>RDEPENDS</command>. As a packager
- you don't need to worry about shared libraries anymore they will be
- added automatically.</para>
-
- <remark>NOTE: This does not apply to plug-ins used by the
- program.</remark>
- </section>
-
- <section id="special_bitbake_collections">
- <title>BitBake Collections <anchor id="collections" /></title>
-
- <para>This section is a stub, help us by expanding it</para>
-
- <para><screen>
-BBFILES := "${OEDIR}/openembedded/packages/*/*.bb ${LOCALDIR}/packages/*/*.bb"
-BBFILE_COLLECTIONS = "upstream local"
-BBFILE_PATTERN_upstream = "^${OEDIR}/openembedded/packages/"
-BBFILE_PATTERN_local = "^${LOCALDIR}/packages/"
-BBFILE_PRIORITY_upstream = "5"
-BBFILE_PRIORITY_local = "10"
-</screen></para>
- </section>
-
- <section id="special_task_base">
- <title>Task-base <anchor id="task-base" /></title>
-
- <para>Task-base is new way of creating basic root filesystems. Instead
- of having each machine setting a ton of duplicate variables, this allow
- a machine to specify its features and <command>task-base</command>
- builds it a customised package based on what the machine needs along
- with what the distro supports.</para>
-
- <para>To illustrate, the distro config file can say: <screen>
-DISTRO_FEATURES = "nfs smbfs ipsec wifi ppp alsa bluetooth ext2 irda pcmcia usbgadget usbhost"
-</screen> and the machine config: <screen>
-MACHINE_FEATURES = "kernel26 apm alsa pcmcia bluetooth irda usbgadget"
-</screen> and the resulting <command>task-base</command> would support pcmcia
- but not usbhost.</para>
-
- <para>Task-base details exactly which options are either machine or
- distro settings (or need to be in both). Machine options are meant to
- reflect capabilities of the machine, distro options list things
- distribution maintainers might want to add or remove from their distros
- images.</para>
- </section>
-
- <section id="special_overrides">
- <title>Overrides <anchor id="overrides" /></title>
-
- <para>This section is a stub, help us by expanding it</para>
- </section>
- </chapter>
+ &chapter-gettingoe;
- <chapter id="chapter_common_use_cases">
- <title>Common Use-cases/tasks</title>
-
- <section id="commonuse_new_distro">
- <title>Creating a new Distribution</title>
-
- <para>Creating a new distribution is not complicated, however we urge you to try existing distributions first, because it's also very easy to do wrong. The config need to be
- created in /conf/distro directory. So what has to be inside? <itemizedlist>
- <listitem>
- <para><command>DISTRO_VERSION</command> so users will know which
- version of distribution they use.</para>
- </listitem>
-
- <listitem>
- <para><command>DISTRO_TYPE</command> (release/debug) variable is
- used in some recipes to enable/disable some features - for example
- kernel output on screen for "debug" builds.</para>
- </listitem>
-
- <listitem>
- <para>Type of libc used: will it be glibc
- (<command>TARGET_OS</command> = "linux") or uclibc
- (<command>TARGET_OS</command> = "linux-uclibc")?</para>
- </listitem>
-
- <listitem>
- <para>Toolchain versions - for example gcc 3.4.4 based distro will
- have: <screen>
-PREFERRED_PROVIDERS += " virtual/${TARGET_PREFIX}gcc-initial:gcc-cross-initial"
-PREFERRED_PROVIDERS += " virtual/${TARGET_PREFIX}gcc:gcc-cross"
-PREFERRED_PROVIDERS += " virtual/${TARGET_PREFIX}g++:gcc-cross"
-
-PREFERRED_VERSION_binutils = "2.16"
-PREFERRED_VERSION_binutils-cross = "2.16"
-
-PREFERRED_VERSION_gcc = "3.4.4"
-PREFERRED_VERSION_gcc-cross = "3.4.4"
-PREFERRED_VERSION_gcc-initial-cross = "3.4.4"
- </screen></para>
- </listitem>
-
- <listitem>
- <para><command>DISTRO_FEATURES</command> which describe which
- features distro has. More about it in <link
- linkend="task-base">task-base</link> section.</para>
- </listitem>
-
- <listitem>
- <para>Versions of kernels used for supported devices: <screen>
-PREFERRED_VERSION_linux-omap1_omap5912osk ?= "2.6.18+git"
-PREFERRED_VERSION_linux-openzaurus ?= "2.6.17"
- </screen></para>
- </listitem>
-
- <listitem>
- <para>To get more stable build it is good to make use of
- sane-srcdates.inc file which contain working SRCDATE for many of
- floating recipes. <screen>
-require conf/distro/include/sane-srcdates.inc
- </screen> It also should have global <command>SRCDATE</command>
- value set (format is ISO date: YYYYMMDD): <screen>
-SRCDATE = "20061014"
- </screen></para>
- </listitem>
- </itemizedlist></para>
- </section>
-
- <section id="commonuse_new_machine">
- <title>Adding a new Machine</title>
-
- <para>To be able to build for device OpenEmbedded have to know it, so
- machine config file need to be written. All those configs are stored in
- /conf/machine/ directory.</para>
-
- <para>As usual some variables are required: <itemizedlist>
- <listitem>
- <para><command>TARGET_ARCH</command> which describe which CPU
- architecture does machine use.</para>
- </listitem>
-
- <listitem>
- <para><command>MACHINE_FEATURES</command> which describe which
- features device has. More about it in <link
- linkend="task-base">task-base</link> section.</para>
- </listitem>
-
- <listitem>
- <para><command>PREFERRED_PROVIDER_virtual/kernel</command> has to
- point into proper kernel recipe for this machine.</para>
- </listitem>
- </itemizedlist></para>
-
- <para>Next kernel recipe needs to be added.</para>
- </section>
-
- <section id="commonuse_new_package">
- <title>Adding a new Package</title>
-
- <para>This section is a stub, help us by expanding it</para>
- </section>
-
- <section id="commonuse_new_image">
- <title>Creating your own image</title>
-
- <para>Creating own image is easy - only few variables needs to be set:
- <itemizedlist>
- <listitem>
- <para><command>IMAGE_BASENAME</command> to give a name for your own
- image</para>
- </listitem>
-
- <listitem>
- <para><command>PACKAGE_INSTALL</command> to give a list of packages to
- install into the image</para>
- </listitem>
-
- <listitem>
- <para><command>RDEPENDS</command> to give a list of recipes which
- are needed to be built to create this image</para>
- </listitem>
-
- <listitem>
- <para><command>IMAGE_LINGUAS</command> is an optional list of
- languages which has to be installed into the image</para>
- </listitem>
- </itemizedlist> Then adding of the <emphasis>image</emphasis> class
- use: <screen>
-inherit image
-</screen> And the image recipe is ready for usage.</para>
- </section>
-
- <section id="commonuse_prebuilt_toolchain">
- <title>Using a prebuilt toolchain to create your packages</title>
-
- <para>It might be necessary to integrate a prebuilt toolchain and other
- libraries but still be use OpenEmbedded to build packages. One of many
- approaches is shown and discussed here.</para>
-
- <section>
- <title>The toolchain</title>
-
- <para>We assume the toolchain provides a C and C++ compiler, an
- assembler and other tools to build packages. The list below shows a
- gcc 3.4.4 toolchain for ARM architectures using glibc. We assume that
- the toolchain is in your <command>PATH</command>.</para>
-
- <screen>
-<command>ls</command> pre-built/cross/bin
-
-arm-linux-g++
-arm-linux-ld
-arm-linux-ranlib
-arm-linux-ar
-arm-linux-g77
-arm-linux-readelf
-arm-linux-as
-arm-linux-gcc
-arm-linux-gcc-3.4.4
-arm-linux-c++
-arm-linux-size
-arm-linux-c++filt
-arm-linux-nm
-arm-linux-strings
-arm-linux-cpp
-arm-linux-objcopy
-arm-linux-strip
-arm-linux-objdump
-</screen>
- </section>
-
- <section>
- <title>The prebuilt libraries</title>
-
- <para>We need the header files and the libraries itself. The following
- directory layout is assume. <command>PRE_BUILT</command> has two
- subdirectories one is called <emphasis>include</emphasis> and holds
- the header files and the other directory is called
- <emphasis>lib</emphasis> and holds the shared and static libraries.
- Additionally a Qt2 directory is present having a
- <emphasis>include</emphasis> and <emphasis>lib</emphasis>
- sub-directory.</para>
-
- <screen>
-<command>ls</command> $PRE_BUILT
-include
-lib
-qt2
-</screen>
- </section>
-
- <section>
- <title>Setting up OpenEmbedded</title>
-
- <para>OpenEmbedded will be setup here. We assume that your machine and
- distribution is not part of OpenEmbedded and they will be created
- ad-hoc in the <emphasis>local.conf</emphasis> file. You will need to
- have <application>BitBake</application> and a current OpenEmbedded
- version available.</para>
-
- <section>
- <title>Sourcable script</title>
-
- <para>To ease the usage of OpenEmbedded we start by creating a
- source-able script. This is actually a small variation from the
- already seen script. We will name it
- <emphasis>build_source</emphasis> and you will need to source
- it.</para>
-
- <screen>
-BITBAKE_PATH=/where/is/bitbake/bin
-TOOLCHAIN=/where/is/toolchain/bin
-HOST_TOOLS=/where/is/hosttools/bin
-export PRE_BUILT=/where/is/pre-built
-
-export PATH=$BITBAKE_PATH:$TOOLCHAIN:$HOST_TOOLS:$PATH
-export OEDIR=$PWD
-export LOCALDIR=$PWD/secret-isv
- </screen>
-
- <para>Use <command>source build_source</command> to source the
- script, use <command>env</command> to check that the variable where
- exported.</para>
- </section>
-
- <section>
- <title>Creating the local.conf</title>
-
- <para>We will configure OpenEmbedded now, it is very similar to what
- we have done above.</para>
-
- <screen>
-DL_DIR = "${OEDIR}/sources"
-BBFILES := "${OEDIR}/openembedded/packages/*/*.bb ${LOCALDIR}/packages/*/*.bb"
-BBFILE_COLLECTIONS = "upstream local"
-BBFILE_PATTERN_upstream = "^${OEDIR}/openembedded/packages/"
-BBFILE_PATTERN_local = "^${LOCALDIR}/packages/"
-BBFILE_PRIORITY_upstream = "5"
-BBFILE_PRIORITY_local = "10"
-BBMASK = ""
- </screen>
-
- <para>${OEDIR}/openembedded will be a upstream release of
- OpenEmbedded. Above we have assumed it is in the current working
- directory. Additionally we have a ${LOCALDIR}, we combine these two
- directories as a special <link linkend="collections">BitBake
- Collection</link>.</para>
-
- <screen>
-#
-# machine stuff
-#
-MACHINE = "secret-killer"
-PACKAGE_EXTRA_ARCHS = "armv4 armv4t armv5te iwmmxt xscale""
-TARGET_CC_ARCH = "-mcpu=xscale -mtune=iwmmxt"
-TARGET_ARCH = "arm"
-PACKAGE_ARCH="xscale"
- </screen>
-
- <para>We tell OpenEmbedded that we build for the ARM platform and
- optimize for xscale and iwmmxt.</para>
-
- <screen>
-INHERIT += " package_ipk debian"
-TARGET_OS = "linux"
-TARGET_FPU = "soft"
-DISTRO = "secret-disro"
-DISTRO_NAME = "secret-distro"
-DISTRO_VERSION = "x.y.z"
-DISTRO_TYPE = "release"
- </screen>
-
- <para>Create a distribution ad-hoc as well. We tell OpenEmbedded
- that we build for linux and glibc using soft float as fpu. If your
- toolchain is a uclibc toolchain you will need to set
- <command>TARGET_OS</command> to linux-uclibc.</para>
-
- <screen>
-export CC = "${CCACHE}arm-linux-gcc-3.4.4 ${HOST_CC_ARCH}"
-export CXX = "${CCACHE}arm-linux-g++ ${HOST_CC_ARCH}"
-export CPP = "arm-linux-gcc-3.4.4 -E"
-export LD = "arm-linux-ld"
-export AR = "arm-linux-ar"
-export AS = "arm-linux-as"
-export RANLIB = "arm-linux-ranlib"
-export STRIP = "arm-linux-strip"
- </screen>
-
- <para>The above variables replace the ones from
- <emphasis>bitbake.conf</emphasis>. This will make OpenEmbedded use
- the prebuilt toolchain.</para>
-
- <screen>
-#
-# point OE to the lib and include directory
-#
-TARGET_CPPFLAGS_append = " -I${PRE_BUILT}/include "
-TARGET_LDFLAGS_prepend = " -L${PRE_BUILT}/qt2/lib -L${PRE_BUILT}/lib \
--Wl,-rpath-link,${PRE_BUILT}/lib -Wl,-rpath-link,${PRE_BUILT}/qt2/lib "
-
-# special to Qt/Qtopia
-QTDIR = "${PRE_BUILT}/qt2"
-QPEDIR = "${PRE_BUILT}"
-palmtopdir = "/opt/Qtopia"
-palmqtdir = "/opt/Qtopia"
- </screen>
-
- <para>We will add the <command>PRE_BUILT</command> libraries to the
- include and library paths. And the same is done for the special
- version of Qt we have in your <command>PRE_BUILT</command>
- directory.</para>
-
- <screen>
-ASSUME_PROVIDED += " virtual/${TARGET_PREFIX}gcc "
-ASSUME_PROVIDED += " virtual/libc "
-ASSUME_PROVIDED += " virtual/qte "
-ASSUME_PROVIDED += " virtual/libqpe "
-ASSUME_PROVIDED += " libqpe-opie "
- </screen>
-
- <para>Now we have told <application>BitBake</application> that the C
- library, compiler and Qtopia is already provided. These lines will
- avoid building binutils, gcc initial, glibc, gcc.</para>
-
- <screen>
-<command>source</command> build_source
-<command>bitbake</command> your-killer-app
- </screen>
-
- <para>You should be able to create the packages you want to using
- the prebuilt toolchain now.</para>
- </section>
- </section>
-
- <section>
- <title>Useful hints</title>
-
- <para>If you have more prebuilt libraries you need to add additional
- <command>ASSUME_PROVIDED</command> lines to your
- <emphasis>local.conf</emphasis>. Using <command>bitbake -vvv
- PACKAGE</command> you can easily see the package names you could
- <command>ASSUME_PROVIDED</command> if you have some prebuilt.</para>
- </section>
-
- <section>
- <title>Issues with this approach</title>
-
- <screen>
-NOTE: Couldn't find shared library provider for libqtopia.so.1
-NOTE: Couldn't find shared library provider for libqtopia2.so.2
-NOTE: Couldn't find shared library provider for libqpe.so.1
-NOTE: Couldn't find shared library provider for libpthread.so.0
-NOTE: Couldn't find shared library provider for libstdc++.so.6
-NOTE: Couldn't find shared library provider for libqte.so.2
-NOTE: Couldn't find shared library provider for libgcc_s.so.1
-NOTE: Couldn't find shared library provider for libc.so.6
-NOTE: Couldn't find shared library provider for libm.so.6
-</screen>
-
- <para>OpenEmbedded tries to automatically add run-time dependencies
- (RDEPENDS) to the package. It uses the <emphasis><link
- linkend="shlibs">shlibs</link></emphasis> system to do add them, in
- this case it was not able to find packages providing these libraries
- as they are prebuilt. This means they will not be added to the
- RDEPENDS of the just created package. The result can be fatal. If you
- use OpenEmbedded to create images you will end up with a image without
- a libc being installed. This will lead to a fatal failure. To
- workaround this issue you could create a package for the metadata to
- install every needed library and use ${BOOTSTRAP_EXTRA_RDEPENDS} to
- make sure this package is installed when creating images.</para>
- </section>
- </section>
-
- <section id="commonuse_new_package_format">
- <title>Using a new package format</title>
-
- <para>This section is a stub, help us by expanding it</para>
- </section>
- </chapter>
+ &chapter-features;
- <chapter id="chapter_comparing">
- <title>Comparing</title>
-
- <section id="comparing_buildroot">
- <title>buildroot</title>
-
- <para>Writing of <application>BitBake</application> recipes is more easy
- and more intuitive than writing Makefiles while providing higher
- flexibility. This allows you to tweak specific recipes for your very
- special needs and to add new recipes very fast. You can build
- toolchains, Software Distribution Kits (SDKs), complete Distributions or
- just single packages. The flexibility of OpenEmbedded allows you to
- reuse the once written recipes for many different purposes. OpenEmbedded
- provides everything buildroot will be able to provide. But in contrast
- to buildroot OpenEmbedded will allow you to achieve what you really want
- to achieve. You can add new package formats, new filesystems, new output
- formats easily. OpenEmbedded will suit your need.</para>
- </section>
-
- <section id="comparing_crosstool">
- <title>crosstool</title>
-
- <para>Crosstool allows to create toolchains for you. It can only create
- the initial toolchain for you. It will not compile other needed
- libraries or applications for you, it will not be able to track
- dependencies or to package them properly. OpenEmbedded supports all
- configurations crosstool supports. You can start to create toolchains
- with OpenEmbedded, then as your needs grow create a more complete SDK
- from already present base libraries and applications and if you
- recognize you need to have packages for the target you have them almost
- built already.</para>
- </section>
-
- <section id="comparing_handmade">
- <title>handmade</title>
-
- <para>Cross-compilation is a tough business. It is not that
- cross-compiling is hard itself but many people misuse the buildsystem
- they use to build their software. This will lead to a variety of issues
- you can run into. This can be failing tests on configuration because of
- executing cross compiled binaries or crashes at run-time due wrong sizes
- of basic types. When utilizing OpenEmbedded you avoid searching for
- patches at many different places and will be able to get things done
- more quickly. <application>OpenEmbedded</application> allows you to
- choose from a pool of ready to use software packages.</para>
-
- <para>OpenEmbedded will create complete flashable images using different
- output formats and filesystems. This allows you to create complete and
- specialized distributions easily.</para>
- </section>
- </chapter>
+ &chapter-commonusecases;
- <!-- Bitbake usage chapter -->
+ &chapter-comparing;
&chapter-usage;
- <!-- Bitbake recipies chapter -->
-
&chapter-recipes;
- <!-- Reference manual. Sorted alphabetically. All entries are pulled in from external files -->
+ <!-- Reference manual. Sorted alphabetically. -->
<chapter id="chapter_reference">
<title>Reference</title>
@@ -877,4 +117,4 @@ NOTE: Couldn't find shared library provider for libm.so.6
&class-update-rcd;
</chapter>
-</book>
+</book> \ No newline at end of file