summaryrefslogtreecommitdiffstats
path: root/handbook/ref-classes.xml
blob: 036044dd28ea50df5203c63241ad5328cffde327 (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
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
<!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

<appendix id='ref-classes'>
<title>Reference: Classes</title>

<para>
    Class files are used to abstract common functionality and share it amongst multiple 
    <filename class="extension">.bb</filename> files. Any metadata usually found in a 
    <filename class="extension">.bb</filename> file can also be placed in a class 
    file. Class files are identified by the extension 
    <filename class="extension">.bbclass</filename> and are usually placed 
    in a <filename class="directory">classes/</filename> directory beneath the 
    <filename class="directory">meta*/</filename> directory or the directory pointed
    by BUILDDIR (e.g. <filename class="directory">build/</filename>)in the same way as
    <filename class="extension">.conf</filename> files in the <filename 
    class="directory">conf</filename> directory. Class files are searched for 
    in BBPATH in the same was as <filename class="extension">.conf</filename> files too.
</para>

<para>
    In most cases inheriting the class is enough to enable its features, although 
    for some classes you may need to set variables and/or override some of the 
    default behaviour.
</para>

<section id='ref-classes-base'>
    <title>The base class - <filename>base.bbclass</filename></title>

    <para>
        The base class is special in that every <filename class="extension">.bb</filename> 
        file inherits it automatically. It contains definitions of standard basic 
        tasks such as fetching, unpacking, configuring (empty by default), compiling 
        (runs any Makefile present), installing (empty by default) and packaging 
        (empty by default). These are often overridden or extended by other classes 
        such as <filename>autotools.bbclass</filename> or 
        <filename>package.bbclass</filename>. The class also contains some commonly
        used functions such as <function>oe_runmake</function>.
    </para>
</section>

<section id='ref-classes-autotools'>
    <title>Autotooled Packages - <filename>autotools.bbclass</filename></title>

    <para>
        Autotools (autoconf, automake, libtool) brings standardisation and this
        class aims to define a set of tasks (configure, compile etc.) that will
        work for all autotooled packages.  It should usualy be enough to define
        a few standard variables as documented in the <link
        linkend='usingpoky-extend-addpkg-autotools'>simple autotools
        example</link> section and then simply "inherit autotools". This class
        can also work with software that emulates autotools.
    </para>

    <para>
        It's useful to have some idea on how the tasks defined by this class work
        and what they do behind the scenes.
    </para>

    <itemizedlist>
      <listitem>
        <para>
            'do_configure' regenearates the configure script (using autoreconf) and
            then launches it with a standard set of arguments used during
            cross-compilation. Additional parameters can be passed to 
            <command>configure</command> through the <glossterm><link 
            linkend='var-EXTRA_OECONF'>EXTRA_OECONF</link></glossterm> variable.
        </para>
      </listitem>
      <listitem>
        <para>
            'do_compile' runs <command>make</command> with arguments specifying 
            the compiler and linker. Additional arguments can be passed through 
            the <glossterm><link linkend='var-EXTRA_OEMAKE'>EXTRA_OEMAKE</link>
            </glossterm> variable.
        </para>
      </listitem>
      <listitem>
        <para>
            'do_install' runs <command>make install</command> passing a DESTDIR 
            option taking its value from the standard <glossterm><link
            linkend='var-DESTDIR'>DESTDIR</link></glossterm> variable.
        </para>
      </listitem>
    </itemizedlist>

</section>

<section id='ref-classes-update-alternatives'>
    <title>Alternatives - <filename>update-alternatives.bbclass</filename></title>

    <para>
        Several programs can fulfill the same or similar function and
        they can be installed with the same name. For example the <command>ar</command> 
        command is available from the "busybox", "binutils" and "elfutils" packages. 
        This class handles the renaming of the binaries so multiple packages 
        can be installed which would otherwise conflict and yet the 
        <command>ar</command> command still works regardless of which are installed
        or subsequently removed. It renames the conflicting binary in each package 
        and symlinks the highest priority binary during installation or removal 
        of packages.

        Four variables control this class:
    </para>


    <variablelist>
    <varlistentry>
    <term>ALTERNATIVE_NAME</term>
    <listitem>
       <para>
            Name of binary which will be replaced (<command>ar</command> in this example)
       </para>
    </listitem>
    </varlistentry>
    <varlistentry>
    <term>ALTERNATIVE_LINK</term>
    <listitem>
        <para>
            Path to resulting binary ("/bin/ar" in this example)
        </para>
    </listitem>
    </varlistentry>
    <varlistentry>
    <term>ALTERNATIVE_PATH</term>
    <listitem>
        <para>
            Path to real binary ("/usr/bin/ar.binutils" in this example)
        </para>
    </listitem>
    </varlistentry>
    <varlistentry>
    <term>ALTERNATIVE_PRIORITY</term>
    <listitem>
        <para>
            Priority of binary, the version with the most features should have the highest priority
        </para>
    </listitem>
    </varlistentry>
    </variablelist>

    <para>
	Currently, only one binary per package is supported.
    </para>
</section>

<section id='ref-classes-update-rc.d'>
    <title>Initscripts - <filename>update-rc.d.bbclass</filename></title>

    <para>
        This class uses update-rc.d to safely install an initscript on behalf of 
        the package. Details such as making sure the initscript is stopped before 
        a package is removed and started when the package is installed are taken 
        care of. Three variables control this class, 
        <link linkend='var-INITSCRIPT_PACKAGES'>INITSCRIPT_PACKAGES</link>, 
        <link linkend='var-INITSCRIPT_NAME'>INITSCRIPT_NAME</link> and
        <link linkend='var-INITSCRIPT_PARAMS'>INITSCRIPT_PARAMS</link>. See the 
        links for details.
    </para>
</section>

<section id='ref-classes-binconfig'>
    <title>Binary config scripts - <filename>binconfig.bbclass</filename></title>

    <para>
        Before pkg-config had become widespread, libraries shipped shell
        scripts to give information about the libraries and include paths needed 
        to build software (usually named 'LIBNAME-config'). This class assists
        any recipe using such scripts.
    </para>

    <para>
        During staging Bitbake installs such scripts into the <filename 
        class="directory">sysroots/</filename> directory. It also changes all
        paths to point into the <filename class="directory">sysroots/</filename>
        directory so all builds which use the script will use the correct 
        directories for the cross compiling layout.
    </para>
</section>

<section id='ref-classes-debian'>
    <title>Debian renaming - <filename>debian.bbclass</filename></title>

    <para>
        This class renames packages so that they follow the Debian naming
        policy, i.e. 'glibc' becomes 'libc6' and 'glibc-devel' becomes
        'libc6-dev'.
    </para>
</section>

<section id='ref-classes-pkgconfig'>
    <title>Pkg-config - <filename>pkgconfig.bbclass</filename></title>

    <para>
        Pkg-config brought standardisation and this class aims to make its
        integration smooth for all libraries which make use of it.
    </para>

    <para>
        During staging Bitbake installs pkg-config data into the <filename 
        class="directory">sysroots/</filename> directory. By making use of
        sysroot functionality within pkgconfig this class no longer has to 
        manipulate the files.
    </para>
</section>

<section id='ref-classes-src-distribute'>
    <title>Distribution of sources - <filename>src_distribute_local.bbclass</filename></title>

    <para>
        Many software licenses require providing the sources for compiled
        binaries. To simplify this process two classes were created:
        <filename>src_distribute.bbclass</filename> and 
        <filename>src_distribute_local.bbclass</filename>.
    </para>

    <para>
        Result of their work are <filename class="directory">tmp/deploy/source/</filename> 
        subdirs with sources sorted by <glossterm><link linkend='var-LICENSE'>LICENSE</link>
        </glossterm> field. If recipe lists few licenses (or has entries like "Bitstream Vera") source archive is put in each
        license dir.
    </para>

    <para>
        Src_distribute_local class has three modes of operating:
    </para>

    <itemizedlist>
        <listitem><para>copy - copies the files to the distribute dir</para></listitem>
        <listitem><para>symlink - symlinks the files to the distribute dir</para></listitem>
        <listitem><para>move+symlink - moves the files into distribute dir, and symlinks them back</para></listitem>
    </itemizedlist>
</section>

<section id='ref-classes-perl'>
    <title>Perl modules - <filename>cpan.bbclass</filename></title>

    <para>
        Recipes for Perl modules are simple - usually needs only
        pointing to source archive and inheriting of proper bbclass.
        Building is split into two methods dependly on method used by
        module authors.
    </para>
    
    <para>
        Modules which use old Makefile.PL based build system require
        using of <filename>cpan.bbclass</filename> in their recipes.
    </para>

    <para>
        Modules which use Build.PL based build system require
        using of <filename>cpan_build.bbclass</filename> in their recipes.
    </para>

</section>

<section id='ref-classes-distutils'>
    <title>Python extensions - <filename>distutils.bbclass</filename></title>

    <para>
        Recipes for Python extensions are simple - they usually only
        require pointing to the source archive and inheriting the proper
        bbclasses.
        Building is split into two methods depending on the build method
        used by the module authors.
    </para>

    <para>
        Extensions which use autotools based build system require use
        of autotools and distutils-base bbclasses in their recipes.
    </para>

    <para>
        Extensions which use distutils build system require use
        of <filename>distutils.bbclass</filename> in their recipes.
    </para>

</section>

<section id='ref-classes-devshell'>
    <title>Developer Shell - <filename>devshell.bbclass</filename></title>

    <para>
        This class adds the devshell task. Its usually up to distribution policy 
        to include this class (Poky does). See the <link 
        linkend='platdev-appdev-devshell'>developing with 'devshell' section</link> 
        for more information about using devshell.
    </para>

</section>

<section id='ref-classes-package'>
    <title>Packaging - <filename>package*.bbclass</filename></title>

    <para>
        The packaging classes add support for generating packages from a builds
        output. The core generic functionality is in
        <filename>package.bbclass</filename>, code specific to particular package
        types is contained in various sub classes such as
        <filename>package_deb.bbclass</filename>, <filename>package_ipk.bbclass</filename>
        and <filename>package_rpm.bbclass</filename>. Most users will
        want one or more of these classes and this is controlled by the <glossterm>
        <link linkend='var-PACKAGE_CLASSES'>PACKAGE_CLASSES</link></glossterm> 
        variable. The first class listed in this  variable will be used for image 
        generation. Since images are generated from packages a packaging class is 
        needed to enable image generation.
    </para>

</section>

<section id='ref-classes-kernel'>
    <title>Building kernels - <filename>kernel.bbclass</filename></title>

    <para>
        This class handles building of Linux kernels and the class contains code to know how to build both 2.4 and 2.6 kernel trees. All needed headers are
        staged into <glossterm><link
                linkend='var-STAGING_KERNEL_DIR'>STAGING_KERNEL_DIR</link></glossterm>
        directory to allow building of out-of-tree modules using <filename>module.bbclass</filename>.
    </para>
    <para>
        This means that each kernel module built is packaged separately and inter-module dependencies are
        created by parsing the <command>modinfo</command> output. If all modules are
        required then installing the "kernel-modules" package will install all
        packages with modules and various other kernel packages such as "kernel-vmlinux".
    </para>

    <para>
        Various other classes are used by the kernel and module classes internally including 
        <filename>kernel-arch.bbclass</filename>, <filename>module_strip.bbclass</filename>, 
        <filename>module-base.bbclass</filename> and <filename>linux-kernel-base.bbclass</filename>.
    </para>
</section>

<section id='ref-classes-image'>
    <title>Creating images - <filename>image.bbclass</filename> and <filename>rootfs*.bbclass</filename></title>

    <para>
        Those classes add support for creating images in many formats. First the
        rootfs is created from packages by one of the <filename>rootfs_*.bbclass</filename> 
        files (depending on package format used) and then image is created.

        The <glossterm><link
                linkend='var-IMAGE_FSTYPES'>IMAGE_FSTYPES</link></glossterm>
        variable controls which types of image to generate.
        
        The list of packages to install into the image is controlled by the
        <glossterm><link
                linkend='var-IMAGE_INSTALL'>IMAGE_INSTALL</link></glossterm>
        variable.
    </para>
</section>

<section id='ref-classes-sanity'>
    <title>Host System sanity checks - <filename>sanity.bbclass</filename></title>

    <para>
        This class checks prerequisite software is present to
        notify the users problems that will affect their build. It also
        performs basic checks of the user configuration from local.conf to
        prevent common mistakes resulting in build failures. It's usually up to
        distribution policy whether to include this class (Poky does).
    </para>
</section>

<section id='ref-classes-insane'>
    <title>Generated output quality assurance checks - <filename>insane.bbclass</filename></title>

    <para>
        This class adds a step to package generation which sanity checks the
        packages generated by Poky. There are an ever increasing range of checks
        it performs, checking for common problems which break builds/packages/images,
        see the bbclass file for more information. It's usually up to distribution
        policy whether to include this class (Poky does).
    </para>
</section>

<section id='ref-classes-siteinfo'>
    <title>Autotools configuration data cache - <filename>siteinfo.bbclass</filename></title>

    <para>
        Autotools can require tests which have to execute on the target hardware.
        Since this isn't possible in general when cross compiling, siteinfo is
        used to provide cached test results so these tests can be skipped over but
        the correct values used. The <link linkend='structure-meta-site'>meta/site directory</link>
        contains test results sorted into different categories like architecture, endianess and
        the libc used. Siteinfo provides a list of files containing data relevant to 
        the current build in the <glossterm><link linkend='var-CONFIG_SITE'>CONFIG_SITE
        </link></glossterm> variable which autotools will automatically pick up.
    </para>
    <para>
        The class also provides variables like <glossterm><link 
        linkend='var-SITEINFO_ENDIANESS'>SITEINFO_ENDIANESS</link></glossterm> 
        and <glossterm><link linkend='var-SITEINFO_BITS'>SITEINFO_BITS</link>
        </glossterm> which can be used elsewhere in the metadata.
    </para>
    <para>
        This class is included from <filename>base.bbclass</filename> and is hence always active.
    </para>
</section>

<section id='ref-classes-others'>
    <title>Other Classes</title>

    <para>
        Only the most useful/important classes are covered here but there are 
        others, see the <filename class="directory">meta/classes</filename> directory for the rest. 
    </para>
</section>

<!-- Undocumented classes are:
        base_srpm.bbclass
        bootimg.bbclass
        ccache.inc
        ccdv.bbclass
        cmake.bbclass
        cml1.bbclass
        cross.bbclass
        flow-lossage.bbclass
        gconf.bbclass
        gettext.bbclass
        gnome.bbclass
        gtk-icon-cache.bbclass
        icecc.bbclass
        lib_package.bbclass
        mirrors.bbclass
        mozilla.bbclass
        multimachine.bbclass
        native.bbclass
        oelint.bbclass
        patch.bbclass
        patcher.bbclass
        pkg_distribute.bbclass
        pkg_metainfo.bbclass
        poky.bbclass
        rm_work.bbclass
        rpm_core.bbclass
        scons.bbclass
        sdk.bbclass
        sdl.bbclass
        sip.bbclass
        sourcepkg.bbclass
        srec.bbclass
        syslinux.bbclass
        tinderclient.bbclass
        tmake.bbclass
        utils.bbclass
        xfce.bbclass
        xlibs.bbclass
-->


</appendix>
<!-- 
vim: expandtab tw=80 ts=4 
-->