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