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