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