summaryrefslogtreecommitdiffstats
path: root/documentation/ref-manual/ref-classes.xml
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/ref-manual/ref-classes.xml')
-rw-r--r--documentation/ref-manual/ref-classes.xml1104
1 files changed, 1104 insertions, 0 deletions
diff --git a/documentation/ref-manual/ref-classes.xml b/documentation/ref-manual/ref-classes.xml
new file mode 100644
index 0000000000..27edfde33d
--- /dev/null
+++ b/documentation/ref-manual/ref-classes.xml
@@ -0,0 +1,1104 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4
5<chapter id='ref-classes'>
6<title>Classes</title>
7
8<para>
9 Class files are used to abstract common functionality and share it amongst multiple
10 <filename>.bb</filename> files.
11 Any <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink> usually
12 found in a <filename>.bb</filename> file can also be placed in a class
13 file.
14 Class files are identified by the extension <filename>.bbclass</filename> and are usually placed
15 in a <filename>classes/</filename> directory beneath the
16 <filename>meta*/</filename> directory found in the
17 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
18 Class files can also be pointed to by
19 <link linkend='var-BUILDDIR'><filename>BUILDDIR</filename></link>
20 (e.g. <filename>build/</filename>) in the same way as
21 <filename>.conf</filename> files in the <filename>conf</filename> directory.
22 Class files are searched for in <link linkend='var-BBPATH'><filename>BBPATH</filename></link>
23 using the same method by which <filename>.conf</filename> files are searched.
24</para>
25
26<para>
27 In most cases inheriting the class is enough to enable its features, although
28 for some classes you might need to set variables or override some of the
29 default behavior.
30</para>
31
32<para>
33 This chapter discusses only the most useful and important classes.
34 Other classes do exist within the <filename>meta/classes</filename>
35 directory in the
36 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
37 You can reference the <filename>.bbclass</filename> files directly
38 for more information.
39</para>
40
41<section id='ref-classes-base'>
42 <title>The base Class - <filename>base.bbclass</filename></title>
43
44 <para>
45 The base class is special in that every <filename>.bb</filename>
46 file inherits it automatically.
47 This class contains definitions for standard basic
48 tasks such as fetching, unpacking, configuring (empty by default), compiling
49 (runs any <filename>Makefile</filename> present), installing (empty by default) and packaging
50 (empty by default).
51 These classes are often overridden or extended by other classes
52 such as <filename>autotools.bbclass</filename> or <filename>package.bbclass</filename>.
53 The class also contains some commonly used functions such as <filename>oe_runmake</filename>.
54 </para>
55</section>
56
57<section id='ref-classes-autotools'>
58 <title>Autotooled Packages - <filename>autotools.bbclass</filename></title>
59
60 <para>
61 Autotools (<filename>autoconf</filename>, <filename>automake</filename>,
62 and <filename>libtool</filename>) bring standardization.
63 This class defines a set of tasks (configure, compile etc.) that
64 work for all Autotooled packages.
65 It should usually be enough to define a few standard variables
66 and then simply <filename>inherit autotools</filename>.
67 This class can also work with software that emulates Autotools.
68 For more information, see the
69 "<ulink url='&YOCTO_DOCS_DEV_URL;#usingpoky-extend-addpkg-autotools'>Autotooled Package</ulink>"
70 section in the Yocto Project Development Manual.
71 </para>
72
73 <para>
74 It's useful to have some idea of how the tasks defined by this class work
75 and what they do behind the scenes.
76 <itemizedlist>
77 <listitem><para><filename>do_configure</filename> &dash; Regenerates the
78 configure script (using <filename>autoreconf</filename>) and then launches it
79 with a standard set of arguments used during cross-compilation.
80 You can pass additional parameters to <filename>configure</filename> through the
81 <filename><link linkend='var-EXTRA_OECONF'>EXTRA_OECONF</link></filename> variable.
82 </para></listitem>
83 <listitem><para><filename>do_compile</filename> &dash; Runs <filename>make</filename> with
84 arguments that specify the compiler and linker.
85 You can pass additional arguments through
86 the <filename><link linkend='var-EXTRA_OEMAKE'>EXTRA_OEMAKE</link></filename> variable.
87 </para></listitem>
88 <listitem><para><filename>do_install</filename> &dash; Runs <filename>make install</filename>
89 and passes in
90 <filename>${</filename><link linkend='var-D'><filename>D</filename></link><filename>}</filename>
91 as <filename>DESTDIR</filename>.
92 </para></listitem>
93 </itemizedlist>
94 </para>
95</section>
96
97<section id='ref-classes-update-alternatives'>
98 <title>Alternatives - <filename>update-alternatives.bbclass</filename></title>
99
100 <para>
101 This class helps the alternatives system when multiple sources provide
102 the same command.
103 This situation occurs when several programs that have the same or
104 similar function are installed with the same name.
105 For example, the <filename>ar</filename> command is available from the
106 <filename>busybox</filename>, <filename>binutils</filename> and
107 <filename>elfutils</filename> packages.
108 The <filename>update-alternatives.bbclass</filename> class handles
109 renaming the binaries so that multiple packages can be installed
110 without conflicts.
111 The <filename>ar</filename> command still works regardless of which
112 packages are installed or subsequently removed.
113 The class renames the conflicting binary in each package and symlinks
114 the highest priority binary during installation or removal of packages.
115 </para>
116
117 <para>
118 To use this class, you need to define a number of variables:
119 <itemizedlist>
120 <listitem><para><link linkend='var-ALTERNATIVE'><filename>ALTERNATIVE</filename></link>
121 </para></listitem>
122 <listitem><para><link linkend='var-ALTERNATIVE_LINK_NAME'><filename>ALTERNATIVE_LINK_NAME</filename></link>
123 </para></listitem>
124 <listitem><para><link linkend='var-ALTERNATIVE_TARGET'><filename>ALTERNATIVE_TARGET</filename></link>
125 </para></listitem>
126 <listitem><para><link linkend='var-ALTERNATIVE_PRIORITY'><filename>ALTERNATIVE_PRIORITY</filename></link>
127 </para></listitem>
128 </itemizedlist>
129 These variables list alternative commands needed by a package,
130 provide pathnames for links, default links for targets, and
131 so forth.
132 For details on how to use this class, see the comments in the
133 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta/classes/update-alternatives.bbclass'><filename>update-alternatives.bbclass</filename></ulink>.
134 </para>
135
136 <note>
137 You can use the <filename>update-alternatives</filename> command
138 directly in your recipes.
139 However, this class simplifies things in most cases.
140 </note>
141</section>
142
143<section id='ref-classes-update-rc.d'>
144 <title>Initscripts - <filename>update-rc.d.bbclass</filename></title>
145
146 <para>
147 This class uses <filename>update-rc.d</filename> to safely install an
148 initialization script on behalf of the package.
149 The OpenEmbedded build system takes care of details such as making sure the script is stopped before
150 a package is removed and started when the package is installed.
151 Three variables control this class:
152 <filename><link linkend='var-INITSCRIPT_PACKAGES'>INITSCRIPT_PACKAGES</link></filename>,
153 <filename><link linkend='var-INITSCRIPT_NAME'>INITSCRIPT_NAME</link></filename> and
154 <filename><link linkend='var-INITSCRIPT_PARAMS'>INITSCRIPT_PARAMS</link></filename>.
155 See the variable links for details.
156 </para>
157</section>
158
159<section id='ref-classes-binconfig'>
160 <title><filename>binconfig.bbclass</filename></title>
161
162 <para>
163 This class helps to correct paths in shell scripts.
164 </para>
165
166 <para>
167 Before <filename>pkg-config</filename> had become widespread, libraries
168 shipped shell scripts to give information about the libraries and
169 include paths needed to build software (usually named
170 <filename>LIBNAME-config</filename>).
171 This class assists any recipe using such scripts.
172 </para>
173
174 <para>
175 During staging, the OpenEmbedded build system installs such scripts
176 into the <filename>sysroots/</filename> directory.
177 Inheriting this class results in all paths in these scripts being
178 changed to point into the <filename>sysroots/</filename> directory so
179 that all builds that use the script use the correct directories
180 for the cross compiling layout.
181 See the
182 <link linkend='var-BINCONFIG_GLOB'><filename>BINCONFIG_GLOB</filename></link>
183 variable for more information.
184 </para>
185</section>
186
187<section id='ref-classes-debian'>
188 <title>Debian Renaming - <filename>debian.bbclass</filename></title>
189
190 <para>
191 This class renames packages so that they follow the Debian naming
192 policy (i.e. <filename>eglibc</filename> becomes <filename>libc6</filename>
193 and <filename>eglibc-devel</filename> becomes <filename>libc6-dev</filename>.)
194 </para>
195</section>
196
197<section id='ref-classes-pkgconfig'>
198 <title>Pkg-config - <filename>pkgconfig.bbclass</filename></title>
199
200 <para>
201 <filename>pkg-config</filename> provides a standard way to get
202 header and library information.
203 This class aims to smooth integration of
204 <filename>pkg-config</filename> into libraries that use it.
205 </para>
206
207 <para>
208 During staging, BitBake installs <filename>pkg-config</filename> data into the
209 <filename>sysroots/</filename> directory.
210 By making use of sysroot functionality within <filename>pkg-config</filename>,
211 this class no longer has to manipulate the files.
212 </para>
213</section>
214
215<section id='ref-classes-archiver'>
216 <title>Archiving Sources - <filename>archive*.bbclass</filename></title>
217
218 <para>
219 Many software licenses require that source code and other materials be
220 released with the binaries.
221 To help with that task, the following classes are provided:
222 <itemizedlist>
223 <listitem><filename>archive-original-sources.bbclass</filename></listitem>
224 <listitem><filename>archive-patched-sources.bbclass</filename></listitem>
225 <listitem><filename>archive-configured-sources.bbclass</filename></listitem>
226 <listitem><filename>archiver.bbclass</filename></listitem>
227 </itemizedlist>
228 </para>
229
230 <para>
231 For more details on the source archiver, see the
232 "<ulink url='&YOCTO_DOCS_DEV_URL;#maintaining-open-source-license-compliance-during-your-products-lifecycle'>Maintaining Open Source License Compliance During Your Product's Lifecycle</ulink>"
233 section in the Yocto Project Development Manual.
234 </para>
235</section>
236
237<section id='ref-classes-perl'>
238 <title>Perl Modules - <filename>cpan.bbclass</filename></title>
239
240 <para>
241 Recipes for Perl modules are simple.
242 These recipes usually only need to point to the source's archive and then inherit the
243 proper <filename>.bbclass</filename> file.
244 Building is split into two methods depending on which method the module authors used.
245 <itemizedlist>
246 <listitem><para>Modules that use old
247 <filename>Makefile.PL</filename>-based build system require
248 <filename>cpan.bbclass</filename> in their recipes.
249 </para></listitem>
250 <listitem><para>Modules that use
251 <filename>Build.PL</filename>-based build system require
252 using <filename>cpan_build.bbclass</filename> in their recipes.
253 </para></listitem>
254 </itemizedlist>
255 </para>
256</section>
257
258<section id='ref-classes-distutils'>
259 <title>Python Extensions - <filename>distutils.bbclass</filename></title>
260
261 <para>
262 Recipes for Python extensions are simple.
263 These recipes usually only need to point to the source's archive and then inherit
264 the proper <filename>.bbclass</filename> file.
265 Building is split into two methods depending on which method the module authors used.
266 <itemizedlist>
267 <listitem><para>Extensions that use an Autotools-based build system
268 require Autotools and
269 <filename>distutils</filename>-based
270 <filename>.bbclasse</filename> files in their recipes.
271 </para></listitem>
272 <listitem><para>Extensions that use
273 <filename>distutils</filename>-based build systems require
274 <filename>distutils.bbclass</filename> in their recipes.
275 </para></listitem>
276 </itemizedlist>
277 </para>
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 <filename>devshell</filename> task.
285 Distribution policy dictates whether to include this class.
286 See the
287 "<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-appdev-devshell'>Using a Development Shell</ulink>" section
288 in the Yocto Project Development Manual for more information about using <filename>devshell</filename>.
289 </para>
290</section>
291
292<section id='ref-classes-packagegroup'>
293 <title>Package Groups - <filename>packagegroup.bbclass</filename></title>
294
295 <para>
296 This class sets default values appropriate for package group recipes (e.g.
297 <filename><link linkend='var-PACKAGES'>PACKAGES</link></filename>,
298 <filename><link linkend='var-PACKAGE_ARCH'>PACKAGE_ARCH</link></filename>,
299 <filename><link linkend='var-ALLOW_EMPTY'>ALLOW_EMPTY</link></filename>,
300 and so forth).
301 It is highly recommended that all package group recipes inherit this class.
302 </para>
303 <para>
304 For information on how to use this class, see the
305 "<ulink url='&YOCTO_DOCS_DEV_URL;#usingpoky-extend-customimage-customtasks'>Customizing Images Using Custom Package Groups</ulink>"
306 section in the Yocto Project Development Manual.
307 </para>
308 <para>
309 Previously, this class was named <filename>task.bbclass</filename>.
310 </para>
311</section>
312
313
314<section id='ref-classes-package'>
315 <title>Packaging - <filename>package*.bbclass</filename></title>
316
317 <para>
318 The packaging classes add support for generating packages from a build's
319 output.
320 The core generic functionality is in <filename>package.bbclass</filename>.
321 The code specific to particular package types is contained in various sub-classes such as
322 <filename>package_deb.bbclass</filename>, <filename>package_ipk.bbclass</filename>,
323 and <filename>package_rpm.bbclass</filename>.
324 Most users will want one or more of these classes.
325 </para>
326
327 <para>
328 You can control the list of resulting package formats by using the
329 <filename><link linkend='var-PACKAGE_CLASSES'>PACKAGE_CLASSES</link></filename>
330 variable defined in the <filename>local.conf</filename> configuration file,
331 which is located in the <filename>conf</filename> folder of the
332 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
333 When defining the variable, you can specify one or more package types.
334 Since images are generated from packages, a packaging class is
335 needed to enable image generation.
336 The first class listed in this variable is used for image generation.
337 </para>
338
339 <para>
340 If you take the optional step to set up a repository (package feed)
341 on the development host that can be used by Smart, you can
342 install packages from the feed while you are running the image
343 on the target (i.e. runtime installation of packages).
344 For more information, see the
345 "<ulink url='&YOCTO_DOCS_DEV_URL;#using-runtime-package-management'>Using Runtime Package Management</ulink>"
346 section in the Yocto Project Development Manual.
347 </para>
348
349 <para>
350 The package class you choose can affect build-time performance and has space
351 ramifications.
352 In general, building a package with IPK takes about thirty percent less
353 time as compared to using RPM to build the same or similar package.
354 This comparison takes into account a complete build of the package with
355 all dependencies previously built.
356 The reason for this discrepancy is because the RPM package manager
357 creates and processes more
358 <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink> than the
359 IPK package manager.
360 Consequently, you might consider setting <filename>PACKAGE_CLASSES</filename>
361 to "package_ipk" if you are building smaller systems.
362 </para>
363
364 <para>
365 Before making your decision on package manager, however, you should
366 consider some further things about using RPM:
367 <itemizedlist>
368 <listitem><para>
369 RPM starts to provide more abilities than IPK due to
370 the fact that it processes more metadata.
371 For example, this information includes individual file types,
372 file checksum generation and evaluation on install, sparse file
373 support, conflict detection and resolution for Multilib systems,
374 ACID style upgrade, and repackaging abilities for rollbacks.
375 </para></listitem>
376 <listitem><para>
377 For smaller systems, the extra space used for the Berkley
378 Database and the amount of metadata when using RPM can affect
379 your ability to perform on-device upgrades.
380 </para></listitem>
381 </itemizedlist>
382 </para>
383
384 <para>
385 You can find additional information on the effects of the package
386 class at these two Yocto Project mailing list links:
387 <itemizedlist>
388 <listitem><para><ulink url='&YOCTO_LISTS_URL;/pipermail/poky/2011-May/006362.html'>
389 https://lists.yoctoproject.org/pipermail/poky/2011-May/006362.html</ulink></para></listitem>
390 <listitem><para><ulink url='&YOCTO_LISTS_URL;/pipermail/poky/2011-May/006363.html'>
391 https://lists.yoctoproject.org/pipermail/poky/2011-May/006363.html</ulink></para></listitem>
392 </itemizedlist>
393 </para>
394</section>
395
396<section id='ref-classes-kernel'>
397 <title>Building Kernels - <filename>kernel.bbclass</filename></title>
398
399 <para>
400 This class handles building Linux kernels.
401 The class contains code to build all kernel trees.
402 All needed headers are staged into the
403 <filename><link linkend='var-STAGING_KERNEL_DIR'>STAGING_KERNEL_DIR</link></filename>
404 directory to allow out-of-tree module builds using <filename>module.bbclass</filename>.
405 </para>
406
407 <para>
408 This means that each built kernel module is packaged separately and inter-module
409 dependencies are created by parsing the <filename>modinfo</filename> output.
410 If all modules are required, then installing the <filename>kernel-modules</filename>
411 package installs all packages with modules and various other kernel packages
412 such as <filename>kernel-vmlinux</filename>.
413 </para>
414
415 <para>
416 Various other classes are used by the kernel and module classes internally including
417 <filename>kernel-arch.bbclass</filename>, <filename>module_strip.bbclass</filename>,
418 <filename>module-base.bbclass</filename>, and <filename>linux-kernel-base.bbclass</filename>.
419 </para>
420</section>
421
422<section id='ref-classes-image'>
423 <title>Creating Images - <filename>image.bbclass</filename> and <filename>rootfs*.bbclass</filename></title>
424
425 <para>
426 These classes add support for creating images in several formats.
427 First, the root filesystem is created from packages using
428 one of the <filename>rootfs_*.bbclass</filename>
429 files (depending on the package format used) and then the image is created.
430 <itemizedlist>
431 <listitem><para>The
432 <filename><link linkend='var-IMAGE_FSTYPES'>IMAGE_FSTYPES</link></filename>
433 variable controls the types of images to generate.
434 </para></listitem>
435 <listitem><para>The
436 <filename><link linkend='var-IMAGE_INSTALL'>IMAGE_INSTALL</link></filename>
437 variable controls the list of packages to install into the
438 image.</para></listitem>
439 </itemizedlist>
440 </para>
441</section>
442
443<section id='ref-classes-sanity'>
444 <title>Host System Sanity Checks - <filename>sanity.bbclass</filename></title>
445
446 <para>
447 This class checks to see if prerequisite software is present on the host system
448 so that users can be notified of potential problems that might affect their build.
449 The class also performs basic user configuration checks from
450 the <filename>local.conf</filename> configuration file to
451 prevent common mistakes that cause build failures.
452 Distribution policy usually determines whether to include this class.
453 </para>
454</section>
455
456<section id='ref-classes-insane'>
457<title><filename>insane.bbclass</filename></title>
458
459 <para>
460 This class adds a step to the package generation process so that
461 output quality assurance checks are generated by the OpenEmbedded
462 build system.
463 A range of checks are performed that check the build's output
464 for common problems that show up during runtime.
465 Distribution policy usually dictates whether to include this class.
466 </para>
467
468 <para>
469 You can configure the sanity checks so that specific test failures
470 either raise a warning or an error message.
471 Typically, failures for new tests generate a warning.
472 Subsequent failures for the same test would then generate an error
473 message once the metadata is in a known and good condition.
474 </para>
475
476 <para>
477 Use the
478 <link linkend='var-WARN_QA'><filename>WARN_QA</filename></link> and
479 <link linkend='var-ERROR_QA'><filename>ERROR_QA</filename></link>
480 variables to control the behavior of
481 these checks at the global level (i.e. in your custom distro
482 configuration).
483 However, to skip one or more checks in recipes, you should use
484 <link linkend='var-INSANE_SKIP'><filename>INSANE_SKIP</filename></link>.
485 For example, to skip the check for symbolic link
486 <filename>.so</filename> files in the main package of a recipe,
487 add the following to the recipe.
488 You need to realize that the package name override, in this example
489 <filename>${PN}</filename>, must be used:
490 <literallayout class='monospaced'>
491 INSANE_SKIP_${PN} += "dev-so"
492 </literallayout>
493 Please keep in mind that the QA checks exist in order to detect real
494 or potential problems in the packaged output.
495 So exercise caution when disabling these checks.
496 </para>
497
498 <para>
499 The following list shows the tests you can list with the
500 <filename>WARN_QA</filename> and <filename>ERROR_QA</filename>
501 variables:
502 <itemizedlist>
503 <listitem><para><emphasis><filename>ldflags:</filename></emphasis>
504 Ensures that the binaries were linked with the
505 <filename>LDFLAGS</filename> options provided by the build system.
506 If this test fails, check that the <filename>LDFLAGS</filename> variable
507 is being passed to the linker command.</para></listitem>
508 <listitem><para><emphasis><filename>useless-rpaths:</filename></emphasis>
509 Checks for dynamic library load paths (rpaths) in the binaries that
510 by default on a standard system are searched by the linker (e.g.
511 <filename>/lib</filename> and <filename>/usr/lib</filename>).
512 While these paths will not cause any breakage, they do waste space and
513 are unnecessary.</para></listitem>
514 <listitem><para><emphasis><filename>rpaths:</filename></emphasis>
515 Checks for rpaths in the binaries that contain build system paths such
516 as <filename>TMPDIR</filename>.
517 If this test fails, bad <filename>-rpath</filename> options are being
518 passed to the linker commands and your binaries have potential security
519 issues.</para></listitem>
520 <listitem><para><emphasis><filename>dev-so:</filename></emphasis>
521 Checks that the <filename>.so</filename> symbolic links are in the
522 <filename>-dev</filename> package and not in any of the other packages.
523 In general, these symlinks are only useful for development purposes.
524 Thus, the <filename>-dev</filename> package is the correct location for
525 them.
526 Some very rare cases do exist for dynamically loaded modules where
527 these symlinks are needed instead in the main package.
528 </para></listitem>
529 <listitem><para><emphasis><filename>debug-files:</filename></emphasis>
530 Checks for <filename>.debug</filename> directories in anything but the
531 <filename>-dbg</filename> package.
532 The debug files should all be in the <filename>-dbg</filename> package.
533 Thus, anything packaged elsewhere is incorrect packaging.</para></listitem>
534 <listitem><para><emphasis><filename>arch:</filename></emphasis>
535 Checks the Executable and Linkable Format (ELF) type, bit size, and endianness
536 of any binaries to ensure they match the target architecture.
537 This test fails if any binaries don't match the type since there would be an
538 incompatibility.
539 Sometimes software, like bootloaders, might need to bypass this check.
540 </para></listitem>
541 <listitem><para><emphasis><filename>debug-deps:</filename></emphasis>
542 Checks that <filename>-dbg</filename> packages only depend on other
543 <filename>-dbg</filename> packages and not on any other types of packages,
544 which would cause a packaging bug.</para></listitem>
545 <listitem><para><emphasis><filename>dev-deps:</filename></emphasis>
546 Checks that <filename>-dev</filename> packages only depend on other
547 <filename>-dev</filename> packages and not on any other types of packages,
548 which would be a packaging bug.</para></listitem>
549 <listitem><para><emphasis><filename>pkgconfig:</filename></emphasis>
550 Checks <filename>.pc</filename> files for any
551 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>/<link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>
552 paths.
553 Any <filename>.pc</filename> file containing these paths is incorrect
554 since <filename>pkg-config</filename> itself adds the correct sysroot prefix
555 when the files are accessed.</para></listitem>
556 <listitem><para><emphasis><filename>textrel:</filename></emphasis>
557 Checks for ELF binaries that contain relocations in their
558 <filename>.text</filename> sections, which can result in a
559 performance impact at runtime.</para></listitem>
560 <listitem><para><emphasis><filename>pkgvarcheck:</filename></emphasis>
561 Checks through the variables
562 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>,
563 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>,
564 <link linkend='var-RSUGGESTS'><filename>RSUGGESTS</filename></link>,
565 <link linkend='var-RCONFLICTS'><filename>RCONFLICTS</filename></link>,
566 <link linkend='var-RPROVIDES'><filename>RPROVIDES</filename></link>,
567 <link linkend='var-RREPLACES'><filename>RREPLACES</filename></link>,
568 <link linkend='var-FILES'><filename>FILES</filename></link>,
569 <link linkend='var-ALLOW_EMPTY'><filename>ALLOW_EMPTY</filename></link>,
570 <filename>pkg_preinst</filename>,
571 <filename>pkg_postinst</filename>,
572 <filename>pkg_prerm</filename>
573 and <filename>pkg_postrm</filename>, and reports if there are
574 variable sets that are not package-specific.
575 Using these variables without a package suffix is bad practice,
576 and might unnecessarily complicate dependencies of other packages
577 within the same recipe or have other unintended consequences.
578 </para></listitem>
579 <listitem><para><emphasis><filename>xorg-driver-abi:</filename></emphasis>
580 Checks that all packages containing Xorg drivers have ABI
581 dependencies.
582 The <filename>xserver-xorg</filename> recipe provides driver
583 ABI names.
584 All drivers should depend on the ABI versions that they have
585 been built against.
586 Driver recipes that include
587 <filename>xorg-driver-input.inc</filename>
588 or <filename>xorg-driver-video.inc</filename> will
589 automatically get these versions.
590 Consequently, you should only need to explicitly add
591 dependencies to binary driver recipes.
592 </para></listitem>
593 <listitem><para><emphasis><filename>libexec:</filename></emphasis>
594 Checks if a package contains files in
595 <filename>/usr/libexec</filename>.
596 This check is not performed if the
597 <filename>libexecdir</filename> variable has been set
598 explicitly to <filename>/usr/libexec</filename>.
599 </para></listitem>
600 <listitem><para><emphasis><filename>staticdev:</filename></emphasis>
601 Checks for static library files (<filename>*.a</filename>) in
602 non-<filename>staticdev</filename> packages.
603 </para></listitem>
604 <listitem><para><emphasis><filename>la:</filename></emphasis>
605 Checks <filename>.la</filename> files for any <filename>TMPDIR</filename>
606 paths.
607 Any <filename>.la</filename> file containing these paths is incorrect since
608 <filename>libtool</filename> adds the correct sysroot prefix when using the
609 files automatically itself.</para></listitem>
610 <listitem><para><emphasis><filename>desktop:</filename></emphasis>
611 Runs the <filename>desktop-file-validate</filename> program
612 against any <filename>.desktop</filename> files to validate
613 their contents against the specification for
614 <filename>.desktop</filename> files.</para></listitem>
615 <listitem><para><emphasis><filename>already-stripped:</filename></emphasis>
616 Checks that produced binaries have not already been
617 stripped prior to the build system extracting debug symbols.
618 It is common for upstream software projects to default to
619 stripping debug symbols for output binaries.
620 In order for debugging to work on the target using
621 <filename>-dbg</filename> packages, this stripping must be
622 disabled.
623 </para></listitem>
624 <listitem><para><emphasis><filename>split-strip:</filename></emphasis>
625 Reports that splitting or stripping debug symbols from binaries
626 has failed.
627 </para></listitem>
628 <listitem><para><emphasis><filename>arch:</filename></emphasis>
629 Checks to ensure the architecture, bit size, and endianness
630 of all output binaries matches that of the target.
631 This test can detect when the wrong compiler or compiler options
632 have been used.
633 </para></listitem>
634 <listitem><para><emphasis><filename>installed-vs-shipped:</filename></emphasis>
635 Reports when files have been installed within
636 <filename>do_install</filename> but have not been included in
637 any package by way of the
638 <link linkend='var-FILES'><filename>FILES</filename></link>
639 variable.
640 Files that do not appear in any package cannot be present in
641 an image later on in the build process.
642 Ideally, all installed files should be packaged or not
643 installed at all.
644 These files can be deleted at the end of
645 <filename>do_install</filename> if the files are not
646 needed in any package.
647 </para></listitem>
648 <listitem><para><emphasis><filename>dep-cmp:</filename></emphasis>
649 Checks for invalid version comparison statements in runtime
650 dependency relationships between packages (i.e. in
651 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>,
652 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>,
653 <link linkend='var-RSUGGESTS'><filename>RSUGGESTS</filename></link>,
654 <link linkend='var-RPROVIDES'><filename>RPROVIDES</filename></link>,
655 <link linkend='var-RREPLACES'><filename>RREPLACES</filename></link>,
656 and
657 <link linkend='var-RCONFLICTS'><filename>RCONFLICTS</filename></link>
658 variable values).
659 Any invalid comparisons might trigger failures or undesirable
660 behavior when passed to the package manager.
661 </para></listitem>
662 <listitem><para><emphasis><filename>files-invalid:</filename></emphasis>
663 Checks for
664 <link linkend='var-FILES'><filename>FILES</filename></link>
665 variable values that contain "//", which is invalid.
666 </para></listitem>
667 <listitem><para><emphasis><filename>incompatible-license:</filename></emphasis>
668 Report when packages are excluded from being created due to
669 being marked with a license that is in
670 <link linkend='var-INCOMPATIBLE_LICENSE'><filename>INCOMPATIBLE_LICENSE</filename></link>.
671 </para></listitem>
672 <listitem><para><emphasis><filename>compile-host-path:</filename></emphasis>
673 Checks the <filename>do_compile</filename> log for indications
674 that paths to locations on the build host were used.
675 Using such paths might result in host contamination of the
676 build output.
677 </para></listitem>
678 <listitem><para><emphasis><filename>install-host-path:</filename></emphasis>
679 Checks the <filename>do_install</filename> log for indications
680 that paths to locations on the build host were used.
681 Using such paths might result in host contamination of the
682 build output.
683 </para></listitem>
684 <listitem><para><emphasis><filename>libdir:</filename></emphasis>
685 Checks for libraries being installed into incorrect
686 (possibly hardcoded) installation paths.
687 For example, this test will catch recipes that install
688 <filename>/lib/bar.so</filename> when
689 <filename>${base_libdir}</filename> is "lib32".
690 Another example is when recipes install
691 <filename>/usr/lib64/foo.so</filename> when
692 <filename>${libdir}</filename> is "/usr/lib".
693 </para></listitem>
694 <listitem><para><emphasis><filename>packages-list:</filename></emphasis>
695 Checks for the same package being listed multiple times through
696 the <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>
697 variable value.
698 Installing the package in this manner can cause errors during
699 packaging.
700 </para></listitem>
701 <listitem><para><emphasis><filename>perm-config:</filename></emphasis>
702 Reports lines in <filename>fs-perms.txt</filename> that have
703 an invalid format.
704 </para></listitem>
705 <listitem><para><emphasis><filename>perm-line:</filename></emphasis>
706 Reports lines in <filename>fs-perms.txt</filename> that have
707 an invalid format.
708 </para></listitem>
709 <listitem><para><emphasis><filename>perm-link:</filename></emphasis>
710 Reports lines in <filename>fs-perms.txt</filename> that
711 specify 'link' where the specified target already exists.
712 </para></listitem>
713 <listitem><para><emphasis><filename>pkgname:</filename></emphasis>
714 Checks that all packages in
715 <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>
716 have names that do not contain invalid characters (i.e.
717 characters other than 0-9, a-z, ., +, and -).
718 </para></listitem>
719 <listitem><para><emphasis><filename>pn-overrides:</filename></emphasis>
720 Checks that a recipe does not have a name
721 (<link linkend='var-PN'><filename>PN</filename></link>) value
722 that appears in
723 <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>.
724 If a recipe is named such that its <filename>PN</filename>
725 value matches something already in
726 <filename>OVERRIDES</filename> (e.g. <filename>PN</filename>
727 happens to be the same as
728 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>
729 or
730 <link linkend='var-DISTRO'><filename>DISTRO</filename></link>),
731 it can have unexpected consequences.
732 For example, assignments such as
733 <filename>FILES_${PN} = "xyz"</filename> effectively turn into
734 <filename>FILES = "xyz"</filename>.
735 </para></listitem>
736 <listitem><para><emphasis><filename>unsafe-references-in-binaries:</filename></emphasis>
737 Reports when a binary installed in
738 <filename>${base_libdir}</filename>,
739 <filename>${base_bindir}</filename>, or
740 <filename>${base_sbindir}</filename>, depends on another
741 binary installed under <filename>${exec_prefix}</filename>.
742 This dependency is a concern if you want the system to remain
743 basically operable if <filename>/usr</filename> is mounted
744 separately and is not mounted.
745 <note>
746 Defaults for binaries installed in
747 <filename>${base_libdir}</filename>,
748 <filename>${base_bindir}</filename>, and
749 <filename>${base_sbindir}</filename> are
750 <filename>/lib</filename>, <filename>/bin</filename>, and
751 <filename>/sbin</filename>, respectively.
752 The default for a binary installed
753 under <filename>${exec_prefix}</filename> is
754 <filename>/usr</filename>.
755 </note>
756 </para></listitem>
757 <listitem><para><emphasis><filename>unsafe-references-in-scripts:</filename></emphasis>
758 Reports when a script file installed in
759 <filename>${base_libdir}</filename>,
760 <filename>${base_bindir}</filename>, or
761 <filename>${base_sbindir}</filename>, depends on files
762 installed under <filename>${exec_prefix}</filename>.
763 This dependency is a concern if you want the system to remain
764 basically operable if <filename>/usr</filename> is mounted
765 separately and is not mounted.
766 <note>
767 Defaults for binaries installed in
768 <filename>${base_libdir}</filename>,
769 <filename>${base_bindir}</filename>, and
770 <filename>${base_sbindir}</filename> are
771 <filename>/lib</filename>, <filename>/bin</filename>, and
772 <filename>/sbin</filename>, respectively.
773 The default for a binary installed
774 under <filename>${exec_prefix}</filename> is
775 <filename>/usr</filename>.
776 </note>
777 </para></listitem>
778 <listitem><para><emphasis><filename>var-undefined:</filename></emphasis>
779 Reports when variables fundamental to packaging (i.e.
780 <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>,
781 <link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link>,
782 <link linkend='var-D'><filename>D</filename></link>,
783 <link linkend='var-PN'><filename>PN</filename></link>, and
784 <link linkend='var-PKGD'><filename>PKGD</filename></link>) are
785 undefined during <filename>do_package</filename>.
786 </para></listitem>
787 <listitem><para><emphasis><filename>pkgv-undefined:</filename></emphasis>
788 Checks to see if the <filename>PKGV</filename> variable
789 is undefined during <filename>do_package</filename>.
790 </para></listitem>
791 <listitem><para><emphasis><filename>buildpaths:</filename></emphasis>
792 Checks for paths to locations on the build host inside the
793 output files.
794 Currently, this test triggers too many false positives and
795 thus is not normally enabled.
796 </para></listitem>
797 <listitem><para><emphasis><filename>perms:</filename></emphasis>
798 Currently, this check is unused but reserved.
799 </para></listitem>
800 <listitem><para><emphasis><filename>version-going-backwards:</filename></emphasis>
801 If Build History is enabled, reports when a package
802 being written out has a lower version than the previously
803 written package under the same name.
804 If you are placing output packages into a feed and
805 upgrading packages on a target system using that feed, the
806 version of a package going backwards can result in the target
807 system not correctly upgrading to the "new" version of the
808 package.
809 <note>
810 If you are not using runtime package management on your
811 target system, then you do not need to worry about
812 this situation.
813 </note>
814 </para></listitem>
815 </itemizedlist>
816 </para>
817</section>
818
819<section id='ref-classes-rm-work'>
820 <title>Removing Work Files During the Build - <filename>rm_work.bbclass</filename></title>
821
822 <para>
823 The OpenEmbedded build system can use a substantial amount of disk
824 space during the build process.
825 A portion of this space is the work files under the
826 <filename>${TMPDIR}/work</filename> directory for each recipe.
827 Once the build system generates the packages for a recipe, the work
828 files for that recipe are no longer needed.
829 However, by default, the build system preserves these files
830 for inspection and possible debugging purposes.
831 If you would rather have these files deleted to save disk space
832 as the build progresses, you can enable <filename>rm_work</filename>
833 by adding the following to your <filename>local.conf</filename> file,
834 which is found in the
835 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
836 <literallayout class='monospaced'>
837 INHERIT += "rm_work"
838 </literallayout>
839 If you are modifying and building source code out of the work directory
840 for a recipe, enabling <filename>rm_work</filename> will potentially
841 result in your changes to the source being lost.
842 To exclude some recipes from having their work directories deleted by
843 <filename>rm_work</filename>, you can add the names of the recipe or
844 recipes you are working on to the <filename>RM_WORK_EXCLUDE</filename>
845 variable, which can also be set in your <filename>local.conf</filename>
846 file.
847 Here is an example:
848 <literallayout class='monospaced'>
849 RM_WORK_EXCLUDE += "busybox eglibc"
850 </literallayout>
851 </para>
852</section>
853
854
855<section id='ref-classes-siteinfo'>
856 <title>Autotools Configuration Data Cache - <filename>siteinfo.bbclass</filename></title>
857
858 <para>
859 Autotools can require tests that must execute on the target hardware.
860 Since this is not possible in general when cross compiling, site information is
861 used to provide cached test results so these tests can be skipped over but
862 still make the correct values available.
863 The <filename><link linkend='structure-meta-site'>meta/site directory</link></filename>
864 contains test results sorted into different categories such as architecture, endianness, and
865 the <filename>libc</filename> used.
866 Site information provides a list of files containing data relevant to
867 the current build in the
868 <filename><link linkend='var-CONFIG_SITE'>CONFIG_SITE</link></filename> variable
869 that Autotools automatically picks up.
870 </para>
871
872 <para>
873 The class also provides variables like
874 <filename><link linkend='var-SITEINFO_ENDIANNESS'>SITEINFO_ENDIANNESS</link></filename>
875 and <filename><link linkend='var-SITEINFO_BITS'>SITEINFO_BITS</link></filename>
876 that can be used elsewhere in the metadata.
877 </para>
878
879 <para>
880 Because this class is included from <filename>base.bbclass</filename>, it is always active.
881 </para>
882</section>
883
884<section id='ref-classes-useradd'>
885 <title>Adding Users - <filename>useradd.bbclass</filename></title>
886
887 <para>
888 If you have packages that install files that are owned by custom users or groups,
889 you can use this class to specify those packages and associate the users and groups
890 with those packages.
891 The <filename>meta-skeleton/recipes-skeleton/useradd/useradd-example.bb</filename>
892 recipe in the <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
893 provides a simple example that shows how to add three
894 users and groups to two packages.
895 See the <filename>useradd-example.bb</filename> for more information on how to
896 use this class.
897 </para>
898</section>
899
900<section id='ref-classes-externalsrc'>
901 <title><filename>externalsrc.bbclass</filename></title>
902
903 <para>
904 You can use this class to build software from source code that is
905 external to the OpenEmbedded build system.
906 Building software from an external source tree means that the build
907 system's normal fetch, unpack, and patch process is not used.
908 </para>
909
910 <para>
911 By default, the OpenEmbedded build system uses the
912 <link linkend='var-S'><filename>S</filename></link> and
913 <link linkend='var-B'><filename>B</filename></link> variables to
914 locate unpacked recipe source code and to build it, respectively.
915 When your recipe inherits <filename>externalsrc.bbclass</filename>,
916 you use the
917 <link linkend='var-EXTERNALSRC'><filename>EXTERNALSRC</filename></link>
918 and
919 <link linkend='var-EXTERNALSRC_BUILD'><filename>EXTERNALSRC_BUILD</filename></link>
920 variables to ultimately define <filename>S</filename> and
921 <filename>B</filename>.
922 </para>
923
924 <para>
925 By default, this class expects the source code to support recipe builds
926 that use the <link linkend='var-B'><filename>B</filename></link>
927 variable to point to the directory in which the OpenEmbedded build
928 system places the generated objects built from the recipes.
929 By default, the <filename>B</filename> directory is set to the
930 following, which is separate from the source directory
931 (<filename>S</filename>):
932 <literallayout class='monospaced'>
933 ${WORKDIR}/${BPN}/{PV}/
934 </literallayout>
935 See the glossary entries for the
936 <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>,
937 <link linkend='var-BPN'><filename>BPN</filename></link>,
938 <link linkend='var-PV'><filename>PV</filename></link>,
939 </para>
940
941 <para>
942 For more information on
943 <filename>externalsrc.bbclass</filename>, see the comments in
944 <filename>meta/classes/externalsrc.bbclass</filename> in the
945 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
946 For information on how to use <filename>externalsrc.bbclass</filename>,
947 see the
948 "<ulink url='&YOCTO_DOCS_DEV_URL;#building-software-from-an-external-source'>Building Software from an External Source</ulink>"
949 section in the Yocto Project Development Manual.
950 </para>
951</section>
952
953<section id='ref-classes-testimage'>
954 <title><filename>testimage.bbclass</filename></title>
955
956 <para>
957 You can use this class to enable running a series of automated tests
958 for images.
959 The class handles loading the tests and starting the image.
960 <note>
961 Currently, there is only support for running these tests
962 under QEMU.
963 </note>
964 </para>
965
966 <para>
967 To use the class, you need to perform steps to set up the
968 environment.
969 The tests are commands that run on the target system over
970 <filename>ssh</filename>.
971 they are written in Python and make use of the
972 <filename>unittest</filename> module.
973 </para>
974
975 <para>
976 For information on how to enable, run, and create new tests, see the
977 "<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"
978 section.
979 </para>
980</section>
981
982<section id='ref-classes-others'>
983 <title>Other Classes</title>
984
985 <para>
986 Thus far, this chapter has discussed only the most useful and important
987 classes.
988 However, other classes exist within the <filename>meta/classes</filename> directory
989 in the <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
990 You can examine the <filename>.bbclass</filename> files directly for more
991 information.
992 </para>
993</section>
994
995<!-- Undocumented classes are:
996 allarch.bbclass
997 archive*.bbclass
998 binconfig.bbclass
999 bin_package.bbclass
1000 blacklist.bbclass
1001 bootimg.bbclass
1002 boot-directdisk.bbclass
1003 bugzilla.bbclass
1004 buildhistory.bbclass
1005 buildstats.bbclass
1006 ccache.bbclass
1007 chrpath.bbclass
1008 clutter.bbclass
1009 cmake.bbclass
1010 cml1.bbclass
1011 copyleft_compliance.bbclass
1012 core-image.bbclass
1013 cross.bbclass
1014 cross-canadian.bbclass
1015 crosssdk.bbclass
1016 deploy.bbclass
1017 distrodata.bbclass
1018 distro_features_check.bbclass
1019 dummy.bbclass
1020 extrausers.bbclass
1021 fontcache.bbclass
1022 gconf.bbclass
1023 gettext.bbclass
1024 gnomebase.bbclass
1025 gnome.bbclass
1026 grub-efi.bbclass
1027 gsettings.bbclass
1028 gtk-doc.bbclass
1029 gtk-icon-cache.bbclass
1030 gtk-immodules-cache.bbclass
1031 gzipnative.bbclass
1032 icecc.bbclass
1033 image-empty.bbclass
1034 image-live.bbclass
1035 image-vmdk.bbclass
1036 image-mklibs.bbclass
1037 image-prelink.bbclass
1038 image-swab.bbclass
1039 image_types.bbclass
1040 image_types_uboot.bbclass
1041 insserv.bbclass
1042 kernel-arch.bbclass
1043 kernel-module-split.bbclass
1044 kernel-yocto.bbclass
1045 lib_package.bbclass
1046 linux-kernel-base.bbclass
1047 license.bbclass
1048 logging.bbclass
1049 meta.bbclass
1050 metadata_scm.bbclass
1051 migrate_localcount.bbclass
1052 mime.bbclass
1053 mirrors.bbclass
1054 multilib*.bbclass
1055 native.bbclass
1056 nativesdk.bbclass
1057 oelint.bbclass
1058 own-mirrors.bbclass
1059 packagedata.bbclass
1060 packageinfo.bbclass
1061 patch.bbclass
1062 perlnative.bbclass
1063 pixbufcache.bbclass
1064 pkg_distribute.bbclass
1065 pkg_metainfo.bbclass
1066 populate_sdk*.bbclass
1067 prexport.bbclass
1068 primport.bbclass
1069 prserv.bbclass
1070 ptest.bbclass
1071 python-dir.bbclass
1072 pythonnative.bbclass
1073 qemu.bbclass
1074 qmake*.bbclass
1075 qt4*.bbclass
1076 recipe_sanity.bbclass
1077 relocatable.bbclass
1078 scons.bbclass
1079 sdl.bbclass
1080 setuptools.bbclass
1081 sip.bbclass
1082 siteconfig.bbclass
1083 sourcepkg.bbclass
1084 spdx.bbclass
1085 sstate.bbclass
1086 staging.bbclass
1087 syslinux.bbclass
1088 systemd.bbclass
1089 terminal.bbclass
1090 tinderclient.bbclass
1091 toolchain-scripts.bbclass
1092 typecheck.bbclass
1093 uboot-config.bbclass
1094 utility-tasks.bbclass
1095 utils.bbclass
1096 vala.bbclass
1097 waf.bbclass
1098-->
1099
1100
1101</chapter>
1102<!--
1103vim: expandtab tw=80 ts=4
1104-->
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-04-26 05:28:10 +0000