diff options
| -rw-r--r-- | usermanual/chapters/common_use_cases.xml | 388 | ||||
| -rw-r--r-- | usermanual/chapters/comparing.xml | 51 | ||||
| -rw-r--r-- | usermanual/chapters/features.xml | 78 | ||||
| -rw-r--r-- | usermanual/chapters/getting_oe.xml | 70 | ||||
| -rw-r--r-- | usermanual/chapters/introduction.xml | 72 | ||||
| -rw-r--r-- | usermanual/chapters/metadata.xml | 129 | ||||
| -rw-r--r-- | usermanual/chapters/recipes.xml | 386 | ||||
| -rw-r--r-- | usermanual/chapters/usage.xml | 63 | ||||
| -rw-r--r-- | usermanual/reference/class_image.xml | 95 | ||||
| -rw-r--r-- | usermanual/usermanual.xml | 788 |
10 files changed, 1213 insertions, 907 deletions
diff --git a/usermanual/chapters/common_use_cases.xml b/usermanual/chapters/common_use_cases.xml new file mode 100644 index 0000000000..c504b3bba3 --- /dev/null +++ b/usermanual/chapters/common_use_cases.xml @@ -0,0 +1,388 @@ +<?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> + + <para>However, the correct way to resolve this is to provide explicit + mapping using ASSUME_SHLIBS variable. For example, for the libraries + above (partial): + <screen> +ASSUME_SHLIBS = "libqtopia2.so.2:qtopia2_2.4 libc.so.6:libc" +</screen> + The format is shlib_file_name:package[_version]. If a version is specified it will be + used as the minimal (>=) version for the dependency.</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..9238e4f29d --- /dev/null +++ b/usermanual/chapters/getting_oe.xml @@ -0,0 +1,70 @@ +<?xml version="1.0" encoding="UTF-8"?> +<chapter id="chapter_getting_oe"> + <title>Getting Started</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 (end 2007) + <application>BitBake</application> 1.8.latest 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>Once BitBake and OpenEmbedded are set up and configured, one can build + software and images like this: +<screen> +bitbake <recipe_name> +</screen> + </para> + + <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/chapters/recipes.xml b/usermanual/chapters/recipes.xml index 8f9754b0a7..c1ca456fa0 100644 --- a/usermanual/chapters/recipes.xml +++ b/usermanual/chapters/recipes.xml @@ -1079,11 +1079,11 @@ ${FILE_DIRNAME}/${PN}:${FILE_DIRNAME}/files:${FILE_DIRNAME}"</screen></para> it's a useful example because it doesn't depend on any of the helper classes which can sometime hide a lot of what is going on.</para> - <para>First we'll create the helloworld.c file and a readme file. We'll - place this in the files subdirectory, which is one of the places that is - searched for file:// URI's:<screen>mkdir packages/helloworld -mkdir pacakges/helloworld/files -cat > pacakges/helloworld/files/helloworld.c + <para>First we'll create the myhelloworld.c file and a readme file. + We'll place this in the files subdirectory, which is one of the places + that is searched for file:// URI's:<screen>mkdir packages/myhelloworld +mkdir packages/myhelloworld/files +cat > packages/myhelloworld/files/myhelloworld.c #include <stdio.h> int main(int argc, char** argv) @@ -1092,11 +1092,11 @@ int main(int argc, char** argv) return 0; } ^D -cat > pacakges/helloworld/files/README.txt -Readme file for helloworld. +cat > packages/myhelloworld/files/README.txt +Readme file for myhelloworld. ^D</screen></para> - <para>Now we have a directory for our recipe, packages/helloworld, and + <para>Now we have a directory for our recipe, packages/myhelloworld, and we've created a files subdirectory in there to store our local files. We've created two local files, the C source code for our helloworld program and a readme file. Now we need to create the bitbake @@ -1104,11 +1104,11 @@ Readme file for helloworld. <para>First we need the header section, which will contain a description of the package and the release number. We'll leave the other header - variables out for now:<screen>DESCRIPTION = "Hello world program" + variables out for now:<screen>DESCRIPTION = "My hello world program" PR = "r0"</screen></para> <para>Next we need to tell it which files we want to be included in the - recipe, which we do via file:// URI's and the SRC_URI variable:<screen>SRC_URI = "file://helloworld.c \ + recipe, which we do via file:// URI's and the SRC_URI variable:<screen>SRC_URI = "file://myhelloworld.c \ file://README.txt"</screen></para> <para>Note the use of the \ to continue a file and the file of file:// @@ -1119,7 +1119,7 @@ PR = "r0"</screen></para> the recipe and providing the appropriate commands:</para> <para><screen>do_compile() { - ${CC} ${CFLAGS} ${LDFLAGS} ${WORKDIR}/helloworld.c -o helloworld + ${CC} ${CFLAGS} ${LDFLAGS} ${WORKDIR}/myhelloworld.c -o myhelloworld }</screen></para> <para>Note the:</para> @@ -1146,9 +1146,9 @@ PR = "r0"</screen></para> the destination directory so that it'll be packaged up correctly. This is done via the install task, so we need to define a do_install function in the recipe to describe how to install the package:<screen>do_install() { - install -m 0755 -d ${D}${bindir} ${D}${docdir}/helloworld - install -m 0644 ${S}/helloworld ${D}${bindir} - install -m 0644 ${WORKDIR}/README.txt ${D}${docdir}/helloworld + install -m 0755 -d ${D}${bindir} ${D}${docdir}/myhelloworld + install -m 0644 ${S}/myhelloworld ${D}${bindir} + install -m 0644 ${WORKDIR}/README.txt ${D}${docdir}/myhelloworld }</screen></para> <para>Note the:</para> @@ -1186,120 +1186,120 @@ PR = "r0"</screen></para> </itemizedlist> <para>We'll consider this release 0 and version 0.1 of a program called - helloworld. So we'll name the recipe helloworld_0.1.bb:<screen>cat > packages/helloworld/helloworld_0.1.bb + helloworld. So we'll name the recipe myhelloworld_0.1.bb:<screen>cat > packages/myhelloworld/myhelloworld_0.1.bb DESCRIPTION = "Hello world program" PR = "r0" -SRC_URI = "file://helloworld.c \ +SRC_URI = "file://myhelloworld.c \ file://README.txt" do_compile() { - ${CC} ${CFLAGS} ${LDFLAGS} ${WORKDIR}/helloworld.c -o helloworld + ${CC} ${CFLAGS} ${LDFLAGS} ${WORKDIR}/myhelloworld.c -o myhelloworld } do_install() { - install -m 0755 -d ${D}${bindir} ${D}${docdir}/helloworld - install -m 0644 ${S}/helloworld ${D}${bindir} - install -m 0644 ${WORKDIR}/README.txt ${D}${docdir}/helloworld + install -m 0755 -d ${D}${bindir} ${D}${docdir}/myhelloworld + install -m 0644 ${S}/myhelloworld ${D}${bindir} + install -m 0644 ${WORKDIR}/README.txt ${D}${docdir}/myhelloworld } ^D</screen>Now we are ready to build our package, hopefully it'll all work - since it's such a simple example:<screen>~/oe%> bitbake -b packages/helloworld/helloworld_0.1.bb -NOTE: package helloworld-0.1: started -NOTE: package helloworld-0.1-r0: task do_fetch: started -NOTE: package helloworld-0.1-r0: task do_fetch: completed -NOTE: package helloworld-0.1-r0: task do_unpack: started -NOTE: Unpacking /home/lenehan/devel/oe/local-packages/helloworld/files/helloworld.c to /home/lenehan/devel/oe/build/titan-glibc-25/tmp/work/helloworld-0.1-r0/ -NOTE: Unpacking /home/lenehan/devel/oe/local-packages/helloworld/files/README.txt to /home/lenehan/devel/oe/build/titan-glibc-25/tmp/work/helloworld-0.1-r0/ -NOTE: package helloworld-0.1-r0: task do_unpack: completed -NOTE: package helloworld-0.1-r0: task do_patch: started -NOTE: package helloworld-0.1-r0: task do_patch: completed -NOTE: package helloworld-0.1-r0: task do_configure: started -NOTE: package helloworld-0.1-r0: task do_configure: completed -NOTE: package helloworld-0.1-r0: task do_compile: started -NOTE: package helloworld-0.1-r0: task do_compile: completed -NOTE: package helloworld-0.1-r0: task do_install: started -NOTE: package helloworld-0.1-r0: task do_install: completed -NOTE: package helloworld-0.1-r0: task do_package: started -NOTE: package helloworld-0.1-r0: task do_package: completed -NOTE: package helloworld-0.1-r0: task do_package_write: started -NOTE: Not creating empty archive for helloworld-dbg-0.1-r0 -Packaged contents of helloworld into /home/lenehan/devel/oe/build/titan-glibc-25/tmp/deploy/ipk/sh4/helloworld_0.1-r0_sh4.ipk -Packaged contents of helloworld-doc into /home/lenehan/devel/oe/build/titan-glibc-25/tmp/deploy/ipk/sh4/helloworld-doc_0.1-r0_sh4.ipk -NOTE: Not creating empty archive for helloworld-dev-0.1-r0 -NOTE: Not creating empty archive for helloworld-locale-0.1-r0 -NOTE: package helloworld-0.1-r0: task do_package_write: completed -NOTE: package helloworld-0.1-r0: task do_populate_staging: started -NOTE: package helloworld-0.1-r0: task do_populate_staging: completed -NOTE: package helloworld-0.1-r0: task do_build: started -NOTE: package helloworld-0.1-r0: task do_build: completed -NOTE: package helloworld-0.1: completed + since it's such a simple example:<screen>~/oe%> bitbake -b packages/myhelloworld/myhelloworld_0.1.bb +NOTE: package myhelloworld-0.1: started +NOTE: package myhelloworld-0.1-r0: task do_fetch: started +NOTE: package myhelloworld-0.1-r0: task do_fetch: completed +NOTE: package myhelloworld-0.1-r0: task do_unpack: started +NOTE: Unpacking /home/lenehan/devel/oe/local-packages/myhelloworld/files/helloworld.c to /home/lenehan/devel/oe/build/titan-glibc-25/tmp/work/myhelloworld-0.1-r0/ +NOTE: Unpacking /home/lenehan/devel/oe/local-packages/myhelloworld/files/README.txt to /home/lenehan/devel/oe/build/titan-glibc-25/tmp/work/myhelloworld-0.1-r0/ +NOTE: package myhelloworld-0.1-r0: task do_unpack: completed +NOTE: package myhelloworld-0.1-r0: task do_patch: started +NOTE: package myhelloworld-0.1-r0: task do_patch: completed +NOTE: package myhelloworld-0.1-r0: task do_configure: started +NOTE: package myhelloworld-0.1-r0: task do_configure: completed +NOTE: package myhelloworld-0.1-r0: task do_compile: started +NOTE: package myhelloworld-0.1-r0: task do_compile: completed +NOTE: package myhelloworld-0.1-r0: task do_install: started +NOTE: package myhelloworld-0.1-r0: task do_install: completed +NOTE: package myhelloworld-0.1-r0: task do_package: started +NOTE: package myhelloworld-0.1-r0: task do_package: completed +NOTE: package myhelloworld-0.1-r0: task do_package_write: started +NOTE: Not creating empty archive for myhelloworld-dbg-0.1-r0 +Packaged contents of myhelloworld into /home/lenehan/devel/oe/build/titan-glibc-25/tmp/deploy/ipk/sh4/myhelloworld_0.1-r0_sh4.ipk +Packaged contents of myhelloworld-doc into /home/lenehan/devel/oe/build/titan-glibc-25/tmp/deploy/ipk/sh4/myhelloworld-doc_0.1-r0_sh4.ipk +NOTE: Not creating empty archive for myhelloworld-dev-0.1-r0 +NOTE: Not creating empty archive for myhelloworld-locale-0.1-r0 +NOTE: package myhelloworld-0.1-r0: task do_package_write: completed +NOTE: package myhelloworld-0.1-r0: task do_populate_staging: started +NOTE: package myhelloworld-0.1-r0: task do_populate_staging: completed +NOTE: package myhelloworld-0.1-r0: task do_build: started +NOTE: package myhelloworld-0.1-r0: task do_build: completed +NOTE: package myhelloworld-0.1: completed Build statistics: Attempted builds: 1 ~/oe%></screen></para> <para>The package was successfully built, the output consists of two .ipkg files, which are ready to be installed on the target. One contains - the binary and the other contains the readme file:<screen>~/oe%> ls -l tmp/deploy/ipk/*/helloworld* --rw-r--r-- 1 lenehan lenehan 3040 Jan 12 14:46 tmp/deploy/ipk/sh4/helloworld_0.1-r0_sh4.ipk --rw-r--r-- 1 lenehan lenehan 768 Jan 12 14:46 tmp/deploy/ipk/sh4/helloworld-doc_0.1-r0_sh4.ipk + the binary and the other contains the readme file:<screen>~/oe%> ls -l tmp/deploy/ipk/*/myhelloworld* +-rw-r--r-- 1 lenehan lenehan 3040 Jan 12 14:46 tmp/deploy/ipk/sh4/myhelloworld_0.1-r0_sh4.ipk +-rw-r--r-- 1 lenehan lenehan 768 Jan 12 14:46 tmp/deploy/ipk/sh4/myhelloworld-doc_0.1-r0_sh4.ipk ~/oe%></screen></para> <para>It's worthwhile looking at the working directory to see where - various files ended up:<screen>~/oe%> find tmp/work/helloworld-0.1-r0 -tmp/work/helloworld-0.1-r0 -tmp/work/helloworld-0.1-r0/helloworld-0.1 -tmp/work/helloworld-0.1-r0/helloworld-0.1/patches -tmp/work/helloworld-0.1-r0/helloworld-0.1/helloworld -tmp/work/helloworld-0.1-r0/temp -tmp/work/helloworld-0.1-r0/temp/run.do_configure.21840 -tmp/work/helloworld-0.1-r0/temp/log.do_stage.21840 -tmp/work/helloworld-0.1-r0/temp/log.do_install.21840 -tmp/work/helloworld-0.1-r0/temp/log.do_compile.21840 -tmp/work/helloworld-0.1-r0/temp/run.do_stage.21840 -tmp/work/helloworld-0.1-r0/temp/log.do_configure.21840 -tmp/work/helloworld-0.1-r0/temp/run.do_install.21840 -tmp/work/helloworld-0.1-r0/temp/run.do_compile.21840 -tmp/work/helloworld-0.1-r0/install -tmp/work/helloworld-0.1-r0/install/helloworld-locale -tmp/work/helloworld-0.1-r0/install/helloworld-dbg -tmp/work/helloworld-0.1-r0/install/helloworld-dev -tmp/work/helloworld-0.1-r0/install/helloworld-doc -tmp/work/helloworld-0.1-r0/install/helloworld-doc/usr -tmp/work/helloworld-0.1-r0/install/helloworld-doc/usr/share -tmp/work/helloworld-0.1-r0/install/helloworld-doc/usr/share/doc -tmp/work/helloworld-0.1-r0/install/helloworld-doc/usr/share/doc/helloworld -tmp/work/helloworld-0.1-r0/install/helloworld-doc/usr/share/doc/helloworld/README.txt -tmp/work/helloworld-0.1-r0/install/helloworld -tmp/work/helloworld-0.1-r0/install/helloworld/usr -tmp/work/helloworld-0.1-r0/install/helloworld/usr/bin -tmp/work/helloworld-0.1-r0/install/helloworld/usr/bin/helloworld -tmp/work/helloworld-0.1-r0/image -tmp/work/helloworld-0.1-r0/image/usr -tmp/work/helloworld-0.1-r0/image/usr/bin -tmp/work/helloworld-0.1-r0/image/usr/share -tmp/work/helloworld-0.1-r0/image/usr/share/doc -tmp/work/helloworld-0.1-r0/image/usr/share/doc/helloworld -tmp/work/helloworld-0.1-r0/helloworld.c -tmp/work/helloworld-0.1-r0/README.txt + various files ended up:<screen>~/oe%> find tmp/work/myhelloworld-0.1-r0 +tmp/work/myhelloworld-0.1-r0 +tmp/work/myhelloworld-0.1-r0/myhelloworld-0.1 +tmp/work/myhelloworld-0.1-r0/myhelloworld-0.1/patches +tmp/work/myhelloworld-0.1-r0/myhelloworld-0.1/myhelloworld +tmp/work/myhelloworld-0.1-r0/temp +tmp/work/myhelloworld-0.1-r0/temp/run.do_configure.21840 +tmp/work/myhelloworld-0.1-r0/temp/log.do_stage.21840 +tmp/work/myhelloworld-0.1-r0/temp/log.do_install.21840 +tmp/work/myhelloworld-0.1-r0/temp/log.do_compile.21840 +tmp/work/myhelloworld-0.1-r0/temp/run.do_stage.21840 +tmp/work/myhelloworld-0.1-r0/temp/log.do_configure.21840 +tmp/work/myhelloworld-0.1-r0/temp/run.do_install.21840 +tmp/work/myhelloworld-0.1-r0/temp/run.do_compile.21840 +tmp/work/myhelloworld-0.1-r0/install +tmp/work/myhelloworld-0.1-r0/install/myhelloworld-locale +tmp/work/myhelloworld-0.1-r0/install/myhelloworld-dbg +tmp/work/myhelloworld-0.1-r0/install/myhelloworld-dev +tmp/work/myhelloworld-0.1-r0/install/myhelloworld-doc +tmp/work/myhelloworld-0.1-r0/install/myhelloworld-doc/usr +tmp/work/myhelloworld-0.1-r0/install/myhelloworld-doc/usr/share +tmp/work/myhelloworld-0.1-r0/install/myhelloworld-doc/usr/share/doc +tmp/work/myhelloworld-0.1-r0/install/myhelloworld-doc/usr/share/doc/myhelloworld +tmp/work/myhelloworld-0.1-r0/install/myhelloworld-doc/usr/share/doc/myhelloworld/README.txt +tmp/work/myhelloworld-0.1-r0/install/myhelloworld +tmp/work/myhelloworld-0.1-r0/install/myhelloworld/usr +tmp/work/myhelloworld-0.1-r0/install/myhelloworld/usr/bin +tmp/work/myhelloworld-0.1-r0/install/myhelloworld/usr/bin/myhelloworld +tmp/work/myhelloworld-0.1-r0/image +tmp/work/myhelloworld-0.1-r0/image/usr +tmp/work/myhelloworld-0.1-r0/image/usr/bin +tmp/work/myhelloworld-0.1-r0/image/usr/share +tmp/work/myhelloworld-0.1-r0/image/usr/share/doc +tmp/work/myhelloworld-0.1-r0/image/usr/share/doc/myhelloworld +tmp/work/myhelloworld-0.1-r0/myhelloworld.c +tmp/work/myhelloworld-0.1-r0/README.txt ~/oe%></screen>Things to note here are:</para> <itemizedlist> <listitem> <para>The two source files are in <emphasis - role="bold">tmp/work/helloworld-0.1-r0</emphasis>, which is the + role="bold">tmp/work/myhelloworld-0.1-r0</emphasis>, which is the working directory as specified via the <emphasis role="bold">${WORKDIR}</emphasis> variable;</para> </listitem> <listitem> <para>There's logs of the various tasks in <emphasis - role="bold">tmp/work/helloworld-0.1-r0/temp</emphasis> which you can - look at for more details on what was done in each task;</para> + role="bold">tmp/work/myhelloworld-0.1-r0/temp</emphasis> which you + can look at for more details on what was done in each task;</para> </listitem> <listitem> <para>There's an image directory at <emphasis - role="bold">tmp/work/helloworld-0.1-r0/image</emphasis> which + role="bold">tmp/work/myhelloworld-0.1-r0/image</emphasis> which contains just the directories that were to be packaged up. This is actually the destination directory, as specified via the <emphasis role="bold">${D}</emphasis> variable. The two files that we @@ -1311,28 +1311,28 @@ tmp/work/helloworld-0.1-r0/README.txt <listitem> <para>The program was actually compiled in the <emphasis - role="bold">tmp/work/helloworld-0.1-r0/helloworld-0.1</emphasis> + role="bold">tmp/work/myhelloworld-0.1-r0/myhelloworld-0.1</emphasis> directory, this is the source directory as specified via the <emphasis role="bold">${S}</emphasis> variable.</para> </listitem> <listitem> <para>There's an install directory at <emphasis - role="bold">tmp/work/helloworld-0.1-r0/install</emphasis> which + role="bold">tmp/work/myhelloworld-0.1-r0/install</emphasis> which contains the packages that were being generated and the files that - go in the package. So we can see that the helloworld-doc package + go in the package. So we can see that the myhelloworld-doc package contains the single file <emphasis - role="bold">/usr/share/doc/helloworld/README.txt</emphasis>, the - helloworld package contains the single file <emphasis - role="bold">/usr/bin/helloworld</emphasis> and the -dev, -dbg and + role="bold">/usr/share/doc/myhelloworld/README.txt</emphasis>, the + myhelloworld package contains the single file <emphasis + role="bold">/usr/bin/myhelloworld</emphasis> and the -dev, -dbg and -local packages are all empty.</para> </listitem> </itemizedlist> <para>At this stage it's good to verify that we really did produce a binary for the target and not for our host system. We can check that - with the file command:<screen>~/oe%> file tmp/work/helloworld-0.1-r0/install/helloworld/usr/bin/helloworld -tmp/work/helloworld-0.1-r0/install/helloworld/usr/bin/helloworld: ELF 32-bit LSB executable, Hitachi SH, version 1 (SYSV), for GNU/Linux 2.4.0, dynamically linked (uses shared libs), for GNU/Linux 2.4.0, not stripped + with the file command:<screen>~/oe%> file tmp/work/myhelloworld-0.1-r0/install/myhelloworld/usr/bin/myhelloworld +tmp/work/myhelloworld-0.1-r0/install/myhelloworld/usr/bin/myhelloworld: ELF 32-bit LSB executable, Hitachi SH, version 1 (SYSV), for GNU/Linux 2.4.0, dynamically linked (uses shared libs), for GNU/Linux 2.4.0, not stripped ~/oe%> file /bin/ls /bin/ls: ELF 64-bit LSB executable, AMD x86-64, version 1 (SYSV), for GNU/Linux 2.4.0, dynamically linked (uses shared libs), for GNU/Linux 2.4.0, stripped ~/oe%></screen>This shows us that the helloworld program is for an SH @@ -2370,42 +2370,192 @@ addtask unpack_extra after do_unpack before do_patch</screen></para> <section id="recipes_classes" xreflabel="classes"> <title>Classes: The separation of common functionality</title> - <para>This section is to be completed.</para> + <para>Often a certain pattern is followed in more than one recipe, or + maybe some complex python based functionality is required to achieve the + desired end result. This is achieved through the use of classes, which can + be found in the classes subdirectory at the top-level of on OE + checkout.</para> + + <para>Being aware of the available classes and understanding their + functionality is important because classes:</para> <itemizedlist> <listitem> - <para>What are classes</para> + <para>Save developers time being performing actions that they would + otherwise need to perform themselves;</para> </listitem> <listitem> - <para>How you use classes</para> + <para>Perform a lot of actions in the background making a lot of + recipes difficult to understand unless you are aware of classes and + how they work;</para> </listitem> <listitem> - <para>Some example - autotools, update-r.d, distutils</para> + <para>A lot of detail on how things work can be learnt for looking at + how classes are implement.</para> </listitem> </itemizedlist> + + <para>A class is used via the inherit method. The following is an example + for the <emphasis>curl</emphasis> recipe showing that it uses three + classes:<screen>inherit autotools pkgconfig binconfig</screen>In this case + it is utilising the services of three separate classes:</para> + + <variablelist> + <varlistentry> + <term>autotools</term> + + <listitem> + <para>The <xref linkend="autotools_class" /> is used by programs + that use the GNU configuration tools and takes care of the + configuration and compilation of the software;</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>pkgconfig</term> + + <listitem> + <para>The <xref linkend="pkgconfig_class" /> is used to stage the + <emphasis>.pc</emphasis> files which are used by the <emphasis + role="bold">pkg-config</emphasis> program to provide information + about the package to other software that wants to link to this + software;</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>binconfig</term> + + <listitem> + <para>The <xref linkend="binconfig_class" /> is used to stage the + <emphasis><name>-config</emphasis> files which are used to + provide information about the package to other software that wants + to link to this software;</para> + </listitem> + </varlistentry> + </variablelist> + + <para>Each class is implemented via the file in the <emphasis + role="bold">classes</emphasis> subdirectory named <emphasis + role="bold"><classname>.bbclass</emphasis> and these can be examined + for further details on a particular class, although sometimes it's not + easy to understand everything that's happening. Many of the classes are + covered in detail in various sections in this user manual.</para> </section> <section id="recipes_staging" xreflabel="staging"> <title>Staging: Making includes and libraries available for building</title> - <para>This section is to be completed:</para> + <para>Staging is the process of making files, such as include files and + libraries, available for use by other recipes. This is different to + installing because installing is about making things available for + packaging and then eventually for use on the target device. Staging on the + other hand is about making things available on the host system for use by + building later applications.</para> + + <para>Taking bzip2 as an example you can see that it stages a header file + and it's library files:<screen>do_stage () { + install -m 0644 bzlib.h ${STAGING_INCDIR}/ + oe_libinstall -a -so libbz2 ${STAGING_LIBDIR} +}</screen></para> - <itemizedlist> - <listitem> - <para>Why we have staging</para> - </listitem> + <para>The <emphasis>oe_libinstall</emphasis> method used in the bzip2 + recipe is described in the <xref linkend="recipes_methods" /> section, and + it takes care of installing libraries (into the staging area in this + case). The staging variables are automatically defined to the correct + staging location, in this case the main staging variables are used:</para> - <listitem> - <para>How staging is used</para> - </listitem> + <variablelist> + <varlistentry> + <term>STAGING_INCDIR</term> - <listitem> - <para>What does and does not need to be staged</para> - </listitem> - </itemizedlist> + <listitem> + <para>The directory into which staged headers files should be + installed. This is the equivalent of the standard <emphasis + role="bold">/usr/include</emphasis> directory.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>STAGING_LIBDIR</term> + + <listitem> + <para>The directory into which staged library files should be + installed. This is the equivalent of the standard <emphasis + role="bold">/usr/lib</emphasis> directory.</para> + </listitem> + </varlistentry> + </variablelist> + + <para>Additional staging related variables are covered in the <xref + linkend="directories_staging" /> section in <xref + linkend="chapter_reference" />.</para> + + <para>Looking in the staging area under tmp you can see the result of the + bzip2 recipes staging task:<screen>%> find tmp/staging -name '*bzlib*' +tmp/staging/sh4-linux/include/bzlib.h +%> find tmp/staging -name '*libbz*' +tmp/staging/sh4-linux/lib/libbz2.so +tmp/staging/sh4-linux/lib/libbz2.so.1.0 +tmp/staging/sh4-linux/lib/libbz2.so.1 +tmp/staging/sh4-linux/lib/libbz2.so.1.0.2 +tmp/staging/sh4-linux/lib/libbz2.a</screen></para> + + <para>As well as being used during the stage task the staging related + variables are used when building other packages. Looking at the gnupg + recipe we see two bzip2 related items:<screen>DEPENDS = "zlib <emphasis + role="bold">bzip2</emphasis>" +... +EXTRA_OECONF = "--disable-ldap \ + --with-zlib=${STAGING_LIBDIR}/.. \ + <emphasis role="bold">--with-bzip2=${STAGING_LIBDIR}/..</emphasis> \ + --disable-selinux-support" +</screen></para> + + <para>Bzip2 is referred to in two places in the recipe:</para> + + <variablelist> + <varlistentry> + <term>DEPENDS</term> + + <listitem> + <para>Remember that <emphasis role="bold">DEPENDS</emphasis> defines + the list of build time dependencies. In this case the staged headers + and libraries from bzip2 are required to build gnupg, and therefore + we need to make sure the bzip2 recipe has run and staging the + headers and libraries. By adding the <emphasis + role="bold">DEPENDS</emphasis> on bzip2 this ensures that this + happens.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><emphasis role="bold">EXTRA_OECONF</emphasis></term> + + <listitem> + <para>This variable is used by the <xref + linkend="autotools_class" /> to provide options to the configure + script of the package. In the gnupg case it needs to be told where + the bzip2 headers and libraries files are, and this is done via the + <emphasis>--with-bzip2</emphasis> option. In this case it needs to + the directory which include the lib and include subdirectories. + Since OE doesn't define a variable for one level above the include + and lib directories <emphasis role="bold">..</emphasis> is used to + indicate one directory up. Without this gnupg would search the host + system headers and libraries instead of those we have provided in + the staging area for the target.</para> + </listitem> + </varlistentry> + </variablelist> + + <para>Remember that staging is used to make things, such as headers and + libraries, available to used by other recipes later on. While header and + libraries are the most common item requiring staging other items such as + the pkgconfig files need to be staged as well, while for native packages + the binaries also need to be staged.</para> </section> <section id="recipes_autoconf" xreflabel="about autoconf"> @@ -3557,4 +3707,4 @@ which find <para></para> </section> -</chapter> +</chapter>
\ No newline at end of file diff --git a/usermanual/chapters/usage.xml b/usermanual/chapters/usage.xml index 4c58fc700a..9fe20faf8c 100644 --- a/usermanual/chapters/usage.xml +++ b/usermanual/chapters/usage.xml @@ -1,6 +1,6 @@ <?xml version="1.0" encoding="UTF-8"?> <chapter id="chapter_using_bitbake_and_oe"> - <title>Using bitbake and OE</title> + <title>Using bitbake and OpenEmbedded</title> <section id="usage_introduction" xreflabel="introduction"> <title>Introduction</title> @@ -129,6 +129,67 @@ these variables.</para> </section> + <section id="usage_configuration" xreflabel="configuration"> + <title>Configuration</title> + + <para>Configuration covers basic items such as where the various files can + be found and where output should be placed to more specific items such as + which hardware is being targeted and what features you want to have + included in the final image. The main configuration areas in OE + are:</para> + + <variablelist> + <varlistentry> + <term>conf/machine</term> + + <listitem> + <para>This directory contains machine configuration information. For + each physical device a configuration file is required in this + directory that describes various aspects of the device, such as + architecture of the device, hardware features of the device (does it + have usb? a keyboard? etc), the type of flash or disk images needed + for the device, the serial console settings (if any) etc. If you are + adding support for a new device you would need to create a machine + configuration in this directory for the device.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>conf/distro</term> + + <listitem> + <para>This directory contains distribution related files. A + distribution decides how various activities are handled in the final + image, such as how networking configured, if usb devices will be + supported, what packaging system is used, which libc is used + etc.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>conf/bitbake.conf</term> + + <listitem> + <para>This is the main bitbake configuration file. This file is not + to be edited but it is useful to look at it since it declares a + larger number of the predefined variables used by OE and controls a + lot of the base functionality provided by OE.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>conf/local.conf</term> + + <listitem> + <para>This is the end-user specific configuration. This file needs + to be copied and edited and is used to specify the various working + directories, the machine to build for and the distribution to + use.</para> + </listitem> + </varlistentry> + </variablelist> + </section> + <section id="usage_workspace" xreflabel="workspace"> <title>Work space</title> diff --git a/usermanual/reference/class_image.xml b/usermanual/reference/class_image.xml index 7d203f888c..b591e9aae2 100644 --- a/usermanual/reference/class_image.xml +++ b/usermanual/reference/class_image.xml @@ -56,8 +56,8 @@ </listitem> <listitem> - <para>Configures the ipkg feed information in the root filesystem for - the <command>FEED_URIS</command>;</para> + <para>Configures the ipkg feed information in the root filesystem + (using <command>FEED_URIS</command> and <command>FEED_DEPLOYDIR_BASE_URI</command>);</para> </listitem> <listitem> @@ -190,6 +190,20 @@ <para>Default: <command>""</command></para> </listitem> </varlistentry> + + <varlistentry> + <term>FEED_DEPLOYDIR_BASE_URI</term> + + <listitem> + <para>If set, configures local testing feeds using OE package deploy dir + contents. The value is URL, corresponding to the ipk deploy dir.</para> + + <para>Example: <command>FEED_DEPLOYDIR_BASE_URI = + "http://192.168.2.200/bogofeed/"</command></para> + + <para>Default: <command>""</command></para> + </listitem> + </varlistentry> </variablelist> <section> @@ -274,18 +288,71 @@ IMAGE_DEVICE_TABLES = "files/device_table-minimal.txt files/device_table_add-sci </section> <section> - <title>Package feeds (feed_uris)</title> - - <para>Package feeds are used by the ipkg command to determine where to - retrieve updates and new packages from.</para> - - <para>Multiple feeds are supported. Each feed provides a feed name and the - URL which will contain the packages. The following example shows the - addition of two feeds, one called <emphasis>base</emphasis> and one called - <emphasis>updates</emphasis>:</para> - - <para><screen>FEED_URIS += " \ + <title>Package feeds</title> + + <para>"Package feed", or feed for short, is a term used by <command>ipkg</command> + package manager, commonly used in embedded systems, to name a package repository + holding packages. Structurally, a feed is a directory - local, or on HTTP of FTP server, - + holding packages and package descriptor file, named <command>Packages</command> or + <command>Packages.gz</command> if compressed. Multiple feeds are supported.</para> + + <para>OpenEmbedded has support to pre-configure feeds within generated images, + so once image is installed on a device, user can immediately install new software, + without the need to manually edit config files. There are several ways to pre-configure + feed support, described below.</para> + + <section> + <title>Method 1: Using existing feed</title> + <para>If you already have the feed(s) set up and available via specific URL, they + can be added to the image using FEED_URIS variable: +<screen>FEED_URIS = " \ base##http://oe.example.com/releases/${DISTRO_VERSION}/feed/base \ - updates##http://oe.example.com/releases/${DISTRO_VERSION}/feed/updates"</screen></para> + updates##http://oe.example.com/releases/${DISTRO_VERSION}/feed/updates"</screen> + + FEED_URIS contains list of feed descriptors, separated by spaces, per + OE conventions. Each descriptor consists of feed name and feed URL, + joined with "##". Feed name is an identifier used by ipkg to distinguish + among the feeds. It can be arbitrary, just useful to the users to understood + which feed is used for one or another action.</para> + </section> + + <section> + <title>Method 2: Using OE deploy directory as a feed (development only)</title> + <para>OE internally maintains a feed-like collection of directories to create + images from packages. This package deployment directory however has structure internal to OE + and subject to change without notice. Thus, using it as feed directly is not recommended + (distributions which ignored this recommendation are known to have their feeds broken when + OE upgraded its internal mechanisms).</para> + <para>However, using deploy directory as feed directly may be beneficial during + development and testing, as it allows developers to easily install newly built packages + without many manual actions. To facilitate this, OE offers a way to prepare feed configs + for using deploy dir as such. To start with this, you first need to configure local + HTTP server to export a package deployment directory via HTTP. + Suppose you will export it via URL "http://192.168.2.200/bogofeed" (where 192.168.2.200 is the address + which will be reachable from the device). Add the following to your local.conf: +<screen> +FEED_DEPLOYDIR_BASE_URI = "http://192.168.2.200/bogofeed" +</screen> + Now you need to setup local HTTP server to actually export that directory. For Apache it can be: +<screen> +<![CDATA[ +Alias /bogofeed ${DEPLOY_DIR} + +<Directory ${DEPLOY_DIR}> + Options Indexes FollowSymLinks + Order deny,allow + Allow from 192.168.2.0/24 +</Directory> +]]> +</screen> + Replace ${DEPLOY_DIR} with the full path of deploy directory (last components of its path will be + <command>deploy/ipk</command>).</para> + <para>Now, every image built will automatically contain feed configs + for the deploy directory (as of time of writing, deploy directory is internally structured with + per-arch subdirectories; so, there several feed configs are being generated, one for each subdirectory). + </para> + + </section> + </section> </section>
\ No newline at end of file diff --git a/usermanual/usermanual.xml b/usermanual/usermanual.xml index 06ccf59573..84dac27baf 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-gettingoe; - <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-metadata; - <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> |