metadata.xml: Update 'File Layout' section.
[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>The OpenEmbedded
9       directory, <filename>$OEBASE/openembedded/</filename>, has seven
10       directories, three of which hold
11       <application>BitBake</application> metadata.
12
13       <variablelist>
14         <varlistentry>
15           <term><filename>classes/</filename></term>
16           <listitem>
17             <para>Contains <application>BitBake</application>
18               <filename>.bbclass</filename> files. These classes can
19               be inherited by other <application>BitBake</application>
20               files. Every <application>BitBake</application>
21               <filename>.bb</filename> file automatically inherits the
22               <filename>base.bbclass</filename>. <varname>BBPATH</varname>
23               is used to find the <filename>.bbclass</filename> files.
24             </para>
25           </listitem>
26         </varlistentry>
27
28         <varlistentry>
29           <term><filename>conf/</filename></term>
30           <listitem>
31             <para>Contains the configuration files for OpenEmbedded.
32               The <filename>bitbake.conf</filename> is read when
33               <application>BitBake</application> is started and this will
34               include the <filename>local.conf</filename>, the machine and
35               distribution configuration files, among others. These files
36               will be located using the <varname>BBPATH</varname> environment
37               variable as a search path.
38             </para>
39           </listitem>
40         </varlistentry>
41
42         <varlistentry>
43           <term><filename>contrib/</filename></term>
44           <listitem>
45             <para>Contains miscellaneous scripts that do not
46               belong in the other directories.
47             </para>
48           </listitem>
49         </varlistentry>
50
51         <varlistentry>
52           <term><filename>docs/</filename></term>
53           <listitem>
54             <para>Contains the source for the user manual and other
55               documentation files.
56             </para>
57           </listitem>
58         </varlistentry>
59
60         <varlistentry>
61           <term><filename>files/</filename></term>
62           <listitem><para>Contains setup tables for populating
63               the <filename>/dev</filename> directory of various target images.
64           </para></listitem>
65         </varlistentry>
66
67         <varlistentry>
68           <term><filename>packages/</filename></term>
69           <listitem>
70             <para>Conatins all of the
71               <application>BitBake</application> <filename>.bb</filename>
72               files. There is a subdirectory for each task or application
73               and within that subdirectory is
74               a <application>BitBake</application> <filename>.bb</filename> file
75               for each supported version of an application or task.
76             </para>
77           </listitem>
78         </varlistentry>
79
80         <varlistentry>
81           <term><filename>site/</filename></term>
82           <listitem>
83             <para>Contains site configuration files for
84               the <application>autoconf</application>/<application>automake</application>
85               system.
86             </para>
87           </listitem>
88         </varlistentry>
89       </variablelist>
90     </para>
91   </section>
92
93   <section id="metadata_syntax">
94     <title>Syntax</title>
95
96     <para>OpenEmbedded has files ending with <emphasis>.conf</emphasis>,
97     <emphasis>.inc</emphasis>, <emphasis>.bb</emphasis>
98     and<emphasis>.bbclass</emphasis>. The syntax and semantic of these files
99     are best described in the <ulink
100     url="http://bitbake.berlios.de/manual"><application>BitBake</application>
101     manual</ulink>.</para>
102   </section>
103
104   <section id="metadata_classes">
105     <title>Classes</title>
106
107     <para>OpenEmbedded provides special <application>BitBake</application>
108     classes to ease compiling, packaging and other things. FIXME.</para>
109   </section>
110
111   <section id="metadata_writing_data">
112     <title>Writing Meta Data (Adding packages)</title>
113
114     <para>This page will guide you trough the effort of writing a .bb file or
115     <emphasis>recipe</emphasis> in BitBake speak.</para>
116
117     <para>Let's start with the easy stuff, like the package description,
118     license, etc: <screen>
119 DESCRIPTION = "My first application, a really cool app containing lots of foo and bar"
120 LICENSE = "GPLv2"
121 HOMEPAGE = "http://www.host.com/foo/"
122                 </screen> The description and license fields are mandatory, so
123     better check them twice.</para>
124
125     <para>The next step is to specify what the package needs to build and run,
126     the so called <emphasis>dependencies</emphasis>: <screen>
127 DEPENDS = "gtk+"
128 RDEPENDS = "cool-ttf-fonts"
129                 </screen> The package needs gtk+ to build ('DEPENDS') and
130     requires the 'cool-ttf-fonts' package to run ('RDEPENDS'). OE will add
131     run-time dependencies on libraries on its own via the so called
132     <emphasis>shlibs</emphasis>-code, but you need to specify everything other
133     by yourself, which in this case is the 'cool-ttf-fonts' package.</para>
134
135     <para>After entering all this OE will know what to build before trying to
136     build your application, but it doesn't know where to get it yet. So let's
137     add the source location: <screen>
138 SRC_URI = "http://www.host.com/foo/files/${P}.tar.bz2;md5sum=yoursum"
139                 </screen> This will tell the fetcher to where to download the
140     sources from and it will check the integrity using md5sum if you provided
141     the appropriate <emphasis>yoursum</emphasis>. You can make one by doing
142     <screen>md5sum foo-1.9.tar.bz2</screen> and replacing
143     <emphasis>yoursum</emphasis> with the md5sum on your screen. A typical
144     md5sum will look like this: <screen>a6434b0fc8a54c3dec3d6875bf3be8mtn </screen>Notice
145     the <emphasis>${P}</emphasis> variable, that one holds the package name,
146     <emphasis>${PN}</emphasis> in BitBake speak and the package version,
147     <emphasis>${PV}</emphasis> in BitBake speak. It's a short way of writing
148     <emphasis>${PN}-${PV}</emphasis>. Using this notation means you can copy
149     the recipe when a new version is released without having to alter the
150     contents. You do need to check if everything is still correct, because new
151     versions mean new bugs.</para>
152
153     <para>Before we can move to the actual building we need to find out which
154     build system the package is using. If we're lucky, we see a
155     <emphasis>configure</emphasis> file in the build tree this is an indicator
156     that we can <emphasis>inherit autotools</emphasis> if we see a
157     <emphasis>.pro</emphasis> file, it might be qmake, which needs
158     <emphasis>inherit qmake</emphasis>. Virtually all gtk apps use autotools:
159     <screen>
160 inherit autotools pkgconfig
161                 </screen> We are in luck! The package is a well-behaved
162     application using autotools and pkgconfig to configure and build it
163     self.</para>
164
165     <para>Lets start the build: <screen>
166 <command>bitbake</command> foo
167                 </screen> Depending on what you have built before and the
168     speed of your computer this can take a few seconds to a few hours, so be
169     prepared.</para>
170
171     <para>.... some time goes by .....</para>
172
173     <para>Your screen should now have something like this on it: <screen>
174 NOTE: package foo-1.9-r0: task do_build: completed
175 NOTE: package foo-1.9: completed
176 NOTE: build 200605052219: completed
177                 </screen></para>
178
179     <para>All looks well, but wait, let's scroll up: <screen>
180 NOTE: the following files where installed but not shipped:
181     /usr/weirdpath/importantfile.foo
182                 </screen> OE has a standard list of paths which need to be
183     included, but it can't know everything, so we have to tell OE to include
184     that file as well: <screen>
185 FILES_${PN} += "/usr/weirdpath/importantfile.foo"
186                 </screen> It's important to use <emphasis>+=</emphasis> so it
187     will get appended to the standard file-list, not replace the standard
188     one.</para>
189   </section>
190 </chapter>