[oe-commits] org.oe.documentation merge of '338f5fc9c32e401a6033a90c9d909663dc527857'
pfalcon commit
openembedded-commits at lists.openembedded.org
Sat Dec 22 22:09:44 UTC 2007
merge of '338f5fc9c32e401a6033a90c9d909663dc527857'
and 'a345293c1e1d325c7d86ed713f89778c64f62735'
Author: pfalcon at openembedded.org
Branch: org.openembedded.documentation
Revision: 9b1b144cfdd27182aae561871a08f2b820a7b1e8
ViewMTN: http://monotone.openembedded.org/revision/info/9b1b144cfdd27182aae561871a08f2b820a7b1e8
Files:
1
usermanual/chapters
usermanual/reference
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_autotools.xml
usermanual/reference/class_binconfig.xml
usermanual/reference/class_distutils.xml
usermanual/reference/class_image.xml
usermanual/reference/class_pkgconfig.xml
usermanual/reference/class_rootfs_ipkg.xml
usermanual/reference/class_siteinfo.xml
usermanual/reference/class_update-alternatives.xml
usermanual/reference/class_update-rc.d.xml
usermanual/reference/dirs_install.xml
usermanual/reference/dirs_staging.xml
usermanual/reference/fakeroot.xml
usermanual/reference/image_types.xml
usermanual/reference/var_section.xml
usermanual/reference/var_src_uri.xml
usermanual/Makefile
usermanual/README
usermanual/usermanual.xml
Diffs:
#
# mt diff -r338f5fc9c32e401a6033a90c9d909663dc527857 -r9b1b144cfdd27182aae561871a08f2b820a7b1e8
#
#
#
# add_dir "usermanual/chapters"
#
# add_dir "usermanual/reference"
#
# add_file "usermanual/chapters/common_use_cases.xml"
# content [37764efb1144aa212574fd880620a2b3bbb1bc55]
#
# add_file "usermanual/chapters/comparing.xml"
# content [d6d7a822ab80ea08f54460b57fcf1aa69e4d5c37]
#
# add_file "usermanual/chapters/features.xml"
# content [a2b1b3fa0f8b456695547e99d86f68854bf0cdc4]
#
# add_file "usermanual/chapters/getting_oe.xml"
# content [985e64a58ce18ca201997c2f6626b74743979f6f]
#
# add_file "usermanual/chapters/introduction.xml"
# content [838ca921135fcee2dbe61f58c3ed82e515600f02]
#
# add_file "usermanual/chapters/metadata.xml"
# content [df8b08181a31ab64f52c61f1b1ba0f0f2d3a0a37]
#
# add_file "usermanual/chapters/recipes.xml"
# content [c31a6738c189cdfb3c67e544fb9e2fb15ac3485e]
#
# add_file "usermanual/chapters/usage.xml"
# content [1a8ec734388bacaae7ebf82c082c20685caec033]
#
# add_file "usermanual/reference/class_autotools.xml"
# content [f3484b55bc48764aa9655d08cc808243eaffd3e1]
#
# add_file "usermanual/reference/class_binconfig.xml"
# content [f17c4ab118a6d2457bee463e6935cba0deef8827]
#
# add_file "usermanual/reference/class_distutils.xml"
# content [6d80bc633e8b482e5c96cc69e9ea20062bf09d88]
#
# add_file "usermanual/reference/class_image.xml"
# content [9f70be2bfeda405f006dc804a6db6c9107e02a4b]
#
# add_file "usermanual/reference/class_pkgconfig.xml"
# content [09ca85de783b70700ce52029ceee8eb6a582ea1b]
#
# add_file "usermanual/reference/class_rootfs_ipkg.xml"
# content [0ea1173f0b68e639d0b311190c8081e55f9171b3]
#
# add_file "usermanual/reference/class_siteinfo.xml"
# content [5774268a608c6529e29ce4db7a3e7ea92272df75]
#
# add_file "usermanual/reference/class_update-alternatives.xml"
# content [fc6cdfe292e5f500883be10e9dc3845d6cd068d9]
#
# add_file "usermanual/reference/class_update-rc.d.xml"
# content [1264b3d46e520b653108cf3d02047b30b4a94e1e]
#
# add_file "usermanual/reference/dirs_install.xml"
# content [7997e68b9578aaec69b791f5bdaa65c985271155]
#
# add_file "usermanual/reference/dirs_staging.xml"
# content [91032fa7c4a2da7ca5a516e8abd15e3993a850c2]
#
# add_file "usermanual/reference/fakeroot.xml"
# content [70de811d39b0372ca3de195cb6d97b920cb44152]
#
# add_file "usermanual/reference/image_types.xml"
# content [dc2307f707c91884058966c4472059d219139229]
#
# add_file "usermanual/reference/var_section.xml"
# content [3bdb00292487e00fae6bb9418528134108456f77]
#
# add_file "usermanual/reference/var_src_uri.xml"
# content [c1ca56cb2df8a2f39982c528890fcde1e11fc452]
#
# patch "usermanual/Makefile"
# from [0a2989036c17ebde6381a8b0bcec7c82862c5119]
# to [d5c93d6ef5339503e4126a46c5f48d7e004677bd]
#
# patch "usermanual/README"
# from [49ad5c0cc8345a90ad8286fb1a901172eaa11953]
# to [430049c6902e4d89b99966ac0a0a7df28b48d2f0]
#
# patch "usermanual/usermanual.xml"
# from [ff16b9d6696e4f622e32121c803362ec111c32f8]
# to [3c92a6dae8be33141f5f739c04d54e28406681ea]
#
============================================================
--- usermanual/chapters/common_use_cases.xml 37764efb1144aa212574fd880620a2b3bbb1bc55
+++ usermanual/chapters/common_use_cases.xml 37764efb1144aa212574fd880620a2b3bbb1bc55
@@ -0,0 +1,379 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="chapter_common_use_cases">
+ <title>Common Use-cases/tasks</title>
+
+ <section id="commonuse_new_distro">
+ <title>Creating a new Distribution</title>
+
+ <para>Creating a new distribution is not complicated, however we urge you
+ to try existing distributions first, because it's also very easy to do
+ wrong. The config need to be created in /conf/distro directory. So what
+ has to be inside? <itemizedlist>
+ <listitem>
+ <para><command>DISTRO_VERSION</command> so users will know which
+ version of distribution they use.</para>
+ </listitem>
+
+ <listitem>
+ <para><command>DISTRO_TYPE</command> (release/debug) variable is
+ used in some recipes to enable/disable some features - for example
+ kernel output on screen for "debug" builds.</para>
+ </listitem>
+
+ <listitem>
+ <para>Type of libc used: will it be glibc
+ (<command>TARGET_OS</command> = "linux") or uclibc
+ (<command>TARGET_OS</command> = "linux-uclibc")?</para>
+ </listitem>
+
+ <listitem>
+ <para>Toolchain versions - for example gcc 3.4.4 based distro will
+ have: <screen>
+PREFERRED_PROVIDERS += " virtual/${TARGET_PREFIX}gcc-initial:gcc-cross-initial"
+PREFERRED_PROVIDERS += " virtual/${TARGET_PREFIX}gcc:gcc-cross"
+PREFERRED_PROVIDERS += " virtual/${TARGET_PREFIX}g++:gcc-cross"
+
+PREFERRED_VERSION_binutils = "2.16"
+PREFERRED_VERSION_binutils-cross = "2.16"
+
+PREFERRED_VERSION_gcc = "3.4.4"
+PREFERRED_VERSION_gcc-cross = "3.4.4"
+PREFERRED_VERSION_gcc-initial-cross = "3.4.4"
+ </screen></para>
+ </listitem>
+
+ <listitem>
+ <para><command>DISTRO_FEATURES</command> which describe which
+ features distro has. More about it in <link
+ linkend="task-base">task-base</link> section.</para>
+ </listitem>
+
+ <listitem>
+ <para>Versions of kernels used for supported devices: <screen>
+PREFERRED_VERSION_linux-omap1_omap5912osk ?= "2.6.18+git"
+PREFERRED_VERSION_linux-openzaurus ?= "2.6.17"
+ </screen></para>
+ </listitem>
+
+ <listitem>
+ <para>To get more stable build it is good to make use of
+ sane-srcdates.inc file which contain working SRCDATE for many of
+ floating recipes. <screen>
+require conf/distro/include/sane-srcdates.inc
+ </screen> It also should have global <command>SRCDATE</command>
+ value set (format is ISO date: YYYYMMDD): <screen>
+SRCDATE = "20061014"
+ </screen></para>
+ </listitem>
+ </itemizedlist></para>
+ </section>
+
+ <section id="commonuse_new_machine">
+ <title>Adding a new Machine</title>
+
+ <para>To be able to build for device OpenEmbedded have to know it, so
+ machine config file need to be written. All those configs are stored in
+ /conf/machine/ directory.</para>
+
+ <para>As usual some variables are required: <itemizedlist>
+ <listitem>
+ <para><command>TARGET_ARCH</command> which describe which CPU
+ architecture does machine use.</para>
+ </listitem>
+
+ <listitem>
+ <para><command>MACHINE_FEATURES</command> which describe which
+ features device has. More about it in <link
+ linkend="task-base">task-base</link> section.</para>
+ </listitem>
+
+ <listitem>
+ <para><command>PREFERRED_PROVIDER_virtual/kernel</command> has to
+ point into proper kernel recipe for this machine.</para>
+ </listitem>
+ </itemizedlist></para>
+
+ <para>Next kernel recipe needs to be added.</para>
+ </section>
+
+ <section id="commonuse_new_package">
+ <title>Adding a new Package</title>
+
+ <para>This section is a stub, help us by expanding it</para>
+ </section>
+
+ <section id="commonuse_new_image">
+ <title>Creating your own image</title>
+
+ <para>Creating own image is easy - only few variables needs to be set:
+ <itemizedlist>
+ <listitem>
+ <para><command>IMAGE_BASENAME</command> to give a name for your own
+ image</para>
+ </listitem>
+
+ <listitem>
+ <para><command>PACKAGE_INSTALL</command> to give a list of packages
+ to install into the image</para>
+ </listitem>
+
+ <listitem>
+ <para><command>RDEPENDS</command> to give a list of recipes which
+ are needed to be built to create this image</para>
+ </listitem>
+
+ <listitem>
+ <para><command>IMAGE_LINGUAS</command> is an optional list of
+ languages which has to be installed into the image</para>
+ </listitem>
+ </itemizedlist> Then adding of the <emphasis>image</emphasis> class use:
+ <screen>
+inherit image
+</screen> And the image recipe is ready for usage.</para>
+ </section>
+
+ <section id="commonuse_prebuilt_toolchain">
+ <title>Using a prebuilt toolchain to create your packages</title>
+
+ <para>It might be necessary to integrate a prebuilt toolchain and other
+ libraries but still be use OpenEmbedded to build packages. One of many
+ approaches is shown and discussed here.</para>
+
+ <section>
+ <title>The toolchain</title>
+
+ <para>We assume the toolchain provides a C and C++ compiler, an
+ assembler and other tools to build packages. The list below shows a gcc
+ 3.4.4 toolchain for ARM architectures using glibc. We assume that the
+ toolchain is in your <command>PATH</command>.</para>
+
+ <screen>
+<command>ls</command> pre-built/cross/bin
+
+arm-linux-g++
+arm-linux-ld
+arm-linux-ranlib
+arm-linux-ar
+arm-linux-g77
+arm-linux-readelf
+arm-linux-as
+arm-linux-gcc
+arm-linux-gcc-3.4.4
+arm-linux-c++
+arm-linux-size
+arm-linux-c++filt
+arm-linux-nm
+arm-linux-strings
+arm-linux-cpp
+arm-linux-objcopy
+arm-linux-strip
+arm-linux-objdump
+</screen>
+ </section>
+
+ <section>
+ <title>The prebuilt libraries</title>
+
+ <para>We need the header files and the libraries itself. The following
+ directory layout is assume. <command>PRE_BUILT</command> has two
+ subdirectories one is called <emphasis>include</emphasis> and holds the
+ header files and the other directory is called <emphasis>lib</emphasis>
+ and holds the shared and static libraries. Additionally a Qt2 directory
+ is present having a <emphasis>include</emphasis> and
+ <emphasis>lib</emphasis> sub-directory.</para>
+
+ <screen>
+<command>ls</command> $PRE_BUILT
+include
+lib
+qt2
+</screen>
+ </section>
+
+ <section>
+ <title>Setting up OpenEmbedded</title>
+
+ <para>OpenEmbedded will be setup here. We assume that your machine and
+ distribution is not part of OpenEmbedded and they will be created ad-hoc
+ in the <emphasis>local.conf</emphasis> file. You will need to have
+ <application>BitBake</application> and a current OpenEmbedded version
+ available.</para>
+
+ <section>
+ <title>Sourcable script</title>
+
+ <para>To ease the usage of OpenEmbedded we start by creating a
+ source-able script. This is actually a small variation from the
+ already seen script. We will name it <emphasis>build_source</emphasis>
+ and you will need to source it.</para>
+
+ <screen>
+BITBAKE_PATH=/where/is/bitbake/bin
+TOOLCHAIN=/where/is/toolchain/bin
+HOST_TOOLS=/where/is/hosttools/bin
+export PRE_BUILT=/where/is/pre-built
+
+export PATH=$BITBAKE_PATH:$TOOLCHAIN:$HOST_TOOLS:$PATH
+export OEDIR=$PWD
+export LOCALDIR=$PWD/secret-isv
+ </screen>
+
+ <para>Use <command>source build_source</command> to source the script,
+ use <command>env</command> to check that the variable where
+ exported.</para>
+ </section>
+
+ <section>
+ <title>Creating the local.conf</title>
+
+ <para>We will configure OpenEmbedded now, it is very similar to what
+ we have done above.</para>
+
+ <screen>
+DL_DIR = "${OEDIR}/sources"
+BBFILES := "${OEDIR}/openembedded/packages/*/*.bb ${LOCALDIR}/packages/*/*.bb"
+BBFILE_COLLECTIONS = "upstream local"
+BBFILE_PATTERN_upstream = "^${OEDIR}/openembedded/packages/"
+BBFILE_PATTERN_local = "^${LOCALDIR}/packages/"
+BBFILE_PRIORITY_upstream = "5"
+BBFILE_PRIORITY_local = "10"
+BBMASK = ""
+ </screen>
+
+ <para>${OEDIR}/openembedded will be a upstream release of
+ OpenEmbedded. Above we have assumed it is in the current working
+ directory. Additionally we have a ${LOCALDIR}, we combine these two
+ directories as a special <link linkend="collections">BitBake
+ Collection</link>.</para>
+
+ <screen>
+#
+# machine stuff
+#
+MACHINE = "secret-killer"
+PACKAGE_EXTRA_ARCHS = "armv4 armv4t armv5te iwmmxt xscale""
+TARGET_CC_ARCH = "-mcpu=xscale -mtune=iwmmxt"
+TARGET_ARCH = "arm"
+PACKAGE_ARCH="xscale"
+ </screen>
+
+ <para>We tell OpenEmbedded that we build for the ARM platform and
+ optimize for xscale and iwmmxt.</para>
+
+ <screen>
+INHERIT += " package_ipk debian"
+TARGET_OS = "linux"
+TARGET_FPU = "soft"
+DISTRO = "secret-disro"
+DISTRO_NAME = "secret-distro"
+DISTRO_VERSION = "x.y.z"
+DISTRO_TYPE = "release"
+ </screen>
+
+ <para>Create a distribution ad-hoc as well. We tell OpenEmbedded that
+ we build for linux and glibc using soft float as fpu. If your
+ toolchain is a uclibc toolchain you will need to set
+ <command>TARGET_OS</command> to linux-uclibc.</para>
+
+ <screen>
+export CC = "${CCACHE}arm-linux-gcc-3.4.4 ${HOST_CC_ARCH}"
+export CXX = "${CCACHE}arm-linux-g++ ${HOST_CC_ARCH}"
+export CPP = "arm-linux-gcc-3.4.4 -E"
+export LD = "arm-linux-ld"
+export AR = "arm-linux-ar"
+export AS = "arm-linux-as"
+export RANLIB = "arm-linux-ranlib"
+export STRIP = "arm-linux-strip"
+ </screen>
+
+ <para>The above variables replace the ones from
+ <emphasis>bitbake.conf</emphasis>. This will make OpenEmbedded use the
+ prebuilt toolchain.</para>
+
+ <screen>
+#
+# point OE to the lib and include directory
+#
+TARGET_CPPFLAGS_append = " -I${PRE_BUILT}/include "
+TARGET_LDFLAGS_prepend = " -L${PRE_BUILT}/qt2/lib -L${PRE_BUILT}/lib \
+-Wl,-rpath-link,${PRE_BUILT}/lib -Wl,-rpath-link,${PRE_BUILT}/qt2/lib "
+
+# special to Qt/Qtopia
+QTDIR = "${PRE_BUILT}/qt2"
+QPEDIR = "${PRE_BUILT}"
+palmtopdir = "/opt/Qtopia"
+palmqtdir = "/opt/Qtopia"
+ </screen>
+
+ <para>We will add the <command>PRE_BUILT</command> libraries to the
+ include and library paths. And the same is done for the special
+ version of Qt we have in your <command>PRE_BUILT</command>
+ directory.</para>
+
+ <screen>
+ASSUME_PROVIDED += " virtual/${TARGET_PREFIX}gcc "
+ASSUME_PROVIDED += " virtual/libc "
+ASSUME_PROVIDED += " virtual/qte "
+ASSUME_PROVIDED += " virtual/libqpe "
+ASSUME_PROVIDED += " libqpe-opie "
+ </screen>
+
+ <para>Now we have told <application>BitBake</application> that the C
+ library, compiler and Qtopia is already provided. These lines will
+ avoid building binutils, gcc initial, glibc, gcc.</para>
+
+ <screen>
+<command>source</command> build_source
+<command>bitbake</command> your-killer-app
+ </screen>
+
+ <para>You should be able to create the packages you want to using the
+ prebuilt toolchain now.</para>
+ </section>
+ </section>
+
+ <section>
+ <title>Useful hints</title>
+
+ <para>If you have more prebuilt libraries you need to add additional
+ <command>ASSUME_PROVIDED</command> lines to your
+ <emphasis>local.conf</emphasis>. Using <command>bitbake -vvv
+ PACKAGE</command> you can easily see the package names you could
+ <command>ASSUME_PROVIDED</command> if you have some prebuilt.</para>
+ </section>
+
+ <section>
+ <title>Issues with this approach</title>
+
+ <screen>
+NOTE: Couldn't find shared library provider for libqtopia.so.1
+NOTE: Couldn't find shared library provider for libqtopia2.so.2
+NOTE: Couldn't find shared library provider for libqpe.so.1
+NOTE: Couldn't find shared library provider for libpthread.so.0
+NOTE: Couldn't find shared library provider for libstdc++.so.6
+NOTE: Couldn't find shared library provider for libqte.so.2
+NOTE: Couldn't find shared library provider for libgcc_s.so.1
+NOTE: Couldn't find shared library provider for libc.so.6
+NOTE: Couldn't find shared library provider for libm.so.6
+</screen>
+
+ <para>OpenEmbedded tries to automatically add run-time dependencies
+ (RDEPENDS) to the package. It uses the <emphasis><link
+ linkend="shlibs">shlibs</link></emphasis> system to do add them, in this
+ case it was not able to find packages providing these libraries as they
+ are prebuilt. This means they will not be added to the RDEPENDS of the
+ just created package. The result can be fatal. If %s
>>> DIFF TRUNCATED @ 16K
#
# mt diff -ra345293c1e1d325c7d86ed713f89778c64f62735 -r9b1b144cfdd27182aae561871a08f2b820a7b1e8
#
#
#
# patch "usermanual/usermanual.xml"
# from [92cb64c8cf4be8d6b7a7f21369d216a941b6561a]
# to [3c92a6dae8be33141f5f739c04d54e28406681ea]
#
============================================================
--- usermanual/usermanual.xml 92cb64c8cf4be8d6b7a7f21369d216a941b6561a
+++ usermanual/usermanual.xml 3c92a6dae8be33141f5f739c04d54e28406681ea
More information about the Openembedded-commits
mailing list