diff options
Diffstat (limited to 'documentation/ref-manual/ref-classes.rst')
-rw-r--r-- | documentation/ref-manual/ref-classes.rst | 2963 |
1 files changed, 2963 insertions, 0 deletions
diff --git a/documentation/ref-manual/ref-classes.rst b/documentation/ref-manual/ref-classes.rst new file mode 100644 index 0000000000..60ce8efd21 --- /dev/null +++ b/documentation/ref-manual/ref-classes.rst | |||
@@ -0,0 +1,2963 @@ | |||
1 | .. SPDX-License-Identifier: CC-BY-2.0-UK | ||
2 | |||
3 | ******* | ||
4 | Classes | ||
5 | ******* | ||
6 | |||
7 | Class files are used to abstract common functionality and share it | ||
8 | amongst multiple recipe (``.bb``) files. To use a class file, you simply | ||
9 | make sure the recipe inherits the class. In most cases, when a recipe | ||
10 | inherits a class it is enough to enable its features. There are cases, | ||
11 | however, where in the recipe you might need to set variables or override | ||
12 | some default behavior. | ||
13 | |||
14 | Any :term:`Metadata` usually found in a recipe can also be | ||
15 | placed in a class file. Class files are identified by the extension | ||
16 | ``.bbclass`` and are usually placed in a ``classes/`` directory beneath | ||
17 | the ``meta*/`` directory found in the :term:`Source Directory`. | ||
18 | Class files can also be pointed to by | ||
19 | :term:`BUILDDIR` (e.g. ``build/``) in the same way as | ||
20 | ``.conf`` files in the ``conf`` directory. Class files are searched for | ||
21 | in :term:`BBPATH` using the same method by which ``.conf`` | ||
22 | files are searched. | ||
23 | |||
24 | This chapter discusses only the most useful and important classes. Other | ||
25 | classes do exist within the ``meta/classes`` directory in the Source | ||
26 | Directory. You can reference the ``.bbclass`` files directly for more | ||
27 | information. | ||
28 | |||
29 | .. _ref-classes-allarch: | ||
30 | |||
31 | ``allarch.bbclass`` | ||
32 | =================== | ||
33 | |||
34 | The ``allarch`` class is inherited by recipes that do not produce | ||
35 | architecture-specific output. The class disables functionality that is | ||
36 | normally needed for recipes that produce executable binaries (such as | ||
37 | building the cross-compiler and a C library as pre-requisites, and | ||
38 | splitting out of debug symbols during packaging). | ||
39 | |||
40 | .. note:: | ||
41 | |||
42 | Unlike some distro recipes (e.g. Debian), OpenEmbedded recipes that | ||
43 | produce packages that depend on tunings through use of the | ||
44 | :term:`RDEPENDS` and | ||
45 | :term:`TUNE_PKGARCH` variables, should never be | ||
46 | configured for all architectures using ``allarch``. This is the case | ||
47 | even if the recipes do not produce architecture-specific output. | ||
48 | |||
49 | Configuring such recipes for all architectures causes the | ||
50 | ```do_package_write_*`` tasks to | ||
51 | have different signatures for the machines with different tunings. | ||
52 | Additionally, unnecessary rebuilds occur every time an image for a | ||
53 | different ``MACHINE`` is built even when the recipe never changes. | ||
54 | |||
55 | By default, all recipes inherit the :ref:`base <ref-classes-base>` and | ||
56 | :ref:`package <ref-classes-package>` classes, which enable | ||
57 | functionality needed for recipes that produce executable output. If your | ||
58 | recipe, for example, only produces packages that contain configuration | ||
59 | files, media files, or scripts (e.g. Python and Perl), then it should | ||
60 | inherit the ``allarch`` class. | ||
61 | |||
62 | .. _ref-classes-archiver: | ||
63 | |||
64 | ``archiver.bbclass`` | ||
65 | ==================== | ||
66 | |||
67 | The ``archiver`` class supports releasing source code and other | ||
68 | materials with the binaries. | ||
69 | |||
70 | For more details on the source archiver, see the | ||
71 | ":ref:`dev-manual/dev-manual-common-tasks:maintaining open source license compliance during your product's lifecycle`" | ||
72 | section in the Yocto Project Development Tasks Manual. You can also see | ||
73 | the :term:`ARCHIVER_MODE` variable for information | ||
74 | about the variable flags (varflags) that help control archive creation. | ||
75 | |||
76 | .. _ref-classes-autotools: | ||
77 | |||
78 | ``autotools*.bbclass`` | ||
79 | ====================== | ||
80 | |||
81 | The ``autotools*`` classes support Autotooled packages. | ||
82 | |||
83 | The ``autoconf``, ``automake``, and ``libtool`` packages bring | ||
84 | standardization. This class defines a set of tasks (e.g. ``configure``, | ||
85 | ``compile`` and so forth) that work for all Autotooled packages. It | ||
86 | should usually be enough to define a few standard variables and then | ||
87 | simply ``inherit autotools``. These classes can also work with software | ||
88 | that emulates Autotools. For more information, see the | ||
89 | ":ref:`new-recipe-autotooled-package`" section | ||
90 | in the Yocto Project Development Tasks Manual. | ||
91 | |||
92 | By default, the ``autotools*`` classes use out-of-tree builds (i.e. | ||
93 | ``autotools.bbclass`` building with ``B != S``). | ||
94 | |||
95 | If the software being built by a recipe does not support using | ||
96 | out-of-tree builds, you should have the recipe inherit the | ||
97 | ``autotools-brokensep`` class. The ``autotools-brokensep`` class behaves | ||
98 | the same as the ``autotools`` class but builds with :term:`B` | ||
99 | == :term:`S`. This method is useful when out-of-tree build | ||
100 | support is either not present or is broken. | ||
101 | |||
102 | .. note:: | ||
103 | |||
104 | It is recommended that out-of-tree support be fixed and used if at | ||
105 | all possible. | ||
106 | |||
107 | It's useful to have some idea of how the tasks defined by the | ||
108 | ``autotools*`` classes work and what they do behind the scenes. | ||
109 | |||
110 | - :ref:`ref-tasks-configure` - Regenerates the | ||
111 | configure script (using ``autoreconf``) and then launches it with a | ||
112 | standard set of arguments used during cross-compilation. You can pass | ||
113 | additional parameters to ``configure`` through the ``EXTRA_OECONF`` | ||
114 | or :term:`PACKAGECONFIG_CONFARGS` | ||
115 | variables. | ||
116 | |||
117 | - :ref:`ref-tasks-compile` - Runs ``make`` with | ||
118 | arguments that specify the compiler and linker. You can pass | ||
119 | additional arguments through the ``EXTRA_OEMAKE`` variable. | ||
120 | |||
121 | - :ref:`ref-tasks-install` - Runs ``make install`` and | ||
122 | passes in ``${``\ :term:`D`\ ``}`` as ``DESTDIR``. | ||
123 | |||
124 | .. _ref-classes-base: | ||
125 | |||
126 | ``base.bbclass`` | ||
127 | ================ | ||
128 | |||
129 | The ``base`` class is special in that every ``.bb`` file implicitly | ||
130 | inherits the class. This class contains definitions for standard basic | ||
131 | tasks such as fetching, unpacking, configuring (empty by default), | ||
132 | compiling (runs any ``Makefile`` present), installing (empty by default) | ||
133 | and packaging (empty by default). These classes are often overridden or | ||
134 | extended by other classes such as the | ||
135 | :ref:`autotools <ref-classes-autotools>` class or the | ||
136 | :ref:`package <ref-classes-package>` class. | ||
137 | |||
138 | The class also contains some commonly used functions such as | ||
139 | ``oe_runmake``, which runs ``make`` with the arguments specified in | ||
140 | :term:`EXTRA_OEMAKE` variable as well as the | ||
141 | arguments passed directly to ``oe_runmake``. | ||
142 | |||
143 | .. _ref-classes-bash-completion: | ||
144 | |||
145 | ``bash-completion.bbclass`` | ||
146 | =========================== | ||
147 | |||
148 | Sets up packaging and dependencies appropriate for recipes that build | ||
149 | software that includes bash-completion data. | ||
150 | |||
151 | .. _ref-classes-bin-package: | ||
152 | |||
153 | ``bin_package.bbclass`` | ||
154 | ======================= | ||
155 | |||
156 | The ``bin_package`` class is a helper class for recipes that extract the | ||
157 | contents of a binary package (e.g. an RPM) and install those contents | ||
158 | rather than building the binary from source. The binary package is | ||
159 | extracted and new packages in the configured output package format are | ||
160 | created. Extraction and installation of proprietary binaries is a good | ||
161 | example use for this class. | ||
162 | |||
163 | .. note:: | ||
164 | |||
165 | For RPMs and other packages that do not contain a subdirectory, you | ||
166 | should specify an appropriate fetcher parameter to point to the | ||
167 | subdirectory. For example, if BitBake is using the Git fetcher ( | ||
168 | git:// | ||
169 | ), the "subpath" parameter limits the checkout to a specific subpath | ||
170 | of the tree. Here is an example where | ||
171 | ${BP} | ||
172 | is used so that the files are extracted into the subdirectory | ||
173 | expected by the default value of | ||
174 | S | ||
175 | : | ||
176 | :: | ||
177 | |||
178 | SRC_URI = "git://example.com/downloads/somepackage.rpm;subpath=${BP}" | ||
179 | |||
180 | |||
181 | See the " | ||
182 | Fetchers | ||
183 | " section in the BitBake User Manual for more information on | ||
184 | supported BitBake Fetchers. | ||
185 | |||
186 | .. _ref-classes-binconfig: | ||
187 | |||
188 | ``binconfig.bbclass`` | ||
189 | ===================== | ||
190 | |||
191 | The ``binconfig`` class helps to correct paths in shell scripts. | ||
192 | |||
193 | Before ``pkg-config`` had become widespread, libraries shipped shell | ||
194 | scripts to give information about the libraries and include paths needed | ||
195 | to build software (usually named ``LIBNAME-config``). This class assists | ||
196 | any recipe using such scripts. | ||
197 | |||
198 | During staging, the OpenEmbedded build system installs such scripts into | ||
199 | the ``sysroots/`` directory. Inheriting this class results in all paths | ||
200 | in these scripts being changed to point into the ``sysroots/`` directory | ||
201 | so that all builds that use the script use the correct directories for | ||
202 | the cross compiling layout. See the | ||
203 | :term:`BINCONFIG_GLOB` variable for more | ||
204 | information. | ||
205 | |||
206 | .. _ref-classes-binconfig-disabled: | ||
207 | |||
208 | ``binconfig-disabled.bbclass`` | ||
209 | ============================== | ||
210 | |||
211 | An alternative version of the :ref:`binconfig <ref-classes-binconfig>` | ||
212 | class, which disables binary configuration scripts by making them return | ||
213 | an error in favor of using ``pkg-config`` to query the information. The | ||
214 | scripts to be disabled should be specified using the | ||
215 | :term:`BINCONFIG` variable within the recipe inheriting | ||
216 | the class. | ||
217 | |||
218 | .. _ref-classes-blacklist: | ||
219 | |||
220 | ``blacklist.bbclass`` | ||
221 | ===================== | ||
222 | |||
223 | The ``blacklist`` class prevents the OpenEmbedded build system from | ||
224 | building specific recipes (blacklists them). To use this class, inherit | ||
225 | the class globally and set :term:`PNBLACKLIST` for | ||
226 | each recipe you wish to blacklist. Specify the :term:`PN` | ||
227 | value as a variable flag (varflag) and provide a reason, which is | ||
228 | reported, if the package is requested to be built as the value. For | ||
229 | example, if you want to blacklist a recipe called "exoticware", you add | ||
230 | the following to your ``local.conf`` or distribution configuration: | ||
231 | :: | ||
232 | |||
233 | INHERIT += "blacklist" | ||
234 | PNBLACKLIST[exoticware] = "Not supported by our organization." | ||
235 | |||
236 | .. _ref-classes-buildhistory: | ||
237 | |||
238 | ``buildhistory.bbclass`` | ||
239 | ======================== | ||
240 | |||
241 | The ``buildhistory`` class records a history of build output metadata, | ||
242 | which can be used to detect possible regressions as well as used for | ||
243 | analysis of the build output. For more information on using Build | ||
244 | History, see the | ||
245 | ":ref:`dev-manual/dev-manual-common-tasks:maintaining build output quality`" | ||
246 | section in the Yocto Project Development Tasks Manual. | ||
247 | |||
248 | .. _ref-classes-buildstats: | ||
249 | |||
250 | ``buildstats.bbclass`` | ||
251 | ====================== | ||
252 | |||
253 | The ``buildstats`` class records performance statistics about each task | ||
254 | executed during the build (e.g. elapsed time, CPU usage, and I/O usage). | ||
255 | |||
256 | When you use this class, the output goes into the | ||
257 | :term:`BUILDSTATS_BASE` directory, which defaults | ||
258 | to ``${TMPDIR}/buildstats/``. You can analyze the elapsed time using | ||
259 | ``scripts/pybootchartgui/pybootchartgui.py``, which produces a cascading | ||
260 | chart of the entire build process and can be useful for highlighting | ||
261 | bottlenecks. | ||
262 | |||
263 | Collecting build statistics is enabled by default through the | ||
264 | :term:`USER_CLASSES` variable from your | ||
265 | ``local.conf`` file. Consequently, you do not have to do anything to | ||
266 | enable the class. However, if you want to disable the class, simply | ||
267 | remove "buildstats" from the ``USER_CLASSES`` list. | ||
268 | |||
269 | .. _ref-classes-buildstats-summary: | ||
270 | |||
271 | ``buildstats-summary.bbclass`` | ||
272 | ============================== | ||
273 | |||
274 | When inherited globally, prints statistics at the end of the build on | ||
275 | sstate re-use. In order to function, this class requires the | ||
276 | :ref:`buildstats <ref-classes-buildstats>` class be enabled. | ||
277 | |||
278 | .. _ref-classes-ccache: | ||
279 | |||
280 | ``ccache.bbclass`` | ||
281 | ================== | ||
282 | |||
283 | The ``ccache`` class enables the C/C++ Compiler Cache for the build. | ||
284 | This class is used to give a minor performance boost during the build. | ||
285 | However, using the class can lead to unexpected side-effects. Thus, it | ||
286 | is recommended that you do not use this class. See | ||
287 | http://ccache.samba.org/ for information on the C/C++ Compiler | ||
288 | Cache. | ||
289 | |||
290 | .. _ref-classes-chrpath: | ||
291 | |||
292 | ``chrpath.bbclass`` | ||
293 | =================== | ||
294 | |||
295 | The ``chrpath`` class is a wrapper around the "chrpath" utility, which | ||
296 | is used during the build process for ``nativesdk``, ``cross``, and | ||
297 | ``cross-canadian`` recipes to change ``RPATH`` records within binaries | ||
298 | in order to make them relocatable. | ||
299 | |||
300 | .. _ref-classes-clutter: | ||
301 | |||
302 | ``clutter.bbclass`` | ||
303 | =================== | ||
304 | |||
305 | The ``clutter`` class consolidates the major and minor version naming | ||
306 | and other common items used by Clutter and related recipes. | ||
307 | |||
308 | .. note:: | ||
309 | |||
310 | Unlike some other classes related to specific libraries, recipes | ||
311 | building other software that uses Clutter do not need to inherit this | ||
312 | class unless they use the same recipe versioning scheme that the | ||
313 | Clutter and related recipes do. | ||
314 | |||
315 | .. _ref-classes-cmake: | ||
316 | |||
317 | ``cmake.bbclass`` | ||
318 | ================= | ||
319 | |||
320 | The ``cmake`` class allows for recipes that need to build software using | ||
321 | the `CMake <https://cmake.org/overview/>`__ build system. You can use | ||
322 | the :term:`EXTRA_OECMAKE` variable to specify | ||
323 | additional configuration options to be passed using the ``cmake`` | ||
324 | command line. | ||
325 | |||
326 | On the occasion that you would be installing custom CMake toolchain | ||
327 | files supplied by the application being built, you should install them | ||
328 | to the preferred CMake Module directory: ``${D}${datadir}/cmake/`` | ||
329 | Modules during | ||
330 | :ref:`ref-tasks-install`. | ||
331 | |||
332 | .. _ref-classes-cml1: | ||
333 | |||
334 | ``cml1.bbclass`` | ||
335 | ================ | ||
336 | |||
337 | The ``cml1`` class provides basic support for the Linux kernel style | ||
338 | build configuration system. | ||
339 | |||
340 | .. _ref-classes-compress_doc: | ||
341 | |||
342 | ``compress_doc.bbclass`` | ||
343 | ======================== | ||
344 | |||
345 | Enables compression for man pages and info pages. This class is intended | ||
346 | to be inherited globally. The default compression mechanism is gz (gzip) | ||
347 | but you can select an alternative mechanism by setting the | ||
348 | :term:`DOC_COMPRESS` variable. | ||
349 | |||
350 | .. _ref-classes-copyleft_compliance: | ||
351 | |||
352 | ``copyleft_compliance.bbclass`` | ||
353 | =============================== | ||
354 | |||
355 | The ``copyleft_compliance`` class preserves source code for the purposes | ||
356 | of license compliance. This class is an alternative to the ``archiver`` | ||
357 | class and is still used by some users even though it has been deprecated | ||
358 | in favor of the :ref:`archiver <ref-classes-archiver>` class. | ||
359 | |||
360 | .. _ref-classes-copyleft_filter: | ||
361 | |||
362 | ``copyleft_filter.bbclass`` | ||
363 | =========================== | ||
364 | |||
365 | A class used by the :ref:`archiver <ref-classes-archiver>` and | ||
366 | :ref:`copyleft_compliance <ref-classes-copyleft_compliance>` classes | ||
367 | for filtering licenses. The ``copyleft_filter`` class is an internal | ||
368 | class and is not intended to be used directly. | ||
369 | |||
370 | .. _ref-classes-core-image: | ||
371 | |||
372 | ``core-image.bbclass`` | ||
373 | ====================== | ||
374 | |||
375 | The ``core-image`` class provides common definitions for the | ||
376 | ``core-image-*`` image recipes, such as support for additional | ||
377 | :term:`IMAGE_FEATURES`. | ||
378 | |||
379 | .. _ref-classes-cpan: | ||
380 | |||
381 | ``cpan*.bbclass`` | ||
382 | ================= | ||
383 | |||
384 | The ``cpan*`` classes support Perl modules. | ||
385 | |||
386 | Recipes for Perl modules are simple. These recipes usually only need to | ||
387 | point to the source's archive and then inherit the proper class file. | ||
388 | Building is split into two methods depending on which method the module | ||
389 | authors used. | ||
390 | |||
391 | - Modules that use old ``Makefile.PL``-based build system require | ||
392 | ``cpan.bbclass`` in their recipes. | ||
393 | |||
394 | - Modules that use ``Build.PL``-based build system require using | ||
395 | ``cpan_build.bbclass`` in their recipes. | ||
396 | |||
397 | Both build methods inherit the ``cpan-base`` class for basic Perl | ||
398 | support. | ||
399 | |||
400 | .. _ref-classes-cross: | ||
401 | |||
402 | ``cross.bbclass`` | ||
403 | ================= | ||
404 | |||
405 | The ``cross`` class provides support for the recipes that build the | ||
406 | cross-compilation tools. | ||
407 | |||
408 | .. _ref-classes-cross-canadian: | ||
409 | |||
410 | ``cross-canadian.bbclass`` | ||
411 | ========================== | ||
412 | |||
413 | The ``cross-canadian`` class provides support for the recipes that build | ||
414 | the Canadian Cross-compilation tools for SDKs. See the | ||
415 | ":ref:`overview-manual/overview-manual-concepts:cross-development toolchain generation`" | ||
416 | section in the Yocto Project Overview and Concepts Manual for more | ||
417 | discussion on these cross-compilation tools. | ||
418 | |||
419 | .. _ref-classes-crosssdk: | ||
420 | |||
421 | ``crosssdk.bbclass`` | ||
422 | ==================== | ||
423 | |||
424 | The ``crosssdk`` class provides support for the recipes that build the | ||
425 | cross-compilation tools used for building SDKs. See the | ||
426 | ":ref:`overview-manual/overview-manual-concepts:cross-development toolchain generation`" | ||
427 | section in the Yocto Project Overview and Concepts Manual for more | ||
428 | discussion on these cross-compilation tools. | ||
429 | |||
430 | .. _ref-classes-debian: | ||
431 | |||
432 | ``debian.bbclass`` | ||
433 | ================== | ||
434 | |||
435 | The ``debian`` class renames output packages so that they follow the | ||
436 | Debian naming policy (i.e. ``glibc`` becomes ``libc6`` and | ||
437 | ``glibc-devel`` becomes ``libc6-dev``.) Renaming includes the library | ||
438 | name and version as part of the package name. | ||
439 | |||
440 | If a recipe creates packages for multiple libraries (shared object files | ||
441 | of ``.so`` type), use the :term:`LEAD_SONAME` | ||
442 | variable in the recipe to specify the library on which to apply the | ||
443 | naming scheme. | ||
444 | |||
445 | .. _ref-classes-deploy: | ||
446 | |||
447 | ``deploy.bbclass`` | ||
448 | ================== | ||
449 | |||
450 | The ``deploy`` class handles deploying files to the | ||
451 | :term:`DEPLOY_DIR_IMAGE` directory. The main | ||
452 | function of this class is to allow the deploy step to be accelerated by | ||
453 | shared state. Recipes that inherit this class should define their own | ||
454 | :ref:`ref-tasks-deploy` function to copy the files to be | ||
455 | deployed to :term:`DEPLOYDIR`, and use ``addtask`` to | ||
456 | add the task at the appropriate place, which is usually after | ||
457 | :ref:`ref-tasks-compile` or | ||
458 | :ref:`ref-tasks-install`. The class then takes care of | ||
459 | staging the files from ``DEPLOYDIR`` to ``DEPLOY_DIR_IMAGE``. | ||
460 | |||
461 | .. _ref-classes-devshell: | ||
462 | |||
463 | ``devshell.bbclass`` | ||
464 | ==================== | ||
465 | |||
466 | The ``devshell`` class adds the ``do_devshell`` task. Distribution | ||
467 | policy dictates whether to include this class. See the ":ref:`platdev-appdev-devshell`" | ||
468 | section in the Yocto Project Development Tasks Manual for more | ||
469 | information about using ``devshell``. | ||
470 | |||
471 | .. _ref-classes-devupstream: | ||
472 | |||
473 | ``devupstream.bbclass`` | ||
474 | ======================= | ||
475 | |||
476 | The ``devupstream`` class uses | ||
477 | :term:`BBCLASSEXTEND` to add a variant of the | ||
478 | recipe that fetches from an alternative URI (e.g. Git) instead of a | ||
479 | tarball. Following is an example: | ||
480 | :: | ||
481 | |||
482 | BBCLASSEXTEND = "devupstream:target" | ||
483 | SRC_URI_class-devupstream = "git://git.example.com/example" | ||
484 | SRCREV_class-devupstream = "abcd1234" | ||
485 | |||
486 | Adding the above statements to your recipe creates a variant that has | ||
487 | :term:`DEFAULT_PREFERENCE` set to "-1". | ||
488 | Consequently, you need to select the variant of the recipe to use it. | ||
489 | Any development-specific adjustments can be done by using the | ||
490 | ``class-devupstream`` override. Here is an example: | ||
491 | :: | ||
492 | |||
493 | DEPENDS_append_class-devupstream = " gperf-native" | ||
494 | do_configure_prepend_class-devupstream() { | ||
495 | touch ${S}/README | ||
496 | } | ||
497 | |||
498 | The class | ||
499 | currently only supports creating a development variant of the target | ||
500 | recipe, not ``native`` or ``nativesdk`` variants. | ||
501 | |||
502 | The ``BBCLASSEXTEND`` syntax (i.e. ``devupstream:target``) provides | ||
503 | support for ``native`` and ``nativesdk`` variants. Consequently, this | ||
504 | functionality can be added in a future release. | ||
505 | |||
506 | Support for other version control systems such as Subversion is limited | ||
507 | due to BitBake's automatic fetch dependencies (e.g. | ||
508 | ``subversion-native``). | ||
509 | |||
510 | .. _ref-classes-distro_features_check: | ||
511 | |||
512 | ``distro_features_check.bbclass`` | ||
513 | ================================= | ||
514 | |||
515 | The ``distro_features_check`` class allows individual recipes to check | ||
516 | for required and conflicting | ||
517 | :term:`DISTRO_FEATURES`. | ||
518 | |||
519 | This class provides support for the | ||
520 | :term:`REQUIRED_DISTRO_FEATURES` and | ||
521 | :term:`CONFLICT_DISTRO_FEATURES` | ||
522 | variables. If any conditions specified in the recipe using the above | ||
523 | variables are not met, the recipe will be skipped. | ||
524 | |||
525 | .. _ref-classes-distutils: | ||
526 | |||
527 | ``distutils*.bbclass`` | ||
528 | ====================== | ||
529 | |||
530 | The ``distutils*`` classes support recipes for Python version 2.x | ||
531 | extensions, which are simple. These recipes usually only need to point | ||
532 | to the source's archive and then inherit the proper class. Building is | ||
533 | split into two methods depending on which method the module authors | ||
534 | used. | ||
535 | |||
536 | - Extensions that use an Autotools-based build system require Autotools | ||
537 | and the classes based on ``distutils`` in their recipes. | ||
538 | |||
539 | - Extensions that use build systems based on ``distutils`` require the | ||
540 | ``distutils`` class in their recipes. | ||
541 | |||
542 | - Extensions that use build systems based on ``setuptools`` require the | ||
543 | :ref:`setuptools <ref-classes-setuptools>` class in their recipes. | ||
544 | |||
545 | The ``distutils-common-base`` class is required by some of the | ||
546 | ``distutils*`` classes to provide common Python2 support. | ||
547 | |||
548 | .. _ref-classes-distutils3: | ||
549 | |||
550 | ``distutils3*.bbclass`` | ||
551 | ======================= | ||
552 | |||
553 | The ``distutils3*`` classes support recipes for Python version 3.x | ||
554 | extensions, which are simple. These recipes usually only need to point | ||
555 | to the source's archive and then inherit the proper class. Building is | ||
556 | split into three methods depending on which method the module authors | ||
557 | used. | ||
558 | |||
559 | - Extensions that use an Autotools-based build system require Autotools | ||
560 | and ``distutils``-based classes in their recipes. | ||
561 | |||
562 | - Extensions that use ``distutils``-based build systems require the | ||
563 | ``distutils`` class in their recipes. | ||
564 | |||
565 | - Extensions that use build systems based on ``setuptools3`` require | ||
566 | the :ref:`setuptools3 <ref-classes-setuptools>` class in their | ||
567 | recipes. | ||
568 | |||
569 | The ``distutils3*`` classes either inherit their corresponding | ||
570 | ``distutils*`` class or replicate them using a Python3 version instead | ||
571 | (e.g. ``distutils3-base`` inherits ``distutils-common-base``, which is | ||
572 | the same as ``distutils-base`` but inherits ``python3native`` instead of | ||
573 | ``pythonnative``). | ||
574 | |||
575 | .. _ref-classes-externalsrc: | ||
576 | |||
577 | ``externalsrc.bbclass`` | ||
578 | ======================= | ||
579 | |||
580 | The ``externalsrc`` class supports building software from source code | ||
581 | that is external to the OpenEmbedded build system. Building software | ||
582 | from an external source tree means that the build system's normal fetch, | ||
583 | unpack, and patch process is not used. | ||
584 | |||
585 | By default, the OpenEmbedded build system uses the :term:`S` | ||
586 | and :term:`B` variables to locate unpacked recipe source code | ||
587 | and to build it, respectively. When your recipe inherits the | ||
588 | ``externalsrc`` class, you use the | ||
589 | :term:`EXTERNALSRC` and | ||
590 | :term:`EXTERNALSRC_BUILD` variables to | ||
591 | ultimately define ``S`` and ``B``. | ||
592 | |||
593 | By default, this class expects the source code to support recipe builds | ||
594 | that use the :term:`B` variable to point to the directory in | ||
595 | which the OpenEmbedded build system places the generated objects built | ||
596 | from the recipes. By default, the ``B`` directory is set to the | ||
597 | following, which is separate from the source directory (``S``): | ||
598 | :: | ||
599 | |||
600 | ${WORKDIR}/${BPN}/{PV}/ | ||
601 | |||
602 | See these variables for more information: | ||
603 | :term:`WORKDIR`, :term:`BPN`, and | ||
604 | :term:`PV`, | ||
605 | |||
606 | For more information on the ``externalsrc`` class, see the comments in | ||
607 | ``meta/classes/externalsrc.bbclass`` in the :term:`Source Directory`. | ||
608 | For information on how to use the | ||
609 | ``externalsrc`` class, see the | ||
610 | ":ref:`dev-manual/dev-manual-common-tasks:building software from an external source`" | ||
611 | section in the Yocto Project Development Tasks Manual. | ||
612 | |||
613 | .. _ref-classes-extrausers: | ||
614 | |||
615 | ``extrausers.bbclass`` | ||
616 | ====================== | ||
617 | |||
618 | The ``extrausers`` class allows additional user and group configuration | ||
619 | to be applied at the image level. Inheriting this class either globally | ||
620 | or from an image recipe allows additional user and group operations to | ||
621 | be performed using the | ||
622 | :term:`EXTRA_USERS_PARAMS` variable. | ||
623 | |||
624 | .. note:: | ||
625 | |||
626 | The user and group operations added using the | ||
627 | extrausers | ||
628 | class are not tied to a specific recipe outside of the recipe for the | ||
629 | image. Thus, the operations can be performed across the image as a | ||
630 | whole. Use the | ||
631 | useradd | ||
632 | class to add user and group configuration to a specific recipe. | ||
633 | |||
634 | Here is an example that uses this class in an image recipe: | ||
635 | :: | ||
636 | |||
637 | inherit extrausers | ||
638 | EXTRA_USERS_PARAMS = "\ | ||
639 | useradd -p '' tester; \ | ||
640 | groupadd developers; \ | ||
641 | userdel nobody; \ | ||
642 | groupdel -g video; \ | ||
643 | groupmod -g 1020 developers; \ | ||
644 | usermod -s /bin/sh tester; \ | ||
645 | " | ||
646 | |||
647 | Here is an example that adds two users named "tester-jim" and "tester-sue" and assigns | ||
648 | passwords: | ||
649 | :: | ||
650 | |||
651 | inherit extrausers | ||
652 | EXTRA_USERS_PARAMS = "\ | ||
653 | useradd -P tester01 tester-jim; \ | ||
654 | useradd -P tester01 tester-sue; \ | ||
655 | " | ||
656 | |||
657 | Finally, here is an example that sets the root password to "1876*18": | ||
658 | :: | ||
659 | |||
660 | inherit extrausers | ||
661 | EXTRA_USERS_PARAMS = "\ | ||
662 | usermod -P 1876*18 root; \ | ||
663 | " | ||
664 | |||
665 | .. _ref-classes-fontcache: | ||
666 | |||
667 | ``fontcache.bbclass`` | ||
668 | ===================== | ||
669 | |||
670 | The ``fontcache`` class generates the proper post-install and | ||
671 | post-remove (postinst and postrm) scriptlets for font packages. These | ||
672 | scriptlets call ``fc-cache`` (part of ``Fontconfig``) to add the fonts | ||
673 | to the font information cache. Since the cache files are | ||
674 | architecture-specific, ``fc-cache`` runs using QEMU if the postinst | ||
675 | scriptlets need to be run on the build host during image creation. | ||
676 | |||
677 | If the fonts being installed are in packages other than the main | ||
678 | package, set :term:`FONT_PACKAGES` to specify the | ||
679 | packages containing the fonts. | ||
680 | |||
681 | .. _ref-classes-fs-uuid: | ||
682 | |||
683 | ``fs-uuid.bbclass`` | ||
684 | =================== | ||
685 | |||
686 | The ``fs-uuid`` class extracts UUID from | ||
687 | ``${``\ :term:`ROOTFS`\ ``}``, which must have been built | ||
688 | by the time that this function gets called. The ``fs-uuid`` class only | ||
689 | works on ``ext`` file systems and depends on ``tune2fs``. | ||
690 | |||
691 | .. _ref-classes-gconf: | ||
692 | |||
693 | ``gconf.bbclass`` | ||
694 | ================= | ||
695 | |||
696 | The ``gconf`` class provides common functionality for recipes that need | ||
697 | to install GConf schemas. The schemas will be put into a separate | ||
698 | package (``${``\ :term:`PN`\ ``}-gconf``) that is created | ||
699 | automatically when this class is inherited. This package uses the | ||
700 | appropriate post-install and post-remove (postinst/postrm) scriptlets to | ||
701 | register and unregister the schemas in the target image. | ||
702 | |||
703 | .. _ref-classes-gettext: | ||
704 | |||
705 | ``gettext.bbclass`` | ||
706 | =================== | ||
707 | |||
708 | The ``gettext`` class provides support for building software that uses | ||
709 | the GNU ``gettext`` internationalization and localization system. All | ||
710 | recipes building software that use ``gettext`` should inherit this | ||
711 | class. | ||
712 | |||
713 | .. _ref-classes-gnomebase: | ||
714 | |||
715 | ``gnomebase.bbclass`` | ||
716 | ===================== | ||
717 | |||
718 | The ``gnomebase`` class is the base class for recipes that build | ||
719 | software from the GNOME stack. This class sets | ||
720 | :term:`SRC_URI` to download the source from the GNOME | ||
721 | mirrors as well as extending :term:`FILES` with the typical | ||
722 | GNOME installation paths. | ||
723 | |||
724 | .. _ref-classes-gobject-introspection: | ||
725 | |||
726 | ``gobject-introspection.bbclass`` | ||
727 | ================================= | ||
728 | |||
729 | Provides support for recipes building software that supports GObject | ||
730 | introspection. This functionality is only enabled if the | ||
731 | "gobject-introspection-data" feature is in | ||
732 | :term:`DISTRO_FEATURES` as well as | ||
733 | "qemu-usermode" being in | ||
734 | :term:`MACHINE_FEATURES`. | ||
735 | |||
736 | .. note:: | ||
737 | |||
738 | This functionality is backfilled by default and, if not applicable, | ||
739 | should be disabled through | ||
740 | DISTRO_FEATURES_BACKFILL_CONSIDERED | ||
741 | or | ||
742 | MACHINE_FEATURES_BACKFILL_CONSIDERED | ||
743 | , respectively. | ||
744 | |||
745 | .. _ref-classes-grub-efi: | ||
746 | |||
747 | ``grub-efi.bbclass`` | ||
748 | ==================== | ||
749 | |||
750 | The ``grub-efi`` class provides ``grub-efi``-specific functions for | ||
751 | building bootable images. | ||
752 | |||
753 | This class supports several variables: | ||
754 | |||
755 | - :term:`INITRD`: Indicates list of filesystem images to | ||
756 | concatenate and use as an initial RAM disk (initrd) (optional). | ||
757 | |||
758 | - :term:`ROOTFS`: Indicates a filesystem image to include | ||
759 | as the root filesystem (optional). | ||
760 | |||
761 | - :term:`GRUB_GFXSERIAL`: Set this to "1" to have | ||
762 | graphics and serial in the boot menu. | ||
763 | |||
764 | - :term:`LABELS`: A list of targets for the automatic | ||
765 | configuration. | ||
766 | |||
767 | - :term:`APPEND`: An override list of append strings for | ||
768 | each ``LABEL``. | ||
769 | |||
770 | - :term:`GRUB_OPTS`: Additional options to add to the | ||
771 | configuration (optional). Options are delimited using semi-colon | ||
772 | characters (``;``). | ||
773 | |||
774 | - :term:`GRUB_TIMEOUT`: Timeout before executing | ||
775 | the default ``LABEL`` (optional). | ||
776 | |||
777 | .. _ref-classes-gsettings: | ||
778 | |||
779 | ``gsettings.bbclass`` | ||
780 | ===================== | ||
781 | |||
782 | The ``gsettings`` class provides common functionality for recipes that | ||
783 | need to install GSettings (glib) schemas. The schemas are assumed to be | ||
784 | part of the main package. Appropriate post-install and post-remove | ||
785 | (postinst/postrm) scriptlets are added to register and unregister the | ||
786 | schemas in the target image. | ||
787 | |||
788 | .. _ref-classes-gtk-doc: | ||
789 | |||
790 | ``gtk-doc.bbclass`` | ||
791 | =================== | ||
792 | |||
793 | The ``gtk-doc`` class is a helper class to pull in the appropriate | ||
794 | ``gtk-doc`` dependencies and disable ``gtk-doc``. | ||
795 | |||
796 | .. _ref-classes-gtk-icon-cache: | ||
797 | |||
798 | ``gtk-icon-cache.bbclass`` | ||
799 | ========================== | ||
800 | |||
801 | The ``gtk-icon-cache`` class generates the proper post-install and | ||
802 | post-remove (postinst/postrm) scriptlets for packages that use GTK+ and | ||
803 | install icons. These scriptlets call ``gtk-update-icon-cache`` to add | ||
804 | the fonts to GTK+'s icon cache. Since the cache files are | ||
805 | architecture-specific, ``gtk-update-icon-cache`` is run using QEMU if | ||
806 | the postinst scriptlets need to be run on the build host during image | ||
807 | creation. | ||
808 | |||
809 | .. _ref-classes-gtk-immodules-cache: | ||
810 | |||
811 | ``gtk-immodules-cache.bbclass`` | ||
812 | =============================== | ||
813 | |||
814 | The ``gtk-immodules-cache`` class generates the proper post-install and | ||
815 | post-remove (postinst/postrm) scriptlets for packages that install GTK+ | ||
816 | input method modules for virtual keyboards. These scriptlets call | ||
817 | ``gtk-update-icon-cache`` to add the input method modules to the cache. | ||
818 | Since the cache files are architecture-specific, | ||
819 | ``gtk-update-icon-cache`` is run using QEMU if the postinst scriptlets | ||
820 | need to be run on the build host during image creation. | ||
821 | |||
822 | If the input method modules being installed are in packages other than | ||
823 | the main package, set | ||
824 | :term:`GTKIMMODULES_PACKAGES` to specify | ||
825 | the packages containing the modules. | ||
826 | |||
827 | .. _ref-classes-gzipnative: | ||
828 | |||
829 | ``gzipnative.bbclass`` | ||
830 | ====================== | ||
831 | |||
832 | The ``gzipnative`` class enables the use of different native versions of | ||
833 | ``gzip`` and ``pigz`` rather than the versions of these tools from the | ||
834 | build host. | ||
835 | |||
836 | .. _ref-classes-icecc: | ||
837 | |||
838 | ``icecc.bbclass`` | ||
839 | ================= | ||
840 | |||
841 | The ``icecc`` class supports | ||
842 | `Icecream <https://github.com/icecc/icecream>`__, which facilitates | ||
843 | taking compile jobs and distributing them among remote machines. | ||
844 | |||
845 | The class stages directories with symlinks from ``gcc`` and ``g++`` to | ||
846 | ``icecc``, for both native and cross compilers. Depending on each | ||
847 | configure or compile, the OpenEmbedded build system adds the directories | ||
848 | at the head of the ``PATH`` list and then sets the ``ICECC_CXX`` and | ||
849 | ``ICEC_CC`` variables, which are the paths to the ``g++`` and ``gcc`` | ||
850 | compilers, respectively. | ||
851 | |||
852 | For the cross compiler, the class creates a ``tar.gz`` file that | ||
853 | contains the Yocto Project toolchain and sets ``ICECC_VERSION``, which | ||
854 | is the version of the cross-compiler used in the cross-development | ||
855 | toolchain, accordingly. | ||
856 | |||
857 | The class handles all three different compile stages (i.e native | ||
858 | ,cross-kernel and target) and creates the necessary environment | ||
859 | ``tar.gz`` file to be used by the remote machines. The class also | ||
860 | supports SDK generation. | ||
861 | |||
862 | If :term:`ICECC_PATH` is not set in your | ||
863 | ``local.conf`` file, then the class tries to locate the ``icecc`` binary | ||
864 | using ``which``. If :term:`ICECC_ENV_EXEC` is set | ||
865 | in your ``local.conf`` file, the variable should point to the | ||
866 | ``icecc-create-env`` script provided by the user. If you do not point to | ||
867 | a user-provided script, the build system uses the default script | ||
868 | provided by the recipe ``icecc-create-env-native.bb``. | ||
869 | |||
870 | .. note:: | ||
871 | |||
872 | This script is a modified version and not the one that comes with | ||
873 | icecc. | ||
874 | |||
875 | If you do not want the Icecream distributed compile support to apply to | ||
876 | specific recipes or classes, you can effectively "blacklist" them by | ||
877 | listing the recipes and classes using the | ||
878 | :term:`ICECC_USER_PACKAGE_BL` and | ||
879 | :term:`ICECC_USER_CLASS_BL`, variables, | ||
880 | respectively, in your ``local.conf`` file. Doing so causes the | ||
881 | OpenEmbedded build system to handle these compilations locally. | ||
882 | |||
883 | Additionally, you can list recipes using the | ||
884 | :term:`ICECC_USER_PACKAGE_WL` variable in | ||
885 | your ``local.conf`` file to force ``icecc`` to be enabled for recipes | ||
886 | using an empty :term:`PARALLEL_MAKE` variable. | ||
887 | |||
888 | Inheriting the ``icecc`` class changes all sstate signatures. | ||
889 | Consequently, if a development team has a dedicated build system that | ||
890 | populates :term:`SSTATE_MIRRORS` and they want to | ||
891 | reuse sstate from ``SSTATE_MIRRORS``, then all developers and the build | ||
892 | system need to either inherit the ``icecc`` class or nobody should. | ||
893 | |||
894 | At the distribution level, you can inherit the ``icecc`` class to be | ||
895 | sure that all builders start with the same sstate signatures. After | ||
896 | inheriting the class, you can then disable the feature by setting the | ||
897 | :term:`ICECC_DISABLED` variable to "1" as follows: | ||
898 | :: | ||
899 | |||
900 | INHERIT_DISTRO_append = " icecc" | ||
901 | ICECC_DISABLED ??= "1" | ||
902 | |||
903 | This practice | ||
904 | makes sure everyone is using the same signatures but also requires | ||
905 | individuals that do want to use Icecream to enable the feature | ||
906 | individually as follows in your ``local.conf`` file: | ||
907 | :: | ||
908 | |||
909 | ICECC_DISABLED = "" | ||
910 | |||
911 | .. _ref-classes-image: | ||
912 | |||
913 | ``image.bbclass`` | ||
914 | ================= | ||
915 | |||
916 | The ``image`` class helps support creating images in different formats. | ||
917 | First, the root filesystem is created from packages using one of the | ||
918 | ``rootfs*.bbclass`` files (depending on the package format used) and | ||
919 | then one or more image files are created. | ||
920 | |||
921 | - The ``IMAGE_FSTYPES`` variable controls the types of images to | ||
922 | generate. | ||
923 | |||
924 | - The ``IMAGE_INSTALL`` variable controls the list of packages to | ||
925 | install into the image. | ||
926 | |||
927 | For information on customizing images, see the | ||
928 | ":ref:`usingpoky-extend-customimage`" section | ||
929 | in the Yocto Project Development Tasks Manual. For information on how | ||
930 | images are created, see the | ||
931 | ":ref:`images-dev-environment`" section in the | ||
932 | Yocto Project Overview and Concpets Manual. | ||
933 | |||
934 | .. _ref-classes-image-buildinfo: | ||
935 | |||
936 | ``image-buildinfo.bbclass`` | ||
937 | =========================== | ||
938 | |||
939 | The ``image-buildinfo`` class writes information to the target | ||
940 | filesystem on ``/etc/build``. | ||
941 | |||
942 | .. _ref-classes-image_types: | ||
943 | |||
944 | ``image_types.bbclass`` | ||
945 | ======================= | ||
946 | |||
947 | The ``image_types`` class defines all of the standard image output types | ||
948 | that you can enable through the | ||
949 | :term:`IMAGE_FSTYPES` variable. You can use this | ||
950 | class as a reference on how to add support for custom image output | ||
951 | types. | ||
952 | |||
953 | By default, the :ref:`image <ref-classes-image>` class automatically | ||
954 | enables the ``image_types`` class. The ``image`` class uses the | ||
955 | ``IMGCLASSES`` variable as follows: | ||
956 | :: | ||
957 | |||
958 | IMGCLASSES = "rootfs_${IMAGE_PKGTYPE} image_types ${IMAGE_CLASSES}" | ||
959 | IMGCLASSES += "${@['populate_sdk_base', 'populate_sdk_ext']['linux' in d.getVar("SDK_OS")]}" | ||
960 | IMGCLASSES += "${@bb.utils.contains_any('IMAGE_FSTYPES', 'live iso hddimg', 'image-live', '', d)}" | ||
961 | IMGCLASSES += "${@bb.utils.contains('IMAGE_FSTYPES', 'container', 'image-container', '', d)}" | ||
962 | IMGCLASSES += "image_types_wic" | ||
963 | IMGCLASSES += "rootfs-postcommands" | ||
964 | IMGCLASSES += "image-postinst-intercepts" | ||
965 | inherit ${IMGCLASSES} | ||
966 | |||
967 | The ``image_types`` class also handles conversion and compression of images. | ||
968 | |||
969 | .. note:: | ||
970 | |||
971 | To build a VMware VMDK image, you need to add "wic.vmdk" to | ||
972 | IMAGE_FSTYPES | ||
973 | . This would also be similar for Virtual Box Virtual Disk Image | ||
974 | ("vdi") and QEMU Copy On Write Version 2 ("qcow2") images. | ||
975 | |||
976 | .. _ref-classes-image-live: | ||
977 | |||
978 | ``image-live.bbclass`` | ||
979 | ====================== | ||
980 | |||
981 | This class controls building "live" (i.e. HDDIMG and ISO) images. Live | ||
982 | images contain syslinux for legacy booting, as well as the bootloader | ||
983 | specified by :term:`EFI_PROVIDER` if | ||
984 | :term:`MACHINE_FEATURES` contains "efi". | ||
985 | |||
986 | Normally, you do not use this class directly. Instead, you add "live" to | ||
987 | :term:`IMAGE_FSTYPES`. | ||
988 | |||
989 | .. _ref-classes-image-mklibs: | ||
990 | |||
991 | ``image-mklibs.bbclass`` | ||
992 | ======================== | ||
993 | |||
994 | The ``image-mklibs`` class enables the use of the ``mklibs`` utility | ||
995 | during the :ref:`ref-tasks-rootfs` task, which optimizes | ||
996 | the size of libraries contained in the image. | ||
997 | |||
998 | By default, the class is enabled in the ``local.conf.template`` using | ||
999 | the :term:`USER_CLASSES` variable as follows: | ||
1000 | :: | ||
1001 | |||
1002 | USER_CLASSES ?= "buildstats image-mklibs image-prelink" | ||
1003 | |||
1004 | .. _ref-classes-image-prelink: | ||
1005 | |||
1006 | ``image-prelink.bbclass`` | ||
1007 | ========================= | ||
1008 | |||
1009 | The ``image-prelink`` class enables the use of the ``prelink`` utility | ||
1010 | during the :ref:`ref-tasks-rootfs` task, which optimizes | ||
1011 | the dynamic linking of shared libraries to reduce executable startup | ||
1012 | time. | ||
1013 | |||
1014 | By default, the class is enabled in the ``local.conf.template`` using | ||
1015 | the :term:`USER_CLASSES` variable as follows: | ||
1016 | :: | ||
1017 | |||
1018 | USER_CLASSES ?= "buildstats image-mklibs image-prelink" | ||
1019 | |||
1020 | .. _ref-classes-insane: | ||
1021 | |||
1022 | ``insane.bbclass`` | ||
1023 | ================== | ||
1024 | |||
1025 | The ``insane`` class adds a step to the package generation process so | ||
1026 | that output quality assurance checks are generated by the OpenEmbedded | ||
1027 | build system. A range of checks are performed that check the build's | ||
1028 | output for common problems that show up during runtime. Distribution | ||
1029 | policy usually dictates whether to include this class. | ||
1030 | |||
1031 | You can configure the sanity checks so that specific test failures | ||
1032 | either raise a warning or an error message. Typically, failures for new | ||
1033 | tests generate a warning. Subsequent failures for the same test would | ||
1034 | then generate an error message once the metadata is in a known and good | ||
1035 | condition. See the "`QA Error and Warning Messages <#ref-qa-checks>`__" | ||
1036 | Chapter for a list of all the warning and error messages you might | ||
1037 | encounter using a default configuration. | ||
1038 | |||
1039 | Use the :term:`WARN_QA` and | ||
1040 | :term:`ERROR_QA` variables to control the behavior of | ||
1041 | these checks at the global level (i.e. in your custom distro | ||
1042 | configuration). However, to skip one or more checks in recipes, you | ||
1043 | should use :term:`INSANE_SKIP`. For example, to skip | ||
1044 | the check for symbolic link ``.so`` files in the main package of a | ||
1045 | recipe, add the following to the recipe. You need to realize that the | ||
1046 | package name override, in this example ``${PN}``, must be used: | ||
1047 | :: | ||
1048 | |||
1049 | INSANE_SKIP_${PN} += "dev-so" | ||
1050 | |||
1051 | Please keep in mind that the QA checks | ||
1052 | exist in order to detect real or potential problems in the packaged | ||
1053 | output. So exercise caution when disabling these checks. | ||
1054 | |||
1055 | The following list shows the tests you can list with the ``WARN_QA`` and | ||
1056 | ``ERROR_QA`` variables: | ||
1057 | |||
1058 | - ``already-stripped:`` Checks that produced binaries have not | ||
1059 | already been stripped prior to the build system extracting debug | ||
1060 | symbols. It is common for upstream software projects to default to | ||
1061 | stripping debug symbols for output binaries. In order for debugging | ||
1062 | to work on the target using ``-dbg`` packages, this stripping must be | ||
1063 | disabled. | ||
1064 | |||
1065 | - ``arch:`` Checks the Executable and Linkable Format (ELF) type, bit | ||
1066 | size, and endianness of any binaries to ensure they match the target | ||
1067 | architecture. This test fails if any binaries do not match the type | ||
1068 | since there would be an incompatibility. The test could indicate that | ||
1069 | the wrong compiler or compiler options have been used. Sometimes | ||
1070 | software, like bootloaders, might need to bypass this check. | ||
1071 | |||
1072 | - ``buildpaths:`` Checks for paths to locations on the build host | ||
1073 | inside the output files. Currently, this test triggers too many false | ||
1074 | positives and thus is not normally enabled. | ||
1075 | |||
1076 | - ``build-deps:`` Determines if a build-time dependency that is | ||
1077 | specified through :term:`DEPENDS`, explicit | ||
1078 | :term:`RDEPENDS`, or task-level dependencies exists | ||
1079 | to match any runtime dependency. This determination is particularly | ||
1080 | useful to discover where runtime dependencies are detected and added | ||
1081 | during packaging. If no explicit dependency has been specified within | ||
1082 | the metadata, at the packaging stage it is too late to ensure that | ||
1083 | the dependency is built, and thus you can end up with an error when | ||
1084 | the package is installed into the image during the | ||
1085 | :ref:`ref-tasks-rootfs` task because the auto-detected | ||
1086 | dependency was not satisfied. An example of this would be where the | ||
1087 | :ref:`update-rc.d <ref-classes-update-rc.d>` class automatically | ||
1088 | adds a dependency on the ``initscripts-functions`` package to | ||
1089 | packages that install an initscript that refers to | ||
1090 | ``/etc/init.d/functions``. The recipe should really have an explicit | ||
1091 | ``RDEPENDS`` for the package in question on ``initscripts-functions`` | ||
1092 | so that the OpenEmbedded build system is able to ensure that the | ||
1093 | ``initscripts`` recipe is actually built and thus the | ||
1094 | ``initscripts-functions`` package is made available. | ||
1095 | |||
1096 | - ``compile-host-path:`` Checks the | ||
1097 | :ref:`ref-tasks-compile` log for indications that | ||
1098 | paths to locations on the build host were used. Using such paths | ||
1099 | might result in host contamination of the build output. | ||
1100 | |||
1101 | - ``debug-deps:`` Checks that all packages except ``-dbg`` packages | ||
1102 | do not depend on ``-dbg`` packages, which would cause a packaging | ||
1103 | bug. | ||
1104 | |||
1105 | - ``debug-files:`` Checks for ``.debug`` directories in anything but | ||
1106 | the ``-dbg`` package. The debug files should all be in the ``-dbg`` | ||
1107 | package. Thus, anything packaged elsewhere is incorrect packaging. | ||
1108 | |||
1109 | - ``dep-cmp:`` Checks for invalid version comparison statements in | ||
1110 | runtime dependency relationships between packages (i.e. in | ||
1111 | :term:`RDEPENDS`, | ||
1112 | :term:`RRECOMMENDS`, | ||
1113 | :term:`RSUGGESTS`, | ||
1114 | :term:`RPROVIDES`, | ||
1115 | :term:`RREPLACES`, and | ||
1116 | :term:`RCONFLICTS` variable values). Any invalid | ||
1117 | comparisons might trigger failures or undesirable behavior when | ||
1118 | passed to the package manager. | ||
1119 | |||
1120 | - ``desktop:`` Runs the ``desktop-file-validate`` program against any | ||
1121 | ``.desktop`` files to validate their contents against the | ||
1122 | specification for ``.desktop`` files. | ||
1123 | |||
1124 | - ``dev-deps:`` Checks that all packages except ``-dev`` or | ||
1125 | ``-staticdev`` packages do not depend on ``-dev`` packages, which | ||
1126 | would be a packaging bug. | ||
1127 | |||
1128 | - ``dev-so:`` Checks that the ``.so`` symbolic links are in the | ||
1129 | ``-dev`` package and not in any of the other packages. In general, | ||
1130 | these symlinks are only useful for development purposes. Thus, the | ||
1131 | ``-dev`` package is the correct location for them. Some very rare | ||
1132 | cases do exist for dynamically loaded modules where these symlinks | ||
1133 | are needed instead in the main package. | ||
1134 | |||
1135 | - ``file-rdeps:`` Checks that file-level dependencies identified by | ||
1136 | the OpenEmbedded build system at packaging time are satisfied. For | ||
1137 | example, a shell script might start with the line ``#!/bin/bash``. | ||
1138 | This line would translate to a file dependency on ``/bin/bash``. Of | ||
1139 | the three package managers that the OpenEmbedded build system | ||
1140 | supports, only RPM directly handles file-level dependencies, | ||
1141 | resolving them automatically to packages providing the files. | ||
1142 | However, the lack of that functionality in the other two package | ||
1143 | managers does not mean the dependencies do not still need resolving. | ||
1144 | This QA check attempts to ensure that explicitly declared | ||
1145 | :term:`RDEPENDS` exist to handle any file-level | ||
1146 | dependency detected in packaged files. | ||
1147 | |||
1148 | - ``files-invalid:`` Checks for :term:`FILES` variable | ||
1149 | values that contain "//", which is invalid. | ||
1150 | |||
1151 | - ``host-user-contaminated:`` Checks that no package produced by the | ||
1152 | recipe contains any files outside of ``/home`` with a user or group | ||
1153 | ID that matches the user running BitBake. A match usually indicates | ||
1154 | that the files are being installed with an incorrect UID/GID, since | ||
1155 | target IDs are independent from host IDs. For additional information, | ||
1156 | see the section describing the | ||
1157 | :ref:`ref-tasks-install` task. | ||
1158 | |||
1159 | - ``incompatible-license:`` Report when packages are excluded from | ||
1160 | being created due to being marked with a license that is in | ||
1161 | :term:`INCOMPATIBLE_LICENSE`. | ||
1162 | |||
1163 | - ``install-host-path:`` Checks the | ||
1164 | :ref:`ref-tasks-install` log for indications that | ||
1165 | paths to locations on the build host were used. Using such paths | ||
1166 | might result in host contamination of the build output. | ||
1167 | |||
1168 | - ``installed-vs-shipped:`` Reports when files have been installed | ||
1169 | within ``do_install`` but have not been included in any package by | ||
1170 | way of the :term:`FILES` variable. Files that do not | ||
1171 | appear in any package cannot be present in an image later on in the | ||
1172 | build process. Ideally, all installed files should be packaged or not | ||
1173 | installed at all. These files can be deleted at the end of | ||
1174 | ``do_install`` if the files are not needed in any package. | ||
1175 | |||
1176 | - ``invalid-chars:`` Checks that the recipe metadata variables | ||
1177 | :term:`DESCRIPTION`, | ||
1178 | :term:`SUMMARY`, :term:`LICENSE`, and | ||
1179 | :term:`SECTION` do not contain non-UTF-8 characters. | ||
1180 | Some package managers do not support such characters. | ||
1181 | |||
1182 | - ``invalid-packageconfig:`` Checks that no undefined features are | ||
1183 | being added to :term:`PACKAGECONFIG`. For | ||
1184 | example, any name "foo" for which the following form does not exist: | ||
1185 | :: | ||
1186 | |||
1187 | PACKAGECONFIG[foo] = "..." | ||
1188 | |||
1189 | - ``la:`` Checks ``.la`` files for any ``TMPDIR`` paths. Any ``.la`` | ||
1190 | file containing these paths is incorrect since ``libtool`` adds the | ||
1191 | correct sysroot prefix when using the files automatically itself. | ||
1192 | |||
1193 | - ``ldflags:`` Ensures that the binaries were linked with the | ||
1194 | :term:`LDFLAGS` options provided by the build system. | ||
1195 | If this test fails, check that the ``LDFLAGS`` variable is being | ||
1196 | passed to the linker command. | ||
1197 | |||
1198 | - ``libdir:`` Checks for libraries being installed into incorrect | ||
1199 | (possibly hardcoded) installation paths. For example, this test will | ||
1200 | catch recipes that install ``/lib/bar.so`` when ``${base_libdir}`` is | ||
1201 | "lib32". Another example is when recipes install | ||
1202 | ``/usr/lib64/foo.so`` when ``${libdir}`` is "/usr/lib". | ||
1203 | |||
1204 | - ``libexec:`` Checks if a package contains files in | ||
1205 | ``/usr/libexec``. This check is not performed if the ``libexecdir`` | ||
1206 | variable has been set explicitly to ``/usr/libexec``. | ||
1207 | |||
1208 | - ``packages-list:`` Checks for the same package being listed | ||
1209 | multiple times through the :term:`PACKAGES` variable | ||
1210 | value. Installing the package in this manner can cause errors during | ||
1211 | packaging. | ||
1212 | |||
1213 | - ``perm-config:`` Reports lines in ``fs-perms.txt`` that have an | ||
1214 | invalid format. | ||
1215 | |||
1216 | - ``perm-line:`` Reports lines in ``fs-perms.txt`` that have an | ||
1217 | invalid format. | ||
1218 | |||
1219 | - ``perm-link:`` Reports lines in ``fs-perms.txt`` that specify | ||
1220 | 'link' where the specified target already exists. | ||
1221 | |||
1222 | - ``perms:`` Currently, this check is unused but reserved. | ||
1223 | |||
1224 | - ``pkgconfig:`` Checks ``.pc`` files for any | ||
1225 | :term:`TMPDIR`/:term:`WORKDIR` paths. | ||
1226 | Any ``.pc`` file containing these paths is incorrect since | ||
1227 | ``pkg-config`` itself adds the correct sysroot prefix when the files | ||
1228 | are accessed. | ||
1229 | |||
1230 | - ``pkgname:`` Checks that all packages in | ||
1231 | :term:`PACKAGES` have names that do not contain | ||
1232 | invalid characters (i.e. characters other than 0-9, a-z, ., +, and | ||
1233 | -). | ||
1234 | |||
1235 | - ``pkgv-undefined:`` Checks to see if the ``PKGV`` variable is | ||
1236 | undefined during :ref:`ref-tasks-package`. | ||
1237 | |||
1238 | - ``pkgvarcheck:`` Checks through the variables | ||
1239 | :term:`RDEPENDS`, | ||
1240 | :term:`RRECOMMENDS`, | ||
1241 | :term:`RSUGGESTS`, | ||
1242 | :term:`RCONFLICTS`, | ||
1243 | :term:`RPROVIDES`, | ||
1244 | :term:`RREPLACES`, :term:`FILES`, | ||
1245 | :term:`ALLOW_EMPTY`, ``pkg_preinst``, | ||
1246 | ``pkg_postinst``, ``pkg_prerm`` and ``pkg_postrm``, and reports if | ||
1247 | there are variable sets that are not package-specific. Using these | ||
1248 | variables without a package suffix is bad practice, and might | ||
1249 | unnecessarily complicate dependencies of other packages within the | ||
1250 | same recipe or have other unintended consequences. | ||
1251 | |||
1252 | - ``pn-overrides:`` Checks that a recipe does not have a name | ||
1253 | (:term:`PN`) value that appears in | ||
1254 | :term:`OVERRIDES`. If a recipe is named such that | ||
1255 | its ``PN`` value matches something already in ``OVERRIDES`` (e.g. | ||
1256 | ``PN`` happens to be the same as :term:`MACHINE` or | ||
1257 | :term:`DISTRO`), it can have unexpected consequences. | ||
1258 | For example, assignments such as ``FILES_${PN} = "xyz"`` effectively | ||
1259 | turn into ``FILES = "xyz"``. | ||
1260 | |||
1261 | - ``rpaths:`` Checks for rpaths in the binaries that contain build | ||
1262 | system paths such as ``TMPDIR``. If this test fails, bad ``-rpath`` | ||
1263 | options are being passed to the linker commands and your binaries | ||
1264 | have potential security issues. | ||
1265 | |||
1266 | - ``split-strip:`` Reports that splitting or stripping debug symbols | ||
1267 | from binaries has failed. | ||
1268 | |||
1269 | - ``staticdev:`` Checks for static library files (``*.a``) in | ||
1270 | non-``staticdev`` packages. | ||
1271 | |||
1272 | - ``symlink-to-sysroot:`` Checks for symlinks in packages that point | ||
1273 | into :term:`TMPDIR` on the host. Such symlinks will | ||
1274 | work on the host, but are clearly invalid when running on the target. | ||
1275 | |||
1276 | - ``textrel:`` Checks for ELF binaries that contain relocations in | ||
1277 | their ``.text`` sections, which can result in a performance impact at | ||
1278 | runtime. See the explanation for the | ||
1279 | ```ELF binary`` <#qa-issue-textrel>`__ message for more information | ||
1280 | regarding runtime performance issues. | ||
1281 | |||
1282 | - ``unlisted-pkg-lics:`` Checks that all declared licenses applying | ||
1283 | for a package are also declared on the recipe level (i.e. any license | ||
1284 | in ``LICENSE_*`` should appear in :term:`LICENSE`). | ||
1285 | |||
1286 | - ``useless-rpaths:`` Checks for dynamic library load paths (rpaths) | ||
1287 | in the binaries that by default on a standard system are searched by | ||
1288 | the linker (e.g. ``/lib`` and ``/usr/lib``). While these paths will | ||
1289 | not cause any breakage, they do waste space and are unnecessary. | ||
1290 | |||
1291 | - ``var-undefined:`` Reports when variables fundamental to packaging | ||
1292 | (i.e. :term:`WORKDIR`, | ||
1293 | :term:`DEPLOY_DIR`, :term:`D`, | ||
1294 | :term:`PN`, and :term:`PKGD`) are undefined | ||
1295 | during :ref:`ref-tasks-package`. | ||
1296 | |||
1297 | - ``version-going-backwards:`` If Build History is enabled, reports | ||
1298 | when a package being written out has a lower version than the | ||
1299 | previously written package under the same name. If you are placing | ||
1300 | output packages into a feed and upgrading packages on a target system | ||
1301 | using that feed, the version of a package going backwards can result | ||
1302 | in the target system not correctly upgrading to the "new" version of | ||
1303 | the package. | ||
1304 | |||
1305 | .. note:: | ||
1306 | |||
1307 | If you are not using runtime package management on your target | ||
1308 | system, then you do not need to worry about this situation. | ||
1309 | |||
1310 | - ``xorg-driver-abi:`` Checks that all packages containing Xorg | ||
1311 | drivers have ABI dependencies. The ``xserver-xorg`` recipe provides | ||
1312 | driver ABI names. All drivers should depend on the ABI versions that | ||
1313 | they have been built against. Driver recipes that include | ||
1314 | ``xorg-driver-input.inc`` or ``xorg-driver-video.inc`` will | ||
1315 | automatically get these versions. Consequently, you should only need | ||
1316 | to explicitly add dependencies to binary driver recipes. | ||
1317 | |||
1318 | .. _ref-classes-insserv: | ||
1319 | |||
1320 | ``insserv.bbclass`` | ||
1321 | =================== | ||
1322 | |||
1323 | The ``insserv`` class uses the ``insserv`` utility to update the order | ||
1324 | of symbolic links in ``/etc/rc?.d/`` within an image based on | ||
1325 | dependencies specified by LSB headers in the ``init.d`` scripts | ||
1326 | themselves. | ||
1327 | |||
1328 | .. _ref-classes-kernel: | ||
1329 | |||
1330 | ``kernel.bbclass`` | ||
1331 | ================== | ||
1332 | |||
1333 | The ``kernel`` class handles building Linux kernels. The class contains | ||
1334 | code to build all kernel trees. All needed headers are staged into the | ||
1335 | ``STAGING_KERNEL_DIR`` directory to allow out-of-tree module builds | ||
1336 | using the :ref:`module <ref-classes-module>` class. | ||
1337 | |||
1338 | This means that each built kernel module is packaged separately and | ||
1339 | inter-module dependencies are created by parsing the ``modinfo`` output. | ||
1340 | If all modules are required, then installing the ``kernel-modules`` | ||
1341 | package installs all packages with modules and various other kernel | ||
1342 | packages such as ``kernel-vmlinux``. | ||
1343 | |||
1344 | The ``kernel`` class contains logic that allows you to embed an initial | ||
1345 | RAM filesystem (initramfs) image when you build the kernel image. For | ||
1346 | information on how to build an initramfs, see the | ||
1347 | ":ref:`building-an-initramfs-image`" section in | ||
1348 | the Yocto Project Development Tasks Manual. | ||
1349 | |||
1350 | Various other classes are used by the ``kernel`` and ``module`` classes | ||
1351 | internally including the :ref:`kernel-arch <ref-classes-kernel-arch>`, | ||
1352 | :ref:`module-base <ref-classes-module-base>`, and | ||
1353 | :ref:`linux-kernel-base <ref-classes-linux-kernel-base>` classes. | ||
1354 | |||
1355 | .. _ref-classes-kernel-arch: | ||
1356 | |||
1357 | ``kernel-arch.bbclass`` | ||
1358 | ======================= | ||
1359 | |||
1360 | The ``kernel-arch`` class sets the ``ARCH`` environment variable for | ||
1361 | Linux kernel compilation (including modules). | ||
1362 | |||
1363 | .. _ref-classes-kernel-devicetree: | ||
1364 | |||
1365 | ``kernel-devicetree.bbclass`` | ||
1366 | ============================= | ||
1367 | |||
1368 | The ``kernel-devicetree`` class, which is inherited by the | ||
1369 | :ref:`kernel <ref-classes-kernel>` class, supports device tree | ||
1370 | generation. | ||
1371 | |||
1372 | .. _ref-classes-kernel-fitimage: | ||
1373 | |||
1374 | ``kernel-fitimage.bbclass`` | ||
1375 | =========================== | ||
1376 | |||
1377 | The ``kernel-fitimage`` class provides support to pack a kernel Image, | ||
1378 | device trees and a RAM disk into a single FIT image. In theory, a FIT | ||
1379 | image can support any number of kernels, RAM disks and device-trees. | ||
1380 | However, ``kernel-fitimage`` currently only supports | ||
1381 | limited usescases: just one kernel image, an optional RAM disk, and | ||
1382 | any number of device tree. | ||
1383 | |||
1384 | To create a FIT image, it is required that :term:`KERNEL_CLASSES` | ||
1385 | is set to "kernel-fitimage" and :term:`KERNEL_IMAGETYPE` | ||
1386 | is set to "fitImage". | ||
1387 | |||
1388 | The options for the device tree compiler passed to mkimage -D feature | ||
1389 | when creating the FIT image are specified using the | ||
1390 | :term:`UBOOT_MKIMAGE_DTCOPTS` variable. | ||
1391 | |||
1392 | Only a single kernel can be added to the FIT image created by | ||
1393 | ``kernel-fitimage`` and the kernel image in FIT is mandatory. The | ||
1394 | address where the kernel image is to be loaded by U-boot is | ||
1395 | specified by :term:`UBOOT_LOADADDRESS` and the entrypoint by | ||
1396 | :term:`UBOOT_ENTRYPOINT`. | ||
1397 | |||
1398 | Multiple device trees can be added to the FIT image created by | ||
1399 | ``kernel-fitimage`` and the device tree is optional. | ||
1400 | The address where the device tree is to be loaded by U-boot is | ||
1401 | specified by :term:`UBOOT_DTBO_LOADADDRESS` for device tree overlays | ||
1402 | and by `:term:`UBOOT_DTB_LOADADDRESS` for device tree binaries. | ||
1403 | |||
1404 | Only a single RAM disk can be added to the FIT image created by | ||
1405 | ``kernel-fitimage`` and the RAM disk in FIT is optional. | ||
1406 | The address where the RAM disk image is to be loaded by U-boot | ||
1407 | is specified by :term:`UBOOT_RD_LOADADDRESS` and the entrypoint by | ||
1408 | :term:`UBOOT_RD_ENTRYPOINT`. The ramdisk is added to FIT image when | ||
1409 | :term:`INITRAMFS_IMAGE` is specified. | ||
1410 | |||
1411 | The FIT image generated by ``kernel-fitimage`` class is signed when the | ||
1412 | variables :term:`UBOOT_SIGN_ENABLE`, :term:`UBOOT_MKIMAGE_DTCOPTS`, | ||
1413 | :term:`UBOOT_SIGN_KEYDIR` and :term:`UBOOT_SIGN_KEYNAME` are set | ||
1414 | appropriately. The default values used for :term:`FIT_HASH_ALG` and | ||
1415 | :term:`FIT_SIGN_ALG` in ``kernel-fitimage`` are "sha256" and | ||
1416 | "rsa2048" respectively. | ||
1417 | |||
1418 | |||
1419 | .. _ref-classes-kernel-grub: | ||
1420 | |||
1421 | ``kernel-grub.bbclass`` | ||
1422 | ======================= | ||
1423 | |||
1424 | The ``kernel-grub`` class updates the boot area and the boot menu with | ||
1425 | the kernel as the priority boot mechanism while installing a RPM to | ||
1426 | update the kernel on a deployed target. | ||
1427 | |||
1428 | .. _ref-classes-kernel-module-split: | ||
1429 | |||
1430 | ``kernel-module-split.bbclass`` | ||
1431 | =============================== | ||
1432 | |||
1433 | The ``kernel-module-split`` class provides common functionality for | ||
1434 | splitting Linux kernel modules into separate packages. | ||
1435 | |||
1436 | .. _ref-classes-kernel-uboot: | ||
1437 | |||
1438 | ``kernel-uboot.bbclass`` | ||
1439 | ======================== | ||
1440 | |||
1441 | The ``kernel-uboot`` class provides support for building from | ||
1442 | vmlinux-style kernel sources. | ||
1443 | |||
1444 | .. _ref-classes-kernel-uimage: | ||
1445 | |||
1446 | ``kernel-uimage.bbclass`` | ||
1447 | ========================= | ||
1448 | |||
1449 | The ``kernel-uimage`` class provides support to pack uImage. | ||
1450 | |||
1451 | .. _ref-classes-kernel-yocto: | ||
1452 | |||
1453 | ``kernel-yocto.bbclass`` | ||
1454 | ======================== | ||
1455 | |||
1456 | The ``kernel-yocto`` class provides common functionality for building | ||
1457 | from linux-yocto style kernel source repositories. | ||
1458 | |||
1459 | .. _ref-classes-kernelsrc: | ||
1460 | |||
1461 | ``kernelsrc.bbclass`` | ||
1462 | ===================== | ||
1463 | |||
1464 | The ``kernelsrc`` class sets the Linux kernel source and version. | ||
1465 | |||
1466 | .. _ref-classes-lib_package: | ||
1467 | |||
1468 | ``lib_package.bbclass`` | ||
1469 | ======================= | ||
1470 | |||
1471 | The ``lib_package`` class supports recipes that build libraries and | ||
1472 | produce executable binaries, where those binaries should not be | ||
1473 | installed by default along with the library. Instead, the binaries are | ||
1474 | added to a separate ``${``\ :term:`PN`\ ``}-bin`` package to | ||
1475 | make their installation optional. | ||
1476 | |||
1477 | .. _ref-classes-libc*: | ||
1478 | |||
1479 | ``libc*.bbclass`` | ||
1480 | ================= | ||
1481 | |||
1482 | The ``libc*`` classes support recipes that build packages with ``libc``: | ||
1483 | |||
1484 | - The ``libc-common`` class provides common support for building with | ||
1485 | ``libc``. | ||
1486 | |||
1487 | - The ``libc-package`` class supports packaging up ``glibc`` and | ||
1488 | ``eglibc``. | ||
1489 | |||
1490 | .. _ref-classes-license: | ||
1491 | |||
1492 | ``license.bbclass`` | ||
1493 | =================== | ||
1494 | |||
1495 | The ``license`` class provides license manifest creation and license | ||
1496 | exclusion. This class is enabled by default using the default value for | ||
1497 | the :term:`INHERIT_DISTRO` variable. | ||
1498 | |||
1499 | .. _ref-classes-linux-kernel-base: | ||
1500 | |||
1501 | ``linux-kernel-base.bbclass`` | ||
1502 | ============================= | ||
1503 | |||
1504 | The ``linux-kernel-base`` class provides common functionality for | ||
1505 | recipes that build out of the Linux kernel source tree. These builds | ||
1506 | goes beyond the kernel itself. For example, the Perf recipe also | ||
1507 | inherits this class. | ||
1508 | |||
1509 | .. _ref-classes-linuxloader: | ||
1510 | |||
1511 | ``linuxloader.bbclass`` | ||
1512 | ======================= | ||
1513 | |||
1514 | Provides the function ``linuxloader()``, which gives the value of the | ||
1515 | dynamic loader/linker provided on the platform. This value is used by a | ||
1516 | number of other classes. | ||
1517 | |||
1518 | .. _ref-classes-logging: | ||
1519 | |||
1520 | ``logging.bbclass`` | ||
1521 | =================== | ||
1522 | |||
1523 | The ``logging`` class provides the standard shell functions used to log | ||
1524 | messages for various BitBake severity levels (i.e. ``bbplain``, | ||
1525 | ``bbnote``, ``bbwarn``, ``bberror``, ``bbfatal``, and ``bbdebug``). | ||
1526 | |||
1527 | This class is enabled by default since it is inherited by the ``base`` | ||
1528 | class. | ||
1529 | |||
1530 | .. _ref-classes-meta: | ||
1531 | |||
1532 | ``meta.bbclass`` | ||
1533 | ================ | ||
1534 | |||
1535 | The ``meta`` class is inherited by recipes that do not build any output | ||
1536 | packages themselves, but act as a "meta" target for building other | ||
1537 | recipes. | ||
1538 | |||
1539 | .. _ref-classes-metadata_scm: | ||
1540 | |||
1541 | ``metadata_scm.bbclass`` | ||
1542 | ======================== | ||
1543 | |||
1544 | The ``metadata_scm`` class provides functionality for querying the | ||
1545 | branch and revision of a Source Code Manager (SCM) repository. | ||
1546 | |||
1547 | The :ref:`base <ref-classes-base>` class uses this class to print the | ||
1548 | revisions of each layer before starting every build. The | ||
1549 | ``metadata_scm`` class is enabled by default because it is inherited by | ||
1550 | the ``base`` class. | ||
1551 | |||
1552 | .. _ref-classes-migrate_localcount: | ||
1553 | |||
1554 | ``migrate_localcount.bbclass`` | ||
1555 | ============================== | ||
1556 | |||
1557 | The ``migrate_localcount`` class verifies a recipe's localcount data and | ||
1558 | increments it appropriately. | ||
1559 | |||
1560 | .. _ref-classes-mime: | ||
1561 | |||
1562 | ``mime.bbclass`` | ||
1563 | ================ | ||
1564 | |||
1565 | The ``mime`` class generates the proper post-install and post-remove | ||
1566 | (postinst/postrm) scriptlets for packages that install MIME type files. | ||
1567 | These scriptlets call ``update-mime-database`` to add the MIME types to | ||
1568 | the shared database. | ||
1569 | |||
1570 | .. _ref-classes-mirrors: | ||
1571 | |||
1572 | ``mirrors.bbclass`` | ||
1573 | =================== | ||
1574 | |||
1575 | The ``mirrors`` class sets up some standard | ||
1576 | :term:`MIRRORS` entries for source code mirrors. These | ||
1577 | mirrors provide a fall-back path in case the upstream source specified | ||
1578 | in :term:`SRC_URI` within recipes is unavailable. | ||
1579 | |||
1580 | This class is enabled by default since it is inherited by the | ||
1581 | :ref:`base <ref-classes-base>` class. | ||
1582 | |||
1583 | .. _ref-classes-module: | ||
1584 | |||
1585 | ``module.bbclass`` | ||
1586 | ================== | ||
1587 | |||
1588 | The ``module`` class provides support for building out-of-tree Linux | ||
1589 | kernel modules. The class inherits the | ||
1590 | :ref:`module-base <ref-classes-module-base>` and | ||
1591 | :ref:`kernel-module-split <ref-classes-kernel-module-split>` classes, | ||
1592 | and implements the :ref:`ref-tasks-compile` and | ||
1593 | :ref:`ref-tasks-install` tasks. The class provides | ||
1594 | everything needed to build and package a kernel module. | ||
1595 | |||
1596 | For general information on out-of-tree Linux kernel modules, see the | ||
1597 | ":ref:`kernel-dev/kernel-dev-common:incorporating out-of-tree modules`" | ||
1598 | section in the Yocto Project Linux Kernel Development Manual. | ||
1599 | |||
1600 | .. _ref-classes-module-base: | ||
1601 | |||
1602 | ``module-base.bbclass`` | ||
1603 | ======================= | ||
1604 | |||
1605 | The ``module-base`` class provides the base functionality for building | ||
1606 | Linux kernel modules. Typically, a recipe that builds software that | ||
1607 | includes one or more kernel modules and has its own means of building | ||
1608 | the module inherits this class as opposed to inheriting the | ||
1609 | :ref:`module <ref-classes-module>` class. | ||
1610 | |||
1611 | .. _ref-classes-multilib*: | ||
1612 | |||
1613 | ``multilib*.bbclass`` | ||
1614 | ===================== | ||
1615 | |||
1616 | The ``multilib*`` classes provide support for building libraries with | ||
1617 | different target optimizations or target architectures and installing | ||
1618 | them side-by-side in the same image. | ||
1619 | |||
1620 | For more information on using the Multilib feature, see the | ||
1621 | ":ref:`combining-multiple-versions-library-files-into-one-image`" | ||
1622 | section in the Yocto Project Development Tasks Manual. | ||
1623 | |||
1624 | .. _ref-classes-native: | ||
1625 | |||
1626 | ``native.bbclass`` | ||
1627 | ================== | ||
1628 | |||
1629 | The ``native`` class provides common functionality for recipes that | ||
1630 | build tools to run on the `build host <#hardware-build-system-term>`__ | ||
1631 | (i.e. tools that use the compiler or other tools from the build host). | ||
1632 | |||
1633 | You can create a recipe that builds tools that run natively on the host | ||
1634 | a couple different ways: | ||
1635 | |||
1636 | - Create a myrecipe\ ``-native.bb`` recipe that inherits the ``native`` | ||
1637 | class. If you use this method, you must order the inherit statement | ||
1638 | in the recipe after all other inherit statements so that the | ||
1639 | ``native`` class is inherited last. | ||
1640 | |||
1641 | .. note:: | ||
1642 | |||
1643 | When creating a recipe this way, the recipe name must follow this | ||
1644 | naming convention: | ||
1645 | :: | ||
1646 | |||
1647 | myrecipe-native.bb | ||
1648 | |||
1649 | |||
1650 | Not using this naming convention can lead to subtle problems | ||
1651 | caused by existing code that depends on that naming convention. | ||
1652 | |||
1653 | - Create or modify a target recipe that contains the following: | ||
1654 | :: | ||
1655 | |||
1656 | BBCLASSEXTEND = "native" | ||
1657 | |||
1658 | Inside the | ||
1659 | recipe, use ``_class-native`` and ``_class-target`` overrides to | ||
1660 | specify any functionality specific to the respective native or target | ||
1661 | case. | ||
1662 | |||
1663 | Although applied differently, the ``native`` class is used with both | ||
1664 | methods. The advantage of the second method is that you do not need to | ||
1665 | have two separate recipes (assuming you need both) for native and | ||
1666 | target. All common parts of the recipe are automatically shared. | ||
1667 | |||
1668 | .. _ref-classes-nativesdk: | ||
1669 | |||
1670 | ``nativesdk.bbclass`` | ||
1671 | ===================== | ||
1672 | |||
1673 | The ``nativesdk`` class provides common functionality for recipes that | ||
1674 | wish to build tools to run as part of an SDK (i.e. tools that run on | ||
1675 | :term:`SDKMACHINE`). | ||
1676 | |||
1677 | You can create a recipe that builds tools that run on the SDK machine a | ||
1678 | couple different ways: | ||
1679 | |||
1680 | - Create a ``nativesdk-``\ myrecipe\ ``.bb`` recipe that inherits the | ||
1681 | ``nativesdk`` class. If you use this method, you must order the | ||
1682 | inherit statement in the recipe after all other inherit statements so | ||
1683 | that the ``nativesdk`` class is inherited last. | ||
1684 | |||
1685 | - Create a ``nativesdk`` variant of any recipe by adding the following: | ||
1686 | :: | ||
1687 | |||
1688 | BBCLASSEXTEND = "nativesdk" | ||
1689 | |||
1690 | Inside the | ||
1691 | recipe, use ``_class-nativesdk`` and ``_class-target`` overrides to | ||
1692 | specify any functionality specific to the respective SDK machine or | ||
1693 | target case. | ||
1694 | |||
1695 | .. note:: | ||
1696 | |||
1697 | When creating a recipe, you must follow this naming convention: | ||
1698 | :: | ||
1699 | |||
1700 | nativesdk-myrecipe.bb | ||
1701 | |||
1702 | |||
1703 | Not doing so can lead to subtle problems because code exists that | ||
1704 | depends on the naming convention. | ||
1705 | |||
1706 | Although applied differently, the ``nativesdk`` class is used with both | ||
1707 | methods. The advantage of the second method is that you do not need to | ||
1708 | have two separate recipes (assuming you need both) for the SDK machine | ||
1709 | and the target. All common parts of the recipe are automatically shared. | ||
1710 | |||
1711 | .. _ref-classes-nopackages: | ||
1712 | |||
1713 | ``nopackages.bbclass`` | ||
1714 | ====================== | ||
1715 | |||
1716 | Disables packaging tasks for those recipes and classes where packaging | ||
1717 | is not needed. | ||
1718 | |||
1719 | .. _ref-classes-npm: | ||
1720 | |||
1721 | ``npm.bbclass`` | ||
1722 | =============== | ||
1723 | |||
1724 | Provides support for building Node.js software fetched using the `node | ||
1725 | package manager (NPM) <https://en.wikipedia.org/wiki/Npm_(software)>`__. | ||
1726 | |||
1727 | .. note:: | ||
1728 | |||
1729 | Currently, recipes inheriting this class must use the | ||
1730 | npm:// | ||
1731 | fetcher to have dependencies fetched and packaged automatically. | ||
1732 | |||
1733 | For information on how to create NPM packages, see the | ||
1734 | ":ref:`dev-manual/dev-manual-common-tasks:creating node package manager (npm) packages`" | ||
1735 | section in the Yocto Project Development Tasks Manual. | ||
1736 | |||
1737 | .. _ref-classes-oelint: | ||
1738 | |||
1739 | ``oelint.bbclass`` | ||
1740 | ================== | ||
1741 | |||
1742 | The ``oelint`` class is an obsolete lint checking tool that exists in | ||
1743 | ``meta/classes`` in the :term:`Source Directory`. | ||
1744 | |||
1745 | A number of classes exist that could be generally useful in OE-Core but | ||
1746 | are never actually used within OE-Core itself. The ``oelint`` class is | ||
1747 | one such example. However, being aware of this class can reduce the | ||
1748 | proliferation of different versions of similar classes across multiple | ||
1749 | layers. | ||
1750 | |||
1751 | .. _ref-classes-own-mirrors: | ||
1752 | |||
1753 | ``own-mirrors.bbclass`` | ||
1754 | ======================= | ||
1755 | |||
1756 | The ``own-mirrors`` class makes it easier to set up your own | ||
1757 | :term:`PREMIRRORS` from which to first fetch source | ||
1758 | before attempting to fetch it from the upstream specified in | ||
1759 | :term:`SRC_URI` within each recipe. | ||
1760 | |||
1761 | To use this class, inherit it globally and specify | ||
1762 | :term:`SOURCE_MIRROR_URL`. Here is an example: | ||
1763 | :: | ||
1764 | |||
1765 | INHERIT += "own-mirrors" | ||
1766 | SOURCE_MIRROR_URL = "http://example.com/my-source-mirror" | ||
1767 | |||
1768 | You can specify only a single URL | ||
1769 | in ``SOURCE_MIRROR_URL``. | ||
1770 | |||
1771 | .. _ref-classes-package: | ||
1772 | |||
1773 | ``package.bbclass`` | ||
1774 | =================== | ||
1775 | |||
1776 | The ``package`` class supports generating packages from a build's | ||
1777 | output. The core generic functionality is in ``package.bbclass``. The | ||
1778 | code specific to particular package types resides in these | ||
1779 | package-specific classes: | ||
1780 | :ref:`package_deb <ref-classes-package_deb>`, | ||
1781 | :ref:`package_rpm <ref-classes-package_rpm>`, | ||
1782 | :ref:`package_ipk <ref-classes-package_ipk>`, and | ||
1783 | :ref:`package_tar <ref-classes-package_tar>`. | ||
1784 | |||
1785 | .. note:: | ||
1786 | |||
1787 | The | ||
1788 | package_tar | ||
1789 | class is broken and not supported. It is recommended that you do not | ||
1790 | use this class. | ||
1791 | |||
1792 | You can control the list of resulting package formats by using the | ||
1793 | ``PACKAGE_CLASSES`` variable defined in your ``conf/local.conf`` | ||
1794 | configuration file, which is located in the :term:`Build Directory`. | ||
1795 | When defining the variable, you can | ||
1796 | specify one or more package types. Since images are generated from | ||
1797 | packages, a packaging class is needed to enable image generation. The | ||
1798 | first class listed in this variable is used for image generation. | ||
1799 | |||
1800 | If you take the optional step to set up a repository (package feed) on | ||
1801 | the development host that can be used by DNF, you can install packages | ||
1802 | from the feed while you are running the image on the target (i.e. | ||
1803 | runtime installation of packages). For more information, see the | ||
1804 | ":ref:`dev-manual/dev-manual-common-tasks:using runtime package management`" | ||
1805 | section in the Yocto Project Development Tasks Manual. | ||
1806 | |||
1807 | The package-specific class you choose can affect build-time performance | ||
1808 | and has space ramifications. In general, building a package with IPK | ||
1809 | takes about thirty percent less time as compared to using RPM to build | ||
1810 | the same or similar package. This comparison takes into account a | ||
1811 | complete build of the package with all dependencies previously built. | ||
1812 | The reason for this discrepancy is because the RPM package manager | ||
1813 | creates and processes more :term:`Metadata` than the IPK package | ||
1814 | manager. Consequently, you might consider setting ``PACKAGE_CLASSES`` to | ||
1815 | "package_ipk" if you are building smaller systems. | ||
1816 | |||
1817 | Before making your package manager decision, however, you should | ||
1818 | consider some further things about using RPM: | ||
1819 | |||
1820 | - RPM starts to provide more abilities than IPK due to the fact that it | ||
1821 | processes more Metadata. For example, this information includes | ||
1822 | individual file types, file checksum generation and evaluation on | ||
1823 | install, sparse file support, conflict detection and resolution for | ||
1824 | Multilib systems, ACID style upgrade, and repackaging abilities for | ||
1825 | rollbacks. | ||
1826 | |||
1827 | - For smaller systems, the extra space used for the Berkeley Database | ||
1828 | and the amount of metadata when using RPM can affect your ability to | ||
1829 | perform on-device upgrades. | ||
1830 | |||
1831 | You can find additional information on the effects of the package class | ||
1832 | at these two Yocto Project mailing list links: | ||
1833 | |||
1834 | - https://lists.yoctoproject.org/pipermail/poky/2011-May/006362.html | ||
1835 | |||
1836 | - https://lists.yoctoproject.org/pipermail/poky/2011-May/006363.html | ||
1837 | |||
1838 | .. _ref-classes-package_deb: | ||
1839 | |||
1840 | ``package_deb.bbclass`` | ||
1841 | ======================= | ||
1842 | |||
1843 | The ``package_deb`` class provides support for creating packages that | ||
1844 | use the Debian (i.e. ``.deb``) file format. The class ensures the | ||
1845 | packages are written out in a ``.deb`` file format to the | ||
1846 | ``${``\ :term:`DEPLOY_DIR_DEB`\ ``}`` directory. | ||
1847 | |||
1848 | This class inherits the :ref:`package <ref-classes-package>` class and | ||
1849 | is enabled through the :term:`PACKAGE_CLASSES` | ||
1850 | variable in the ``local.conf`` file. | ||
1851 | |||
1852 | .. _ref-classes-package_ipk: | ||
1853 | |||
1854 | ``package_ipk.bbclass`` | ||
1855 | ======================= | ||
1856 | |||
1857 | The ``package_ipk`` class provides support for creating packages that | ||
1858 | use the IPK (i.e. ``.ipk``) file format. The class ensures the packages | ||
1859 | are written out in a ``.ipk`` file format to the | ||
1860 | ``${``\ :term:`DEPLOY_DIR_IPK`\ ``}`` directory. | ||
1861 | |||
1862 | This class inherits the :ref:`package <ref-classes-package>` class and | ||
1863 | is enabled through the :term:`PACKAGE_CLASSES` | ||
1864 | variable in the ``local.conf`` file. | ||
1865 | |||
1866 | .. _ref-classes-package_rpm: | ||
1867 | |||
1868 | ``package_rpm.bbclass`` | ||
1869 | ======================= | ||
1870 | |||
1871 | The ``package_rpm`` class provides support for creating packages that | ||
1872 | use the RPM (i.e. ``.rpm``) file format. The class ensures the packages | ||
1873 | are written out in a ``.rpm`` file format to the | ||
1874 | ``${``\ :term:`DEPLOY_DIR_RPM`\ ``}`` directory. | ||
1875 | |||
1876 | This class inherits the :ref:`package <ref-classes-package>` class and | ||
1877 | is enabled through the :term:`PACKAGE_CLASSES` | ||
1878 | variable in the ``local.conf`` file. | ||
1879 | |||
1880 | .. _ref-classes-package_tar: | ||
1881 | |||
1882 | ``package_tar.bbclass`` | ||
1883 | ======================= | ||
1884 | |||
1885 | The ``package_tar`` class provides support for creating tarballs. The | ||
1886 | class ensures the packages are written out in a tarball format to the | ||
1887 | ``${``\ :term:`DEPLOY_DIR_TAR`\ ``}`` directory. | ||
1888 | |||
1889 | This class inherits the :ref:`package <ref-classes-package>` class and | ||
1890 | is enabled through the :term:`PACKAGE_CLASSES` | ||
1891 | variable in the ``local.conf`` file. | ||
1892 | |||
1893 | .. note:: | ||
1894 | |||
1895 | You cannot specify the | ||
1896 | package_tar | ||
1897 | class first using the | ||
1898 | PACKAGE_CLASSES | ||
1899 | variable. You must use | ||
1900 | .deb | ||
1901 | , | ||
1902 | .ipk | ||
1903 | , or | ||
1904 | .rpm | ||
1905 | file formats for your image or SDK. | ||
1906 | |||
1907 | .. _ref-classes-packagedata: | ||
1908 | |||
1909 | ``packagedata.bbclass`` | ||
1910 | ======================= | ||
1911 | |||
1912 | The ``packagedata`` class provides common functionality for reading | ||
1913 | ``pkgdata`` files found in :term:`PKGDATA_DIR`. These | ||
1914 | files contain information about each output package produced by the | ||
1915 | OpenEmbedded build system. | ||
1916 | |||
1917 | This class is enabled by default because it is inherited by the | ||
1918 | :ref:`package <ref-classes-package>` class. | ||
1919 | |||
1920 | .. _ref-classes-packagegroup: | ||
1921 | |||
1922 | ``packagegroup.bbclass`` | ||
1923 | ======================== | ||
1924 | |||
1925 | The ``packagegroup`` class sets default values appropriate for package | ||
1926 | group recipes (e.g. ``PACKAGES``, ``PACKAGE_ARCH``, ``ALLOW_EMPTY``, and | ||
1927 | so forth). It is highly recommended that all package group recipes | ||
1928 | inherit this class. | ||
1929 | |||
1930 | For information on how to use this class, see the | ||
1931 | ":ref:`usingpoky-extend-customimage-customtasks`" | ||
1932 | section in the Yocto Project Development Tasks Manual. | ||
1933 | |||
1934 | Previously, this class was called the ``task`` class. | ||
1935 | |||
1936 | .. _ref-classes-patch: | ||
1937 | |||
1938 | ``patch.bbclass`` | ||
1939 | ================= | ||
1940 | |||
1941 | The ``patch`` class provides all functionality for applying patches | ||
1942 | during the :ref:`ref-tasks-patch` task. | ||
1943 | |||
1944 | This class is enabled by default because it is inherited by the | ||
1945 | :ref:`base <ref-classes-base>` class. | ||
1946 | |||
1947 | .. _ref-classes-perlnative: | ||
1948 | |||
1949 | ``perlnative.bbclass`` | ||
1950 | ====================== | ||
1951 | |||
1952 | When inherited by a recipe, the ``perlnative`` class supports using the | ||
1953 | native version of Perl built by the build system rather than using the | ||
1954 | version provided by the build host. | ||
1955 | |||
1956 | .. _ref-classes-pixbufcache: | ||
1957 | |||
1958 | ``pixbufcache.bbclass`` | ||
1959 | ======================= | ||
1960 | |||
1961 | The ``pixbufcache`` class generates the proper post-install and | ||
1962 | post-remove (postinst/postrm) scriptlets for packages that install | ||
1963 | pixbuf loaders, which are used with ``gdk-pixbuf``. These scriptlets | ||
1964 | call ``update_pixbuf_cache`` to add the pixbuf loaders to the cache. | ||
1965 | Since the cache files are architecture-specific, ``update_pixbuf_cache`` | ||
1966 | is run using QEMU if the postinst scriptlets need to be run on the build | ||
1967 | host during image creation. | ||
1968 | |||
1969 | If the pixbuf loaders being installed are in packages other than the | ||
1970 | recipe's main package, set | ||
1971 | :term:`PIXBUF_PACKAGES` to specify the packages | ||
1972 | containing the loaders. | ||
1973 | |||
1974 | .. _ref-classes-pkgconfig: | ||
1975 | |||
1976 | ``pkgconfig.bbclass`` | ||
1977 | ===================== | ||
1978 | |||
1979 | The ``pkgconfig`` class provides a standard way to get header and | ||
1980 | library information by using ``pkg-config``. This class aims to smooth | ||
1981 | integration of ``pkg-config`` into libraries that use it. | ||
1982 | |||
1983 | During staging, BitBake installs ``pkg-config`` data into the | ||
1984 | ``sysroots/`` directory. By making use of sysroot functionality within | ||
1985 | ``pkg-config``, the ``pkgconfig`` class no longer has to manipulate the | ||
1986 | files. | ||
1987 | |||
1988 | .. _ref-classes-populate-sdk: | ||
1989 | |||
1990 | ``populate_sdk.bbclass`` | ||
1991 | ======================== | ||
1992 | |||
1993 | The ``populate_sdk`` class provides support for SDK-only recipes. For | ||
1994 | information on advantages gained when building a cross-development | ||
1995 | toolchain using the :ref:`ref-tasks-populate_sdk` | ||
1996 | task, see the ":ref:`sdk-manual/sdk-appendix-obtain:building an sdk installer`" | ||
1997 | section in the Yocto Project Application Development and the Extensible | ||
1998 | Software Development Kit (eSDK) manual. | ||
1999 | |||
2000 | .. _ref-classes-populate-sdk-*: | ||
2001 | |||
2002 | ``populate_sdk_*.bbclass`` | ||
2003 | ========================== | ||
2004 | |||
2005 | The ``populate_sdk_*`` classes support SDK creation and consist of the | ||
2006 | following classes: | ||
2007 | |||
2008 | - ``populate_sdk_base``: The base class supporting SDK creation under | ||
2009 | all package managers (i.e. DEB, RPM, and opkg). | ||
2010 | |||
2011 | - ``populate_sdk_deb``: Supports creation of the SDK given the Debian | ||
2012 | package manager. | ||
2013 | |||
2014 | - ``populate_sdk_rpm``: Supports creation of the SDK given the RPM | ||
2015 | package manager. | ||
2016 | |||
2017 | - ``populate_sdk_ipk``: Supports creation of the SDK given the opkg | ||
2018 | (IPK format) package manager. | ||
2019 | |||
2020 | - ``populate_sdk_ext``: Supports extensible SDK creation under all | ||
2021 | package managers. | ||
2022 | |||
2023 | The ``populate_sdk_base`` class inherits the appropriate | ||
2024 | ``populate_sdk_*`` (i.e. ``deb``, ``rpm``, and ``ipk``) based on | ||
2025 | :term:`IMAGE_PKGTYPE`. | ||
2026 | |||
2027 | The base class ensures all source and destination directories are | ||
2028 | established and then populates the SDK. After populating the SDK, the | ||
2029 | ``populate_sdk_base`` class constructs two sysroots: | ||
2030 | ``${``\ :term:`SDK_ARCH`\ ``}-nativesdk``, which | ||
2031 | contains the cross-compiler and associated tooling, and the target, | ||
2032 | which contains a target root filesystem that is configured for the SDK | ||
2033 | usage. These two images reside in :term:`SDK_OUTPUT`, | ||
2034 | which consists of the following: | ||
2035 | :: | ||
2036 | |||
2037 | ${SDK_OUTPUT}/${SDK_ARCH}-nativesdk-pkgs | ||
2038 | ${SDK_OUTPUT}/${SDKTARGETSYSROOT}/target-pkgs | ||
2039 | |||
2040 | Finally, the base populate SDK class creates the toolchain environment | ||
2041 | setup script, the tarball of the SDK, and the installer. | ||
2042 | |||
2043 | The respective ``populate_sdk_deb``, ``populate_sdk_rpm``, and | ||
2044 | ``populate_sdk_ipk`` classes each support the specific type of SDK. | ||
2045 | These classes are inherited by and used with the ``populate_sdk_base`` | ||
2046 | class. | ||
2047 | |||
2048 | For more information on the cross-development toolchain generation, see | ||
2049 | the ":ref:`overview-manual/overview-manual-concepts:cross-development toolchain generation`" | ||
2050 | section in the Yocto Project Overview and Concepts Manual. For | ||
2051 | information on advantages gained when building a cross-development | ||
2052 | toolchain using the :ref:`ref-tasks-populate_sdk` | ||
2053 | task, see the | ||
2054 | ":ref:`sdk-manual/sdk-appendix-obtain:building an sdk installer`" | ||
2055 | section in the Yocto Project Application Development and the Extensible | ||
2056 | Software Development Kit (eSDK) manual. | ||
2057 | |||
2058 | .. _ref-classes-prexport: | ||
2059 | |||
2060 | ``prexport.bbclass`` | ||
2061 | ==================== | ||
2062 | |||
2063 | The ``prexport`` class provides functionality for exporting | ||
2064 | :term:`PR` values. | ||
2065 | |||
2066 | .. note:: | ||
2067 | |||
2068 | This class is not intended to be used directly. Rather, it is enabled | ||
2069 | when using " | ||
2070 | bitbake-prserv-tool export | ||
2071 | ". | ||
2072 | |||
2073 | .. _ref-classes-primport: | ||
2074 | |||
2075 | ``primport.bbclass`` | ||
2076 | ==================== | ||
2077 | |||
2078 | The ``primport`` class provides functionality for importing | ||
2079 | :term:`PR` values. | ||
2080 | |||
2081 | .. note:: | ||
2082 | |||
2083 | This class is not intended to be used directly. Rather, it is enabled | ||
2084 | when using " | ||
2085 | bitbake-prserv-tool import | ||
2086 | ". | ||
2087 | |||
2088 | .. _ref-classes-prserv: | ||
2089 | |||
2090 | ``prserv.bbclass`` | ||
2091 | ================== | ||
2092 | |||
2093 | The ``prserv`` class provides functionality for using a :ref:`PR | ||
2094 | service <dev-manual/dev-manual-common-tasks:working with a pr service>` in order to | ||
2095 | automatically manage the incrementing of the :term:`PR` | ||
2096 | variable for each recipe. | ||
2097 | |||
2098 | This class is enabled by default because it is inherited by the | ||
2099 | :ref:`package <ref-classes-package>` class. However, the OpenEmbedded | ||
2100 | build system will not enable the functionality of this class unless | ||
2101 | :term:`PRSERV_HOST` has been set. | ||
2102 | |||
2103 | .. _ref-classes-ptest: | ||
2104 | |||
2105 | ``ptest.bbclass`` | ||
2106 | ================= | ||
2107 | |||
2108 | The ``ptest`` class provides functionality for packaging and installing | ||
2109 | runtime tests for recipes that build software that provides these tests. | ||
2110 | |||
2111 | This class is intended to be inherited by individual recipes. However, | ||
2112 | the class' functionality is largely disabled unless "ptest" appears in | ||
2113 | :term:`DISTRO_FEATURES`. See the | ||
2114 | ":ref:`dev-manual/dev-manual-common-tasks:testing packages with ptest`" | ||
2115 | section in the Yocto Project Development Tasks Manual for more information | ||
2116 | on ptest. | ||
2117 | |||
2118 | .. _ref-classes-ptest-gnome: | ||
2119 | |||
2120 | ``ptest-gnome.bbclass`` | ||
2121 | ======================= | ||
2122 | |||
2123 | Enables package tests (ptests) specifically for GNOME packages, which | ||
2124 | have tests intended to be executed with ``gnome-desktop-testing``. | ||
2125 | |||
2126 | For information on setting up and running ptests, see the | ||
2127 | ":ref:`dev-manual/dev-manual-common-tasks:testing packages with ptest`" | ||
2128 | section in the Yocto Project Development Tasks Manual. | ||
2129 | |||
2130 | .. _ref-classes-python-dir: | ||
2131 | |||
2132 | ``python-dir.bbclass`` | ||
2133 | ====================== | ||
2134 | |||
2135 | The ``python-dir`` class provides the base version, location, and site | ||
2136 | package location for Python. | ||
2137 | |||
2138 | .. _ref-classes-python3native: | ||
2139 | |||
2140 | ``python3native.bbclass`` | ||
2141 | ========================= | ||
2142 | |||
2143 | The ``python3native`` class supports using the native version of Python | ||
2144 | 3 built by the build system rather than support of the version provided | ||
2145 | by the build host. | ||
2146 | |||
2147 | .. _ref-classes-pythonnative: | ||
2148 | |||
2149 | ``pythonnative.bbclass`` | ||
2150 | ======================== | ||
2151 | |||
2152 | When inherited by a recipe, the ``pythonnative`` class supports using | ||
2153 | the native version of Python built by the build system rather than using | ||
2154 | the version provided by the build host. | ||
2155 | |||
2156 | .. _ref-classes-qemu: | ||
2157 | |||
2158 | ``qemu.bbclass`` | ||
2159 | ================ | ||
2160 | |||
2161 | The ``qemu`` class provides functionality for recipes that either need | ||
2162 | QEMU or test for the existence of QEMU. Typically, this class is used to | ||
2163 | run programs for a target system on the build host using QEMU's | ||
2164 | application emulation mode. | ||
2165 | |||
2166 | .. _ref-classes-recipe_sanity: | ||
2167 | |||
2168 | ``recipe_sanity.bbclass`` | ||
2169 | ========================= | ||
2170 | |||
2171 | The ``recipe_sanity`` class checks for the presence of any host system | ||
2172 | recipe prerequisites that might affect the build (e.g. variables that | ||
2173 | are set or software that is present). | ||
2174 | |||
2175 | .. _ref-classes-relocatable: | ||
2176 | |||
2177 | ``relocatable.bbclass`` | ||
2178 | ======================= | ||
2179 | |||
2180 | The ``relocatable`` class enables relocation of binaries when they are | ||
2181 | installed into the sysroot. | ||
2182 | |||
2183 | This class makes use of the :ref:`chrpath <ref-classes-chrpath>` class | ||
2184 | and is used by both the :ref:`cross <ref-classes-cross>` and | ||
2185 | :ref:`native <ref-classes-native>` classes. | ||
2186 | |||
2187 | .. _ref-classes-remove-libtool: | ||
2188 | |||
2189 | ``remove-libtool.bbclass`` | ||
2190 | ========================== | ||
2191 | |||
2192 | The ``remove-libtool`` class adds a post function to the | ||
2193 | :ref:`ref-tasks-install` task to remove all ``.la`` files | ||
2194 | installed by ``libtool``. Removing these files results in them being | ||
2195 | absent from both the sysroot and target packages. | ||
2196 | |||
2197 | If a recipe needs the ``.la`` files to be installed, then the recipe can | ||
2198 | override the removal by setting ``REMOVE_LIBTOOL_LA`` to "0" as follows: | ||
2199 | :: | ||
2200 | |||
2201 | REMOVE_LIBTOOL_LA = "0" | ||
2202 | |||
2203 | .. note:: | ||
2204 | |||
2205 | The | ||
2206 | remove-libtool | ||
2207 | class is not enabled by default. | ||
2208 | |||
2209 | .. _ref-classes-report-error: | ||
2210 | |||
2211 | ``report-error.bbclass`` | ||
2212 | ======================== | ||
2213 | |||
2214 | The ``report-error`` class supports enabling the :ref:`error reporting | ||
2215 | tool <dev-manual/dev-manual-common-tasks:using the error reporting tool>`", | ||
2216 | which allows you to submit build error information to a central database. | ||
2217 | |||
2218 | The class collects debug information for recipe, recipe version, task, | ||
2219 | machine, distro, build system, target system, host distro, branch, | ||
2220 | commit, and log. From the information, report files using a JSON format | ||
2221 | are created and stored in | ||
2222 | ``${``\ :term:`LOG_DIR`\ ``}/error-report``. | ||
2223 | |||
2224 | .. _ref-classes-rm-work: | ||
2225 | |||
2226 | ``rm_work.bbclass`` | ||
2227 | =================== | ||
2228 | |||
2229 | The ``rm_work`` class supports deletion of temporary workspace, which | ||
2230 | can ease your hard drive demands during builds. | ||
2231 | |||
2232 | The OpenEmbedded build system can use a substantial amount of disk space | ||
2233 | during the build process. A portion of this space is the work files | ||
2234 | under the ``${TMPDIR}/work`` directory for each recipe. Once the build | ||
2235 | system generates the packages for a recipe, the work files for that | ||
2236 | recipe are no longer needed. However, by default, the build system | ||
2237 | preserves these files for inspection and possible debugging purposes. If | ||
2238 | you would rather have these files deleted to save disk space as the | ||
2239 | build progresses, you can enable ``rm_work`` by adding the following to | ||
2240 | your ``local.conf`` file, which is found in the :term:`Build Directory`. | ||
2241 | :: | ||
2242 | |||
2243 | INHERIT += "rm_work" | ||
2244 | |||
2245 | If you are | ||
2246 | modifying and building source code out of the work directory for a | ||
2247 | recipe, enabling ``rm_work`` will potentially result in your changes to | ||
2248 | the source being lost. To exclude some recipes from having their work | ||
2249 | directories deleted by ``rm_work``, you can add the names of the recipe | ||
2250 | or recipes you are working on to the ``RM_WORK_EXCLUDE`` variable, which | ||
2251 | can also be set in your ``local.conf`` file. Here is an example: | ||
2252 | :: | ||
2253 | |||
2254 | RM_WORK_EXCLUDE += "busybox glibc" | ||
2255 | |||
2256 | .. _ref-classes-rootfs*: | ||
2257 | |||
2258 | ``rootfs*.bbclass`` | ||
2259 | =================== | ||
2260 | |||
2261 | The ``rootfs*`` classes support creating the root filesystem for an | ||
2262 | image and consist of the following classes: | ||
2263 | |||
2264 | - The ``rootfs-postcommands`` class, which defines filesystem | ||
2265 | post-processing functions for image recipes. | ||
2266 | |||
2267 | - The ``rootfs_deb`` class, which supports creation of root filesystems | ||
2268 | for images built using ``.deb`` packages. | ||
2269 | |||
2270 | - The ``rootfs_rpm`` class, which supports creation of root filesystems | ||
2271 | for images built using ``.rpm`` packages. | ||
2272 | |||
2273 | - The ``rootfs_ipk`` class, which supports creation of root filesystems | ||
2274 | for images built using ``.ipk`` packages. | ||
2275 | |||
2276 | - The ``rootfsdebugfiles`` class, which installs additional files found | ||
2277 | on the build host directly into the root filesystem. | ||
2278 | |||
2279 | The root filesystem is created from packages using one of the | ||
2280 | ``rootfs*.bbclass`` files as determined by the | ||
2281 | :term:`PACKAGE_CLASSES` variable. | ||
2282 | |||
2283 | For information on how root filesystem images are created, see the | ||
2284 | :ref:`image-generation-dev-environment`" | ||
2285 | section in the Yocto Project Overview and Concepts Manual. | ||
2286 | |||
2287 | .. _ref-classes-sanity: | ||
2288 | |||
2289 | ``sanity.bbclass`` | ||
2290 | ================== | ||
2291 | |||
2292 | The ``sanity`` class checks to see if prerequisite software is present | ||
2293 | on the host system so that users can be notified of potential problems | ||
2294 | that might affect their build. The class also performs basic user | ||
2295 | configuration checks from the ``local.conf`` configuration file to | ||
2296 | prevent common mistakes that cause build failures. Distribution policy | ||
2297 | usually determines whether to include this class. | ||
2298 | |||
2299 | .. _ref-classes-scons: | ||
2300 | |||
2301 | ``scons.bbclass`` | ||
2302 | ================= | ||
2303 | |||
2304 | The ``scons`` class supports recipes that need to build software that | ||
2305 | uses the SCons build system. You can use the | ||
2306 | :term:`EXTRA_OESCONS` variable to specify | ||
2307 | additional configuration options you want to pass SCons command line. | ||
2308 | |||
2309 | .. _ref-classes-sdl: | ||
2310 | |||
2311 | ``sdl.bbclass`` | ||
2312 | =============== | ||
2313 | |||
2314 | The ``sdl`` class supports recipes that need to build software that uses | ||
2315 | the Simple DirectMedia Layer (SDL) library. | ||
2316 | |||
2317 | .. _ref-classes-setuptools: | ||
2318 | |||
2319 | ``setuptools.bbclass`` | ||
2320 | ====================== | ||
2321 | |||
2322 | The ``setuptools`` class supports Python version 2.x extensions that use | ||
2323 | build systems based on ``setuptools``. If your recipe uses these build | ||
2324 | systems, the recipe needs to inherit the ``setuptools`` class. | ||
2325 | |||
2326 | .. _ref-classes-setuptools3: | ||
2327 | |||
2328 | ``setuptools3.bbclass`` | ||
2329 | ======================= | ||
2330 | |||
2331 | The ``setuptools3`` class supports Python version 3.x extensions that | ||
2332 | use build systems based on ``setuptools3``. If your recipe uses these | ||
2333 | build systems, the recipe needs to inherit the ``setuptools3`` class. | ||
2334 | |||
2335 | .. _ref-classes-sign_rpm: | ||
2336 | |||
2337 | ``sign_rpm.bbclass`` | ||
2338 | ==================== | ||
2339 | |||
2340 | The ``sign_rpm`` class supports generating signed RPM packages. | ||
2341 | |||
2342 | .. _ref-classes-sip: | ||
2343 | |||
2344 | ``sip.bbclass`` | ||
2345 | =============== | ||
2346 | |||
2347 | The ``sip`` class supports recipes that build or package SIP-based | ||
2348 | Python bindings. | ||
2349 | |||
2350 | .. _ref-classes-siteconfig: | ||
2351 | |||
2352 | ``siteconfig.bbclass`` | ||
2353 | ====================== | ||
2354 | |||
2355 | The ``siteconfig`` class provides functionality for handling site | ||
2356 | configuration. The class is used by the | ||
2357 | :ref:`autotools <ref-classes-autotools>` class to accelerate the | ||
2358 | :ref:`ref-tasks-configure` task. | ||
2359 | |||
2360 | .. _ref-classes-siteinfo: | ||
2361 | |||
2362 | ``siteinfo.bbclass`` | ||
2363 | ==================== | ||
2364 | |||
2365 | The ``siteinfo`` class provides information about the targets that might | ||
2366 | be needed by other classes or recipes. | ||
2367 | |||
2368 | As an example, consider Autotools, which can require tests that must | ||
2369 | execute on the target hardware. Since this is not possible in general | ||
2370 | when cross compiling, site information is used to provide cached test | ||
2371 | results so these tests can be skipped over but still make the correct | ||
2372 | values available. The ``meta/site directory`` contains test results | ||
2373 | sorted into different categories such as architecture, endianness, and | ||
2374 | the ``libc`` used. Site information provides a list of files containing | ||
2375 | data relevant to the current build in the ``CONFIG_SITE`` variable that | ||
2376 | Autotools automatically picks up. | ||
2377 | |||
2378 | The class also provides variables like ``SITEINFO_ENDIANNESS`` and | ||
2379 | ``SITEINFO_BITS`` that can be used elsewhere in the metadata. | ||
2380 | |||
2381 | .. _ref-classes-spdx: | ||
2382 | |||
2383 | ``spdx.bbclass`` | ||
2384 | ================ | ||
2385 | |||
2386 | The ``spdx`` class integrates real-time license scanning, generation of | ||
2387 | SPDX standard output, and verification of license information during the | ||
2388 | build. | ||
2389 | |||
2390 | .. note:: | ||
2391 | |||
2392 | This class is currently at the prototype stage in the 1.6 release. | ||
2393 | |||
2394 | .. _ref-classes-sstate: | ||
2395 | |||
2396 | ``sstate.bbclass`` | ||
2397 | ================== | ||
2398 | |||
2399 | The ``sstate`` class provides support for Shared State (sstate). By | ||
2400 | default, the class is enabled through the | ||
2401 | :term:`INHERIT_DISTRO` variable's default value. | ||
2402 | |||
2403 | For more information on sstate, see the | ||
2404 | ":ref:`overview-manual/overview-manual-concepts:shared state cache`" | ||
2405 | section in the Yocto Project Overview and Concepts Manual. | ||
2406 | |||
2407 | .. _ref-classes-staging: | ||
2408 | |||
2409 | ``staging.bbclass`` | ||
2410 | =================== | ||
2411 | |||
2412 | The ``staging`` class installs files into individual recipe work | ||
2413 | directories for sysroots. The class contains the following key tasks: | ||
2414 | |||
2415 | - The :ref:`ref-tasks-populate_sysroot` task, | ||
2416 | which is responsible for handing the files that end up in the recipe | ||
2417 | sysroots. | ||
2418 | |||
2419 | - The | ||
2420 | :ref:`ref-tasks-prepare_recipe_sysroot` | ||
2421 | task (a "partner" task to the ``populate_sysroot`` task), which | ||
2422 | installs the files into the individual recipe work directories (i.e. | ||
2423 | :term:`WORKDIR`). | ||
2424 | |||
2425 | The code in the ``staging`` class is complex and basically works in two | ||
2426 | stages: | ||
2427 | |||
2428 | - *Stage One:* The first stage addresses recipes that have files they | ||
2429 | want to share with other recipes that have dependencies on the | ||
2430 | originating recipe. Normally these dependencies are installed through | ||
2431 | the :ref:`ref-tasks-install` task into | ||
2432 | ``${``\ :term:`D`\ ``}``. The ``do_populate_sysroot`` task | ||
2433 | copies a subset of these files into ``${SYSROOT_DESTDIR}``. This | ||
2434 | subset of files is controlled by the | ||
2435 | :term:`SYSROOT_DIRS`, | ||
2436 | :term:`SYSROOT_DIRS_NATIVE`, and | ||
2437 | :term:`SYSROOT_DIRS_BLACKLIST` | ||
2438 | variables. | ||
2439 | |||
2440 | .. note:: | ||
2441 | |||
2442 | Additionally, a recipe can customize the files further by | ||
2443 | declaring a processing function in the | ||
2444 | SYSROOT_PREPROCESS_FUNCS | ||
2445 | variable. | ||
2446 | |||
2447 | A shared state (sstate) object is built from these files and the | ||
2448 | files are placed into a subdirectory of | ||
2449 | ```tmp/sysroots-components/`` <#structure-build-tmp-sysroots-components>`__. | ||
2450 | The files are scanned for hardcoded paths to the original | ||
2451 | installation location. If the location is found in text files, the | ||
2452 | hardcoded locations are replaced by tokens and a list of the files | ||
2453 | needing such replacements is created. These adjustments are referred | ||
2454 | to as "FIXMEs". The list of files that are scanned for paths is | ||
2455 | controlled by the :term:`SSTATE_SCAN_FILES` | ||
2456 | variable. | ||
2457 | |||
2458 | - *Stage Two:* The second stage addresses recipes that want to use | ||
2459 | something from another recipe and declare a dependency on that recipe | ||
2460 | through the :term:`DEPENDS` variable. The recipe will | ||
2461 | have a | ||
2462 | :ref:`ref-tasks-prepare_recipe_sysroot` | ||
2463 | task and when this task executes, it creates the ``recipe-sysroot`` | ||
2464 | and ``recipe-sysroot-native`` in the recipe work directory (i.e. | ||
2465 | :term:`WORKDIR`). The OpenEmbedded build system | ||
2466 | creates hard links to copies of the relevant files from | ||
2467 | ``sysroots-components`` into the recipe work directory. | ||
2468 | |||
2469 | .. note:: | ||
2470 | |||
2471 | If hard links are not possible, the build system uses actual | ||
2472 | copies. | ||
2473 | |||
2474 | The build system then addresses any "FIXMEs" to paths as defined from | ||
2475 | the list created in the first stage. | ||
2476 | |||
2477 | Finally, any files in ``${bindir}`` within the sysroot that have the | ||
2478 | prefix "``postinst-``" are executed. | ||
2479 | |||
2480 | .. note:: | ||
2481 | |||
2482 | Although such sysroot post installation scripts are not | ||
2483 | recommended for general use, the files do allow some issues such | ||
2484 | as user creation and module indexes to be addressed. | ||
2485 | |||
2486 | Because recipes can have other dependencies outside of ``DEPENDS`` | ||
2487 | (e.g. ``do_unpack[depends] += "tar-native:do_populate_sysroot"``), | ||
2488 | the sysroot creation function ``extend_recipe_sysroot`` is also added | ||
2489 | as a pre-function for those tasks whose dependencies are not through | ||
2490 | ``DEPENDS`` but operate similarly. | ||
2491 | |||
2492 | When installing dependencies into the sysroot, the code traverses the | ||
2493 | dependency graph and processes dependencies in exactly the same way | ||
2494 | as the dependencies would or would not be when installed from sstate. | ||
2495 | This processing means, for example, a native tool would have its | ||
2496 | native dependencies added but a target library would not have its | ||
2497 | dependencies traversed or installed. The same sstate dependency code | ||
2498 | is used so that builds should be identical regardless of whether | ||
2499 | sstate was used or not. For a closer look, see the | ||
2500 | ``setscene_depvalid()`` function in the | ||
2501 | :ref:`sstate <ref-classes-sstate>` class. | ||
2502 | |||
2503 | The build system is careful to maintain manifests of the files it | ||
2504 | installs so that any given dependency can be installed as needed. The | ||
2505 | sstate hash of the installed item is also stored so that if it | ||
2506 | changes, the build system can reinstall it. | ||
2507 | |||
2508 | .. _ref-classes-syslinux: | ||
2509 | |||
2510 | ``syslinux.bbclass`` | ||
2511 | ==================== | ||
2512 | |||
2513 | The ``syslinux`` class provides syslinux-specific functions for building | ||
2514 | bootable images. | ||
2515 | |||
2516 | The class supports the following variables: | ||
2517 | |||
2518 | - :term:`INITRD`: Indicates list of filesystem images to | ||
2519 | concatenate and use as an initial RAM disk (initrd). This variable is | ||
2520 | optional. | ||
2521 | |||
2522 | - :term:`ROOTFS`: Indicates a filesystem image to include | ||
2523 | as the root filesystem. This variable is optional. | ||
2524 | |||
2525 | - :term:`AUTO_SYSLINUXMENU`: Enables creating | ||
2526 | an automatic menu when set to "1". | ||
2527 | |||
2528 | - :term:`LABELS`: Lists targets for automatic | ||
2529 | configuration. | ||
2530 | |||
2531 | - :term:`APPEND`: Lists append string overrides for each | ||
2532 | label. | ||
2533 | |||
2534 | - :term:`SYSLINUX_OPTS`: Lists additional options | ||
2535 | to add to the syslinux file. Semicolon characters separate multiple | ||
2536 | options. | ||
2537 | |||
2538 | - :term:`SYSLINUX_SPLASH`: Lists a background | ||
2539 | for the VGA boot menu when you are using the boot menu. | ||
2540 | |||
2541 | - :term:`SYSLINUX_DEFAULT_CONSOLE`: Set | ||
2542 | to "console=ttyX" to change kernel boot default console. | ||
2543 | |||
2544 | - :term:`SYSLINUX_SERIAL`: Sets an alternate | ||
2545 | serial port. Or, turns off serial when the variable is set with an | ||
2546 | empty string. | ||
2547 | |||
2548 | - :term:`SYSLINUX_SERIAL_TTY`: Sets an | ||
2549 | alternate "console=tty..." kernel boot argument. | ||
2550 | |||
2551 | .. _ref-classes-systemd: | ||
2552 | |||
2553 | ``systemd.bbclass`` | ||
2554 | =================== | ||
2555 | |||
2556 | The ``systemd`` class provides support for recipes that install systemd | ||
2557 | unit files. | ||
2558 | |||
2559 | The functionality for this class is disabled unless you have "systemd" | ||
2560 | in :term:`DISTRO_FEATURES`. | ||
2561 | |||
2562 | Under this class, the recipe or Makefile (i.e. whatever the recipe is | ||
2563 | calling during the :ref:`ref-tasks-install` task) | ||
2564 | installs unit files into | ||
2565 | ``${``\ :term:`D`\ ``}${systemd_unitdir}/system``. If the unit | ||
2566 | files being installed go into packages other than the main package, you | ||
2567 | need to set :term:`SYSTEMD_PACKAGES` in your | ||
2568 | recipe to identify the packages in which the files will be installed. | ||
2569 | |||
2570 | You should set :term:`SYSTEMD_SERVICE` to the | ||
2571 | name of the service file. You should also use a package name override to | ||
2572 | indicate the package to which the value applies. If the value applies to | ||
2573 | the recipe's main package, use ``${``\ :term:`PN`\ ``}``. Here | ||
2574 | is an example from the connman recipe: | ||
2575 | :: | ||
2576 | |||
2577 | SYSTEMD_SERVICE_${PN} = "connman.service" | ||
2578 | |||
2579 | Services are set up to start on boot automatically | ||
2580 | unless you have set | ||
2581 | :term:`SYSTEMD_AUTO_ENABLE` to "disable". | ||
2582 | |||
2583 | For more information on ``systemd``, see the | ||
2584 | ":ref:`dev-manual/dev-manual-common-tasks:selecting an initialization manager`" | ||
2585 | section in the Yocto Project Development Tasks Manual. | ||
2586 | |||
2587 | .. _ref-classes-systemd-boot: | ||
2588 | |||
2589 | ``systemd-boot.bbclass`` | ||
2590 | ======================== | ||
2591 | |||
2592 | The ``systemd-boot`` class provides functions specific to the | ||
2593 | systemd-boot bootloader for building bootable images. This is an | ||
2594 | internal class and is not intended to be used directly. | ||
2595 | |||
2596 | .. note:: | ||
2597 | |||
2598 | The | ||
2599 | systemd-boot | ||
2600 | class is a result from merging the | ||
2601 | gummiboot | ||
2602 | class used in previous Yocto Project releases with the | ||
2603 | systemd | ||
2604 | project. | ||
2605 | |||
2606 | Set the :term:`EFI_PROVIDER` variable to | ||
2607 | "systemd-boot" to use this class. Doing so creates a standalone EFI | ||
2608 | bootloader that is not dependent on systemd. | ||
2609 | |||
2610 | For information on more variables used and supported in this class, see | ||
2611 | the :term:`SYSTEMD_BOOT_CFG`, | ||
2612 | :term:`SYSTEMD_BOOT_ENTRIES`, and | ||
2613 | :term:`SYSTEMD_BOOT_TIMEOUT` variables. | ||
2614 | |||
2615 | You can also see the `Systemd-boot | ||
2616 | documentation <http://www.freedesktop.org/wiki/Software/systemd/systemd-boot/>`__ | ||
2617 | for more information. | ||
2618 | |||
2619 | .. _ref-classes-terminal: | ||
2620 | |||
2621 | ``terminal.bbclass`` | ||
2622 | ==================== | ||
2623 | |||
2624 | The ``terminal`` class provides support for starting a terminal session. | ||
2625 | The :term:`OE_TERMINAL` variable controls which | ||
2626 | terminal emulator is used for the session. | ||
2627 | |||
2628 | Other classes use the ``terminal`` class anywhere a separate terminal | ||
2629 | session needs to be started. For example, the | ||
2630 | :ref:`patch <ref-classes-patch>` class assuming | ||
2631 | :term:`PATCHRESOLVE` is set to "user", the | ||
2632 | :ref:`cml1 <ref-classes-cml1>` class, and the | ||
2633 | :ref:`devshell <ref-classes-devshell>` class all use the ``terminal`` | ||
2634 | class. | ||
2635 | |||
2636 | .. _ref-classes-testimage*: | ||
2637 | |||
2638 | ``testimage*.bbclass`` | ||
2639 | ====================== | ||
2640 | |||
2641 | The ``testimage*`` classes support running automated tests against | ||
2642 | images using QEMU and on actual hardware. The classes handle loading the | ||
2643 | tests and starting the image. To use the classes, you need to perform | ||
2644 | steps to set up the environment. | ||
2645 | |||
2646 | .. note:: | ||
2647 | |||
2648 | Best practices include using | ||
2649 | IMAGE_CLASSES | ||
2650 | rather than | ||
2651 | INHERIT | ||
2652 | to inherit the | ||
2653 | testimage | ||
2654 | class for automated image testing. | ||
2655 | |||
2656 | The tests are commands that run on the target system over ``ssh``. Each | ||
2657 | test is written in Python and makes use of the ``unittest`` module. | ||
2658 | |||
2659 | The ``testimage.bbclass`` runs tests on an image when called using the | ||
2660 | following: | ||
2661 | :: | ||
2662 | |||
2663 | $ bitbake -c testimage image | ||
2664 | |||
2665 | The ``testimage-auto`` class | ||
2666 | runs tests on an image after the image is constructed (i.e. | ||
2667 | :term:`TESTIMAGE_AUTO` must be set to "1"). | ||
2668 | |||
2669 | For information on how to enable, run, and create new tests, see the | ||
2670 | ":ref:`dev-manual/dev-manual-common-tasks:performing automated runtime testing`" | ||
2671 | section in the Yocto Project Development Tasks Manual. | ||
2672 | |||
2673 | .. _ref-classes-testsdk: | ||
2674 | |||
2675 | ``testsdk.bbclass`` | ||
2676 | =================== | ||
2677 | |||
2678 | This class supports running automated tests against software development | ||
2679 | kits (SDKs). The ``testsdk`` class runs tests on an SDK when called | ||
2680 | using the following: | ||
2681 | :: | ||
2682 | |||
2683 | $ bitbake -c testsdk image | ||
2684 | |||
2685 | .. note:: | ||
2686 | |||
2687 | Best practices include using | ||
2688 | IMAGE_CLASSES | ||
2689 | rather than | ||
2690 | INHERIT | ||
2691 | to inherit the | ||
2692 | testsdk | ||
2693 | class for automated SDK testing. | ||
2694 | |||
2695 | .. _ref-classes-texinfo: | ||
2696 | |||
2697 | ``texinfo.bbclass`` | ||
2698 | =================== | ||
2699 | |||
2700 | This class should be inherited by recipes whose upstream packages invoke | ||
2701 | the ``texinfo`` utilities at build-time. Native and cross recipes are | ||
2702 | made to use the dummy scripts provided by ``texinfo-dummy-native``, for | ||
2703 | improved performance. Target architecture recipes use the genuine | ||
2704 | Texinfo utilities. By default, they use the Texinfo utilities on the | ||
2705 | host system. | ||
2706 | |||
2707 | .. note:: | ||
2708 | |||
2709 | If you want to use the Texinfo recipe shipped with the build system, | ||
2710 | you can remove "texinfo-native" from | ||
2711 | ASSUME_PROVIDED | ||
2712 | and makeinfo from | ||
2713 | SANITY_REQUIRED_UTILITIES | ||
2714 | . | ||
2715 | |||
2716 | .. _ref-classes-tinderclient: | ||
2717 | |||
2718 | ``tinderclient.bbclass`` | ||
2719 | ======================== | ||
2720 | |||
2721 | The ``tinderclient`` class submits build results to an external | ||
2722 | Tinderbox instance. | ||
2723 | |||
2724 | .. note:: | ||
2725 | |||
2726 | This class is currently unmaintained. | ||
2727 | |||
2728 | .. _ref-classes-toaster: | ||
2729 | |||
2730 | ``toaster.bbclass`` | ||
2731 | =================== | ||
2732 | |||
2733 | The ``toaster`` class collects information about packages and images and | ||
2734 | sends them as events that the BitBake user interface can receive. The | ||
2735 | class is enabled when the Toaster user interface is running. | ||
2736 | |||
2737 | This class is not intended to be used directly. | ||
2738 | |||
2739 | .. _ref-classes-toolchain-scripts: | ||
2740 | |||
2741 | ``toolchain-scripts.bbclass`` | ||
2742 | ============================= | ||
2743 | |||
2744 | The ``toolchain-scripts`` class provides the scripts used for setting up | ||
2745 | the environment for installed SDKs. | ||
2746 | |||
2747 | .. _ref-classes-typecheck: | ||
2748 | |||
2749 | ``typecheck.bbclass`` | ||
2750 | ===================== | ||
2751 | |||
2752 | The ``typecheck`` class provides support for validating the values of | ||
2753 | variables set at the configuration level against their defined types. | ||
2754 | The OpenEmbedded build system allows you to define the type of a | ||
2755 | variable using the "type" varflag. Here is an example: | ||
2756 | :: | ||
2757 | |||
2758 | IMAGE_FEATURES[type] = "list" | ||
2759 | |||
2760 | .. _ref-classes-uboot-config: | ||
2761 | |||
2762 | ``uboot-config.bbclass`` | ||
2763 | ======================== | ||
2764 | |||
2765 | The ``uboot-config`` class provides support for U-Boot configuration for | ||
2766 | a machine. Specify the machine in your recipe as follows: | ||
2767 | :: | ||
2768 | |||
2769 | UBOOT_CONFIG ??= <default> | ||
2770 | UBOOT_CONFIG[foo] = "config,images" | ||
2771 | |||
2772 | You can also specify the machine using this method: | ||
2773 | :: | ||
2774 | |||
2775 | UBOOT_MACHINE = "config" | ||
2776 | |||
2777 | See the :term:`UBOOT_CONFIG` and :term:`UBOOT_MACHINE` variables for additional | ||
2778 | information. | ||
2779 | |||
2780 | .. _ref-classes-uninative: | ||
2781 | |||
2782 | ``uninative.bbclass`` | ||
2783 | ===================== | ||
2784 | |||
2785 | Attempts to isolate the build system from the host distribution's C | ||
2786 | library in order to make re-use of native shared state artifacts across | ||
2787 | different host distributions practical. With this class enabled, a | ||
2788 | tarball containing a pre-built C library is downloaded at the start of | ||
2789 | the build. In the Poky reference distribution this is enabled by default | ||
2790 | through ``meta/conf/distro/include/yocto-uninative.inc``. Other | ||
2791 | distributions that do not derive from poky can also | ||
2792 | "``require conf/distro/include/yocto-uninative.inc``" to use this. | ||
2793 | Alternatively if you prefer, you can build the uninative-tarball recipe | ||
2794 | yourself, publish the resulting tarball (e.g. via HTTP) and set | ||
2795 | ``UNINATIVE_URL`` and ``UNINATIVE_CHECKSUM`` appropriately. For an | ||
2796 | example, see the ``meta/conf/distro/include/yocto-uninative.inc``. | ||
2797 | |||
2798 | The ``uninative`` class is also used unconditionally by the extensible | ||
2799 | SDK. When building the extensible SDK, ``uninative-tarball`` is built | ||
2800 | and the resulting tarball is included within the SDK. | ||
2801 | |||
2802 | .. _ref-classes-update-alternatives: | ||
2803 | |||
2804 | ``update-alternatives.bbclass`` | ||
2805 | =============================== | ||
2806 | |||
2807 | The ``update-alternatives`` class helps the alternatives system when | ||
2808 | multiple sources provide the same command. This situation occurs when | ||
2809 | several programs that have the same or similar function are installed | ||
2810 | with the same name. For example, the ``ar`` command is available from | ||
2811 | the ``busybox``, ``binutils`` and ``elfutils`` packages. The | ||
2812 | ``update-alternatives`` class handles renaming the binaries so that | ||
2813 | multiple packages can be installed without conflicts. The ``ar`` command | ||
2814 | still works regardless of which packages are installed or subsequently | ||
2815 | removed. The class renames the conflicting binary in each package and | ||
2816 | symlinks the highest priority binary during installation or removal of | ||
2817 | packages. | ||
2818 | |||
2819 | To use this class, you need to define a number of variables: | ||
2820 | |||
2821 | - :term:`ALTERNATIVE` | ||
2822 | |||
2823 | - :term:`ALTERNATIVE_LINK_NAME` | ||
2824 | |||
2825 | - :term:`ALTERNATIVE_TARGET` | ||
2826 | |||
2827 | - :term:`ALTERNATIVE_PRIORITY` | ||
2828 | |||
2829 | These variables list alternative commands needed by a package, provide | ||
2830 | pathnames for links, default links for targets, and so forth. For | ||
2831 | details on how to use this class, see the comments in the | ||
2832 | :yocto_git:`update-alternatives.bbclass </cgit/cgit.cgi/poky/tree/meta/classes/update-alternatives.bbclass>` | ||
2833 | file. | ||
2834 | |||
2835 | .. note:: | ||
2836 | |||
2837 | You can use the | ||
2838 | update-alternatives | ||
2839 | command directly in your recipes. However, this class simplifies | ||
2840 | things in most cases. | ||
2841 | |||
2842 | .. _ref-classes-update-rc.d: | ||
2843 | |||
2844 | ``update-rc.d.bbclass`` | ||
2845 | ======================= | ||
2846 | |||
2847 | The ``update-rc.d`` class uses ``update-rc.d`` to safely install an | ||
2848 | initialization script on behalf of the package. The OpenEmbedded build | ||
2849 | system takes care of details such as making sure the script is stopped | ||
2850 | before a package is removed and started when the package is installed. | ||
2851 | |||
2852 | Three variables control this class: ``INITSCRIPT_PACKAGES``, | ||
2853 | ``INITSCRIPT_NAME`` and ``INITSCRIPT_PARAMS``. See the variable links | ||
2854 | for details. | ||
2855 | |||
2856 | .. _ref-classes-useradd: | ||
2857 | |||
2858 | ``useradd*.bbclass`` | ||
2859 | ==================== | ||
2860 | |||
2861 | The ``useradd*`` classes support the addition of users or groups for | ||
2862 | usage by the package on the target. For example, if you have packages | ||
2863 | that contain system services that should be run under their own user or | ||
2864 | group, you can use these classes to enable creation of the user or | ||
2865 | group. The ``meta-skeleton/recipes-skeleton/useradd/useradd-example.bb`` | ||
2866 | recipe in the :term:`Source Directory` provides a simple | ||
2867 | example that shows how to add three users and groups to two packages. | ||
2868 | See the ``useradd-example.bb`` recipe for more information on how to use | ||
2869 | these classes. | ||
2870 | |||
2871 | The ``useradd_base`` class provides basic functionality for user or | ||
2872 | groups settings. | ||
2873 | |||
2874 | The ``useradd*`` classes support the | ||
2875 | :term:`USERADD_PACKAGES`, | ||
2876 | :term:`USERADD_PARAM`, | ||
2877 | :term:`GROUPADD_PARAM`, and | ||
2878 | :term:`GROUPMEMS_PARAM` variables. | ||
2879 | |||
2880 | The ``useradd-staticids`` class supports the addition of users or groups | ||
2881 | that have static user identification (``uid``) and group identification | ||
2882 | (``gid``) values. | ||
2883 | |||
2884 | The default behavior of the OpenEmbedded build system for assigning | ||
2885 | ``uid`` and ``gid`` values when packages add users and groups during | ||
2886 | package install time is to add them dynamically. This works fine for | ||
2887 | programs that do not care what the values of the resulting users and | ||
2888 | groups become. In these cases, the order of the installation determines | ||
2889 | the final ``uid`` and ``gid`` values. However, if non-deterministic | ||
2890 | ``uid`` and ``gid`` values are a problem, you can override the default, | ||
2891 | dynamic application of these values by setting static values. When you | ||
2892 | set static values, the OpenEmbedded build system looks in | ||
2893 | :term:`BBPATH` for ``files/passwd`` and ``files/group`` | ||
2894 | files for the values. | ||
2895 | |||
2896 | To use static ``uid`` and ``gid`` values, you need to set some | ||
2897 | variables. See the :term:`USERADDEXTENSION`, | ||
2898 | :term:`USERADD_UID_TABLES`, | ||
2899 | :term:`USERADD_GID_TABLES`, and | ||
2900 | :term:`USERADD_ERROR_DYNAMIC` variables. | ||
2901 | You can also see the :ref:`useradd <ref-classes-useradd>` class for | ||
2902 | additional information. | ||
2903 | |||
2904 | .. note:: | ||
2905 | |||
2906 | You do not use the | ||
2907 | useradd-staticids | ||
2908 | class directly. You either enable or disable the class by setting the | ||
2909 | USERADDEXTENSION | ||
2910 | variable. If you enable or disable the class in a configured system, | ||
2911 | TMPDIR | ||
2912 | might contain incorrect | ||
2913 | uid | ||
2914 | and | ||
2915 | gid | ||
2916 | values. Deleting the | ||
2917 | TMPDIR | ||
2918 | directory will correct this condition. | ||
2919 | |||
2920 | .. _ref-classes-utility-tasks: | ||
2921 | |||
2922 | ``utility-tasks.bbclass`` | ||
2923 | ========================= | ||
2924 | |||
2925 | The ``utility-tasks`` class provides support for various "utility" type | ||
2926 | tasks that are applicable to all recipes, such as | ||
2927 | :ref:`ref-tasks-clean` and | ||
2928 | :ref:`ref-tasks-listtasks`. | ||
2929 | |||
2930 | This class is enabled by default because it is inherited by the | ||
2931 | :ref:`base <ref-classes-base>` class. | ||
2932 | |||
2933 | .. _ref-classes-utils: | ||
2934 | |||
2935 | ``utils.bbclass`` | ||
2936 | ================= | ||
2937 | |||
2938 | The ``utils`` class provides some useful Python functions that are | ||
2939 | typically used in inline Python expressions (e.g. ``${@...}``). One | ||
2940 | example use is for ``bb.utils.contains()``. | ||
2941 | |||
2942 | This class is enabled by default because it is inherited by the | ||
2943 | :ref:`base <ref-classes-base>` class. | ||
2944 | |||
2945 | .. _ref-classes-vala: | ||
2946 | |||
2947 | ``vala.bbclass`` | ||
2948 | ================ | ||
2949 | |||
2950 | The ``vala`` class supports recipes that need to build software written | ||
2951 | using the Vala programming language. | ||
2952 | |||
2953 | .. _ref-classes-waf: | ||
2954 | |||
2955 | ``waf.bbclass`` | ||
2956 | =============== | ||
2957 | |||
2958 | The ``waf`` class supports recipes that need to build software that uses | ||
2959 | the Waf build system. You can use the | ||
2960 | :term:`EXTRA_OECONF` or | ||
2961 | :term:`PACKAGECONFIG_CONFARGS` variables | ||
2962 | to specify additional configuration options to be passed on the Waf | ||
2963 | command line. | ||