| <!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>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 |
| <filename>DISTRO FEATURES</filename> 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>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>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;'>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 |
| --> |