summaryrefslogtreecommitdiffstats
path: root/documentation/ref-manual/ref-features.xml
diff options
context:
space:
mode:
authorNicolas Dechesne <nicolas.dechesne@linaro.org>2020-10-05 16:30:32 +0200
committerRichard Purdie <richard.purdie@linuxfoundation.org>2020-10-06 13:56:17 +0100
commit43d07a285181e64c30d98d10ff93ef50391efe59 (patch)
tree78918fc94d55d44d35e1e3e61c7a6fccc28bca24 /documentation/ref-manual/ref-features.xml
parent1fd9c4b2c0ae927df29f7a0d34c3e595bcf48e89 (diff)
downloadpoky-43d07a285181e64c30d98d10ff93ef50391efe59.tar.gz
sphinx: remove DocBook files
The Yocto Project documentation was migrated to Sphinx. Let's remove the deprecated DocBook files. (From yocto-docs rev: 28fb0e63b2fbfd6426b00498bf2682bb53fdd862) Signed-off-by: Nicolas Dechesne <nicolas.dechesne@linaro.org> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/ref-manual/ref-features.xml')
-rw-r--r--documentation/ref-manual/ref-features.xml461
1 files changed, 0 insertions, 461 deletions
diff --git a/documentation/ref-manual/ref-features.xml b/documentation/ref-manual/ref-features.xml
deleted file mode 100644
index 8cab5ec3a8..0000000000
--- a/documentation/ref-manual/ref-features.xml
+++ /dev/null
@@ -1,461 +0,0 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4<!--SPDX-License-Identifier: CC-BY-2.0-UK-->
5
6<chapter id='ref-features'>
7 <title>Features</title>
8
9 <para>
10 This chapter provides a reference of shipped machine and distro features
11 you can include as part of your image, a reference on image features you can
12 select, and a reference on feature backfilling.
13 </para>
14
15 <para>
16 Features provide a mechanism for working out which packages
17 should be included in the generated images.
18 Distributions can select which features they want to support through the
19 <filename><link linkend='var-DISTRO_FEATURES'>DISTRO_FEATURES</link></filename>
20 variable, which is set or appended to in a distribution's configuration file such as
21 <filename>poky.conf</filename>,
22 <filename>poky-tiny.conf</filename>,
23 <filename>poky-lsb.conf</filename> and so forth.
24 Machine features are set in the
25 <filename><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES</link></filename>
26 variable, which is set in the machine configuration file and
27 specifies the hardware features for a given machine.
28 </para>
29
30 <para>
31 These two variables combine to work out which kernel modules,
32 utilities, and other packages to include.
33 A given distribution can support a selected subset of features so some machine features might not
34 be included if the distribution itself does not support them.
35 </para>
36
37 <para>
38 One method you can use to determine which recipes are checking to see if a
39 particular feature is contained or not is to <filename>grep</filename> through
40 the <link linkend='metadata'>Metadata</link>
41 for the feature.
42 Here is an example that discovers the recipes whose build is potentially
43 changed based on a given feature:
44 <literallayout class='monospaced'>
45 $ cd poky
46 $ git grep 'contains.*MACHINE_FEATURES.*<replaceable>feature</replaceable>'
47 </literallayout>
48 </para>
49
50 <section id='ref-features-machine'>
51 <title>Machine Features</title>
52
53 <para>
54 The items below are features you can use with
55 <link linkend='var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></link>.
56 Features do not have a one-to-one correspondence to packages, and they can
57 go beyond simply controlling the installation of a package or packages.
58 Sometimes a feature can influence how certain recipes are built.
59 For example, a feature might determine whether a particular configure option
60 is specified within the
61 <link linkend='ref-tasks-configure'><filename>do_configure</filename></link>
62 task for a particular recipe.
63 </para>
64
65 <para>
66 This feature list only represents features as shipped with the Yocto Project metadata:
67 <itemizedlist>
68 <listitem><para><emphasis>acpi:</emphasis> Hardware has ACPI (x86/x86_64 only)
69 </para></listitem>
70 <listitem><para><emphasis>alsa:</emphasis> Hardware has ALSA audio drivers
71 </para></listitem>
72 <listitem><para><emphasis>apm:</emphasis> Hardware uses APM (or APM emulation)
73 </para></listitem>
74 <listitem><para><emphasis>bluetooth:</emphasis> Hardware has integrated BT
75 </para></listitem>
76 <listitem><para><emphasis>efi:</emphasis> Support for booting through EFI
77 </para></listitem>
78 <listitem><para><emphasis>ext2:</emphasis> Hardware HDD or Microdrive
79 </para></listitem>
80 <listitem><para><emphasis>keyboard:</emphasis> Hardware has a keyboard
81 </para></listitem>
82 <listitem><para><emphasis>pcbios:</emphasis> Support for booting through BIOS
83 </para></listitem>
84 <listitem><para><emphasis>pci:</emphasis> Hardware has a PCI bus
85 </para></listitem>
86 <listitem><para><emphasis>pcmcia:</emphasis> Hardware has PCMCIA or CompactFlash sockets
87 </para></listitem>
88 <listitem><para><emphasis>phone:</emphasis> Mobile phone (voice) support
89 </para></listitem>
90 <listitem><para><emphasis>qvga:</emphasis> Machine has a QVGA (320x240) display
91 </para></listitem>
92 <listitem><para><emphasis>rtc:</emphasis> Machine has a Real-Time Clock
93 </para></listitem>
94 <listitem><para><emphasis>screen:</emphasis> Hardware has a screen
95 </para></listitem>
96 <listitem><para><emphasis>serial:</emphasis> Hardware has serial support (usually RS232)
97 </para></listitem>
98 <listitem><para><emphasis>touchscreen:</emphasis> Hardware has a touchscreen
99 </para></listitem>
100 <listitem><para><emphasis>usbgadget:</emphasis> Hardware is USB gadget device capable
101 </para></listitem>
102 <listitem><para><emphasis>usbhost:</emphasis> Hardware is USB Host capable
103 </para></listitem>
104 <listitem><para><emphasis>vfat:</emphasis> FAT file system support
105 </para></listitem>
106 <listitem><para><emphasis>wifi:</emphasis> Hardware has integrated WiFi
107 </para></listitem>
108 </itemizedlist>
109 </para>
110 </section>
111
112 <section id='ref-features-distro'>
113 <title>Distro Features</title>
114
115 <para>
116 The items below are features you can use with
117 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>
118 to enable features across your distribution.
119 Features do not have a one-to-one correspondence to packages,
120 and they can go beyond simply controlling the installation of a
121 package or packages.
122 In most cases, the presence or absence of a feature translates to
123 the appropriate option supplied to the configure script during the
124 <link linkend='ref-tasks-configure'><filename>do_configure</filename></link>
125 task for the recipes that optionally
126 support the feature.
127 </para>
128
129 <para>
130 Some distro features are also machine features.
131 These select features make sense to be controlled both at
132 the machine and distribution configuration level.
133 See the
134 <link linkend='var-COMBINED_FEATURES'><filename>COMBINED_FEATURES</filename></link>
135 variable for more information.
136 </para>
137
138 <para>
139 This list only represents features as shipped with the Yocto Project metadata:
140 <itemizedlist>
141 <listitem><para><emphasis>alsa:</emphasis> Include ALSA support
142 (OSS compatibility kernel modules installed if available).
143 </para></listitem>
144 <listitem><para><emphasis>api-documentation:</emphasis>
145 Enables generation of API documentation during recipe
146 builds.
147 The resulting documentation is added to SDK tarballs
148 when the
149 <filename>bitbake -c populate_sdk</filename> command
150 is used.
151 See the
152 "<ulink url='&YOCTO_DOCS_SDK_URL;#adding-api-documentation-to-the-standard-sdk'>Adding API Documentation to the Standard SDK</ulink>"
153 section in the Yocto Project Application Development and
154 the Extensible Software Development Kit (eSDK) manual.
155 </para></listitem>
156 <listitem><para><emphasis>bluetooth:</emphasis> Include
157 bluetooth support (integrated BT only).</para></listitem>
158 <listitem><para><emphasis>cramfs:</emphasis> Include CramFS
159 support.</para></listitem>
160 <listitem><para><emphasis>directfb:</emphasis>
161 Include DirectFB support.
162 </para></listitem>
163 <listitem><para><emphasis>ext2:</emphasis> Include tools for
164 supporting for devices with internal HDD/Microdrive for
165 storing files (instead of Flash only devices).
166 </para></listitem>
167 <listitem><para><emphasis>ipsec:</emphasis> Include IPSec
168 support.</para></listitem>
169 <listitem><para><emphasis>ipv6:</emphasis> Include IPv6 support.
170 </para></listitem>
171 <listitem><para><emphasis>keyboard:</emphasis> Include keyboard
172 support (e.g. keymaps will be loaded during boot).
173 </para></listitem>
174 <listitem><para><emphasis>ldconfig:</emphasis>
175 Include support for ldconfig and
176 <filename>ld.so.conf</filename> on the target.
177 </para></listitem>
178 <listitem><para><emphasis>nfs:</emphasis> Include NFS client
179 support (for mounting NFS exports on device).
180 </para></listitem>
181 <listitem><para><emphasis>opengl:</emphasis>
182 Include the Open Graphics Library, which is a
183 cross-language, multi-platform application programming
184 interface used for rendering two and three-dimensional
185 graphics.</para></listitem>
186 <listitem><para><emphasis>pci:</emphasis> Include PCI bus
187 support.</para></listitem>
188 <listitem><para><emphasis>pcmcia:</emphasis> Include
189 PCMCIA/CompactFlash support.</para></listitem>
190 <listitem><para><emphasis>ppp:</emphasis> Include PPP dialup
191 support.</para></listitem>
192 <listitem><para><emphasis>ptest:</emphasis> Enables building
193 the package tests where supported by individual recipes.
194 For more information on package tests, see the
195 "<ulink url='&YOCTO_DOCS_DEV_URL;#testing-packages-with-ptest'>Testing Packages With ptest</ulink>"
196 section in the Yocto Project Development Tasks Manual.
197 </para></listitem>
198 <listitem><para><emphasis>smbfs:</emphasis> Include SMB networks
199 client support (for mounting Samba/Microsoft Windows shares
200 on device).</para></listitem>
201 <listitem><para><emphasis>systemd:</emphasis> Include support
202 for this <filename>init</filename> manager, which is a full
203 replacement of for <filename>init</filename> with parallel
204 starting of services, reduced shell overhead, and other
205 features.
206 This <filename>init</filename> manager is used by many
207 distributions.</para></listitem>
208 <listitem><para><emphasis>usbgadget:</emphasis> Include USB
209 Gadget Device support (for USB networking/serial/storage).
210 </para></listitem>
211 <listitem><para><emphasis>usbhost:</emphasis> Include USB Host
212 support (allows to connect external keyboard, mouse,
213 storage, network etc).</para></listitem>
214 <listitem><para><emphasis>usrmerge:</emphasis> Merges the
215 <filename>/bin</filename>, <filename>/sbin</filename>,
216 <filename>/lib</filename>, and <filename>/lib64</filename>
217 directories into their respective counterparts in the
218 <filename>/usr</filename> directory to provide better package
219 and application compatibility.</para></listitem>
220 <listitem><para><emphasis>wayland:</emphasis> Include the
221 Wayland display server protocol and the library that
222 supports it.</para></listitem>
223 <listitem><para><emphasis>wifi:</emphasis> Include WiFi support
224 (integrated only).</para></listitem>
225 <listitem><para><emphasis>x11:</emphasis> Include the X server
226 and libraries.</para></listitem>
227 </itemizedlist>
228 </para>
229 </section>
230
231 <section id='ref-features-image'>
232 <title>Image Features</title>
233
234 <para>
235 The contents of images generated by the OpenEmbedded build system
236 can be controlled by the
237 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>
238 and
239 <link linkend='var-EXTRA_IMAGE_FEATURES'><filename>EXTRA_IMAGE_FEATURES</filename></link>
240 variables that you typically configure in your image recipes.
241 Through these variables, you can add several different
242 predefined packages such as development utilities or packages with
243 debug information needed to investigate application problems or
244 profile applications.
245 </para>
246
247 <para>
248 The following image features are available for all images:
249 <itemizedlist>
250 <listitem><para><emphasis>allow-empty-password:</emphasis>
251 Allows Dropbear and OpenSSH to accept root logins
252 and logins from accounts having an empty password string.
253 </para></listitem>
254 <listitem><para><emphasis>dbg-pkgs:</emphasis>
255 Installs debug symbol packages for all packages installed
256 in a given image.
257 </para></listitem>
258 <listitem><para><emphasis>debug-tweaks:</emphasis>
259 Makes an image suitable for development (e.g.
260 allows root logins without passwords and enables
261 post-installation logging).
262 See the 'allow-empty-password', 'empty-root-password',
263 and 'post-install-logging' features in this list for
264 additional information.
265 </para></listitem>
266 <listitem><para><emphasis>dev-pkgs:</emphasis>
267 Installs development packages (headers and extra library
268 links) for all packages installed in a given image.
269 </para></listitem>
270 <listitem><para><emphasis>doc-pkgs:</emphasis> Installs
271 documentation packages for all packages installed in a
272 given image.
273 </para></listitem>
274 <listitem><para><emphasis>empty-root-password:</emphasis>
275 Sets the root password to an empty string, which allows
276 logins with a blank password.
277 </para></listitem>
278 <listitem><para><emphasis>package-management:</emphasis>
279 Installs package management tools and preserves the package
280 manager database.
281 </para></listitem>
282 <listitem><para><emphasis>post-install-logging:</emphasis>
283 Enables logging postinstall script runs to
284 the <filename>/var/log/postinstall.log</filename> file
285 on first boot of the image on the target system.
286 <note>
287 To make the <filename>/var/log</filename> directory
288 on the target persistent, use the
289 <link linkend='var-VOLATILE_LOG_DIR'><filename>VOLATILE_LOG_DIR</filename></link>
290 variable by setting it to "no".
291 </note>
292 </para></listitem>
293 <listitem><para><emphasis>ptest-pkgs:</emphasis>
294 Installs ptest packages for all ptest-enabled recipes.
295 </para></listitem>
296 <listitem><para><emphasis>read-only-rootfs:</emphasis>
297 Creates an image whose root filesystem is read-only.
298 See the
299 "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-read-only-root-filesystem'>Creating a Read-Only Root Filesystem</ulink>"
300 section in the Yocto Project Development Tasks Manual for
301 more information.
302 </para></listitem>
303 <listitem><para><emphasis>splash:</emphasis>
304 Enables showing a splash screen during boot.
305 By default, this screen is provided by
306 <filename>psplash</filename>, which does allow
307 customization.
308 If you prefer to use an alternative splash screen package,
309 you can do so by setting the <filename>SPLASH</filename>
310 variable to a different package name (or names) within the
311 image recipe or at the distro configuration level.
312 </para></listitem>
313 <listitem><para><emphasis>staticdev-pkgs:</emphasis>
314 Installs static development packages, which are
315 static libraries (i.e. <filename>*.a</filename> files), for
316 all packages installed in a given image.
317 </para></listitem>
318 </itemizedlist>
319 </para>
320
321 <para>
322 Some image features are available only when you inherit the
323 <link linkend='ref-classes-core-image'><filename>core-image</filename></link>
324 class.
325 The current list of these valid features is as follows:
326 <itemizedlist>
327 <listitem><para><emphasis>hwcodecs:</emphasis> Installs
328 hardware acceleration codecs.
329 </para></listitem>
330 <listitem><para><emphasis>nfs-server:</emphasis>
331 Installs an NFS server.
332 </para></listitem>
333 <listitem><para><emphasis>perf:</emphasis>
334 Installs profiling tools such as
335 <filename>perf</filename>, <filename>systemtap</filename>,
336 and <filename>LTTng</filename>.
337 For general information on user-space tools, see the
338 <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink>
339 manual.
340 </para></listitem>
341 <listitem><para><emphasis>ssh-server-dropbear:</emphasis>
342 Installs the Dropbear minimal SSH server.
343 </para></listitem>
344 <listitem><para><emphasis>ssh-server-openssh:</emphasis>
345 Installs the OpenSSH SSH server, which is more
346 full-featured than Dropbear.
347 Note that if both the OpenSSH SSH server and the Dropbear
348 minimal SSH server are present in
349 <filename>IMAGE_FEATURES</filename>, then OpenSSH will take
350 precedence and Dropbear will not be installed.
351 </para></listitem>
352 <listitem><para><emphasis>tools-debug:</emphasis>
353 Installs debugging tools such as
354 <filename>strace</filename> and <filename>gdb</filename>.
355 For information on GDB, see the
356 "<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-gdb-remotedebug'>Debugging With the GNU Project Debugger (GDB) Remotely</ulink>"
357 section in the Yocto Project Development Tasks Manual.
358 For information on tracing and profiling, see the
359 <ulink url='&YOCTO_DOCS_PROF_URL;'>Yocto Project Profiling and Tracing Manual</ulink>.
360 </para></listitem>
361 <listitem><para><emphasis>tools-sdk:</emphasis>
362 Installs a full SDK that runs on the device.
363 </para></listitem>
364 <listitem><para><emphasis>tools-testapps:</emphasis>
365 Installs device testing tools (e.g. touchscreen debugging).
366 </para></listitem>
367 <listitem><para><emphasis>x11:</emphasis>
368 Installs the X server.
369 </para></listitem>
370 <listitem><para><emphasis>x11-base:</emphasis>
371 Installs the X server with a minimal environment.
372 </para></listitem>
373 <listitem><para><emphasis>x11-sato:</emphasis>
374 Installs the OpenedHand Sato environment.
375 </para></listitem>
376 </itemizedlist>
377 </para>
378
379 </section>
380
381 <section id='ref-features-backfill'>
382 <title>Feature Backfilling</title>
383
384 <para>
385 Sometimes it is necessary in the OpenEmbedded build system to extend
386 <link linkend='var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></link>
387 or <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>
388 to control functionality that was previously enabled and not able
389 to be disabled.
390 For these cases, we need to add an
391 additional feature item to appear in one of these variables,
392 but we do not want to force developers who have existing values
393 of the variables in their configuration to add the new feature
394 in order to retain the same overall level of functionality.
395 Thus, the OpenEmbedded build system has a mechanism to
396 automatically "backfill" these added features into existing
397 distro or machine configurations.
398 You can see the list of features for which this is done by
399 finding the
400 <link linkend='var-DISTRO_FEATURES_BACKFILL'><filename>DISTRO_FEATURES_BACKFILL</filename></link>
401 and <link linkend='var-MACHINE_FEATURES_BACKFILL'><filename>MACHINE_FEATURES_BACKFILL</filename></link>
402 variables in the <filename>meta/conf/bitbake.conf</filename> file.
403 </para>
404
405 <para>
406 Because such features are backfilled by default into all
407 configurations as described in the previous paragraph, developers
408 who wish to disable the new features need to be able to selectively
409 prevent the backfilling from occurring.
410 They can do this by adding the undesired feature or features to the
411 <link linkend='var-DISTRO_FEATURES_BACKFILL_CONSIDERED'><filename>DISTRO_FEATURES_BACKFILL_CONSIDERED</filename></link>
412 or <link linkend='var-MACHINE_FEATURES_BACKFILL_CONSIDERED'><filename>MACHINE_FEATURES_BACKFILL_CONSIDERED</filename></link>
413 variables for distro features and machine features respectively.
414 </para>
415
416 <para>
417 Here are two examples to help illustrate feature backfilling:
418 <itemizedlist>
419 <listitem><para><emphasis>The "pulseaudio" distro feature option</emphasis>:
420 Previously, PulseAudio support was enabled within the Qt and
421 GStreamer frameworks.
422 Because of this, the feature is backfilled and thus
423 enabled for all distros through the
424 <filename>DISTRO_FEATURES_BACKFILL</filename>
425 variable in the <filename>meta/conf/bitbake.conf</filename> file.
426 However, your distro needs to disable the feature.
427 You can disable the feature without affecting
428 other existing distro configurations that need PulseAudio support
429 by adding "pulseaudio" to
430 <filename>DISTRO_FEATURES_BACKFILL_CONSIDERED</filename>
431 in your distro's <filename>.conf</filename> file.
432 Adding the feature to this variable when it also
433 exists in the <filename>DISTRO_FEATURES_BACKFILL</filename>
434 variable prevents the build system from adding the feature to
435 your configuration's <filename>DISTRO_FEATURES</filename>, effectively disabling
436 the feature for that particular distro.</para></listitem>
437 <listitem><para><emphasis>The "rtc" machine feature option</emphasis>:
438 Previously, real time clock (RTC) support was enabled for all
439 target devices.
440 Because of this, the feature is backfilled and thus enabled
441 for all machines through the <filename>MACHINE_FEATURES_BACKFILL</filename>
442 variable in the <filename>meta/conf/bitbake.conf</filename> file.
443 However, your target device does not have this capability.
444 You can disable RTC support for your device without
445 affecting other machines that need RTC support
446 by adding the feature to your machine's
447 <filename>MACHINE_FEATURES_BACKFILL_CONSIDERED</filename>
448 list in the machine's <filename>.conf</filename> file.
449 Adding the feature to this variable when it also
450 exists in the <filename>MACHINE_FEATURES_BACKFILL</filename>
451 variable prevents the build system from adding the feature to
452 your configuration's <filename>MACHINE_FEATURES</filename>, effectively
453 disabling RTC support for that particular machine.</para></listitem>
454 </itemizedlist>
455 </para>
456 </section>
457</chapter>
458
459<!--
460vim: expandtab tw=80 ts=4 spell spelllang=en_gb
461-->
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2026-04-21 21:05:26 +0000