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