diff options
Diffstat (limited to 'documentation/ref-manual/ref-features.rst')
-rw-r--r-- | documentation/ref-manual/ref-features.rst | 353 |
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 | ******** | ||
2 | Features | ||
3 | ******** | ||
4 | |||
5 | This chapter provides a reference of shipped machine and distro features | ||
6 | you can include as part of your image, a reference on image features you | ||
7 | can select, and a reference on feature backfilling. | ||
8 | |||
9 | Features provide a mechanism for working out which packages should be | ||
10 | included in the generated images. Distributions can select which | ||
11 | features they want to support through the ``DISTRO_FEATURES`` variable, | ||
12 | which is set or appended to in a distribution's configuration file such | ||
13 | as ``poky.conf``, ``poky-tiny.conf``, ``poky-lsb.conf`` and so forth. | ||
14 | Machine features are set in the ``MACHINE_FEATURES`` variable, which is | ||
15 | set in the machine configuration file and specifies the hardware | ||
16 | features for a given machine. | ||
17 | |||
18 | These two variables combine to work out which kernel modules, utilities, | ||
19 | and other packages to include. A given distribution can support a | ||
20 | selected subset of features so some machine features might not be | ||
21 | included if the distribution itself does not support them. | ||
22 | |||
23 | One method you can use to determine which recipes are checking to see if | ||
24 | a particular feature is contained or not is to ``grep`` through the | ||
25 | `Metadata <#metadata>`__ for the feature. Here is an example that | ||
26 | discovers the recipes whose build is potentially changed based on a | ||
27 | given feature: $ cd poky $ git grep | ||
28 | 'contains.*MACHINE_FEATURES.*feature' | ||
29 | |||
30 | .. _ref-features-machine: | ||
31 | |||
32 | Machine Features | ||
33 | ================ | ||
34 | |||
35 | The items below are features you can use with | ||
36 | ```MACHINE_FEATURES`` <#var-MACHINE_FEATURES>`__. Features do not have a | ||
37 | one-to-one correspondence to packages, and they can go beyond simply | ||
38 | controlling the installation of a package or packages. Sometimes a | ||
39 | feature can influence how certain recipes are built. For example, a | ||
40 | feature might determine whether a particular configure option is | ||
41 | specified within the ```do_configure`` <#ref-tasks-configure>`__ task | ||
42 | for a particular recipe. | ||
43 | |||
44 | This feature list only represents features as shipped with the Yocto | ||
45 | Project 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 | |||
89 | Distro Features | ||
90 | =============== | ||
91 | |||
92 | The items below are features you can use with | ||
93 | ```DISTRO_FEATURES`` <#var-DISTRO_FEATURES>`__ to enable features across | ||
94 | your distribution. Features do not have a one-to-one correspondence to | ||
95 | packages, and they can go beyond simply controlling the installation of | ||
96 | a package or packages. In most cases, the presence or absence of a | ||
97 | feature translates to the appropriate option supplied to the configure | ||
98 | script during the ```do_configure`` <#ref-tasks-configure>`__ task for | ||
99 | the recipes that optionally support the feature. | ||
100 | |||
101 | Some distro features are also machine features. These select features | ||
102 | make sense to be controlled both at the machine and distribution | ||
103 | configuration level. See the | ||
104 | ```COMBINED_FEATURES`` <#var-COMBINED_FEATURES>`__ variable for more | ||
105 | information. | ||
106 | |||
107 | This list only represents features as shipped with the Yocto Project | ||
108 | metadata: | ||
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 | |||
186 | Image Features | ||
187 | ============== | ||
188 | |||
189 | The contents of images generated by the OpenEmbedded build system can be | ||
190 | controlled by the ```IMAGE_FEATURES`` <#var-IMAGE_FEATURES>`__ and | ||
191 | ```EXTRA_IMAGE_FEATURES`` <#var-EXTRA_IMAGE_FEATURES>`__ variables that | ||
192 | you typically configure in your image recipes. Through these variables, | ||
193 | you can add several different predefined packages such as development | ||
194 | utilities or packages with debug information needed to investigate | ||
195 | application problems or profile applications. | ||
196 | |||
197 | The 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 | |||
254 | Some image features are available only when you inherit the | ||
255 | ```core-image`` <#ref-classes-core-image>`__ class. The current list of | ||
256 | these 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 | |||
296 | Feature Backfilling | ||
297 | =================== | ||
298 | |||
299 | Sometimes 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 | ||
302 | that was previously enabled and not able to be disabled. For these | ||
303 | cases, we need to add an additional feature item to appear in one of | ||
304 | these variables, but we do not want to force developers who have | ||
305 | existing values of the variables in their configuration to add the new | ||
306 | feature in order to retain the same overall level of functionality. | ||
307 | Thus, the OpenEmbedded build system has a mechanism to automatically | ||
308 | "backfill" these added features into existing distro or machine | ||
309 | configurations. You can see the list of features for which this is done | ||
310 | by finding the | ||
311 | ```DISTRO_FEATURES_BACKFILL`` <#var-DISTRO_FEATURES_BACKFILL>`__ and | ||
312 | ```MACHINE_FEATURES_BACKFILL`` <#var-MACHINE_FEATURES_BACKFILL>`__ | ||
313 | variables in the ``meta/conf/bitbake.conf`` file. | ||
314 | |||
315 | Because such features are backfilled by default into all configurations | ||
316 | as described in the previous paragraph, developers who wish to disable | ||
317 | the new features need to be able to selectively prevent the backfilling | ||
318 | from occurring. They can do this by adding the undesired feature or | ||
319 | features to the | ||
320 | ```DISTRO_FEATURES_BACKFILL_CONSIDERED`` <#var-DISTRO_FEATURES_BACKFILL_CONSIDERED>`__ | ||
321 | or | ||
322 | ```MACHINE_FEATURES_BACKFILL_CONSIDERED`` <#var-MACHINE_FEATURES_BACKFILL_CONSIDERED>`__ | ||
323 | variables for distro features and machine features respectively. | ||
324 | |||
325 | Here 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. | ||