diff options
Diffstat (limited to 'import-layers/yocto-poky/documentation/ref-manual/ref-features.xml')
| -rw-r--r-- | import-layers/yocto-poky/documentation/ref-manual/ref-features.xml | 438 |
1 files changed, 438 insertions, 0 deletions
diff --git a/import-layers/yocto-poky/documentation/ref-manual/ref-features.xml b/import-layers/yocto-poky/documentation/ref-manual/ref-features.xml new file mode 100644 index 000000000..fd7693500 --- /dev/null +++ b/import-layers/yocto-poky/documentation/ref-manual/ref-features.xml @@ -0,0 +1,438 @@ +<!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 <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink> + 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 + <ulink url='&YOCTO_DOCS_REF_URL;#var-COMBINED_FEATURES'><filename>COMBINED_FEATURES</filename></ulink> + 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>bluetooth:</emphasis> Include + bluetooth support (integrated BT only).</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>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 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. + </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 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 Software Development Kit (SDK) Developer's Guide</ulink>. + </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 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 +--> |
