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.xml294
1 files changed, 294 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..77c31275ae
--- /dev/null
+++ b/documentation/ref-manual/ref-features.xml
@@ -0,0 +1,294 @@
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 Features provide a mechanism for working out which packages
10 should be included in the generated images.
11 Distributions can select which features they want to support through the
12 <filename><link linkend='var-DISTRO_FEATURES'>DISTRO_FEATURES</link></filename>
13 variable, which is set in the <filename>poky.conf</filename> distribution configuration file.
14 Machine features are set in the
15 <filename><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES</link></filename>
16 variable, which is set in the machine configuration file and
17 specifies the hardware features for a given machine.
18 </para>
19
20 <para>
21 These two variables combine to work out which kernel modules,
22 utilities, and other packages to include.
23 A given distribution can support a selected subset of features so some machine features might not
24 be included if the distribution itself does not support them.
25 </para>
26
27 <para>
28 One method you can use to determine which recipes are checking to see if a
29 particular feature is contained or not is to <filename>grep</filename> through
30 the metadata for the feature.
31 Here is an example that discovers the recipes whose build is potentially
32 changed based on a given feature:
33 <literallayout class='monospaced'>
34 $ cd $HOME/poky
35 $ git grep 'contains.*MACHINE_FEATURES.*&lt;feature&gt;'
36 </literallayout>
37 </para>
38
39 <para>
40 This chapter provides a reference of shipped machine and distro features
41 you can include as part of the image, a reference on image types you can
42 build, and a reference on feature backfilling.
43 </para>
44
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> ALSA support will be included (OSS compatibility
64 kernel modules will be installed if available).</para></listitem>
65 <listitem><para><emphasis>bluetooth:</emphasis> Include bluetooth support (integrated BT only)
66 </para></listitem>
67 <listitem><para><emphasis>ext2:</emphasis> Include tools for supporting for devices with internal
68 HDD/Microdrive for storing files (instead of Flash only devices)
69 </para></listitem>
70 <listitem><para><emphasis>irda:</emphasis> Include Irda support
71 </para></listitem>
72 <listitem><para><emphasis>keyboard:</emphasis> Include keyboard support (e.g. keymaps will be
73 loaded during boot).
74 </para></listitem>
75 <listitem><para><emphasis>pci:</emphasis> Include PCI bus support
76 </para></listitem>
77 <listitem><para><emphasis>pcmcia:</emphasis> Include PCMCIA/CompactFlash support
78 </para></listitem>
79 <listitem><para><emphasis>usbgadget:</emphasis> USB Gadget Device support (for USB
80 networking/serial/storage)
81 </para></listitem>
82 <listitem><para><emphasis>usbhost:</emphasis> USB Host support (allows to connect external
83 keyboard, mouse, storage, network etc)
84 </para></listitem>
85 <listitem><para><emphasis>wifi:</emphasis> WiFi support (integrated only)
86 </para></listitem>
87 <listitem><para><emphasis>cramfs:</emphasis> CramFS support
88 </para></listitem>
89 <listitem><para><emphasis>ipsec:</emphasis> IPSec support
90 </para></listitem>
91 <listitem><para><emphasis>ipv6:</emphasis> IPv6 support
92 </para></listitem>
93 <listitem><para><emphasis>nfs:</emphasis> NFS client support (for mounting NFS exports on
94 device)</para></listitem>
95 <listitem><para><emphasis>ppp:</emphasis> PPP dialup support</para></listitem>
96 <listitem><para><emphasis>smbfs:</emphasis> SMB networks client support (for mounting
97 Samba/Microsoft Windows shares on device)</para></listitem>
98 </itemizedlist>
99 </para>
100 </section>
101
102 <section id='ref-features-machine'>
103 <title>Machine</title>
104
105 <para>
106 The items below are features you can use with
107 <link linkend='var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></link>.
108 Features do not have a one-to-one correspondence to packages, and they can
109 go beyond simply controlling the installation of a package or packages.
110 Sometimes a feature can influence how certain recipes are built.
111 For example, a feature might determine whether a particular configure option
112 is specified within <filename>do_configure</filename> for a particular
113 recipe.
114 </para>
115
116 <para>
117 This feature list only represents features as shipped with the Yocto Project metadata:
118 <itemizedlist>
119 <listitem><para><emphasis>acpi:</emphasis> Hardware has ACPI (x86/x86_64 only)
120 </para></listitem>
121 <listitem><para><emphasis>alsa:</emphasis> Hardware has ALSA audio drivers
122 </para></listitem>
123 <listitem><para><emphasis>apm:</emphasis> Hardware uses APM (or APM emulation)
124 </para></listitem>
125 <listitem><para><emphasis>bluetooth:</emphasis> Hardware has integrated BT
126 </para></listitem>
127 <listitem><para><emphasis>ext2:</emphasis> Hardware HDD or Microdrive
128 </para></listitem>
129 <listitem><para><emphasis>irda:</emphasis> Hardware has Irda support
130 </para></listitem>
131 <listitem><para><emphasis>keyboard:</emphasis> Hardware has a keyboard
132 </para></listitem>
133 <listitem><para><emphasis>pci:</emphasis> Hardware has a PCI bus
134 </para></listitem>
135 <listitem><para><emphasis>pcmcia:</emphasis> Hardware has PCMCIA or CompactFlash sockets
136 </para></listitem>
137 <listitem><para><emphasis>screen:</emphasis> Hardware has a screen
138 </para></listitem>
139 <listitem><para><emphasis>serial:</emphasis> Hardware has serial support (usually RS232)
140 </para></listitem>
141 <listitem><para><emphasis>touchscreen:</emphasis> Hardware has a touchscreen
142 </para></listitem>
143 <listitem><para><emphasis>usbgadget:</emphasis> Hardware is USB gadget device capable
144 </para></listitem>
145 <listitem><para><emphasis>usbhost:</emphasis> Hardware is USB Host capable
146 </para></listitem>
147 <listitem><para><emphasis>wifi:</emphasis> Hardware has integrated WiFi
148 </para></listitem>
149 </itemizedlist>
150 </para>
151 </section>
152
153 <section id='ref-features-image'>
154 <title>Images</title>
155
156 <para>
157 The contents of images generated by the OpenEmbedded build system can be controlled by the
158 <filename><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></filename>
159 and <filename><link linkend='var-EXTRA_IMAGE_FEATURES'>EXTRA_IMAGE_FEATURES</link></filename>
160 variables that you typically configure in your image recipes.
161 Through these variables you can add several different
162 predefined packages such as development utilities or packages with debug
163 information needed to investigate application problems or profile applications.
164 </para>
165
166 <para>
167 Current list of
168 <filename>IMAGE_FEATURES</filename> contains the following:
169 <itemizedlist>
170 <listitem><para><emphasis>splash:</emphasis> Enables showing a splash screen during boot.
171 By default, this screen is provided by <filename>psplash</filename>, which does
172 allow customization.
173 If you prefer to use an alternative splash screen package, you can do so by
174 setting the <filename>SPLASH</filename> variable
175 to a different package name (or names) within the image recipe or at the distro
176 configuration level.</para></listitem>
177 <listitem><para><emphasis>ssh-server-dropbear:</emphasis> Installs the Dropbear minimal
178 SSH server.
179 </para></listitem>
180 <listitem><para><emphasis>ssh-server-openssh:</emphasis> Installs the OpenSSH SSH server,
181 which is more full-featured than Dropbear.
182 Note that if both the OpenSSH SSH server and the Dropbear minimal SSH server
183 are present in <filename>IMAGE_FEATURES</filename>, then OpenSSH will take
184 precedence and Dropbear will not be installed.</para></listitem>
185 <listitem><para><emphasis>x11:</emphasis> Installs the X server</para></listitem>
186 <listitem><para><emphasis>x11-base:</emphasis> Installs the X server with a
187 minimal environment.</para></listitem>
188 <listitem><para><emphasis>x11-sato:</emphasis> Installs the OpenedHand Sato environment.
189 </para></listitem>
190 <listitem><para><emphasis>tools-sdk:</emphasis> Installs a full SDK that runs on the device.
191 </para></listitem>
192 <listitem><para><emphasis>tools-debug:</emphasis> Installs debugging tools such as
193 <filename>strace</filename> and <filename>gdb</filename>.
194 </para></listitem>
195 <listitem><para><emphasis>tools-profile:</emphasis> Installs profiling tools such as
196 <filename>oprofile</filename>, <filename>exmap</filename>, and
197 <filename>LTTng</filename>.</para></listitem>
198 <listitem><para><emphasis>tools-testapps:</emphasis> Installs device testing tools (e.g.
199 touchscreen debugging).</para></listitem>
200 <listitem><para><emphasis>nfs-server:</emphasis> Installs an NFS server.</para></listitem>
201 <listitem><para><emphasis>dev-pkgs:</emphasis> Installs development packages (headers and
202 extra library links) for all packages installed in a given image.</para></listitem>
203 <listitem><para><emphasis>staticdev-pkgs:</emphasis> Installs static development
204 packages (i.e. static libraries containing <filename>*.a</filename> files) for all
205 packages installed in a given image.</para></listitem>
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>doc-pkgs:</emphasis> Installs documentation packages for all packages
209 installed in a given image.</para></listitem>
210 </itemizedlist>
211 </para>
212 </section>
213
214 <section id='ref-features-backfill'>
215 <title>Feature Backfilling</title>
216
217 <para>
218 Sometimes it is necessary in the OpenEmbedded build system to extend
219 <link linkend='var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></link>
220 or <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>
221 to control functionality that was previously enabled and not able
222 to be disabled.
223 For these cases, we need to add an
224 additional feature item to appear in one of these variables,
225 but we do not want to force developers who have existing values
226 of the variables in their configuration to add the new feature
227 in order to retain the same overall level of functionality.
228 Thus, the OpenEmbedded build system has a mechanism to
229 automatically "backfill" these added features into existing
230 distro or machine configurations.
231 You can see the list of features for which this is done by
232 finding the
233 <link linkend='var-DISTRO_FEATURES_BACKFILL'><filename>DISTRO_FEATURES_BACKFILL</filename></link>
234 and <link linkend='var-MACHINE_FEATURES_BACKFILL'><filename>MACHINE_FEATURES_BACKFILL</filename></link>
235 variables in the <filename>meta/conf/bitbake.conf</filename> file.
236 </para>
237
238 <para>
239 Because such features are backfilled by default into all
240 configurations as described in the previous paragraph, developers
241 who wish to disable the new features need to be able to selectively
242 prevent the backfilling from occurring.
243 They can do this by adding the undesired feature or features to the
244 <link linkend='var-DISTRO_FEATURES_BACKFILL_CONSIDERED'><filename>DISTRO_FEATURES_BACKFILL_CONSIDERED</filename></link>
245 or <link linkend='var-MACHINE_FEATURES_BACKFILL_CONSIDERED'><filename>MACHINE_FEATURES_BACKFILL_CONSIDERED</filename></link>
246 variables for distro features and machine features respectively.
247 </para>
248
249 <para>
250 Here are two examples to help illustrate feature backfilling:
251 <itemizedlist>
252 <listitem><para><emphasis>The "pulseaudio" distro feature option</emphasis>:
253 Previously, PulseAudio support was enabled within the Qt and
254 GStreamer frameworks.
255 Because of this, the feature is backfilled and thus
256 enabled for all distros through the
257 <filename>DISTRO_FEATURES_BACKFILL</filename>
258 variable in the <filename>meta/conf/bitbake.conf</filename> file.
259 However, your distro needs to disable the feature.
260 You can disable the feature without affecting
261 other existing distro configurations that need PulseAudio support
262 by adding "pulseaudio" to
263 <filename>DISTRO_FEATURES_BACKFILL_CONSIDERED</filename>
264 in your distro's <filename>.conf</filename> file.
265 Adding the feature to this variable when it also
266 exists in the <filename>DISTRO_FEATURES_BACKFILL</filename>
267 variable prevents the build system from adding the feature to
268 your configuration's <filename>DISTRO_FEATURES</filename>, effectively disabling
269 the feature for that particular distro.</para></listitem>
270 <listitem><para><emphasis>The "rtc" machine feature option</emphasis>:
271 Previously, real time clock (RTC) support was enabled for all
272 target devices.
273 Because of this, the feature is backfilled and thus enabled
274 for all machines through the <filename>MACHINE_FEATURES_BACKFILL</filename>
275 variable in the <filename>meta/conf/bitbake.conf</filename> file.
276 However, your target device does not have this capability.
277 You can disable RTC support for your device without
278 affecting other machines that need RTC support
279 by adding the feature to your machine's
280 <filename>MACHINE_FEATURES_BACKFILL_CONSIDERED</filename>
281 list in the machine's <filename>.conf</filename> file.
282 Adding the feature to this variable when it also
283 exists in the <filename>MACHINE_FEATURES_BACKFILL</filename>
284 variable prevents the build system from adding the feature to
285 your configuration's <filename>MACHINE_FEATURES</filename>, effectively
286 disabling RTC support for that particular machine.</para></listitem>
287 </itemizedlist>
288 </para>
289 </section>
290</chapter>
291
292<!--
293vim: expandtab tw=80 ts=4 spell spelllang=en_gb
294-->
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-11-10 20:47:45 +0000