From 25b51d32c982a6767f3d4a88dec12f70c8c8f875 Mon Sep 17 00:00:00 2001 From: Michael 'Mickey' Lauer Date: Wed, 25 Feb 2009 01:47:30 +0100 Subject: docs: import usermanual from org.openembedded.documentation. org.openembedded.documentation is deprecated now; please do all updates here! --- docs/usermanual/chapters/common_use_cases.xml | 409 ++++++++++++++++++++++++++ 1 file changed, 409 insertions(+) create mode 100644 docs/usermanual/chapters/common_use_cases.xml (limited to 'docs/usermanual/chapters/common_use_cases.xml') diff --git a/docs/usermanual/chapters/common_use_cases.xml b/docs/usermanual/chapters/common_use_cases.xml new file mode 100644 index 0000000000..4497683fa9 --- /dev/null +++ b/docs/usermanual/chapters/common_use_cases.xml @@ -0,0 +1,409 @@ + + + Common Use-cases/tasks + +
+ Creating a new Distribution + + 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? + + DISTRO_VERSION so users will know which + version of distribution they use. + + + + DISTRO_TYPE (release/debug) variable is + used in some recipes to enable/disable some features - for example + kernel output on screen for "debug" builds. + + + + Type of libc used: will it be glibc + (TARGET_OS = "linux") or uclibc + (TARGET_OS = "linux-uclibc")? + + + + Toolchain versions - for example gcc 3.4.4 based distro will + have: +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" + + + + + DISTRO_FEATURES which describe which + features distro has. More about it in task-base section. + + + + Versions of kernels used for supported devices: +PREFERRED_VERSION_linux-omap1_omap5912osk ?= "2.6.18+git" +PREFERRED_VERSION_linux-openzaurus ?= "2.6.17" + + + + + 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. +require conf/distro/include/sane-srcdates.inc + It also should have global SRCDATE + value set (format is ISO date: YYYYMMDD): +SRCDATE = "20061014" + + + +
+ +
+ Adding a new Machine + + 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. + + As usual some variables are required: + + TARGET_ARCH which describe which CPU + architecture does machine use. + + + + MACHINE_FEATURES which describe which + features device has. More about it in task-base section. + + + + PREFERRED_PROVIDER_virtual/kernel has to + point into proper kernel recipe for this machine. + + + + Next kernel recipe needs to be added. +
+ +
+ Adding a new Package + + This section is a stub, help us by expanding it. Learn by example, go through the + recipes that are already there and mimic them to do what you want. + +
+ building from unstable source code + Building against the latest, bleeding-edge source has some intricacies of its own. + For one, it is desirable to pin down a souce code revision that is known to build to + prevent random breakage in OE at the most inopportune time for all OE users. Here is + how to do that properly. + + for svn: add 'PV = "1.1+svnr${SRCREV}"' to your bb file. + for cvs: add 'PV = "1.1+cvs${SRCREV}"' to your bb file. + + Accompany either with an entry to conf/distro/include/sane-srcrevs.inc for a revision that you know + builds successfully. + + + If you really absolutely have to follow the latest commits, you can do that by adding + 'SRCREV_pn-linux-davinci ?= ${AUTOREV}' to your local.conf, for example. In this case, + you'd build against the most recent and unstable source for the pn-linux-davinci package. + +
+
+ +
+ Creating your own image + + Creating own image is easy - only few variables needs to be set: + + + IMAGE_BASENAME to give a name for your own + image + + + + PACKAGE_INSTALL to give a list of packages + to install into the image + + + + RDEPENDS to give a list of recipes which + are needed to be built to create this image + + + + IMAGE_LINGUAS is an optional list of + languages which has to be installed into the image + + Then adding of the image class use: + +inherit image + And the image recipe is ready for usage. +
+ +
+ Using a prebuilt toolchain to create your packages + + 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. + +
+ The toolchain + + 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 PATH. + + +ls 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 + +
+ +
+ The prebuilt libraries + + We need the header files and the libraries itself. The following + directory layout is assume. PRE_BUILT has two + subdirectories one is called include and holds the + header files and the other directory is called lib + and holds the shared and static libraries. Additionally a Qt2 directory + is present having a include and + lib sub-directory. + + +ls $PRE_BUILT +include +lib +qt2 + +
+ +
+ Setting up OpenEmbedded + + 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 local.conf file. You will need to have + BitBake and a current OpenEmbedded version + available. + +
+ Sourcable script + + 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 build_source + and you will need to source it. + + +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 + + + Use source build_source to source the script, + use env to check that the variable where + exported. +
+ +
+ Creating the local.conf + + We will configure OpenEmbedded now, it is very similar to what + we have done above. + + +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 = "" + + + ${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 BitBake + Collection. + + +# +# 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" + + + We tell OpenEmbedded that we build for the ARM platform and + optimize for xscale and iwmmxt. + + +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" + + + 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 + TARGET_OS to linux-uclibc. + + +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" + + + The above variables replace the ones from + bitbake.conf. This will make OpenEmbedded use the + prebuilt toolchain. + + +# +# 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" + + + We will add the PRE_BUILT libraries to the + include and library paths. And the same is done for the special + version of Qt we have in your PRE_BUILT + directory. + + +ASSUME_PROVIDED += " virtual/${TARGET_PREFIX}gcc " +ASSUME_PROVIDED += " virtual/libc " +ASSUME_PROVIDED += " virtual/qte " +ASSUME_PROVIDED += " virtual/libqpe " +ASSUME_PROVIDED += " libqpe-opie " + + + Now we have told BitBake that the C + library, compiler and Qtopia is already provided. These lines will + avoid building binutils, gcc initial, glibc, gcc. + + +source build_source +bitbake your-killer-app + + + You should be able to create the packages you want to using the + prebuilt toolchain now. +
+
+ +
+ Useful hints + + If you have more prebuilt libraries you need to add additional + ASSUME_PROVIDED lines to your + local.conf. Using bitbake -vvv + PACKAGE you can easily see the package names you could + ASSUME_PROVIDED if you have some prebuilt. +
+ +
+ Issues with this approach + + +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 + + + OpenEmbedded tries to automatically add run-time dependencies + (RDEPENDS) to the package. It uses the shlibs 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. + + However, the correct way to resolve this is to provide explicit + mapping using ASSUME_SHLIBS variable. For example, for the libraries + above (partial): + +ASSUME_SHLIBS = "libqtopia2.so.2:qtopia2_2.4 libc.so.6:libc" + + The format is shlib_file_name:package[_version]. If a version is specified it will be + used as the minimal (>=) version for the dependency. +
+
+ +
+ Using a new package format + + This section is a stub, help us by expanding it +
+ -- cgit 1.2.3-korg