summaryrefslogtreecommitdiff
path: root/docs/usermanual/chapters/metadata.xml
blob: 54fb523553b4857c057a5b95468310c63a455268 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
<?xml version="1.0" encoding="UTF-8"?>
<chapter id="chapter_metadata">
  <title>Metadata</title>

  <section id="metadata_file_layout">
    <title>File Layout</title>

    <para>The OpenEmbedded
      directory, <filename>$OEBASE/openembedded/</filename>, has seven
      directories, three of which hold
      <application>BitBake</application> metadata.

      <variablelist>
        <varlistentry>
          <term><filename>classes/</filename></term>
          <listitem>
            <para>Contains <application>BitBake</application>
              <filename>.bbclass</filename> files. These classes can
              be inherited by other <application>BitBake</application>
              files. Every <application>BitBake</application>
              <filename>.bb</filename> file automatically inherits the
              <filename>base.bbclass</filename>. <varname>BBPATH</varname>
              is used to find the <filename>.bbclass</filename> files.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><filename>conf/</filename></term>
          <listitem>
            <para>Contains the configuration files for OpenEmbedded.
              The <filename>bitbake.conf</filename> is read when
              <application>BitBake</application> is started and this will
              include the <filename>local.conf</filename>, the machine and
              distribution configuration files, among others. These files
              will be located using the <varname>BBPATH</varname> environment
              variable as a search path.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><filename>contrib/</filename></term>
          <listitem>
            <para>Contains miscellaneous scripts that do not
              belong in the other directories.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><filename>docs/</filename></term>
          <listitem>
            <para>Contains the source for the user manual and other
              documentation files.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><filename>files/</filename></term>
          <listitem><para>Contains setup tables for populating
              the <filename>/dev</filename> directory of various target images.
          </para></listitem>
        </varlistentry>

        <varlistentry>
          <term><filename>packages/</filename></term>
          <listitem>
            <para>Conatins all of the
              <application>BitBake</application> <filename>.bb</filename>
              files. There is a subdirectory for each task or application
              and within that subdirectory is
              a <application>BitBake</application> <filename>.bb</filename> file
              for each supported version of an application or task.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><filename>site/</filename></term>
          <listitem>
            <para>Contains site configuration files for
              the <application>autoconf</application>/<application>automake</application>
              system.
            </para>
          </listitem>
        </varlistentry>
      </variablelist>
    </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>