summaryrefslogtreecommitdiffstats
path: root/documentation/ref-manual/ref-features.rst
diff options
context:
space:
mode:
authorNicolas Dechesne <nicolas.dechesne@linaro.org>2020-06-26 19:10:51 +0200
committerRichard Purdie <richard.purdie@linuxfoundation.org>2020-09-17 10:09:33 +0100
commit9bd69b1f1d71a9692189beeac75af9dfbad816cc (patch)
tree305347fca899074aed5610e0e82eaec180bf630c /documentation/ref-manual/ref-features.rst
parentc40a8d5904c29046f1cbbeb998e6cd7c24f9b206 (diff)
downloadpoky-9bd69b1f1d71a9692189beeac75af9dfbad816cc.tar.gz
sphinx: initial sphinx support
This commit is autogenerated pandoc to generate an inital set of reST files based on DocBook XML files. A .rst file is generated for each .xml files in all manuals with this command: cd <manual> for i in *.xml; do \ pandoc -f docbook -t rst --shift-heading-level-by=-1 \ $i -o $(basename $i .xml).rst \ done The conversion was done with: pandoc 2.9.2.1-91 (Arch Linux). Also created an initial top level index file for each document, and added all 'books' to the top leve index.rst file. The YP manuals layout is organized as: Book Chapter Section Section Section Sphinx uses section headers to create the document structure. ReStructuredText defines sections headers like that: To break longer text up into sections, you use section headers. These are a single line of text (one or more words) with adornment: an underline alone, or an underline and an overline together, in dashes "-----", equals "======", tildes "~~~~~~" or any of the non-alphanumeric characters = - ` : ' " ~ ^ _ * + # < > that you feel comfortable with. An underline-only adornment is distinct from an overline-and-underline adornment using the same character. The underline/overline must be at least as long as the title text. Be consistent, since all sections marked with the same adornment style are deemed to be at the same level: Let's define the following convention when converting from Docbook: Book => overline === (Title) Chapter => overline *** (1.) Section => ==== (1.1) Section => ---- (1.1.1) Section => ~~~~ (1.1.1.1) Section => ^^^^ (1.1.1.1.1) During the conversion with pandoc, we used --shift-heading-level=-1 to convert most of DocBook headings automatically. However with this setting, the Chapter header was removed, so I added it back manually. Without this setting all headings were off by one, which was more difficult to manually fix. At least with this change, we now have the same TOC with Sphinx and DocBook. (From yocto-docs rev: 3c73d64a476d4423ee4c6808c685fa94d88d7df8) 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.rst')
-rw-r--r--documentation/ref-manual/ref-features.rst353
1 files changed, 353 insertions, 0 deletions
diff --git a/documentation/ref-manual/ref-features.rst b/documentation/ref-manual/ref-features.rst
new file mode 100644
index 0000000000..1cdf09bfdb
--- /dev/null
+++ b/documentation/ref-manual/ref-features.rst
@@ -0,0 +1,353 @@
1********
2Features
3********
4
5This chapter provides a reference of shipped machine and distro features
6you can include as part of your image, a reference on image features you
7can select, and a reference on feature backfilling.
8
9Features provide a mechanism for working out which packages should be
10included in the generated images. Distributions can select which
11features they want to support through the ``DISTRO_FEATURES`` variable,
12which is set or appended to in a distribution's configuration file such
13as ``poky.conf``, ``poky-tiny.conf``, ``poky-lsb.conf`` and so forth.
14Machine features are set in the ``MACHINE_FEATURES`` variable, which is
15set in the machine configuration file and specifies the hardware
16features for a given machine.
17
18These two variables combine to work out which kernel modules, utilities,
19and other packages to include. A given distribution can support a
20selected subset of features so some machine features might not be
21included if the distribution itself does not support them.
22
23One method you can use to determine which recipes are checking to see if
24a particular feature is contained or not is to ``grep`` through the
25`Metadata <#metadata>`__ for the feature. Here is an example that
26discovers the recipes whose build is potentially changed based on a
27given feature: $ cd poky $ git grep
28'contains.*MACHINE_FEATURES.*feature'
29
30.. _ref-features-machine:
31
32Machine Features
33================
34
35The items below are features you can use with
36```MACHINE_FEATURES`` <#var-MACHINE_FEATURES>`__. Features do not have a
37one-to-one correspondence to packages, and they can go beyond simply
38controlling the installation of a package or packages. Sometimes a
39feature can influence how certain recipes are built. For example, a
40feature might determine whether a particular configure option is
41specified within the ```do_configure`` <#ref-tasks-configure>`__ task
42for a particular recipe.
43
44This feature list only represents features as shipped with the Yocto
45Project metadata:
46
47- *acpi:* Hardware has ACPI (x86/x86_64 only)
48
49- *alsa:* Hardware has ALSA audio drivers
50
51- *apm:* Hardware uses APM (or APM emulation)
52
53- *bluetooth:* Hardware has integrated BT
54
55- *efi:* Support for booting through EFI
56
57- *ext2:* Hardware HDD or Microdrive
58
59- *keyboard:* Hardware has a keyboard
60
61- *pcbios:* Support for booting through BIOS
62
63- *pci:* Hardware has a PCI bus
64
65- *pcmcia:* Hardware has PCMCIA or CompactFlash sockets
66
67- *phone:* Mobile phone (voice) support
68
69- *qvga:* Machine has a QVGA (320x240) display
70
71- *rtc:* Machine has a Real-Time Clock
72
73- *screen:* Hardware has a screen
74
75- *serial:* Hardware has serial support (usually RS232)
76
77- *touchscreen:* Hardware has a touchscreen
78
79- *usbgadget:* Hardware is USB gadget device capable
80
81- *usbhost:* Hardware is USB Host capable
82
83- *vfat:* FAT file system support
84
85- *wifi:* Hardware has integrated WiFi
86
87.. _ref-features-distro:
88
89Distro Features
90===============
91
92The items below are features you can use with
93```DISTRO_FEATURES`` <#var-DISTRO_FEATURES>`__ to enable features across
94your distribution. Features do not have a one-to-one correspondence to
95packages, and they can go beyond simply controlling the installation of
96a package or packages. In most cases, the presence or absence of a
97feature translates to the appropriate option supplied to the configure
98script during the ```do_configure`` <#ref-tasks-configure>`__ task for
99the recipes that optionally support the feature.
100
101Some distro features are also machine features. These select features
102make sense to be controlled both at the machine and distribution
103configuration level. See the
104```COMBINED_FEATURES`` <#var-COMBINED_FEATURES>`__ variable for more
105information.
106
107This list only represents features as shipped with the Yocto Project
108metadata:
109
110- *alsa:* Include ALSA support (OSS compatibility kernel modules
111 installed if available).
112
113- *api-documentation:* Enables generation of API documentation during
114 recipe builds. The resulting documentation is added to SDK tarballs
115 when the ``bitbake -c populate_sdk`` command is used. See the
116 "`Adding API Documentation to the Standard
117 SDK <&YOCTO_DOCS_SDK_URL;#adding-api-documentation-to-the-standard-sdk>`__"
118 section in the Yocto Project Application Development and the
119 Extensible Software Development Kit (eSDK) manual.
120
121- *bluetooth:* Include bluetooth support (integrated BT only).
122
123- *cramfs:* Include CramFS support.
124
125- *directfb:* Include DirectFB support.
126
127- *ext2:* Include tools for supporting for devices with internal
128 HDD/Microdrive for storing files (instead of Flash only devices).
129
130- *ipsec:* Include IPSec support.
131
132- *ipv6:* Include IPv6 support.
133
134- *keyboard:* Include keyboard support (e.g. keymaps will be loaded
135 during boot).
136
137- *ldconfig:* Include support for ldconfig and ``ld.so.conf`` on the
138 target.
139
140- *nfs:* Include NFS client support (for mounting NFS exports on
141 device).
142
143- *opengl:* Include the Open Graphics Library, which is a
144 cross-language, multi-platform application programming interface used
145 for rendering two and three-dimensional graphics.
146
147- *pci:* Include PCI bus support.
148
149- *pcmcia:* Include PCMCIA/CompactFlash support.
150
151- *ppp:* Include PPP dialup support.
152
153- *ptest:* Enables building the package tests where supported by
154 individual recipes. For more information on package tests, see the
155 "`Testing Packages With
156 ptest <&YOCTO_DOCS_DEV_URL;#testing-packages-with-ptest>`__" section
157 in the Yocto Project Development Tasks Manual.
158
159- *smbfs:* Include SMB networks client support (for mounting
160 Samba/Microsoft Windows shares on device).
161
162- *systemd:* Include support for this ``init`` manager, which is a full
163 replacement of for ``init`` with parallel starting of services,
164 reduced shell overhead, and other features. This ``init`` manager is
165 used by many distributions.
166
167- *usbgadget:* Include USB Gadget Device support (for USB
168 networking/serial/storage).
169
170- *usbhost:* Include USB Host support (allows to connect external
171 keyboard, mouse, storage, network etc).
172
173- *usrmerge:* Merges the ``/bin``, ``/sbin``, ``/lib``, and ``/lib64``
174 directories into their respective counterparts in the ``/usr``
175 directory to provide better package and application compatibility.
176
177- *wayland:* Include the Wayland display server protocol and the
178 library that supports it.
179
180- *wifi:* Include WiFi support (integrated only).
181
182- *x11:* Include the X server and libraries.
183
184.. _ref-features-image:
185
186Image Features
187==============
188
189The contents of images generated by the OpenEmbedded build system can be
190controlled by the ```IMAGE_FEATURES`` <#var-IMAGE_FEATURES>`__ and
191```EXTRA_IMAGE_FEATURES`` <#var-EXTRA_IMAGE_FEATURES>`__ variables that
192you typically configure in your image recipes. Through these variables,
193you can add several different predefined packages such as development
194utilities or packages with debug information needed to investigate
195application problems or profile applications.
196
197The following image features are available for all images:
198
199- *allow-empty-password:* Allows Dropbear and OpenSSH to accept root
200 logins and logins from accounts having an empty password string.
201
202- *dbg-pkgs:* Installs debug symbol packages for all packages installed
203 in a given image.
204
205- *debug-tweaks:* Makes an image suitable for development (e.g. allows
206 root logins without passwords and enables post-installation logging).
207 See the 'allow-empty-password', 'empty-root-password', and
208 'post-install-logging' features in this list for additional
209 information.
210
211- *dev-pkgs:* Installs development packages (headers and extra library
212 links) for all packages installed in a given image.
213
214- *doc-pkgs:* Installs documentation packages for all packages
215 installed in a given image.
216
217- *empty-root-password:* Sets the root password to an empty string,
218 which allows logins with a blank password.
219
220- *package-management:* Installs package management tools and preserves
221 the package manager database.
222
223- *post-install-logging:* Enables logging postinstall script runs to
224 the ``/var/log/postinstall.log`` file on first boot of the image on
225 the target system.
226
227 .. note::
228
229 To make the
230 /var/log
231 directory on the target persistent, use the
232 VOLATILE_LOG_DIR
233 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 "`Creating a Read-Only Root
239 Filesystem <&YOCTO_DOCS_DEV_URL;#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```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 `Yocto Project Application Development and the Extensible Software
265 Development Kit (eSDK) <&YOCTO_DOCS_SDK_URL;>`__ manual.
266
267- *ssh-server-dropbear:* Installs the Dropbear minimal SSH server.
268
269- *ssh-server-openssh:* Installs the OpenSSH SSH server, which is more
270 full-featured than Dropbear. Note that if both the OpenSSH SSH server
271 and the Dropbear minimal SSH server are present in
272 ``IMAGE_FEATURES``, then OpenSSH will take precedence and Dropbear
273 will not be installed.
274
275- *tools-debug:* Installs debugging tools such as ``strace`` and
276 ``gdb``. For information on GDB, see the "`Debugging With the GNU
277 Project Debugger (GDB)
278 Remotely <&YOCTO_DOCS_DEV_URL;#platdev-gdb-remotedebug>`__" section
279 in the Yocto Project Development Tasks Manual. For information on
280 tracing and profiling, see the `Yocto Project Profiling and Tracing
281 Manual <&YOCTO_DOCS_PROF_URL;>`__.
282
283- *tools-sdk:* Installs a full SDK that runs on the device.
284
285- *tools-testapps:* Installs device testing tools (e.g. touchscreen
286 debugging).
287
288- *x11:* Installs the X server.
289
290- *x11-base:* Installs the X server with a minimal environment.
291
292- *x11-sato:* Installs the OpenedHand Sato environment.
293
294.. _ref-features-backfill:
295
296Feature Backfilling
297===================
298
299Sometimes it is necessary in the OpenEmbedded build system to extend
300```MACHINE_FEATURES`` <#var-MACHINE_FEATURES>`__ or
301```DISTRO_FEATURES`` <#var-DISTRO_FEATURES>`__ to control functionality
302that was previously enabled and not able to be disabled. For these
303cases, we need to add an additional feature item to appear in one of
304these variables, but we do not want to force developers who have
305existing values of the variables in their configuration to add the new
306feature in order to retain the same overall level of functionality.
307Thus, the OpenEmbedded build system has a mechanism to automatically
308"backfill" these added features into existing distro or machine
309configurations. You can see the list of features for which this is done
310by finding the
311```DISTRO_FEATURES_BACKFILL`` <#var-DISTRO_FEATURES_BACKFILL>`__ and
312```MACHINE_FEATURES_BACKFILL`` <#var-MACHINE_FEATURES_BACKFILL>`__
313variables in the ``meta/conf/bitbake.conf`` file.
314
315Because such features are backfilled by default into all configurations
316as described in the previous paragraph, developers who wish to disable
317the new features need to be able to selectively prevent the backfilling
318from occurring. They can do this by adding the undesired feature or
319features to the
320```DISTRO_FEATURES_BACKFILL_CONSIDERED`` <#var-DISTRO_FEATURES_BACKFILL_CONSIDERED>`__
321or
322```MACHINE_FEATURES_BACKFILL_CONSIDERED`` <#var-MACHINE_FEATURES_BACKFILL_CONSIDERED>`__
323variables for distro features and machine features respectively.
324
325Here are two examples to help illustrate feature backfilling:
326
327- *The "pulseaudio" distro feature option*: Previously, PulseAudio
328 support was enabled within the Qt and GStreamer frameworks. Because
329 of this, the feature is backfilled and thus enabled for all distros
330 through the ``DISTRO_FEATURES_BACKFILL`` variable in the
331 ``meta/conf/bitbake.conf`` file. However, your distro needs to
332 disable the feature. You can disable the feature without affecting
333 other existing distro configurations that need PulseAudio support by
334 adding "pulseaudio" to ``DISTRO_FEATURES_BACKFILL_CONSIDERED`` in
335 your distro's ``.conf`` file. Adding the feature to this variable
336 when it also exists in the ``DISTRO_FEATURES_BACKFILL`` variable
337 prevents the build system from adding the feature to your
338 configuration's ``DISTRO_FEATURES``, effectively disabling the
339 feature for that particular distro.
340
341- *The "rtc" machine feature option*: Previously, real time clock (RTC)
342 support was enabled for all target devices. Because of this, the
343 feature is backfilled and thus enabled for all machines through the
344 ``MACHINE_FEATURES_BACKFILL`` variable in the
345 ``meta/conf/bitbake.conf`` file. However, your target device does not
346 have this capability. You can disable RTC support for your device
347 without affecting other machines that need RTC support by adding the
348 feature to your machine's ``MACHINE_FEATURES_BACKFILL_CONSIDERED``
349 list in the machine's ``.conf`` file. Adding the feature to this
350 variable when it also exists in the ``MACHINE_FEATURES_BACKFILL``
351 variable prevents the build system from adding the feature to your
352 configuration's ``MACHINE_FEATURES``, effectively disabling RTC
353 support for that particular machine.