aboutsummaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/usermanual/chapters/common_use_cases.xml241
1 files changed, 3 insertions, 238 deletions
diff --git a/docs/usermanual/chapters/common_use_cases.xml b/docs/usermanual/chapters/common_use_cases.xml
index ef81b95fa9..8202dda64b 100644
--- a/docs/usermanual/chapters/common_use_cases.xml
+++ b/docs/usermanual/chapters/common_use_cases.xml
@@ -183,245 +183,10 @@ inherit image
<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>
+ <para>TODO: You want to use external-toolchain. Setting PREFERRED_PROVIDER
+ for the toolchain to that + environment variables + toolchain layout. Please
+ someone write the documentation for that.</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 assumed. <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>Sourceable 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 variables were
- 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/recipes/*/*.bb ${LOCALDIR}/recipes/*/*.bb"
-BBFILE_COLLECTIONS = "upstream local"
-BBFILE_PATTERN_upstream = "^${OEDIR}/openembedded/recipes/"
-BBFILE_PATTERN_local = "^${LOCALDIR}/recipes/"
-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 generated packages. It is inspecting binaries and
- libraries and uses the <emphasis><link linkend="shlibs">shlibs</link>
- </emphasis> system to do add dependencies for the linked libraries,
- however in this case it was not able to find packages providing these
- libraries as they were prebuilt.
- </para>
-
- <para>One way to resolve this problem is to provide an explicit mapping
- using the ASSUME_SHLIBS variable in a config file <filename>local.conf</filename>.
- 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">