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