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