[oe-commits] org.oe.documentation merge of '3437f20735d7e47c5e1b66b06048bf07a88dcb10'
Laibsch commit
openembedded-commits at lists.openembedded.org
Mon Jan 7 14:07:03 UTC 2008
merge of '3437f20735d7e47c5e1b66b06048bf07a88dcb10'
and '6eb0ce0ee03896c04704340de3de39f7b173e851'
Author: Laibsch at openembedded.org
Branch: org.openembedded.documentation
Revision: 9b35cd745d3158465f0faf0168c235f39441c6f0
ViewMTN: http://monotone.openembedded.org/revision/info/9b35cd745d3158465f0faf0168c235f39441c6f0
Files:
1
usermanual/chapters/common_use_cases.xml
usermanual/chapters/comparing.xml
usermanual/chapters/features.xml
usermanual/chapters/getting_oe.xml
usermanual/chapters/introduction.xml
usermanual/chapters/metadata.xml
usermanual/chapters/recipes.xml
usermanual/chapters/usage.xml
usermanual/reference/class_image.xml
usermanual/usermanual.xml
Diffs:
#
# mt diff -r3437f20735d7e47c5e1b66b06048bf07a88dcb10 -r9b35cd745d3158465f0faf0168c235f39441c6f0
#
#
# no changes
#
#
# mt diff -r6eb0ce0ee03896c04704340de3de39f7b173e851 -r9b35cd745d3158465f0faf0168c235f39441c6f0
#
#
#
# add_file "usermanual/chapters/common_use_cases.xml"
# content [32bb970eceefb30ea6e80c97ab925dd6550e826a]
#
# add_file "usermanual/chapters/comparing.xml"
# content [d6d7a822ab80ea08f54460b57fcf1aa69e4d5c37]
#
# add_file "usermanual/chapters/features.xml"
# content [a2b1b3fa0f8b456695547e99d86f68854bf0cdc4]
#
# add_file "usermanual/chapters/getting_oe.xml"
# content [9856be39cd0698ca685279f09f42c4619854bebd]
#
# add_file "usermanual/chapters/introduction.xml"
# content [838ca921135fcee2dbe61f58c3ed82e515600f02]
#
# add_file "usermanual/chapters/metadata.xml"
# content [df8b08181a31ab64f52c61f1b1ba0f0f2d3a0a37]
#
# patch "usermanual/chapters/recipes.xml"
# from [aeb287080cb3c1deeecf8071aa5af5f302f44f4f]
# to [c31a6738c189cdfb3c67e544fb9e2fb15ac3485e]
#
# patch "usermanual/chapters/usage.xml"
# from [701325afadf39c3f6a0ed2f0c1929d9b4814805b]
# to [1a8ec734388bacaae7ebf82c082c20685caec033]
#
# patch "usermanual/reference/class_image.xml"
# from [9f70be2bfeda405f006dc804a6db6c9107e02a4b]
# to [e1fe4007e4d41b2198a3671342711c339632f943]
#
# patch "usermanual/usermanual.xml"
# from [9d79c5f01b273eddb6799df72680d59398f05e2f]
# to [9aed7e37d4ae612d24b2e556c28ef151fb082d27]
#
============================================================
--- usermanual/chapters/common_use_cases.xml 32bb970eceefb30ea6e80c97ab925dd6550e826a
+++ usermanual/chapters/common_use_cases.xml 32bb970eceefb30ea6e80c97ab925dd6550e826a
@@ -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>
============================================================
--- usermanual/chapters/comparing.xml d6d7a822ab80ea08f54460b57fcf1aa69e4d5c37
+++ usermanual/chapters/comparing.xml d6d7a822ab80ea08f54460b57fcf1aa69e4d5c37
@@ -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,
+ %s
>>> DIFF TRUNCATED @ 16K
More information about the Openembedded-commits
mailing list