mirror of
https://git.yoctoproject.org/poky
synced 2026-02-20 08:29:42 +01:00
88924d6dea
Document DISTRO_FEATURES_BACKFILL and MACHINE_FEATURES_BACKFILL. We may wish to expand upon this in future, but at least this explains what these variables are for and how to use them. Also add a link from the DISTRO_FEATURES entry to the section that lists valid DISTRO_FEATURES items. (From yocto-docs rev: 018af5c28b44464ae66646780ade910bdcab2bef) Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
234 lines
14 KiB
XML
234 lines
14 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>Reference: Features</title>
|
|
|
|
<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 in the <filename>poky.conf</filename> distribution configuration file.
|
|
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>
|
|
|
|
<section id='ref-features-distro'>
|
|
<title>Distro</title>
|
|
|
|
<para>
|
|
The items below are valid options for
|
|
<filename><link linkend='var-DISTRO_FEATURES'>DISTRO_FEATURES</link></filename>:
|
|
<itemizedlist>
|
|
<listitem><para><emphasis>alsa:</emphasis> ALSA support will be included (OSS compatibility
|
|
kernel modules will be installed if available).</para></listitem>
|
|
<listitem><para><emphasis>bluetooth:</emphasis> Include bluetooth support (integrated BT only)
|
|
</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>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>pci:</emphasis> Include PCI bus support
|
|
</para></listitem>
|
|
<listitem><para><emphasis>pcmcia:</emphasis> Include PCMCIA/CompactFlash support
|
|
</para></listitem>
|
|
<listitem><para><emphasis>usbgadget:</emphasis> USB Gadget Device support (for USB
|
|
networking/serial/storage)
|
|
</para></listitem>
|
|
<listitem><para><emphasis>usbhost:</emphasis> USB Host support (allows to connect external
|
|
keyboard, mouse, storage, network etc)
|
|
</para></listitem>
|
|
<listitem><para><emphasis>wifi:</emphasis> WiFi support (integrated only)
|
|
</para></listitem>
|
|
<listitem><para><emphasis>cramfs:</emphasis> CramFS support
|
|
</para></listitem>
|
|
<listitem><para><emphasis>ipsec:</emphasis> IPSec support
|
|
</para></listitem>
|
|
<listitem><para><emphasis>ipv6:</emphasis> IPv6 support
|
|
</para></listitem>
|
|
<listitem><para><emphasis>nfs:</emphasis> NFS client support (for mounting NFS exports on
|
|
device)</para></listitem>
|
|
<listitem><para><emphasis>ppp:</emphasis> PPP dialup support</para></listitem>
|
|
<listitem><para><emphasis>smbfs:</emphasis> SMB networks client support (for mounting
|
|
Samba/Microsoft Windows shares on device)</para></listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</section>
|
|
|
|
<section id='ref-features-machine'>
|
|
<title>Machine</title>
|
|
|
|
<para>
|
|
The items below are valid options for
|
|
<filename><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES</link></filename>:
|
|
<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>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>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>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>wifi:</emphasis> Hardware has integrated WiFi
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</section>
|
|
|
|
<section id='ref-features-image'>
|
|
<title>Images</title>
|
|
|
|
<para>
|
|
The contents of images generated by the OpenEmbedded build system can be controlled by the
|
|
<filename><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></filename>
|
|
and <filename><link linkend='var-EXTRA_IMAGE_FEATURES'>EXTRA_IMAGE_FEATURES</link></filename>
|
|
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>
|
|
Current list of
|
|
<filename>IMAGE_FEATURES</filename> contains the following:
|
|
<itemizedlist>
|
|
<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>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>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>
|
|
<listitem><para><emphasis>tools-sdk:</emphasis> Installs a full SDK that runs on the device.
|
|
</para></listitem>
|
|
<listitem><para><emphasis>tools-debug:</emphasis> Installs debugging tools such as
|
|
<filename>strace</filename> and <filename>gdb</filename>.
|
|
</para></listitem>
|
|
<listitem><para><emphasis>tools-profile:</emphasis> Installs profiling tools such as
|
|
<filename>oprofile</filename>, <filename>exmap</filename>, and
|
|
<filename>LTTng</filename>.</para></listitem>
|
|
<listitem><para><emphasis>tools-testapps:</emphasis> Installs device testing tools (e.g.
|
|
touchscreen debugging).</para></listitem>
|
|
<listitem><para><emphasis>nfs-server:</emphasis> Installs an NFS server.</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>staticdev-pkgs:</emphasis> Installs static development
|
|
packages (i.e. static libraries containing <filename>*.a</filename> files) for all
|
|
packages installed in a given image.</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>doc-pkgs:</emphasis> Installs documentation packages for all packages
|
|
installed in a given image.</para></listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</section>
|
|
|
|
<section id='ref-features-backfill'>
|
|
<title>Feature Backfilling</title>
|
|
|
|
<para>
|
|
Sometimes, it is necessary for a new feature to be added to control existing
|
|
functionality that was previously enabled by default and not able to be disabled.
|
|
In order to ensure that the feature remains enabled for users with existing
|
|
configurations that upgrade to a new version of the core metadata without that
|
|
configuration having to be changed, while still allowing others who want to turn
|
|
the feature off to do so, the backfilling mechanism was introduced.
|
|
This
|
|
functionality is available for <filename><link linkend='var-DISTRO_FEATURES'>DISTRO_FEATURES</link></filename>
|
|
and <filename><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES</link></filename>.
|
|
</para>
|
|
|
|
<para>
|
|
An example is the "pulseaudio" distro feature.
|
|
Previously, PulseAudio support
|
|
was enabled within the Qt and GStreamer frameworks.
|
|
However some users desired
|
|
to be able to disable this.
|
|
To allow this to be disabled without affecting
|
|
existing configurations in which PulseAudio support should remain enabled,
|
|
"pulseaudio" was added to
|
|
<filename><link linkend='var-DISTRO_FEATURES_BACKFILL'>DISTRO_FEATURES_BACKFILL</link></filename>
|
|
within <filename>meta/conf/bitbake.conf</filename>.
|
|
This means that "pulseaudio"
|
|
is automatically added to <filename>DISTRO_FEATURES</filename> without the distro
|
|
configuration needing to be updated to do so itself.
|
|
Those who do not want PulseAudio support can add "pulseaudio" to
|
|
<filename><link linkend='var-DISTRO_FEATURES_BACKFILL_CONSIDERED'>DISTRO_FEATURES_BACKFILL_CONSIDERED</link></filename>
|
|
in their distro <filename>.conf</filename> file and this will disable adding "pulseaudio" to
|
|
<filename>DISTRO_FEATURES</filename>.
|
|
</para>
|
|
|
|
<para>
|
|
Another example is the "rtc" machine feature.
|
|
Previously, real time clock (RTC)
|
|
support was enabled for all target devices.
|
|
However certain targets do not have
|
|
this capability.
|
|
To allow this to be disabled by such machines without affecting
|
|
other machines in which RTC support should remain enabled, "rtc" was added to
|
|
<filename><link linkend='var-MACHINE_FEATURES_BACKFILL'>MACHINE_FEATURES_BACKFILL</link></filename>
|
|
within <filename>meta/conf/bitbake.conf</filename>.
|
|
This means that "rtc"
|
|
is automatically added to <filename>MACHINE_FEATURES</filename> without the
|
|
machine configuration needing to be updated to do so itself.
|
|
For machines that not need RTC support can add "rtc" to
|
|
<filename><link linkend='var-MACHINE_FEATURES_BACKFILL_CONSIDERED'>MACHINE_FEATURES_BACKFILL_CONSIDERED</link></filename>
|
|
in their machine <filename>.conf</filename> file and this will disable adding "rtc" to
|
|
<filename>MACHINE_FEATURES</filename>.
|
|
</para>
|
|
</section>
|
|
</chapter>
|
|
|
|
<!--
|
|
vim: expandtab tw=80 ts=4 spell spelllang=en_gb
|
|
-->
|