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