summaryrefslogtreecommitdiffstats
path: root/handbook/ref-classes.xml
diff options
context:
space:
mode:
Diffstat (limited to 'handbook/ref-classes.xml')
-rw-r--r--handbook/ref-classes.xml460
1 files changed, 460 insertions, 0 deletions
diff --git a/handbook/ref-classes.xml b/handbook/ref-classes.xml
new file mode 100644
index 0000000000..1cef9012c1
--- /dev/null
+++ b/handbook/ref-classes.xml
@@ -0,0 +1,460 @@
1<!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
3
4<appendix id='ref-classes'>
5<title>Reference: Classes</title>
6
7<para>
8 Class files are used to abstract common functionality and share it amongst multiple
9 <filename class="extension">.bb</filename> files. Any metadata usually found in a
10 <filename class="extension">.bb</filename> file can also be placed in a class
11 file. Class files are identified by the extension
12 <filename class="extension">.bbclass</filename> and are usually placed
13 in a <filename class="directory">classes/</filename> directory beneath the
14 <filename class="directory">meta/</filename> directory or the <filename
15 class="directory">build/</filename> directory in the same way as <filename
16 class="extension">.conf</filename> files in the <filename
17 class="directory">conf</filename> directory. Class files are searched for
18 in BBPATH in the same was as <filename class="extension">.conf</filename> files too.
19</para>
20
21<para>
22 In most cases inheriting the class is enough to enable its features, although
23 for some classes you may need to set variables and/or override some of the
24 default behaviour.
25</para>
26
27<section id='ref-classes-base'>
28 <title>The base class - <filename>base.bbclass</filename></title>
29
30 <para>
31 The base class is special in that every <filename class="extension">.bb</filename>
32 file inherits it automatically. It contains definitions of standard basic
33 tasks such as fetching, unpacking, configuring (empty by default), compiling
34 (runs any Makefile present), installing (empty by default) and packaging
35 (empty by default). These are often overridden or extended by other classes
36 such as <filename>autotools.bbclass</filename> or
37 <filename>package.bbclass</filename>. The class contains some commonly
38 some commonly used functions such as <function>oe_libinstall</function>
39 and <function>oe_runmake</function>. The end of the class file has a
40 list of standard mirrors for software projects for use by the fetcher code.
41 </para>
42</section>
43
44<section id='ref-classes-autotools'>
45 <title>Autotooled Packages - <filename>autotools.bbclass</filename></title>
46
47 <para>
48 Autotools (autoconf, automake, libtool) brings standardisation and this
49 class aims to define a set of tasks (configure, compile etc.) that will
50 work for all autotooled packages. It should usualy be enough to define
51 a few standard variables as documented in the <link
52 linkend='usingpoky-extend-addpkg-autotools'>simple autotools
53 example</link> section and then simply "inherit autotools". This class
54 can also work with software that emulates autotools.
55 </para>
56
57 <para>
58 Its useful to have some idea of the tasks this class defines work and
59 what they do behind the scenes.
60 </para>
61
62 <itemizedlist>
63 <listitem>
64 <para>
65 'do_configure' regenearates the configure script and
66 then launches it with a standard set of arguments used during
67 cross-compilation. Additional parameters can be passed to
68 <command>configure</command> through the <glossterm><link
69 linkend='var-EXTRA_OECONF'>EXTRA_OECONF</link></glossterm> variable.
70 </para>
71 </listitem>
72 <listitem>
73 <para>
74 'do_compile' runs <command>make</command> with arguments specifying
75 the compiler and linker. Additional arguments can be passed through
76 the <glossterm><link linkend='var-EXTRA_OEMAKE'>EXTRA_OEMAKE</link>
77 </glossterm> variable.
78 </para>
79 </listitem>
80 <listitem>
81 <para>
82 'do_install' runs <command>make install</command> passing a DESTDIR
83 option taking its value from the standard <glossterm><link
84 linkend='var-DESTDIR'>DESTDIR</link></glossterm> variable.
85 </para>
86 </listitem>
87 </itemizedlist>
88
89 <para>
90 By default the class does not stage headers and libraries so
91 the recipe author needs to add their own <function>do_stage()</function>
92 task. For typical recipes the following example code will usually be
93 enough:
94 <programlisting>
95do_stage() {
96autotools_stage_all
97}</programlisting>
98 </para>
99</section>
100
101<section id='ref-classes-update-alternatives'>
102 <title>Alternatives - <filename>update-alternatives.bbclass</filename></title>
103
104 <para>
105 Several programs can fulfill the same or similar function and
106 they can be installed with the same name. For example the <command>ar</command>
107 command is available from the "busybox", "binutils" and "elfutils" packages.
108 This class handles the renaming of the binaries so multiple packages
109 can be installed which would otherwise conflict and yet the
110 <command>ar</command> command still works regardless of which are installed
111 or subsequently removed. It renames the conflicting binary in each package
112 and symlinks the highest priority binary during installation or removal
113 of packages.
114
115 Four variables control this class:
116 </para>
117
118
119 <variablelist>
120 <varlistentry>
121 <term>ALTERNATIVE_NAME</term>
122 <listitem>
123 <para>
124 Name of binary which will be replaced (<command>ar</command> in this example)
125 </para>
126 </listitem>
127 </varlistentry>
128 <varlistentry>
129 <term>ALTERNATIVE_LINK</term>
130 <listitem>
131 <para>
132 Path to resulting binary ("/bin/ar" in this example)
133 </para>
134 </listitem>
135 </varlistentry>
136 <varlistentry>
137 <term>ALTERNATIVE_PATH</term>
138 <listitem>
139 <para>
140 Path to real binary ("/usr/bin/ar.binutils" in this example)
141 </para>
142 </listitem>
143 </varlistentry>
144 <varlistentry>
145 <term>ALTERNATIVE_PRIORITY</term>
146 <listitem>
147 <para>
148 Priority of binary, the version with the most features should have the highest priority
149 </para>
150 </listitem>
151 </varlistentry>
152 </variablelist>
153</section>
154
155<section id='ref-classes-update-rc.d'>
156 <title>Initscripts - <filename>update-rc.d.bbclass</filename></title>
157
158 <para>
159 This class uses update-rc.d to safely install an initscript on behalf of
160 the package. Details such as making sure the initscript is stopped before
161 a package is removed and started when the package is installed are taken
162 care of. Three variables control this class,
163 <link linkend='var-INITSCRIPT_PACKAGES'>INITSCRIPT_PACKAGES</link>,
164 <link linkend='var-INITSCRIPT_NAME'>INITSCRIPT_NAME</link> and
165 <link linkend='var-INITSCRIPT_PARAMS'>INITSCRIPT_PARAMS</link>. See the
166 links for details.
167 </para>
168</section>
169
170<section id='ref-classes-binconfig'>
171 <title>Binary config scripts - <filename>binconfig.bbclass</filename></title>
172
173 <para>
174 Before pkg-config became widespread, libraries shipped shell
175 scripts to give information about the libraries and include paths needed
176 to build software (usually named 'LIBNAME-config'). This class assists
177 any recipe using such scripts.
178 </para>
179
180 <para>
181 During staging Bitbake installs such scripts into the <filename
182 class="directory">staging/</filename> directory. It also changes all
183 paths to point into the <filename class="directory">staging/</filename>
184 directory so all builds which use the script will use the correct
185 directories for the cross compiling layout.
186 </para>
187</section>
188
189<section id='ref-classes-debian'>
190 <title>Debian renaming - <filename>debian.bbclass</filename></title>
191
192 <para>
193 This class renames packages so that they follow the Debian naming
194 policy, i.e. 'glibc' becomes 'libc6' and 'glibc-devel' becomes
195 'libc6-dev'.
196 </para>
197</section>
198
199<section id='ref-classes-pkgconfig'>
200 <title>Pkg-config - <filename>pkgconfig.bbclass</filename></title>
201
202 <para>
203 Pkg-config brought standardisation and this class aims to make its
204 integration smooth for all libraries which make use of it.
205 </para>
206
207 <para>
208 During staging Bitbake installs pkg-config data into the <filename
209 class="directory">staging/</filename> directory. By making use of
210 sysroot functionality within pkgconfig this class no longer has to
211 manipulate the files.
212 </para>
213</section>
214
215<section id='ref-classes-src-distribute'>
216 <title>Distribution of sources - <filename>src_distribute_local.bbclass</filename></title>
217
218 <para>
219 Many software licenses require providing the sources for compiled
220 binaries. To simplify this process two classes were created:
221 <filename>src_distribute.bbclass</filename> and
222 <filename>src_distribute_local.bbclass</filename>.
223 </para>
224
225 <para>
226 Result of their work are <filename class="directory">tmp/deploy/source/</filename>
227 subdirs with sources sorted by <glossterm><link linkend='var-LICENSE'>LICENSE</link>
228 </glossterm> field. If recipe lists few licenses (or has entries like "Bitstream Vera") source archive is put in each
229 license dir.
230 </para>
231
232 <para>
233 Src_distribute_local class has three modes of operating:
234 </para>
235
236 <itemizedlist>
237 <listitem><para>copy - copies the files to the distribute dir</para></listitem>
238 <listitem><para>symlink - symlinks the files to the distribute dir</para></listitem>
239 <listitem><para>move+symlink - moves the files into distribute dir, and symlinks them back</para></listitem>
240 </itemizedlist>
241</section>
242
243<section id='ref-classes-perl'>
244 <title>Perl modules - <filename>cpan.bbclass</filename></title>
245
246 <para>
247 Recipes for Perl modules are simple - usually needs only
248 pointing to source archive and inheriting of proper bbclass.
249 Building is split into two methods dependly on method used by
250 module authors.
251 </para>
252
253 <para>
254 Modules which use old Makefile.PL based build system require
255 using of <filename>cpan.bbclass</filename> in their recipes.
256 </para>
257
258 <para>
259 Modules which use Build.PL based build system require
260 using of <filename>cpan_build.bbclass</filename> in their recipes.
261 </para>
262
263</section>
264
265<section id='ref-classes-distutils'>
266 <title>Python extensions - <filename>distutils.bbclass</filename></title>
267
268 <para>
269 Recipes for Python extensions are simple - usually needs only
270 pointing to source archive and inheriting of proper bbclass.
271 Building is split into two methods dependly on method used by
272 module authors.
273 </para>
274
275 <para>
276 Extensions which use autotools based build system require using
277 of autotools and distutils-base bbclasses in their recipes.
278 </para>
279
280 <para>
281 Extensions which use distutils build system require using
282 of <filename>distutils.bbclass</filename> in their recipes.
283 </para>
284
285</section>
286
287<section id='ref-classes-devshell'>
288 <title>Developer Shell - <filename>devshell.bbclass</filename></title>
289
290 <para>
291 This class adds the devshell task. Its usually up to distribution policy
292 to include this class (Poky does). See the <link
293 linkend='platdev-appdev-devshell'>developing with 'devshell' section</link>
294 for more information about using devshell.
295 </para>
296
297</section>
298
299<section id='ref-classes-package'>
300 <title>Packaging - <filename>package*.bbclass</filename></title>
301
302 <para>
303 The packaging classes add support for generating packages from the output
304 from builds. The core generic functionality is in
305 <filename>package.bbclass</filename>, code specific to particular package
306 types is contained in various sub classes such as
307 <filename>package_deb.bbclass</filename> and <filename>package_ipk.bbclass</filename>.
308 Most users will
309 want one or more of these classes and this is controlled by the <glossterm>
310 <link linkend='var-PACKAGE_CLASSES'>PACKAGE_CLASSES</link></glossterm>
311 variable. The first class listed in this variable will be used for image
312 generation. Since images are generated from packages a packaging class is
313 needed to enable image generation.
314 </para>
315
316</section>
317
318<section id='ref-classes-kernel'>
319 <title>Building kernels - <filename>kernel.bbclass</filename></title>
320
321 <para>
322 This class handle 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
323 staged into <glossterm><link
324 linkend='var-STAGING_KERNEL_DIR'>STAGING_KERNEL_DIR</link></glossterm>
325 directory to allow building of out-of-tree modules using <filename>module.bbclass</filename>.
326 </para>
327 <para>
328 The means that each kerel module built is packaged separately and inter-modules dependencies are
329 created by parsing the <command>modinfo</command> output. If all modules are
330 required then installing "kernel-modules" package will install all
331 packages with modules and various other kernel packages such as "kernel-vmlinux" are also generated.
332 </para>
333
334 <para>
335 Various other classes are used by the kernel and module classes internally including
336 <filename>kernel-arch.bbclass</filename>, <filename>module_strip.bbclass</filename>,
337 <filename>module-base.bbclass</filename> and <filename>linux-kernel-base.bbclass</filename>.
338 </para>
339</section>
340
341<section id='ref-classes-image'>
342 <title>Creating images - <filename>image.bbclass</filename> and <filename>rootfs*.bbclass</filename></title>
343
344 <para>
345 Those classes add support for creating images in many formats. First the
346 rootfs is created from packages by one of the <filename>rootfs_*.bbclass</filename>
347 files (depending on package format used) and then image is created.
348
349 The <glossterm><link
350 linkend='var-IMAGE_FSTYPES'>IMAGE_FSTYPES</link></glossterm>
351 variable controls which types of image to generate.
352
353 The list of packages to install into the image is controlled by the
354 <glossterm><link
355 linkend='var-IMAGE_INSTALL'>IMAGE_INSTALL</link></glossterm>
356 variable.
357 </para>
358</section>
359
360<section id='ref-classes-sanity'>
361 <title>Host System sanity checks - <filename>sanity.bbclass</filename></title>
362
363 <para>
364 This class checks prerequisite software is present to try and identify
365 and notify the user of problems which will affect their build. It also
366 performs basic checks of the users configuration from local.conf to
367 prevent common mistakes and resulting build failures. Its usually up to
368 distribution policy to include this class (Poky does).
369 </para>
370</section>
371
372<section id='ref-classes-insane'>
373 <title>Generated output quality assurance checks - <filename>insane.bbclass</filename></title>
374
375 <para>
376 This class adds a step to package generation which sanity checks the
377 packages generated by Poky. There are an ever increasing range of checks
378 this makes, checking for common problems which break builds/packages/images,
379 see the bbclass file for more information. Its usually up to distribution
380 policy to include this class (Poky doesn't at the time of writing but plans
381 to soon).
382 </para>
383</section>
384
385<section id='ref-classes-siteinfo'>
386 <title>Autotools configuration data cache - <filename>siteinfo.bbclass</filename></title>
387
388 <para>
389 Autotools can require tests which have to execute on the target hardware.
390 Since this isn't possible in general when cross compiling, siteinfo is
391 used to provide cached test results so these tests can be skipped over but
392 the correct values used. The <link linkend='structure-meta-site'>meta/site directory</link>
393 contains test results sorted into different categories like architecture, endianess and
394 the libc used. Siteinfo provides a list of files containing data relevant to
395 the current build in the <glossterm><link linkend='var-CONFIG_SITE'>CONFIG_SITE
396 </link></glossterm> variable which autotools will automatically pick up.
397 </para>
398 <para>
399 The class also provides variables like <glossterm><link
400 linkend='var-SITEINFO_ENDIANESS'>SITEINFO_ENDIANESS</link></glossterm>
401 and <glossterm><link linkend='var-SITEINFO_BITS'>SITEINFO_BITS</link>
402 </glossterm> which can be used elsewhere in the metadata.
403 </para>
404 <para>
405 This class is included from <filename>base.bbclass</filename> and is hence always active.
406 </para>
407</section>
408
409<section id='ref-classes-others'>
410 <title>Other Classes</title>
411
412 <para>
413 Only the most useful/important classes are covered here but there are
414 others, see the <filename class="directory">meta/classes</filename> directory for the rest.
415 </para>
416</section>
417
418<!-- Undocumented classes are:
419 base_srpm.bbclass
420 bootimg.bbclass
421 ccache.inc
422 ccdv.bbclass
423 cml1.bbclass
424 cross.bbclass
425 flow-lossage.bbclass
426 gconf.bbclass
427 gettext.bbclass
428 gnome.bbclass
429 gtk-icon-cache.bbclass
430 icecc.bbclass
431 lib_package.bbclass
432 mozilla.bbclass
433 multimachine.bbclass
434 native.bbclass
435 oelint.bbclass
436 patch.bbclass
437 patcher.bbclass
438 pkg_distribute.bbclass
439 pkg_metainfo.bbclass
440 poky.bbclass
441 rm_work.bbclass
442 rpm_core.bbclass
443 scons.bbclass
444 sdk.bbclass
445 sdl.bbclass
446 sip.bbclass
447 sourcepkg.bbclass
448 srec.bbclass
449 syslinux.bbclass
450 tinderclient.bbclass
451 tmake.bbclass
452 xfce.bbclass
453 xlibs.bbclass
454-->
455
456
457</appendix>
458<!--
459vim: expandtab tw=80 ts=4
460-->