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/Makefile | 60 + docs/usermanual/README | 18 + docs/usermanual/chapters/.mtn2git_empty | 0 docs/usermanual/chapters/common_use_cases.xml | 409 +++ docs/usermanual/chapters/comparing.xml | 51 + docs/usermanual/chapters/features.xml | 78 + docs/usermanual/chapters/getting_oe.xml | 70 + docs/usermanual/chapters/introduction.xml | 72 + docs/usermanual/chapters/metadata.xml | 129 + docs/usermanual/chapters/recipes.xml | 3710 ++++++++++++++++++++ docs/usermanual/chapters/usage.xml | 1193 +++++++ docs/usermanual/docbook-utf8.xsl | 10 + docs/usermanual/embworld-oe.dbk | 888 +++++ docs/usermanual/html.css | 282 ++ docs/usermanual/reference/.mtn2git_empty | 0 docs/usermanual/reference/class_autotools.xml | 153 + docs/usermanual/reference/class_binconfig.xml | 46 + docs/usermanual/reference/class_distutils.xml | 48 + docs/usermanual/reference/class_image.xml | 358 ++ docs/usermanual/reference/class_pkgconfig.xml | 39 + docs/usermanual/reference/class_rootfs_ipkg.xml | 215 ++ docs/usermanual/reference/class_siteinfo.xml | 180 + .../reference/class_update-alternatives.xml | 241 ++ docs/usermanual/reference/class_update-rc.d.xml | 133 + docs/usermanual/reference/dirs_install.xml | 198 ++ docs/usermanual/reference/dirs_staging.xml | 169 + docs/usermanual/reference/fakeroot.xml | 186 + docs/usermanual/reference/image_types.xml | 385 ++ docs/usermanual/reference/var_section.xml | 704 ++++ docs/usermanual/reference/var_src_uri.xml | 692 ++++ docs/usermanual/usermanual.xml | 122 + 31 files changed, 10839 insertions(+) create mode 100644 docs/usermanual/Makefile create mode 100644 docs/usermanual/README create mode 100644 docs/usermanual/chapters/.mtn2git_empty create mode 100644 docs/usermanual/chapters/common_use_cases.xml create mode 100644 docs/usermanual/chapters/comparing.xml create mode 100644 docs/usermanual/chapters/features.xml create mode 100644 docs/usermanual/chapters/getting_oe.xml create mode 100644 docs/usermanual/chapters/introduction.xml create mode 100644 docs/usermanual/chapters/metadata.xml create mode 100644 docs/usermanual/chapters/recipes.xml create mode 100644 docs/usermanual/chapters/usage.xml create mode 100644 docs/usermanual/docbook-utf8.xsl create mode 100644 docs/usermanual/embworld-oe.dbk create mode 100644 docs/usermanual/html.css create mode 100644 docs/usermanual/reference/.mtn2git_empty create mode 100644 docs/usermanual/reference/class_autotools.xml create mode 100644 docs/usermanual/reference/class_binconfig.xml create mode 100644 docs/usermanual/reference/class_distutils.xml create mode 100644 docs/usermanual/reference/class_image.xml create mode 100644 docs/usermanual/reference/class_pkgconfig.xml create mode 100644 docs/usermanual/reference/class_rootfs_ipkg.xml create mode 100644 docs/usermanual/reference/class_siteinfo.xml create mode 100644 docs/usermanual/reference/class_update-alternatives.xml create mode 100644 docs/usermanual/reference/class_update-rc.d.xml create mode 100644 docs/usermanual/reference/dirs_install.xml create mode 100644 docs/usermanual/reference/dirs_staging.xml create mode 100644 docs/usermanual/reference/fakeroot.xml create mode 100644 docs/usermanual/reference/image_types.xml create mode 100644 docs/usermanual/reference/var_section.xml create mode 100644 docs/usermanual/reference/var_src_uri.xml create mode 100644 docs/usermanual/usermanual.xml (limited to 'docs') diff --git a/docs/usermanual/Makefile b/docs/usermanual/Makefile new file mode 100644 index 0000000000..5649442ed5 --- /dev/null +++ b/docs/usermanual/Makefile @@ -0,0 +1,60 @@ +topdir = . +manual = $(topdir)/usermanual.xml +# types = pdf txt rtf ps xhtml html man tex texi dvi +# types = pdf txt +types = $(xmltotypes) $(htmltypes) $(docbooktotypes) +xmltotypes = +docbooktotypes = dvi pdf ps rtf tex texi txt +htmltypes = html xhtml +htmlxsl = $(if $(filter $@,$(foreach type,$(htmltypes),$(type)-nochunks)),docbook-utf8.xsl,http://docbook.sourceforge.net/release/xsl/current/$@/chunk.xsl) +htmlcssfile = docbook.css +htmlcss = $(topdir)/html.css +# htmlcssfile = +# htmlcss = +cleanfiles = $(foreach i,$(types),$(topdir)/$(i)) + +ifdef DEBUG +define command + $(1) +endef +else +define command + @echo $(2) $(3) $(4) + @$(1) >/dev/null +endef +endif + +all: $(types) + +lint: $(manual) FORCE + $(call command,xmllint --xinclude --postvalid --noout $(manual),XMLLINT $(manual)) + +$(types) $(foreach type,$(htmltypes),$(type)-nochunks): lint FORCE + +$(foreach type,$(htmltypes),$(type)-nochunks): $(if $(htmlcss),$(htmlcss)) $(manual) + @mkdir -p $@ +ifdef htmlcss + $(call command,install -m 0644 $(htmlcss) $@/$(htmlcssfile),CP $(htmlcss) $@/$(htmlcssfile)) +endif + $(call command,xsltproc --stringparam base.dir $@/ $(if $(htmlcssfile),--stringparam html.stylesheet $(htmlcssfile)) $(htmlxsl) $(manual) > $@/index.$(patsubst %-nochunks,%,$@),XSLTPROC $@ $(manual)) + +$(htmltypes): $(if $(htmlcss),$(htmlcss)) $(manual) + @mkdir -p $@ +ifdef htmlcss + $(call command,install -m 0644 $(htmlcss) $@/$(htmlcssfile),CP $(htmlcss) $@/$(htmlcssfile)) +endif + $(call command,xsltproc --param use.id.as.filename 1 --stringparam base.dir $@/ $(if $(htmlcssfile),--stringparam html.stylesheet $(htmlcssfile)) $(htmlxsl) $(manual),XSLTPROC $@ $(manual)) + +$(xmltotypes): $(manual) + $(call command,xmlto --extensions -o $(topdir)/$@ $@ $(manual),XMLTO $@ $(manual)) + +$(docbooktotypes): $(manual) + $(call command,docbook2$@ $(manual),DOCBOOK2 $@ $(manual)) + +clean: + rm -rf $(cleanfiles) + +$(foreach i,$(types) $(foreach type,$(htmltypes),$(type)-nochunks),clean-$(i)): + rm -rf $(patsubst clean-%,%,$@) + +FORCE: diff --git a/docs/usermanual/README b/docs/usermanual/README new file mode 100644 index 0000000000..f2aecf8a6e --- /dev/null +++ b/docs/usermanual/README @@ -0,0 +1,18 @@ +To generate the user-manual, run: + + make + +in this directory, where type is one of: + + xhtml + html + dvi + pdf + ps + rtf + tex + texi + txt + +For html and xhtml you need xsltproc installed. +For the other you need docbook-utils installed. diff --git a/docs/usermanual/chapters/.mtn2git_empty b/docs/usermanual/chapters/.mtn2git_empty new file mode 100644 index 0000000000..e69de29bb2 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 +
+ diff --git a/docs/usermanual/chapters/comparing.xml b/docs/usermanual/chapters/comparing.xml new file mode 100644 index 0000000000..1347010977 --- /dev/null +++ b/docs/usermanual/chapters/comparing.xml @@ -0,0 +1,51 @@ + + + Comparing + +
+ buildroot + + Writing of BitBake 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, + Software Distribution Kits (SDKs), complete Distributions or just single + packages. The flexibility of OpenEmbedded allows you to reuse the once + written recipes for many different purposes. OpenEmbedded provides + everything buildroot will be able to provide. But in contrast to buildroot + OpenEmbedded will allow you to achieve what you really want to achieve. + You can add new package formats, new filesystems, new output formats + easily. OpenEmbedded will suit your need. +
+ +
+ crosstool + + Crosstool allows to create toolchains for you. It can only create + the initial toolchain for you. It will not compile other needed libraries + or applications for you, it will not be able to track dependencies or to + package them properly. OpenEmbedded supports all configurations crosstool + supports. You can start to create toolchains with OpenEmbedded, then as + your needs grow create a more complete SDK from already present base + libraries and applications and if you recognize you need to have packages + for the target you have them almost built already. +
+ +
+ handmade + + Cross-compilation is a tough business. It is not that + cross-compiling is hard itself but many people misuse the buildsystem they + use to build their software. This will lead to a variety of issues you can + run into. This can be failing tests on configuration because of executing + cross compiled binaries or crashes at run-time due wrong sizes of basic + types. When utilizing OpenEmbedded you avoid searching for patches at many + different places and will be able to get things done more quickly. + OpenEmbedded allows you to choose from a pool + of ready to use software packages. + + OpenEmbedded will create complete flashable images using different + output formats and filesystems. This allows you to create complete and + specialized distributions easily. +
+ \ No newline at end of file diff --git a/docs/usermanual/chapters/features.xml b/docs/usermanual/chapters/features.xml new file mode 100644 index 0000000000..8eecaa9ed4 --- /dev/null +++ b/docs/usermanual/chapters/features.xml @@ -0,0 +1,78 @@ + + + Special features + +
+ Debian package naming <anchor id="debian" /> + + INHERIT += "debian" + + Placing the above line into your ${DISTRO}.conf + or local.conf will trigger renaming of packages if + they only ship one library. Imagine a package where the package name + (PN) is foo and this packages ships a file named + libfoo.so.1.2.3. Now this package will be renamed to + libfoo1 to follow the Debian package naming + policy. +
+ +
+ Shared Library handling (shlibs) <anchor id="shlibs" /> + + Run-time Dependencies (RDEPENDS) will be added + when packaging the software. They should only contain the minimal + dependencies to run the program. OpenEmbedded will analyze each packaged + binary and search for SO_NEEDED libraries. The + libraries are absolutely required by the program then OpenEmbedded is + searching for packages that installs these libraries. these packages are + automatically added to the RDEPENDS. As a packager you + don't need to worry about shared libraries anymore they will be added + automatically. + + NOTE: This does not apply to plug-ins used by the + program. +
+ +
+ BitBake Collections <anchor id="collections" /> + + This section is a stub, help us by expanding it + + +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" + +
+ +
+ Task-base <anchor id="task-base" /> + + Task-base is new way of creating basic root filesystems. Instead of + having each machine setting a ton of duplicate variables, this allow a + machine to specify its features and task-base builds it + a customised package based on what the machine needs along with what the + distro supports. + + To illustrate, the distro config file can say: +DISTRO_FEATURES = "nfs smbfs ipsec wifi ppp alsa bluetooth ext2 irda pcmcia usbgadget usbhost" + and the machine config: +MACHINE_FEATURES = "kernel26 apm alsa pcmcia bluetooth irda usbgadget" + and the resulting task-base would support pcmcia + but not usbhost. + + Task-base details exactly which options are either machine or distro + settings (or need to be in both). Machine options are meant to reflect + capabilities of the machine, distro options list things distribution + maintainers might want to add or remove from their distros images. +
+ +
+ Overrides <anchor id="overrides" /> + + This section is a stub, help us by expanding it +
+ \ No newline at end of file diff --git a/docs/usermanual/chapters/getting_oe.xml b/docs/usermanual/chapters/getting_oe.xml new file mode 100644 index 0000000000..9238e4f29d --- /dev/null +++ b/docs/usermanual/chapters/getting_oe.xml @@ -0,0 +1,70 @@ + + + Getting Started + +
+ Getting <application>BitBake</application> + + The required version of BitBake is + changing rapidly. At the time of writing (end 2007) + BitBake 1.8.latest was required. + + A safe method is to get the BitBake from + a stable Subversion branch (those with an even minor number). +svn co http://svn.berlios.de/svnroot/repos/bitbake/branches/bitbake-1.8 +... +A bitbake-1.8/classes/base.bbclass +U bitbake-1.8 +At revision 827. + BitBake is checked out now; + this completes the first and most critical dependency of OpenEmbedded. + Issuing svn up in the + bitbake-1.8 directory will update + BitBake to the latest stable version, but + generally it is a good idea to stick with a specific known working version + of BitBake until OpenEmbedded asks you to + upgrade. +
+ +
+ Getting OpenEmbedded + + The OpenEmbedded metadata has a high rate of development, so it's a + good idea to stay up to date. You'll need monotone 0.28 to get the + metadata and stay up to date. Monotone is available in most distributions + and has binaries at Monotone + homepage. + + Next step is getting snapshot of database. +wget http://openembedded.org/snapshots/OE.mtn.bz2 http://openembedded.org/snapshots/OE.mtn.bz2.md5 + Or if you have monotone 0.30 or later: +wget http://www.openembedded.org/snapshots/OE-this-is-for-mtn-0.30.mtn.bz2 +wget http://www.openembedded.org/snapshots/OE-this-is-for-mtn-0.30.mtn.bz2.md5 + Then verify integrity of snapshot by checking md5sum. +md5sum -c OE.mtn.bz2.md5sum + Then unpack database. +bunzip OE.mtn.bz2 + Finally checkout the development branch. +mtn --db=OE.mtn co -b org.openembedded.dev + +
+ +
+ Configuring OpenEmbedded + + This section is a stub, help us by expanding it +
+ +
+ Building Software + + Once BitBake and OpenEmbedded are set up and configured, one can build + software and images like this: + +bitbake <recipe_name> + + + + This section is a stub, help us by expanding it +
+ \ No newline at end of file diff --git a/docs/usermanual/chapters/introduction.xml b/docs/usermanual/chapters/introduction.xml new file mode 100644 index 0000000000..cbe58332e1 --- /dev/null +++ b/docs/usermanual/chapters/introduction.xml @@ -0,0 +1,72 @@ + + + Introduction + +
+ Overview + + Like any build tool (make, ant, jam), the OpenEmbedded build tool + BitBake controls how to build things and the build dependencies. But + unlike single project tools like make it is not based + on one makefile or a closed set of inter-dependent makefiles, but collects + and manages an open set of largely independent build descriptions (package + recipes) and builds them in proper order. + + To be more precise: OpenEmbedded + is a set of metadata used to cross-compile, package and install software + packages. OpenEmbedded is being used to build + and maintain a number of embedded Linux distributions, including + OpenZaurus, Ångström, Familiar and SlugOS. + + The primary use-case of OpenEmbedded are: + + + Handle cross-compilation. + + + + Handle inter-package dependencies + + + + Must be able to emit packages (tar, rpm, ipk) + + + + Must be able to create images and feeds from packages + + + + Must be highly configurable to support many machines, + distribution and architectures. + + + + Writing of metadata must be easy and reusable + + + + Together with BitBake, + OpenEmbedded satisfies all these and many more. Flexibility and power have + always been the priorities. +
+ +
+ History + + OpenEmbedded was invented and founded by the creators of the + OpenZaurus project. At this time the project had pushed + buildroot to its limits. It supported the creation of + ipk packages, feeds and images and had support for + more than one machine. But it was impossible to use different patches, + files for different architectures, machines or distributions. To overcome + this shortcoming OpenEmbedded was created. + + After a few months other projects started using OpenEmbedded and + contributing back. On 7 December 2004 Chris Larson split the project into + two parts: BitBake, a generic task executor and OpenEmbedded, the metadata + for BitBake. +
+ diff --git a/docs/usermanual/chapters/metadata.xml b/docs/usermanual/chapters/metadata.xml new file mode 100644 index 0000000000..f4cf3bc5e6 --- /dev/null +++ b/docs/usermanual/chapters/metadata.xml @@ -0,0 +1,129 @@ + + + Metadata + +
+ File Layout + + OpenEmbedded has six directories three of them hold + BitBake metadata. + + The conf directory is holding the bitbake.conf, + machine and distribution configuration. bitbake.conf is read when + BitBake is started and this will include among + others a local.conf the machine and distribution configuration files. + These files will be searched in the BBPATH environment + variable. + + classes is the directory holding + BitBake bbclass. These classes can be inherited + by the BitBake files. BitBake automatically + inherits the base.bbclass on every parsed file. BBPATH + is used to find the class. + + In packages the + BitBake files are stored. For each task or + application we have a directory. These directories store the real + BitBake files. They are the ones ending with + .bb. And for each application and version we have + one. +
+ +
+ Syntax + + OpenEmbedded has files ending with .conf, + .inc, .bb + and.bbclass. The syntax and semantic of these files + are best described in the BitBake + manual. +
+ +
+ Classes + + OpenEmbedded provides special BitBake + classes to ease compiling, packaging and other things. FIXME. +
+ +
+ Writing Meta Data (Adding packages) + + This page will guide you trough the effort of writing a .bb file or + recipe in BitBake speak. + + Let's start with the easy stuff, like the package description, + license, etc: +DESCRIPTION = "My first application, a really cool app containing lots of foo and bar" +LICENSE = "GPLv2" +HOMEPAGE = "http://www.host.com/foo/" + The description and license fields are mandatory, so + better check them twice. + + The next step is to specify what the package needs to build and run, + the so called dependencies: +DEPENDS = "gtk+" +RDEPENDS = "cool-ttf-fonts" + The package needs gtk+ to build ('DEPENDS') and + requires the 'cool-ttf-fonts' package to run ('RDEPENDS'). OE will add + run-time dependencies on libraries on its own via the so called + shlibs-code, but you need to specify everything other + by yourself, which in this case is the 'cool-ttf-fonts' package. + + After entering all this OE will know what to build before trying to + build your application, but it doesn't know where to get it yet. So let's + add the source location: +SRC_URI = "http://www.host.com/foo/files/${P}.tar.bz2;md5sum=yoursum" + This will tell the fetcher to where to download the + sources from and it will check the integrity using md5sum if you provided + the appropriate yoursum. You can make one by doing + md5sum foo-1.9.tar.bz2 and replacing + yoursum with the md5sum on your screen. A typical + md5sum will look like this: a6434b0fc8a54c3dec3d6875bf3be8mtn Notice + the ${P} variable, that one holds the package name, + ${PN} in BitBake speak and the package version, + ${PV} in BitBake speak. It's a short way of writing + ${PN}-${PV}. Using this notation means you can copy + the recipe when a new version is released without having to alter the + contents. You do need to check if everything is still correct, because new + versions mean new bugs. + + Before we can move to the actual building we need to find out which + build system the package is using. If we're lucky, we see a + configure file in the build tree this is an indicator + that we can inherit autotools if we see a + .pro file, it might be qmake, which needs + inherit qmake. Virtually all gtk apps use autotools: + +inherit autotools pkgconfig + We are in luck! The package is a well-behaved + application using autotools and pkgconfig to configure and build it + self. + + Lets start the build: +bitbake foo + Depending on what you have built before and the + speed of your computer this can take a few seconds to a few hours, so be + prepared. + + .... some time goes by ..... + + Your screen should now have something like this on it: +NOTE: package foo-1.9-r0: task do_build: completed +NOTE: package foo-1.9: completed +NOTE: build 200605052219: completed + + + All looks well, but wait, let's scroll up: +NOTE: the following files where installed but not shipped: + /usr/weirdpath/importantfile.foo + OE has a standard list of paths which need to be + included, but it can't know everything, so we have to tell OE to include + that file as well: +FILES_${PN} += "/usr/weirdpath/importantfile.foo" + It's important to use += so it + will get appended to the standard file-list, not replace the standard + one. +
+ \ No newline at end of file diff --git a/docs/usermanual/chapters/recipes.xml b/docs/usermanual/chapters/recipes.xml new file mode 100644 index 0000000000..c1ca456fa0 --- /dev/null +++ b/docs/usermanual/chapters/recipes.xml @@ -0,0 +1,3710 @@ + + + Recipes + +
+ Introduction + + A bitbake recipe is a set of instructions that describe what needs + to be done to retrieve the source code for some application, apply any + necessary patches, provide any additional files (such as init scripts), + compile it, install it and generated binary packages. The end result is a + binary package that you can install on your target device, and maybe some + intermediate files, such as libraries and headers, which can be used when + building other application. + + In many ways the process is similar to creating .deb or .rpm + packages for your standard desktop distributions with one major difference + - in OpenEmbedded everything is being cross-compiled. This often makes the + task far more difficult (depending on how well suited the application is + to cross compiling), then it is for other packaging systems and sometime + impossible. + + This chapter assumes that you are familiar with working with + bitbake, including the work flow, required directory structures, bitbake + configuration and the use of monotone. If you are not familiar with these + then first take a look at the chapter on bitbake usage. +
+ +
+ Syntax of recipes + + The basic items that make up a bitbake recipe file are: + + + + functions + + + Functions provide a series of actions to be performed. + Functions are usually used to override the default implementation of + a task function, or to compliment (append or prepend to an existing + function) a default function. Standard functions use sh shell + syntax, although access to OpenEmbedded variables and internal + methods is also available. + + The following is an example function from the sed + recipe: + + do_install () { + autotools_do_install + install -d ${D}${base_bindir} + mv ${D}${bindir}/sed ${D}${base_bindir}/sed.${PN} +}It is also possible to implement new functions, that are not + replacing or complimenting the default functions, which are called + between existing tasks. It is also possible to implement functions + in python instead of sh. Both of these options are not seen in the + majority of recipes. + + + + + variable assignments and manipulations + + + Variable assignments allow a value to be assigned to a + variable. The assignment may be static text or might include the + contents of other variables. In addition to assignment, appending + and prepending operations are also supported. + + The follow example shows the some of the ways variables can be + used in recipes:S = "${WORKDIR}/postfix-${PV}" +PR = "r4" +CFLAGS += "-DNO_ASM" +SRC_URI_append = "file://fixup.patch;patch=1" + + + + + keywords + + + Only a few keywords are used in bitbake recipes. They are used + for things such as including common functions + (inherit), loading parts of a recipe from other + files (include and + require) and exporting variables to the + environment (export). + + The following example shows the use of some of these + keywords:export POSTCONF = "${STAGING_BINDIR}/postconf" +inherit autoconf +require otherfile.inc + + + + + comments + + + Any lines that begin with a # are treated as comment lines and + are ignored.# This is a comment + + + + + The following is a summary of the most important (and most commonly + used) parts of the recipe syntax: + + + + Line continuation: \ + + + To split a line over multiple lines you should place a \ at + the end of the line that is to be continued on the next line. + + VAR = "A really long \ + line" + + Note that there must not be anything (no spaces or tabs) after + the \. + + + + + Comments: # + + + Any lines beginning with a # are comments and will be + ignored.# This is a comment + + + + + Using variables: ${...} + + + To access the contents of a variable you need to access it via + ${<varname>}:SRC_URI = "${SOURCEFORGE_MIRROR}/libpng/zlib-${PV}.tar.gz" + + + + + Quote all assignments + + + All variable assignments should be quoted with double quotes. + (It may work without them at present, but it will not work in the + future).VAR1 = "${OTHERVAR}" +VAR2 = "The version is ${PV}" + + + + + Conditional assignment + + + Conditional assignement is used to assign a value to a + variable, but only when the variable is currently unset. This is + commonly used to provide a default value for use when no specific + definition is provided by the machine or distro configuration of the + users local.conf configuration. + + The following example:VAR1 ?= "New value"will + set VAR1 to "New + value" if its currently empty. However if it was already + set it would be unchanged. In the following VAR1 is left with the value + "Original value":VAR1 = "Original value" +VAR1 ?= "New value" + + + + + Appending: += + + + You can append values to existing variables using the + += operator. Note that this operator will add a + space between the existing content of the variable and the new + content.SRC_URI += "file://fix-makefile.patch;patch=1" + + + + + Prepending: =+ + + + You can prepend values to existing variables using the + =+ operator. Note that this operator will add a + space between the new content and the existing content of the + variable.VAR =+ "Starts" + + + + + Appending: _append + + + You can append values to existing variables using the + _append method. Note that this operator does + not add any additional space, and it is applied after all the + +=, and =+ operators have + been applied. + + The following example show the space being explicitly added to + the start to ensure the appended value is not merged with the + existing value:SRC_URI_append = " file://fix-makefile.patch;patch=1"The + _append method can also be used with overrides, + which result in the actions only being performed for the specified + target or machine: [TODO: Link to section on overrides]SRC_URI_append_sh4 = " file://fix-makefile.patch;patch=1"Note + that the appended information is a variable itself, and therefore + it's possible to used += or + =+ to assign variables to the + _append information:SRC_URI_append = " file://fix-makefile.patch;patch=1" +SRC_URI_append += "file://fix-install.patch;patch=1" + + + + + Prepending: _prepend + + + You can prepend values to existing variables using the + _prepend method. Note that this operator does not add any additional + space, and it is applied after all the +=, and + =+ operators have been applied. + + The following example show the space being explicitly added to + the end to ensure the prepended value is not merged with the + existing value:CFLAGS_prepend = "-I${S}/myincludes "The + _prepend method can also be used with + overrides, which result in the actions only being performed for the + specified target or machine: [TODO: Link to section on + overrides]CFLAGS_prepend_sh4 = " file://fix-makefile.patch;patch=1"Note + that the appended information is a variable itself, and therefore + it's possible to used += or + =+ to assign variables to the + _prepend information:CFLAGS_prepend = "-I${S}/myincludes " +CFLAGS_prepend += "-I${S}/myincludes2 "Note also the lack of a space + when using += to append to a prepend value - remember that the += + operator is adding space itself. + + + + + Spaces vs tabs + + + Spaces should be used for indentation, not hard tabs. Both + currently work, however it is a policy decision of OE that spaces + always be used. + + + + + Style: oe-stylize.py + + + To help with using the correct style in your recipes there is + a python script in the contrib directory called + oe-stylize.py which can be used to reformat + your recipes to the correct style. The output will contain a list of + warning (to let you know what you did wrong) which should be edited + out before using the new file.contrib/oe-stylize.py myrecipe.bb > fixed-recipe.bb +vi fixed-recipe.bb +mv fixed.recipe.bb myrecipe.bb + + + + + Using python for complex operations: ${@...} + + + For more advanced processing it is possible to use python code + during variable assignments, for doing search and replace on a + variable for example. + + Python code is indicated by a proceeding @ sign in the + variable assignment.CXXFLAGS := "${@'${CXXFLAGS}'.replace('-frename-registers', '')}"More + information about using python is available in the section. + + + + + Shell syntax + + + When describing a list of actions to take shell syntax is used + (as if you were writing a shell script). You should ensure that you + script would work with a generic sh and not require any bash (or + other shell) specific functionality. The same applies to various + system utilities (sed, grep, awk etc) that you may wish to use. If + in doubt you should check with multiple implementations - including + those from busybox. + + + + + For a detailed description of the syntax for the bitbake recipe + files you should refer to the bitbake use manual. +
+ +
+ Recipe naming: Names, versions and releases + + Recipes in OpenEmbedded use a standard naming convention that + includes the package name and version number in the filename. In addition + to the name and version there is also a release number, which is indicates + changes to the way the package is built and/or packaged. The release + number is contained within the recipe itself. + + The expected format of recipe name is:<package-name>_<version>.bb + + where <package-name> is the name of the + package (application, library, module, or whatever it is that is being + packaged) and version is the version number. + + So a typical recipe name would be:strace_4.5.14.bbwhich + would be for version 4.5.14 of the + strace application. + + The release version is defined via the package release variable, PR, + contained in the recipe. The expected format is:r<n>where + <n> is an integer number starting from 0 + initially and then incremented each time the recipe, or something that + effects the recipe, is modified. So a typical definition of the release + would be:PR = "r1"to specify release number + 1 (the second release, the first would have been + 0). If there is no definition of PR in the recipe + then the default value of "r0" is used. + + + It is good practice to always define PR in your recipes, even + for the "r0" release, so that when editing the + recipe it is clear that the PR number needs to be updated. + + You should always increment PR when modifying a recipe. + Sometimes this can be avoided if the change will have no effect on the + actual packages generated by the recipe, such as updating the SRC_URI + to point to a new host. If in any doubt then you should increase the + PR regardless of what has been changed. + + The PR value should never be decremented. If you accidentally + submit a large PR value for example then it should be left at the + value and just increased for new releases, not reset back to a lower + version. + + + When a recipe is being processed some variables are automatically + set based on the recipe file name and can be used for other purposes from + within the recipe itself. These include: + + + + PN + + + The package name. Determined from the recipe filename - + everything up until the first underscore is considered to be the + package name. For the strace_4.5.14.bb recipe the + PN variable would be set to "strace". + + + + + PV + + + The package version. Determined from the recipe filename - + everything between the first underscore and the final .bb is + considered to be the package version. For the + strace_4.5.14.bb recipe the PV variable would be + set to "4.5.14". + + + + + PR + + + The package release. This is explicitly set in the recipe, or + if not set it defaults to "r0" if not + set. + + + + + P + + + The package name and versions separated by a hyphen.P = "${PN}-${PV}" + + For the strace_4.5.14.bb recipe the P + variable would be set to + "strace-4.5.14". + + + + + PF + + + The package name, version and release separated by + hyphens.PF = "${PN}-${PV}-${PR}" + + For the strace_4.5.14.bb recipe, with PR + set to "r1" in the recipe, the PF variable + would be set to "strace-4.5.14-r1". + + + + + While some of these variables are not commonly used in recipes (they + are used internally though) both PN and PV are used a lot. + + In the following example we are instructing the packaging system to + include an additional directory in the package. We use PN to refer to the + name of the package rather than spelling out the package name:FILES_${PN} += "${sysconfdir}/myconf" + + In the next example we are specifying the URL for the package + source, by using PV in place of the actual version number it is possible + to duplicate, or rename, the recipe for a new version without having to + edit the URL:SRC_URI = "ftp://ftp.vim.org/pub/vim/unix/vim-${PV}.tar.bz2" +
+ +
+ Variables + + One of the most confusing part of bitbake recipes for new users is + the large amount of variables that appear to be available to change and/or + control the behaviour of some aspect of the recipe. Some variables, such + as those derived from the file name are reasonably obvious, others are not + at all obvious. + + There are several places where these variables are derived from + and/or used: + + + + A large number of variables are defined in the bitbake + configuration file conf/bitbake.conf - it's often a good idea to look + through that file when trying to determine what a particular variable + means. + + + + Machine and distribution configuration files in conf/machine and + conf/distro will sometimes define some variables specific to the + machine and/or distribution. You should look at the appropriate files + for your targets to see if anything is being defined that effects the + recipes you are building. + + + + Bitbake itself will define some variables. The FILE variables + that defines the name of the bitbake recipe being processed is set by + bitbake itself for example. Refer to the bitbake manual for more + information on the variables that bitbake sets. + + + + The classes, that are used via the inherit keyword, define + and/or use the majority of the remaining variables. A class is a like + a library that contain parts of a bitbake recipe that are used by + multiple recipes. To make them usable in more situations they often + include a large number of variables to control how the class + operates. + + + + Another important aspect is that there are three different types of + things that binaries and libraries are used for and they often have + different variables for each. These include: + + + + target + + + Refers to things built for the target are expected to be run + on the target device itself. + + + + + native + + + Refers to things built to run natively on the build host + itself. + + + + + cross + + + Refers to things built to run natively on the build host + itself, but produce output which is suitable for the target device. + Cross versions of packages usually only exist for things like + compilers and assemblers - i.e. things which are used to produce + binary applications themselves. + + + +
+ +
+ Header + + Practically all recipes start was the header section which describes + various aspects of the package that is being built. This information is + typically used directly by the package format (such as ipkg or deb) as + it's meta data used to describe the package. + + Variables used in the header include: + + + + DESCRIPTION + + + Describes what the software does. Hopefully this gives enough + information to a use to know if it's the right applicat