getting_oe.xml: Update documentation.
[openembedded.git] / docs / usermanual / chapters / metadata.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <chapter id="chapter_metadata">
3   <title>Metadata</title>
4
5   <section id="metadata_file_layout">
6     <title>File Layout</title>
7
8     <para>OpenEmbedded has six directories three of them hold
9     <application>BitBake</application> metadata.</para>
10
11     <para>The <emphasis>conf</emphasis> directory is holding the bitbake.conf,
12     machine and distribution configuration. bitbake.conf is read when
13     <application>BitBake</application> is started and this will include among
14     others a local.conf the machine and distribution configuration files.
15     These files will be searched in the <command>BBPATH</command> environment
16     variable.</para>
17
18     <para><emphasis>classes</emphasis> is the directory holding
19     <application>BitBake</application> bbclass. These classes can be inherited
20     by the <application>BitBake</application> files. BitBake automatically
21     inherits the base.bbclass on every parsed file. <command>BBPATH</command>
22     is used to find the class.</para>
23
24     <para>In <emphasis>packages</emphasis> the
25     <application>BitBake</application> files are stored. For each task or
26     application we have a directory. These directories store the real
27     <application>BitBake</application> files. They are the ones ending with
28     <emphasis>.bb</emphasis>. And for each application and version we have
29     one.</para>
30   </section>
31
32   <section id="metadata_syntax">
33     <title>Syntax</title>
34
35     <para>OpenEmbedded has files ending with <emphasis>.conf</emphasis>,
36     <emphasis>.inc</emphasis>, <emphasis>.bb</emphasis>
37     and<emphasis>.bbclass</emphasis>. The syntax and semantic of these files
38     are best described in the <ulink
39     url="http://bitbake.berlios.de/manual"><application>BitBake</application>
40     manual</ulink>.</para>
41   </section>
42
43   <section id="metadata_classes">
44     <title>Classes</title>
45
46     <para>OpenEmbedded provides special <application>BitBake</application>
47     classes to ease compiling, packaging and other things. FIXME.</para>
48   </section>
49
50   <section id="metadata_writing_data">
51     <title>Writing Meta Data (Adding packages)</title>
52
53     <para>This page will guide you trough the effort of writing a .bb file or
54     <emphasis>recipe</emphasis> in BitBake speak.</para>
55
56     <para>Let's start with the easy stuff, like the package description,
57     license, etc: <screen>
58 DESCRIPTION = "My first application, a really cool app containing lots of foo and bar"
59 LICENSE = "GPLv2"
60 HOMEPAGE = "http://www.host.com/foo/"
61                 </screen> The description and license fields are mandatory, so
62     better check them twice.</para>
63
64     <para>The next step is to specify what the package needs to build and run,
65     the so called <emphasis>dependencies</emphasis>: <screen>
66 DEPENDS = "gtk+"
67 RDEPENDS = "cool-ttf-fonts"
68                 </screen> The package needs gtk+ to build ('DEPENDS') and
69     requires the 'cool-ttf-fonts' package to run ('RDEPENDS'). OE will add
70     run-time dependencies on libraries on its own via the so called
71     <emphasis>shlibs</emphasis>-code, but you need to specify everything other
72     by yourself, which in this case is the 'cool-ttf-fonts' package.</para>
73
74     <para>After entering all this OE will know what to build before trying to
75     build your application, but it doesn't know where to get it yet. So let's
76     add the source location: <screen>
77 SRC_URI = "http://www.host.com/foo/files/${P}.tar.bz2;md5sum=yoursum"
78                 </screen> This will tell the fetcher to where to download the
79     sources from and it will check the integrity using md5sum if you provided
80     the appropriate <emphasis>yoursum</emphasis>. You can make one by doing
81     <screen>md5sum foo-1.9.tar.bz2</screen> and replacing
82     <emphasis>yoursum</emphasis> with the md5sum on your screen. A typical
83     md5sum will look like this: <screen>a6434b0fc8a54c3dec3d6875bf3be8mtn </screen>Notice
84     the <emphasis>${P}</emphasis> variable, that one holds the package name,
85     <emphasis>${PN}</emphasis> in BitBake speak and the package version,
86     <emphasis>${PV}</emphasis> in BitBake speak. It's a short way of writing
87     <emphasis>${PN}-${PV}</emphasis>. Using this notation means you can copy
88     the recipe when a new version is released without having to alter the
89     contents. You do need to check if everything is still correct, because new
90     versions mean new bugs.</para>
91
92     <para>Before we can move to the actual building we need to find out which
93     build system the package is using. If we're lucky, we see a
94     <emphasis>configure</emphasis> file in the build tree this is an indicator
95     that we can <emphasis>inherit autotools</emphasis> if we see a
96     <emphasis>.pro</emphasis> file, it might be qmake, which needs
97     <emphasis>inherit qmake</emphasis>. Virtually all gtk apps use autotools:
98     <screen>
99 inherit autotools pkgconfig
100                 </screen> We are in luck! The package is a well-behaved
101     application using autotools and pkgconfig to configure and build it
102     self.</para>
103
104     <para>Lets start the build: <screen>
105 <command>bitbake</command> foo
106                 </screen> Depending on what you have built before and the
107     speed of your computer this can take a few seconds to a few hours, so be
108     prepared.</para>
109
110     <para>.... some time goes by .....</para>
111
112     <para>Your screen should now have something like this on it: <screen>
113 NOTE: package foo-1.9-r0: task do_build: completed
114 NOTE: package foo-1.9: completed
115 NOTE: build 200605052219: completed
116                 </screen></para>
117
118     <para>All looks well, but wait, let's scroll up: <screen>
119 NOTE: the following files where installed but not shipped:
120     /usr/weirdpath/importantfile.foo
121                 </screen> OE has a standard list of paths which need to be
122     included, but it can't know everything, so we have to tell OE to include
123     that file as well: <screen>
124 FILES_${PN} += "/usr/weirdpath/importantfile.foo"
125                 </screen> It's important to use <emphasis>+=</emphasis> so it
126     will get appended to the standard file-list, not replace the standard
127     one.</para>
128   </section>
129 </chapter>