483 lines
27 KiB
XML
483 lines
27 KiB
XML
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
|
|
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
|
|
[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
|
|
|
|
<chapter id='ref-features'>
|
|
<title>Features</title>
|
|
|
|
<para>
|
|
This chapter provides a reference of shipped machine and distro features
|
|
you can include as part of your image, a reference on image features you can
|
|
select, and a reference on feature backfilling.
|
|
</para>
|
|
|
|
<para>
|
|
Features provide a mechanism for working out which packages
|
|
should be included in the generated images.
|
|
Distributions can select which features they want to support through the
|
|
<filename><link linkend='var-DISTRO_FEATURES'>DISTRO_FEATURES</link></filename>
|
|
variable, which is set or appended to in a distribution's configuration file such as
|
|
<filename>poky.conf</filename>,
|
|
<filename>poky-tiny.conf</filename>,
|
|
<filename>poky-lsb.conf</filename> and so forth.
|
|
Machine features are set in the
|
|
<filename><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES</link></filename>
|
|
variable, which is set in the machine configuration file and
|
|
specifies the hardware features for a given machine.
|
|
</para>
|
|
|
|
<para>
|
|
These two variables combine to work out which kernel modules,
|
|
utilities, and other packages to include.
|
|
A given distribution can support a selected subset of features so some machine features might not
|
|
be included if the distribution itself does not support them.
|
|
</para>
|
|
|
|
<para>
|
|
One method you can use to determine which recipes are checking to see if a
|
|
particular feature is contained or not is to <filename>grep</filename> through
|
|
the <link linkend='metadata'>Metadata</link>
|
|
for the feature.
|
|
Here is an example that discovers the recipes whose build is potentially
|
|
changed based on a given feature:
|
|
<literallayout class='monospaced'>
|
|
$ cd poky
|
|
$ git grep 'contains.*MACHINE_FEATURES.*<replaceable>feature</replaceable>'
|
|
</literallayout>
|
|
</para>
|
|
|
|
<section id='ref-features-machine'>
|
|
<title>Machine Features</title>
|
|
|
|
<para>
|
|
The items below are features you can use with
|
|
<link linkend='var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></link>.
|
|
Features do not have a one-to-one correspondence to packages, and they can
|
|
go beyond simply controlling the installation of a package or packages.
|
|
Sometimes a feature can influence how certain recipes are built.
|
|
For example, a feature might determine whether a particular configure option
|
|
is specified within the
|
|
<link linkend='ref-tasks-configure'><filename>do_configure</filename></link>
|
|
task for a particular recipe.
|
|
</para>
|
|
|
|
<para>
|
|
This feature list only represents features as shipped with the Yocto Project metadata:
|
|
<itemizedlist>
|
|
<listitem><para><emphasis>acpi:</emphasis> Hardware has ACPI (x86/x86_64 only)
|
|
</para></listitem>
|
|
<listitem><para><emphasis>alsa:</emphasis> Hardware has ALSA audio drivers
|
|
</para></listitem>
|
|
<listitem><para><emphasis>apm:</emphasis> Hardware uses APM (or APM emulation)
|
|
</para></listitem>
|
|
<listitem><para><emphasis>bluetooth:</emphasis> Hardware has integrated BT
|
|
</para></listitem>
|
|
<listitem><para><emphasis>efi:</emphasis> Support for booting through EFI
|
|
</para></listitem>
|
|
<listitem><para><emphasis>ext2:</emphasis> Hardware HDD or Microdrive
|
|
</para></listitem>
|
|
<listitem><para><emphasis>irda:</emphasis> Hardware has IrDA support
|
|
</para></listitem>
|
|
<listitem><para><emphasis>keyboard:</emphasis> Hardware has a keyboard
|
|
</para></listitem>
|
|
<listitem><para><emphasis>pcbios:</emphasis> Support for booting through BIOS
|
|
</para></listitem>
|
|
<listitem><para><emphasis>pci:</emphasis> Hardware has a PCI bus
|
|
</para></listitem>
|
|
<listitem><para><emphasis>pcmcia:</emphasis> Hardware has PCMCIA or CompactFlash sockets
|
|
</para></listitem>
|
|
<listitem><para><emphasis>phone:</emphasis> Mobile phone (voice) support
|
|
</para></listitem>
|
|
<listitem><para><emphasis>qvga:</emphasis> Machine has a QVGA (320x240) display
|
|
</para></listitem>
|
|
<listitem><para><emphasis>rtc:</emphasis> Machine has a Real-Time Clock
|
|
</para></listitem>
|
|
<listitem><para><emphasis>screen:</emphasis> Hardware has a screen
|
|
</para></listitem>
|
|
<listitem><para><emphasis>serial:</emphasis> Hardware has serial support (usually RS232)
|
|
</para></listitem>
|
|
<listitem><para><emphasis>touchscreen:</emphasis> Hardware has a touchscreen
|
|
</para></listitem>
|
|
<listitem><para><emphasis>usbgadget:</emphasis> Hardware is USB gadget device capable
|
|
</para></listitem>
|
|
<listitem><para><emphasis>usbhost:</emphasis> Hardware is USB Host capable
|
|
</para></listitem>
|
|
<listitem><para><emphasis>vfat:</emphasis> FAT file system support
|
|
</para></listitem>
|
|
<listitem><para><emphasis>wifi:</emphasis> Hardware has integrated WiFi
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</section>
|
|
|
|
<section id='ref-features-distro'>
|
|
<title>Distro Features</title>
|
|
|
|
<para>
|
|
The items below are features you can use with
|
|
<link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>
|
|
to enable features across your distribution.
|
|
Features do not have a one-to-one correspondence to packages,
|
|
and they can go beyond simply controlling the installation of a
|
|
package or packages.
|
|
In most cases, the presence or absence of a feature translates to
|
|
the appropriate option supplied to the configure script during the
|
|
<link linkend='ref-tasks-configure'><filename>do_configure</filename></link>
|
|
task for the recipes that optionally
|
|
support the feature.
|
|
</para>
|
|
|
|
<para>
|
|
Some distro features are also machine features.
|
|
These select features make sense to be controlled both at
|
|
the machine and distribution configuration level.
|
|
See the
|
|
<link linkend='var-COMBINED_FEATURES'><filename>COMBINED_FEATURES</filename></link>
|
|
variable for more information.
|
|
</para>
|
|
|
|
<para>
|
|
This list only represents features as shipped with the Yocto Project metadata:
|
|
<itemizedlist>
|
|
<listitem><para><emphasis>alsa:</emphasis> Include ALSA support
|
|
(OSS compatibility kernel modules installed if available).
|
|
</para></listitem>
|
|
<listitem><para><emphasis>api-documentation:</emphasis>
|
|
Enables generation of API documentation during recipe
|
|
builds.
|
|
The resulting documentation is added to SDK tarballs
|
|
when the
|
|
<filename>bitbake -c populate_sdk</filename> command
|
|
is used.
|
|
See the
|
|
"<ulink url='&YOCTO_DOCS_SDK_URL;#adding-api-documentation-to-the-standard-sdk'>Adding API Documentation to the Standard SDK</ulink>"
|
|
section in the Yocto Project Application Development and
|
|
the Extensible Software Development Kit (eSDK) manual.
|
|
</para></listitem>
|
|
<listitem><para><emphasis>bluetooth:</emphasis> Include
|
|
bluetooth support (integrated BT only).</para></listitem>
|
|
<listitem><para><emphasis>bluez5:</emphasis> Include
|
|
BlueZ Version 5, which provides core Bluetooth layers and
|
|
protocols support.
|
|
<note>
|
|
The default value for the
|
|
<link linkend='var-DISTRO_FEATURES'><filename>DISTRO FEATURES</filename></link>
|
|
variable includes "bluetooth", which causes bluez5
|
|
to be backfilled in for bluetooth support.
|
|
If you do not want bluez5 backfilled and would rather
|
|
use bluez4, you need to use the
|
|
<link linkend='var-DISTRO_FEATURES_BACKFILL_CONSIDERED'><filename>DISTRO_FEATURES_BACKFILL_CONSIDERED</filename></link>
|
|
variable as follows:
|
|
<literallayout class='monospaced'>
|
|
DISTRO_FEATURES_BACKFILL_CONSIDERED = "bluez5"
|
|
</literallayout>
|
|
Setting this variable tells the OpenEmbedded build
|
|
system that you have considered but ruled
|
|
out using the bluez5 feature and that bluez4 will be
|
|
used.
|
|
</note>
|
|
</para></listitem>
|
|
<listitem><para><emphasis>cramfs:</emphasis> Include CramFS
|
|
support.</para></listitem>
|
|
<listitem><para><emphasis>directfb:</emphasis>
|
|
Include DirectFB support.
|
|
</para></listitem>
|
|
<listitem><para><emphasis>ext2:</emphasis> Include tools for
|
|
supporting for devices with internal HDD/Microdrive for
|
|
storing files (instead of Flash only devices).
|
|
</para></listitem>
|
|
<listitem><para><emphasis>ipsec:</emphasis> Include IPSec
|
|
support.</para></listitem>
|
|
<listitem><para><emphasis>ipv6:</emphasis> Include IPv6 support.
|
|
</para></listitem>
|
|
<listitem><para><emphasis>irda:</emphasis> Include IrDA support.
|
|
</para></listitem>
|
|
<listitem><para><emphasis>keyboard:</emphasis> Include keyboard
|
|
support (e.g. keymaps will be loaded during boot).
|
|
</para></listitem>
|
|
<listitem><para><emphasis>ldconfig:</emphasis>
|
|
Include support for ldconfig and
|
|
<filename>ld.so.conf</filename> on the target.
|
|
</para></listitem>
|
|
<listitem><para><emphasis>nfs:</emphasis> Include NFS client
|
|
support (for mounting NFS exports on device).
|
|
</para></listitem>
|
|
<listitem><para><emphasis>opengl:</emphasis>
|
|
Include the Open Graphics Library, which is a
|
|
cross-language, multi-platform application programming
|
|
interface used for rendering two and three-dimensional
|
|
graphics.</para></listitem>
|
|
<listitem><para><emphasis>pci:</emphasis> Include PCI bus
|
|
support.</para></listitem>
|
|
<listitem><para><emphasis>pcmcia:</emphasis> Include
|
|
PCMCIA/CompactFlash support.</para></listitem>
|
|
<listitem><para><emphasis>ppp:</emphasis> Include PPP dialup
|
|
support.</para></listitem>
|
|
<listitem><para><emphasis>ptest:</emphasis> Enables building
|
|
the package tests where supported by individual recipes.
|
|
For more information on package tests, see the
|
|
"<ulink url='&YOCTO_DOCS_DEV_URL;#testing-packages-with-ptest'>Testing Packages With ptest</ulink>"
|
|
section in the Yocto Project Development Tasks Manual.
|
|
</para></listitem>
|
|
<listitem><para><emphasis>smbfs:</emphasis> Include SMB networks
|
|
client support (for mounting Samba/Microsoft Windows shares
|
|
on device).</para></listitem>
|
|
<listitem><para><emphasis>systemd:</emphasis> Include support
|
|
for this <filename>init</filename> manager, which is a full
|
|
replacement of for <filename>init</filename> with parallel
|
|
starting of services, reduced shell overhead, and other
|
|
features.
|
|
This <filename>init</filename> manager is used by many
|
|
distributions.</para></listitem>
|
|
<listitem><para><emphasis>usbgadget:</emphasis> Include USB
|
|
Gadget Device support (for USB networking/serial/storage).
|
|
</para></listitem>
|
|
<listitem><para><emphasis>usbhost:</emphasis> Include USB Host
|
|
support (allows to connect external keyboard, mouse,
|
|
storage, network etc).</para></listitem>
|
|
<listitem><para><emphasis>wayland:</emphasis> Include the
|
|
Wayland display server protocol and the library that
|
|
supports it.</para></listitem>
|
|
<listitem><para><emphasis>wifi:</emphasis> Include WiFi support
|
|
(integrated only).</para></listitem>
|
|
<listitem><para><emphasis>x11:</emphasis> Include the X server
|
|
and libraries.</para></listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</section>
|
|
|
|
<section id='ref-features-image'>
|
|
<title>Image Features</title>
|
|
|
|
<para>
|
|
The contents of images generated by the OpenEmbedded build system
|
|
can be controlled by the
|
|
<link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>
|
|
and
|
|
<link linkend='var-EXTRA_IMAGE_FEATURES'><filename>EXTRA_IMAGE_FEATURES</filename></link>
|
|
variables that you typically configure in your image recipes.
|
|
Through these variables, you can add several different
|
|
predefined packages such as development utilities or packages with
|
|
debug information needed to investigate application problems or
|
|
profile applications.
|
|
</para>
|
|
|
|
<para>
|
|
The following image features are available for all images:
|
|
<itemizedlist>
|
|
<listitem><para><emphasis>allow-empty-password:</emphasis>
|
|
Allows Dropbear and OpenSSH to accept root logins
|
|
and logins from accounts having an empty password string.
|
|
</para></listitem>
|
|
<listitem><para><emphasis>dbg-pkgs:</emphasis>
|
|
Installs debug symbol packages for all packages installed
|
|
in a given image.
|
|
</para></listitem>
|
|
<listitem><para><emphasis>debug-tweaks:</emphasis>
|
|
Makes an image suitable for development (e.g.
|
|
allows root logins without passwords and enables
|
|
post-installation logging).
|
|
See the 'allow-empty-password', 'empty-root-password',
|
|
and 'post-install-logging' features in this list for
|
|
additional information.
|
|
</para></listitem>
|
|
<listitem><para><emphasis>dev-pkgs:</emphasis>
|
|
Installs development packages (headers and extra library
|
|
links) for all packages installed in a given image.
|
|
</para></listitem>
|
|
<listitem><para><emphasis>doc-pkgs:</emphasis> Installs
|
|
documentation packages for all packages installed in a
|
|
given image.
|
|
</para></listitem>
|
|
<listitem><para><emphasis>empty-root-password:</emphasis>
|
|
Sets the root password to an empty string, which allows
|
|
logins with a blank password.
|
|
</para></listitem>
|
|
<listitem><para><emphasis>package-management:</emphasis>
|
|
Installs package management tools and preserves the package
|
|
manager database.
|
|
</para></listitem>
|
|
<listitem><para><emphasis>post-install-logging:</emphasis>
|
|
Enables logging postinstall script runs to
|
|
the <filename>/var/log/postinstall.log</filename> file
|
|
on first boot of the image on the target system.
|
|
<note>
|
|
To make the <filename>/var/log</filename> directory
|
|
on the target persistent, use the
|
|
<link linkend='var-VOLATILE_LOG_DIR'><filename>VOLATILE_LOG_DIR</filename></link>
|
|
variable by setting it to "no".
|
|
</note>
|
|
</para></listitem>
|
|
<listitem><para><emphasis>ptest-pkgs:</emphasis>
|
|
Installs ptest packages for all ptest-enabled recipes.
|
|
</para></listitem>
|
|
<listitem><para><emphasis>read-only-rootfs:</emphasis>
|
|
Creates an image whose root filesystem is read-only.
|
|
See the
|
|
"<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-read-only-root-filesystem'>Creating a Read-Only Root Filesystem</ulink>"
|
|
section in the Yocto Project Development Tasks Manual for
|
|
more information.
|
|
</para></listitem>
|
|
<listitem><para><emphasis>splash:</emphasis>
|
|
Enables showing a splash screen during boot.
|
|
By default, this screen is provided by
|
|
<filename>psplash</filename>, which does allow
|
|
customization.
|
|
If you prefer to use an alternative splash screen package,
|
|
you can do so by setting the <filename>SPLASH</filename>
|
|
variable to a different package name (or names) within the
|
|
image recipe or at the distro configuration level.
|
|
</para></listitem>
|
|
<listitem><para><emphasis>staticdev-pkgs:</emphasis>
|
|
Installs static development packages, which are
|
|
static libraries (i.e. <filename>*.a</filename> files), for
|
|
all packages installed in a given image.
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
|
|
<para>
|
|
Some image features are available only when you inherit the
|
|
<link linkend='ref-classes-core-image'><filename>core-image</filename></link>
|
|
class.
|
|
The current list of these valid features is as follows:
|
|
<itemizedlist>
|
|
<listitem><para><emphasis>eclipse-debug:</emphasis> Provides
|
|
Eclipse remote debugging support.
|
|
</para></listitem>
|
|
<listitem><para><emphasis>hwcodecs:</emphasis> Installs
|
|
hardware acceleration codecs.
|
|
</para></listitem>
|
|
<listitem><para><emphasis>nfs-server:</emphasis>
|
|
Installs an NFS server.
|
|
</para></listitem>
|
|
<listitem><para><emphasis>perf:</emphasis>
|
|
Installs profiling tools such as
|
|
<filename>perf</filename>, <filename>systemtap</filename>,
|
|
and <filename>LTTng</filename>.
|
|
For general information on user-space tools, see the
|
|
<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-manual'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink>
|
|
manual.
|
|
</para></listitem>
|
|
<listitem><para><emphasis>ssh-server-dropbear:</emphasis>
|
|
Installs the Dropbear minimal SSH server.
|
|
</para></listitem>
|
|
<listitem><para><emphasis>ssh-server-openssh:</emphasis>
|
|
Installs the OpenSSH SSH server, which is more
|
|
full-featured than Dropbear.
|
|
Note that if both the OpenSSH SSH server and the Dropbear
|
|
minimal SSH server are present in
|
|
<filename>IMAGE_FEATURES</filename>, then OpenSSH will take
|
|
precedence and Dropbear will not be installed.
|
|
</para></listitem>
|
|
<listitem><para><emphasis>tools-debug:</emphasis>
|
|
Installs debugging tools such as
|
|
<filename>strace</filename> and <filename>gdb</filename>.
|
|
For information on GDB, see the
|
|
"<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-gdb-remotedebug'>Debugging With the GNU Project Debugger (GDB) Remotely</ulink>"
|
|
section in the Yocto Project Development Tasks Manual.
|
|
For information on tracing and profiling, see the
|
|
<ulink url='&YOCTO_DOCS_PROF_URL;'>Yocto Project Profiling and Tracing Manual</ulink>.
|
|
</para></listitem>
|
|
<listitem><para><emphasis>tools-sdk:</emphasis>
|
|
Installs a full SDK that runs on the device.
|
|
</para></listitem>
|
|
<listitem><para><emphasis>tools-testapps:</emphasis>
|
|
Installs device testing tools (e.g. touchscreen debugging).
|
|
</para></listitem>
|
|
<listitem><para><emphasis>x11:</emphasis>
|
|
Installs the X server.
|
|
</para></listitem>
|
|
<listitem><para><emphasis>x11-base:</emphasis>
|
|
Installs the X server with a minimal environment.
|
|
</para></listitem>
|
|
<listitem><para><emphasis>x11-sato:</emphasis>
|
|
Installs the OpenedHand Sato environment.
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
|
|
</section>
|
|
|
|
<section id='ref-features-backfill'>
|
|
<title>Feature Backfilling</title>
|
|
|
|
<para>
|
|
Sometimes it is necessary in the OpenEmbedded build system to extend
|
|
<link linkend='var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></link>
|
|
or <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>
|
|
to control functionality that was previously enabled and not able
|
|
to be disabled.
|
|
For these cases, we need to add an
|
|
additional feature item to appear in one of these variables,
|
|
but we do not want to force developers who have existing values
|
|
of the variables in their configuration to add the new feature
|
|
in order to retain the same overall level of functionality.
|
|
Thus, the OpenEmbedded build system has a mechanism to
|
|
automatically "backfill" these added features into existing
|
|
distro or machine configurations.
|
|
You can see the list of features for which this is done by
|
|
finding the
|
|
<link linkend='var-DISTRO_FEATURES_BACKFILL'><filename>DISTRO_FEATURES_BACKFILL</filename></link>
|
|
and <link linkend='var-MACHINE_FEATURES_BACKFILL'><filename>MACHINE_FEATURES_BACKFILL</filename></link>
|
|
variables in the <filename>meta/conf/bitbake.conf</filename> file.
|
|
</para>
|
|
|
|
<para>
|
|
Because such features are backfilled by default into all
|
|
configurations as described in the previous paragraph, developers
|
|
who wish to disable the new features need to be able to selectively
|
|
prevent the backfilling from occurring.
|
|
They can do this by adding the undesired feature or features to the
|
|
<link linkend='var-DISTRO_FEATURES_BACKFILL_CONSIDERED'><filename>DISTRO_FEATURES_BACKFILL_CONSIDERED</filename></link>
|
|
or <link linkend='var-MACHINE_FEATURES_BACKFILL_CONSIDERED'><filename>MACHINE_FEATURES_BACKFILL_CONSIDERED</filename></link>
|
|
variables for distro features and machine features respectively.
|
|
</para>
|
|
|
|
<para>
|
|
Here are two examples to help illustrate feature backfilling:
|
|
<itemizedlist>
|
|
<listitem><para><emphasis>The "pulseaudio" distro feature option</emphasis>:
|
|
Previously, PulseAudio support was enabled within the Qt and
|
|
GStreamer frameworks.
|
|
Because of this, the feature is backfilled and thus
|
|
enabled for all distros through the
|
|
<filename>DISTRO_FEATURES_BACKFILL</filename>
|
|
variable in the <filename>meta/conf/bitbake.conf</filename> file.
|
|
However, your distro needs to disable the feature.
|
|
You can disable the feature without affecting
|
|
other existing distro configurations that need PulseAudio support
|
|
by adding "pulseaudio" to
|
|
<filename>DISTRO_FEATURES_BACKFILL_CONSIDERED</filename>
|
|
in your distro's <filename>.conf</filename> file.
|
|
Adding the feature to this variable when it also
|
|
exists in the <filename>DISTRO_FEATURES_BACKFILL</filename>
|
|
variable prevents the build system from adding the feature to
|
|
your configuration's <filename>DISTRO_FEATURES</filename>, effectively disabling
|
|
the feature for that particular distro.</para></listitem>
|
|
<listitem><para><emphasis>The "rtc" machine feature option</emphasis>:
|
|
Previously, real time clock (RTC) support was enabled for all
|
|
target devices.
|
|
Because of this, the feature is backfilled and thus enabled
|
|
for all machines through the <filename>MACHINE_FEATURES_BACKFILL</filename>
|
|
variable in the <filename>meta/conf/bitbake.conf</filename> file.
|
|
However, your target device does not have this capability.
|
|
You can disable RTC support for your device without
|
|
affecting other machines that need RTC support
|
|
by adding the feature to your machine's
|
|
<filename>MACHINE_FEATURES_BACKFILL_CONSIDERED</filename>
|
|
list in the machine's <filename>.conf</filename> file.
|
|
Adding the feature to this variable when it also
|
|
exists in the <filename>MACHINE_FEATURES_BACKFILL</filename>
|
|
variable prevents the build system from adding the feature to
|
|
your configuration's <filename>MACHINE_FEATURES</filename>, effectively
|
|
disabling RTC support for that particular machine.</para></listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</section>
|
|
</chapter>
|
|
|
|
<!--
|
|
vim: expandtab tw=80 ts=4 spell spelllang=en_gb
|
|
-->
|