docs: import usermanual from org.openembedded.documentation.

org.openembedded.documentation is deprecated now; please do all updates here!

1 files changed, 129 insertions, 0 deletions

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 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="chapter_metadata">
+  <title>Metadata</title>
+
+  <section id="metadata_file_layout">
+    <title>File Layout</title>
+
+    <para>OpenEmbedded has six directories three of them hold
+    <application>BitBake</application> metadata.</para>
+
+    <para>The <emphasis>conf</emphasis> directory is holding the bitbake.conf,
+    machine and distribution configuration. bitbake.conf is read when
+    <application>BitBake</application> is started and this will include among
+    others a local.conf the machine and distribution configuration files.
+    These files will be searched in the <command>BBPATH</command> environment
+    variable.</para>
+
+    <para><emphasis>classes</emphasis> is the directory holding
+    <application>BitBake</application> bbclass. These classes can be inherited
+    by the <application>BitBake</application> files. BitBake automatically
+    inherits the base.bbclass on every parsed file. <command>BBPATH</command>
+    is used to find the class.</para>
+
+    <para>In <emphasis>packages</emphasis> the
+    <application>BitBake</application> files are stored. For each task or
+    application we have a directory. These directories store the real
+    <application>BitBake</application> files. They are the ones ending with
+    <emphasis>.bb</emphasis>. And for each application and version we have
+    one.</para>
+  </section>
+
+  <section id="metadata_syntax">
+    <title>Syntax</title>
+
+    <para>OpenEmbedded has files ending with <emphasis>.conf</emphasis>,
+    <emphasis>.inc</emphasis>, <emphasis>.bb</emphasis>
+    and<emphasis>.bbclass</emphasis>. The syntax and semantic of these files
+    are best described in the <ulink
+    url="http://bitbake.berlios.de/manual"><application>BitBake</application>
+    manual</ulink>.</para>
+  </section>
+
+  <section id="metadata_classes">
+    <title>Classes</title>
+
+    <para>OpenEmbedded provides special <application>BitBake</application>
+    classes to ease compiling, packaging and other things. FIXME.</para>
+  </section>
+
+  <section id="metadata_writing_data">
+    <title>Writing Meta Data (Adding packages)</title>
+
+    <para>This page will guide you trough the effort of writing a .bb file or
+    <emphasis>recipe</emphasis> in BitBake speak.</para>
+
+    <para>Let's start with the easy stuff, like the package description,
+    license, etc: <screen>
+DESCRIPTION = "My first application, a really cool app containing lots of foo and bar"
+LICENSE = "GPLv2"
+HOMEPAGE = "http://www.host.com/foo/"
+                </screen> The description and license fields are mandatory, so
+    better check them twice.</para>
+
+    <para>The next step is to specify what the package needs to build and run,
+    the so called <emphasis>dependencies</emphasis>: <screen>
+DEPENDS = "gtk+"
+RDEPENDS = "cool-ttf-fonts"
+                </screen> 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
+    <emphasis>shlibs</emphasis>-code, but you need to specify everything other
+    by yourself, which in this case is the 'cool-ttf-fonts' package.</para>
+
+    <para>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: <screen>
+SRC_URI = "http://www.host.com/foo/files/${P}.tar.bz2;md5sum=yoursum"
+                </screen> 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 <emphasis>yoursum</emphasis>. You can make one by doing
+    <screen>md5sum foo-1.9.tar.bz2</screen> and replacing
+    <emphasis>yoursum</emphasis> with the md5sum on your screen. A typical
+    md5sum will look like this: <screen>a6434b0fc8a54c3dec3d6875bf3be8mtn </screen>Notice
+    the <emphasis>${P}</emphasis> variable, that one holds the package name,
+    <emphasis>${PN}</emphasis> in BitBake speak and the package version,
+    <emphasis>${PV}</emphasis> in BitBake speak. It's a short way of writing
+    <emphasis>${PN}-${PV}</emphasis>. 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.</para>
+
+    <para>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
+    <emphasis>configure</emphasis> file in the build tree this is an indicator
+    that we can <emphasis>inherit autotools</emphasis> if we see a
+    <emphasis>.pro</emphasis> file, it might be qmake, which needs
+    <emphasis>inherit qmake</emphasis>. Virtually all gtk apps use autotools:
+    <screen>
+inherit autotools pkgconfig
+                </screen> We are in luck! The package is a well-behaved
+    application using autotools and pkgconfig to configure and build it
+    self.</para>
+
+    <para>Lets start the build: <screen>
+<command>bitbake</command> foo
+                </screen> 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.</para>
+
+    <para>.... some time goes by .....</para>
+
+    <para>Your screen should now have something like this on it: <screen>
+NOTE: package foo-1.9-r0: task do_build: completed
+NOTE: package foo-1.9: completed
+NOTE: build 200605052219: completed
+                </screen></para>
+
+    <para>All looks well, but wait, let's scroll up: <screen>
+NOTE: the following files where installed but not shipped:
+    /usr/weirdpath/importantfile.foo
+                </screen> 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: <screen>
+FILES_${PN} += "/usr/weirdpath/importantfile.foo"
+                </screen> It's important to use <emphasis>+=</emphasis> so it
+    will get appended to the standard file-list, not replace the standard
+    one.</para>
+  </section>
+</chapter>
\ No newline at end of file