diff options
Diffstat (limited to 'usermanual')
-rw-r--r-- | usermanual/chapters/common_use_cases.xml | 379 | ||||
-rw-r--r-- | usermanual/chapters/comparing.xml | 51 | ||||
-rw-r--r-- | usermanual/chapters/features.xml | 78 | ||||
-rw-r--r-- | usermanual/chapters/getting_oe.xml | 63 | ||||
-rw-r--r-- | usermanual/chapters/introduction.xml | 72 | ||||
-rw-r--r-- | usermanual/chapters/metadata.xml | 129 | ||||
-rw-r--r-- | usermanual/usermanual.xml | 790 |
7 files changed, 787 insertions, 775 deletions
diff --git a/usermanual/chapters/common_use_cases.xml b/usermanual/chapters/common_use_cases.xml new file mode 100644 index 0000000000..6526612035 --- /dev/null +++ b/usermanual/chapters/common_use_cases.xml @@ -0,0 +1,379 @@ +<?xml version="1.0" encoding="UTF-8"?> +<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>
\ No newline at end of file diff --git a/usermanual/chapters/comparing.xml b/usermanual/chapters/comparing.xml new file mode 100644 index 0000000000..1347010977 --- /dev/null +++ b/usermanual/chapters/comparing.xml @@ -0,0 +1,51 @@ +<?xml version="1.0" encoding="UTF-8"?> +<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>
\ No newline at end of file diff --git a/usermanual/chapters/features.xml b/usermanual/chapters/features.xml new file mode 100644 index 0000000000..8eecaa9ed4 --- /dev/null +++ b/usermanual/chapters/features.xml @@ -0,0 +1,78 @@ +<?xml version="1.0" encoding="UTF-8"?> +<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>
\ No newline at end of file diff --git a/usermanual/chapters/getting_oe.xml b/usermanual/chapters/getting_oe.xml new file mode 100644 index 0000000000..eb9aaf6a8f --- /dev/null +++ b/usermanual/chapters/getting_oe.xml @@ -0,0 +1,63 @@ +<?xml version="1.0" encoding="UTF-8"?> +<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>
\ No newline at end of file diff --git a/usermanual/chapters/introduction.xml b/usermanual/chapters/introduction.xml new file mode 100644 index 0000000000..b218cb596c --- /dev/null +++ b/usermanual/chapters/introduction.xml @@ -0,0 +1,72 @@ +<?xml version="1.0" encoding="UTF-8"?> +<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>
\ No newline at end of file diff --git a/usermanual/chapters/metadata.xml b/usermanual/chapters/metadata.xml new file mode 100644 index 0000000000..f4cf3bc5e6 --- /dev/null +++ b/usermanual/chapters/metadata.xml @@ -0,0 +1,129 @@ +<?xml version="1.0" encoding="UTF-8"?> +<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>
\ No newline at end of file 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 |