usermanual:

    Write something on how to setup this beast. Cross reference it
    to the BitBake collections section in the special feature
    chapter.

1 files changed, 132 insertions, 3 deletions

diff --git a/usermanual/usermanual.xml b/usermanual/usermanual.xml
index d5f99ba568..802814051a 100644
--- a/usermanual/usermanual.xml
+++ b/usermanual/usermanual.xml
@@ -198,6 +198,16 @@ packages are automatically added to the <command>RDEPENDS</command>. As a packag
 they will be added automatically.</para>
             <remark>NOTE: This does not apply to plugins used by the program.</remark>
         </section>
+
+        <section>
+            <title>BitBake Collections <anchor id="collections" /></title>
+            <para></para>
+        </section>
+
+        <section>
+            <title>Overrides <anchor id="overrides" /></title>
+            <para></para>
+        </section>
     </chapter>
 
     <chapter>
@@ -243,6 +253,7 @@ 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
@@ -258,18 +269,136 @@ arm-linux-objdump
                 <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.</para>
+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> subdirectory.</para>
                 <screen>
 <command>ls</command> $PRE_BUILT
 include
 lib
+qt2
 </screen>
             </section>
 
             <section>
                 <title>Setting up OpenEmbedded</title>
-                <para>Setting up OpenEmbedded
+                <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 sourcable 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 similiar 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"
+IPKG_ARCHS = "all arm armv4 armv5te iwmmxt xscale ${MACHINE}"
+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>
@@ -290,7 +419,7 @@ NOTE: Couldn't find shared library provider for libm.so.6
 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.</para>
+needed library and use ${BOOTSTRAP_EXTRA_RDEPENDS} to make sure this package is installed when creating images.</para>
             </section>
 
         </section>