[yocto-docs][PATCH 00/11] Documentation improvements

[yocto-docs][PATCH 00/11] Documentation improvements

[Paul Eggleton]

Add some missing variables to the variable reference and improve
the descriptions of others. Also fix references to "package" where
we mean "recipe" and a couple of other issues I noticed at the same
time.


The following changes since commit 821162221818f5ce53bb903aeef57c85314f5083:

  documentation: dev-manual - mentioned SRC_URI in the kernel example (2012-10-05 11:25:03 -0700)

are available in the git repository at:

  git://git.yoctoproject.org/poky-contrib paule/doc-fixes-5
  http://git.yoctoproject.org/cgit.cgi/poky-contrib/log/?h=paule/doc-fixes-5

Paul Eggleton (11):
  documentation: dev-manual: fix spelling
  documentation: poky-ref-manual: correct LICENSE_DIR -> LICENSE_PATH
  documentation: poky-ref-manual: improve MACHINE_* variable
    descriptions
  documentation: poky-ref-manual: extend description of MACHINE
    variable
  documentation: poky-ref-manual: add PACKAGECONFIG variable
  documentation: poky-ref-manual: extend DISTRO description
  documentation: poky-ref-manual: add information on
    *_FEATURES_BACKFILL
  documentation: poky-ref-manual: fix description of SUMMARY variable
  documentation: poky-ref-manual: remove references to ipkg
  documentation: poky-ref-manual: replace "package" with "recipe" where
    appropriate
  documentation: poky-ref-manual: update directory structure
    information

 documentation/dev-manual/dev-manual-newbie.xml  |    2 +-
 documentation/poky-ref-manual/faq.xml           |    2 +-
 documentation/poky-ref-manual/ref-features.xml  |   46 ++++
 documentation/poky-ref-manual/ref-structure.xml |   30 ++-
 documentation/poky-ref-manual/ref-variables.xml |  267 +++++++++++++++--------
 5 files changed, 249 insertions(+), 98 deletions(-)

-- 
1.7.9.5

[yocto-docs][PATCH 01/11] documentation: dev-manual: fix spelling

[Paul Eggleton]

sence -> sense

Signed-off-by: Paul Eggleton <paul.eggleton@linux.intel.com>
---
 documentation/dev-manual/dev-manual-newbie.xml |    2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/documentation/dev-manual/dev-manual-newbie.xml b/documentation/dev-manual/dev-manual-newbie.xml
index 9b922b1..20cf234 100644
--- a/documentation/dev-manual/dev-manual-newbie.xml
+++ b/documentation/dev-manual/dev-manual-newbie.xml
@@ -325,7 +325,7 @@
                 <ulink url='&YOCTO_DOCS_REF_URL;#var-PE'><filename>PE</filename></ulink>).
                 </para></listitem>
             <listitem><para id='poky'><emphasis>Poky:</emphasis> The term "poky" can mean several things.
-                In its most general sence, it is an open-source project that was initially developed
+                In its most general sense, it is an open-source project that was initially developed
                 by OpenedHand.  With OpenedHand, poky was developed off of the existing OpenEmbedded
                 build system becoming a build system for embedded images. 
                 After Intel Corporation aquired OpenedHand, the project poky became the basis for 
-- 
1.7.9.5

[yocto-docs][PATCH 02/11] documentation: poky-ref-manual: correct LICENSE_DIR -> LICENSE_PATH

[Paul Eggleton]

LICENSE_PATH is the correct variable to use for 1.3 - see:

https://bugzilla.yoctoproject.org/show_bug.cgi?id=3118

Fixes documentation for [YOCTO #3118].

Signed-off-by: Paul Eggleton <paul.eggleton@linux.intel.com>
---
 documentation/poky-ref-manual/ref-variables.xml |    6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/documentation/poky-ref-manual/ref-variables.xml b/documentation/poky-ref-manual/ref-variables.xml
index fd04017..62c2596 100644
--- a/documentation/poky-ref-manual/ref-variables.xml
+++ b/documentation/poky-ref-manual/ref-variables.xml
@@ -1327,15 +1327,15 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
             </glossdef>
         </glossentry>
 
-        <glossentry id='var-LICENSE_DIR'><glossterm>LICENSE_DIR</glossterm>
+        <glossentry id='var-LICENSE_PATH'><glossterm>LICENSE_PATH</glossterm>
             <glossdef>
                 <para>Path to additional licenses used during the build.
                     By default, the OpenEmbedded build system uses <filename>COMMON_LICENSE_DIR</filename>  
                     to define the directory that holds common license text used during the build. 
-                    The <filename>LICENSE_DIR</filename> variable allows you to extend that
+                    The <filename>LICENSE_PATH</filename> variable allows you to extend that
                     location to other areas that have additional licenses: 
                     <literallayout class='monospaced'>
-  LICENSE_DIR += "/path/to/additional/common/licenses"
+  LICENSE_PATH += "/path/to/additional/common/licenses"
                     </literallayout></para>
             </glossdef>
         </glossentry>
-- 
1.7.9.5

[yocto-docs][PATCH 03/11] documentation: poky-ref-manual: improve MACHINE_* variable descriptions

[Paul Eggleton]

Adjust the descriptions so that it is clearer that these are specific
to a machine and should appear in the machine's .conf file, and are
intended to affect the image contents, not the dependencies of a
specific package. Also change the examples so that they demonstrate more
realistic usage scenarios for these variables.

Signed-off-by: Paul Eggleton <paul.eggleton@linux.intel.com>
---
 documentation/poky-ref-manual/ref-variables.xml |  124 +++++++++++------------
 1 file changed, 60 insertions(+), 64 deletions(-)

diff --git a/documentation/poky-ref-manual/ref-variables.xml b/documentation/poky-ref-manual/ref-variables.xml
index 62c2596..af1c9e1 100644
--- a/documentation/poky-ref-manual/ref-variables.xml
+++ b/documentation/poky-ref-manual/ref-variables.xml
@@ -1354,8 +1354,8 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
             <glossdef>
                 <para></para>
                 <para>
-                    A list of required packages to install as part of the package being
-                    built.
+                    A list of required machine-specific packages to install as part of
+                    the image being built.
                     The build process depends on these packages being present.
                     Furthermore, because this is a "machine essential" variable, the list of 
                     packages are essential for the machine to boot.
@@ -1365,16 +1365,18 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
                 <para>
                     This variable is similar to the 
                     <filename><link linkend='var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</link></filename>
-                    variable with the exception that the package being built has a build 
+                    variable with the exception that the image being built has a build 
                     dependency on the variable's list of packages.
                     In other words, the image will not build if a file in this list is not found.
                 </para>
                 <para>
-                    For example, suppose you are building a runtime package that depends
-                    on a certain disk driver.
-                    In this case, you would use the following:
+                    For example, suppose the machine you are building for requires
+                    a specific program to be run during boot to initialise the hardware.
+                    In this case, assuming the package name for the program was
+                    <filename>example-init</filename>, you would use the following in the
+                    .conf file for the machine:
                     <literallayout class='monospaced'>
-     MACHINE_ESSENTIAL_EXTRA_RDEPENDS += "&lt;disk_driver&gt;"
+     MACHINE_ESSENTIAL_EXTRA_RDEPENDS += "example-init"
                     </literallayout>
                 </para>
             </glossdef>
@@ -1384,8 +1386,8 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
             <glossdef>
                 <para></para>
                 <para>
-                    A list of recommended packages to install as part of the package being 
-                    built. 
+                    A list of recommended machine-specific packages to install as part of
+                    the image being built.
                     The build process does not depend on these packages being present.
                     Furthermore, because this is a "machine essential" variable, the list of 
                     packages are essential for the machine to boot.
@@ -1395,46 +1397,41 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
                 <para>
                     This variable is similar to the 
                     <filename><link linkend='var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</link></filename>
-                    variable with the exception that the package being built does not have a build 
+                    variable with the exception that the image being built does not have a build 
                     dependency on the variable's list of packages.
-                    In other words, the image will build if a file in this list is not found.
-                    However, because this is one of the "essential" variables, the resulting image
-                    might not boot on the machine. 
-                    Or, if the machine does boot using the image, the machine might not be fully 
-                    functional.
-                </para>
-                <para>
-                    Consider an example where you have a custom kernel with a disk driver
-                    built into the kernel itself, rather than using the driver built as a module.
-                    If you include the package that has the driver module as part of 
-                    the variable's list, the 
-                    build process will not find that package.  
-                    However, because these packages are "recommends" packages, the build will 
-                    not fail due to the missing package.
-                    Not accounting for any other problems, the custom kernel would still boot the machine.
+                    In other words, the image will still build if a package in this list is not found.
+                    Typically this variable is used to handle essential kernel modules, whose
+                    functionality may be selected to be built into the kernel rather than as a module,
+                    in which case a package will not be produced.
+                </para>
+                <para>
+                    Consider an example where you have a custom kernel where a specific touchscreen
+                    driver is required for the machine to be usable, but may be built as a module or
+                    into the kernel depending on the kernel configuration.
+                    If the driver is built as a module, you want it to be installed; however if
+                    the driver is built into the kernel you still want the build to succeed.
+                    This variable sets up a "recommends" relationship so that in the latter case,
+                    the build will not fail due to the missing package.
+                    To accomplish this, assuming the package for the module was called
+                    <filename>kernel-module-ab123</filename>, you would use the
+                    following in the .conf file for the machine:
+                    <literallayout class='monospaced'>
+     MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-module-ab123"
+                    </literallayout>
                 </para>
                 <para>
-                    Some example packages of these machine essentials are flash, screen, keyboard, mouse, 
+                    Some examples of these machine essentials are flash, screen, keyboard, mouse, 
                     or touchscreen drivers (depending on the machine).
                 </para>
-                <para>
-                    For example, suppose you are building a runtime package that depends
-                    on a mouse driver.
-                    In this case, you would use the following:
-                    <literallayout class='monospaced'>
-     MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "&lt;mouse_driver&gt;"
-                    </literallayout>
-                </para>
             </glossdef>
         </glossentry>
 
          <glossentry id='var-MACHINE_EXTRA_RDEPENDS'><glossterm>MACHINE_EXTRA_RDEPENDS</glossterm>
             <glossdef>
                 <para>
-                    A list of optional but non-machine essential packages to install as 
-                    part of the package being built.
-                    Even though these packages are not essential for the machine to boot,  
-                    the build process depends on them being present.
+                    A list of machine-specific packages that are not essential for booting to install as 
+                    part of the image being built.
+                    The build process for more fully-featured images depends on them being present.
                     The impact of this variable affects all images based on
                     <filename>packagegroup-base</filename>, which does not include the 
                     <filename>core-image-minimal</filename> or <filename>core-image-basic</filename> 
@@ -1443,22 +1440,22 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
                 <para>
                     This variable is similar to the 
                     <filename><link linkend='var-MACHINE_EXTRA_RRECOMMENDS'>MACHINE_EXTRA_RRECOMMENDS</link></filename>
-                    variable with the exception that the package being built has a build 
+                    variable with the exception that the image being built has a build 
                     dependency on the variable's list of packages.
                     In other words, the image will not build if a file in this list is not found.
                 </para>
                 <para>
-                    An example is a machine that might or might not have a WiFi card.
-                    The package containing the WiFi support is not essential for the 
-                    machine to boot the image.
-                    If it is not there, the machine will boot but not be able to use the 
-                    WiFi functionality.
-                    However, if you include the package with the WiFi support as part of the 
-                    variable's package list, the build 
-                    process depends on finding the package.
-                    In this case, you would use the following:
+                    An example is a machine that has WiFi capability.
+                    WiFi being enabled is not essential for the machine to boot the image,
+                    however if you are building a more fully-featured image, you want to enable
+                    it. The package containing the firmware for the WiFi hardware is always 
+                    expected to exist, so it is acceptable for the build process to depend upon
+                    finding the package.
+                    In this case, assuming the package for the firmware was called
+                    <filename>wifidriver-firmware</filename>, you would use the following in the
+                    .conf file for the machine:
                     <literallayout class='monospaced'>
-     MACHINE_EXTRA_RDEPENDS += "&lt;wifi_driver&gt;"
+     MACHINE_EXTRA_RDEPENDS += "wifidriver-firmware"
                     </literallayout>
                 </para>
             </glossdef>
@@ -1468,9 +1465,9 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
             <glossdef>
                 <para></para>
                 <para>
-                    A list of optional but non-machine essential packages to install as 
-                    part of the package being built.
-                    The package being built has no build dependency on the list of packages 
+                    A list of machine-specific packages that are not essential for booting
+                    to install as part of the image being built, if present.
+                    The image being built has no build dependency on the list of packages 
                     with this variable.  
                     The impact of this variable affects only images based on 
                     <filename>packagegroup-base</filename>, which does not include the 
@@ -1480,23 +1477,22 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
                 <para>
                     This variable is similar to the 
                     <filename><link linkend='var-MACHINE_EXTRA_RDEPENDS'>MACHINE_EXTRA_RDEPENDS</link></filename>
-                    variable with the exception that the package being built does not have a build 
+                    variable with the exception that the image being built does not have a build 
                     dependency on the variable's list of packages.
                     In other words, the image will build if a file in this list is not found.
                 </para>
                 <para>
-                    An example is a machine that might or might not have a WiFi card.
-                    The package containing the WiFi support is not essential for the 
-                    machine to boot the image.
-                    If it is not there, the machine will boot but not be able to use the 
-                    WiFi functionality.
-                    You are free to either include or not include the 
-                    the package with the WiFi support as part of the 
-                    variable's package list, the build 
-                    process does not depend on finding the package.
-                    If you include the package, you would use the following:
+                    An example is a machine that has WiFi capability.
+                    WiFi being enabled is not essential for the machine to boot the image,
+                    however if you are building a more fully-featured image, you want to enable
+                    it. However, the package containing the WiFi kernel module will not be produced
+                    if the WiFi driver is built into the kernel, in which case you still want the
+                    build to succeed instead of failing because the package could not be found.
+                    To accomplish this, assuming the package for the module was called
+                    <filename>kernel-module-examplewifi</filename>, you would use the
+                    following in the .conf file for the machine:
                     <literallayout class='monospaced'>
-     MACHINE_EXTRA_RRECOMMENDS += "&lt;wifi_driver&gt;"
+     MACHINE_EXTRA_RRECOMMENDS += "kernel-module-examplewifi"
                     </literallayout>
                 </para>
             </glossdef>
-- 
1.7.9.5

[yocto-docs][PATCH 04/11] documentation: poky-ref-manual: extend description of MACHINE variable

[Paul Eggleton]

Extend the description of the MACHINE variable so that it mentions that
this points to a .conf file under conf/machine.

Signed-off-by: Paul Eggleton <paul.eggleton@linux.intel.com>
---
 documentation/poky-ref-manual/ref-variables.xml |    6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/documentation/poky-ref-manual/ref-variables.xml b/documentation/poky-ref-manual/ref-variables.xml
index af1c9e1..fa2bc7f 100644
--- a/documentation/poky-ref-manual/ref-variables.xml
+++ b/documentation/poky-ref-manual/ref-variables.xml
@@ -1346,7 +1346,11 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
 
          <glossentry id='var-MACHINE'><glossterm>MACHINE</glossterm>
             <glossdef>
-                <para>Specifies the target device.</para>
+                <para>
+                    Specifies the target device. This corresponds to a file with the
+                    extension .conf located in a <filename>conf/machine</filename> directory
+                    within the metadata that contains the target device configuration.
+                </para>
             </glossdef>
          </glossentry>
 
-- 
1.7.9.5

[yocto-docs][PATCH 05/11] documentation: poky-ref-manual: add PACKAGECONFIG variable

[Paul Eggleton]

Add a description of the PACKAGECONFIG variable to the variable
glossary.

Signed-off-by: Paul Eggleton <paul.eggleton@linux.intel.com>
---
 documentation/poky-ref-manual/ref-variables.xml |   31 +++++++++++++++++++++++
 1 file changed, 31 insertions(+)

diff --git a/documentation/poky-ref-manual/ref-variables.xml b/documentation/poky-ref-manual/ref-variables.xml
index fa2bc7f..0bb3094 100644
--- a/documentation/poky-ref-manual/ref-variables.xml
+++ b/documentation/poky-ref-manual/ref-variables.xml
@@ -1577,6 +1577,37 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
             </glossdef>
         </glossentry>
 
+        <glossentry id='var-PACKAGECONFIG'><glossterm>PACKAGECONFIG</glossterm>
+            <glossdef>
+                <para>
+                    Provides a means of enabling or disabling features of a recipe
+                    on a per-recipe basis. The <filename>PACKAGECONFIG</filename>
+                    variable itself specifies a space-separated list of the features
+                    to enable, whilst the named flags set on the variable specify
+                    for each feature the additional build dependencies 
+                    (<filename><link linkend='var-DEPENDS'>DEPENDS</link></filename>)
+                    that should be added if the feature is enabled, and any extra arguments
+                    that should be added to the configure script argument list
+                    (<filename><link linkend='var-EXTRA_OECONF'>EXTRA_OECONF</link></filename>)
+                    if the feature is enabled or disabled.
+                </para>
+                <para>
+                    For example, the following taken from the <filename>librsvg</filename>
+                    recipe will add <filename>--with-croco</filename> to the
+                    configure script arguments and <filename>libcroco</filename> to
+                    <filename><link linkend='var-DEPENDS'>DEPENDS</link></filename>
+                    by default; however, if "croco" is removed from <filename>PACKAGECONFIG</filename>
+                    (for example, by using a bbappend in another layer) then
+                    <filename>--without-croco</filename> will be added to the configure
+                    script arguments instead:
+                    <literallayout class='monospaced'>
+     PACKAGECONFIG ??= "croco"
+     PACKAGECONFIG[croco] = "--with-croco,--without-croco,libcroco"
+                    </literallayout>
+                </para>
+            </glossdef>
+        </glossentry>
+
         <glossentry id='var-PACKAGES'><glossterm>PACKAGES</glossterm>
             <glossdef>
                 <para>The list of packages to be created from the recipe.
-- 
1.7.9.5

[yocto-docs][PATCH 06/11] documentation: poky-ref-manual: extend DISTRO description

[Paul Eggleton]

Extend the description of the DISTRO variable so that it mentions that
this points to a .conf file under conf/distro and mentions what happens
if the value is left blank.

Signed-off-by: Paul Eggleton <paul.eggleton@linux.intel.com>
---
 documentation/poky-ref-manual/ref-variables.xml |   11 ++++++++++-
 1 file changed, 10 insertions(+), 1 deletion(-)

diff --git a/documentation/poky-ref-manual/ref-variables.xml b/documentation/poky-ref-manual/ref-variables.xml
index 0bb3094..ba81f96 100644
--- a/documentation/poky-ref-manual/ref-variables.xml
+++ b/documentation/poky-ref-manual/ref-variables.xml
@@ -448,7 +448,16 @@
 
         <glossentry id='var-DISTRO'><glossterm>DISTRO</glossterm>
             <glossdef>
-                <para>The short name of the distribution.</para>
+                <para>
+                    The short name of the distribution. This corresponds to a file with the
+                    extension .conf located in a <filename>conf/distro</filename> directory
+                    within the metadata that contains the distribution configuration. The
+                    value must not contain spaces, and is typically all lower-case.
+                </para>
+                <para>
+                    If blank, a set of default configuration will be used, which is specified
+                    within <filename>meta/conf/distro/defaultsetup.conf</filename>.
+                </para>
             </glossdef>
         </glossentry>
 
-- 
1.7.9.5

[yocto-docs][PATCH 07/11] documentation: poky-ref-manual: add information on *_FEATURES_BACKFILL

[Paul Eggleton]

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.

Signed-off-by: Paul Eggleton <paul.eggleton@linux.intel.com>
---
 documentation/poky-ref-manual/ref-features.xml  |   46 +++++++++++++++++++
 documentation/poky-ref-manual/ref-variables.xml |   54 ++++++++++++++++++++++-
 2 files changed, 99 insertions(+), 1 deletion(-)

diff --git a/documentation/poky-ref-manual/ref-features.xml b/documentation/poky-ref-manual/ref-features.xml
index 159d56d..81ba8e5 100644
--- a/documentation/poky-ref-manual/ref-features.xml
+++ b/documentation/poky-ref-manual/ref-features.xml
@@ -171,6 +171,52 @@
             </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, whilst 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 .conf 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 .conf file and this will disable adding "rtc" to
+            <filename>MACHINE_FEATURES</filename>.
+        </para>
+    </section>
 </chapter>
 
 <!-- 
diff --git a/documentation/poky-ref-manual/ref-variables.xml b/documentation/poky-ref-manual/ref-variables.xml
index ba81f96..c71a959 100644
--- a/documentation/poky-ref-manual/ref-variables.xml
+++ b/documentation/poky-ref-manual/ref-variables.xml
@@ -471,7 +471,35 @@
 
         <glossentry id='var-DISTRO_FEATURES'><glossterm>DISTRO_FEATURES</glossterm>
             <glossdef>
-                <para>The features of the distribution.</para>
+                <para>The features enabled for the distribution.
+                    For a list of valid features, see the
+                    <link linkend='ref-features-distro'>Distro</link>
+                    section.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-DISTRO_FEATURES_BACKFILL'><glossterm>DISTRO_FEATURES_BACKFILL</glossterm>
+            <glossdef>
+                <para>Features to be added to 
+                    <filename><link linkend='var-DISTRO_FEATURES'>DISTRO_FEATURES</link></filename>
+                    if not also present in 
+                    <filename><link linkend='var-DISTRO_FEATURES_BACKFILL_CONSIDERED'>DISTRO_FEATURES_BACKFILL_CONSIDERED</link></filename>.
+                    See the <link linkend='ref-features-backfill'>Feature backfilling</link> section for 
+                    more information.
+                    </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-DISTRO_FEATURES_BACKFILL_CONSIDERED'><glossterm>DISTRO_FEATURES_BACKFILL_CONSIDERED</glossterm>
+            <glossdef>
+                <para>Features from
+                    <filename><link linkend='var-DISTRO_FEATURES_BACKFILL'>DISTRO_FEATURES_BACKFILL</link></filename>
+                    that should not be added to
+                    <filename><link linkend='var-DISTRO_FEATURES'>DISTRO_FEATURES</link></filename>.
+                    See the <link linkend='ref-features-backfill'>Feature backfilling</link> section for 
+                    more information.
+                    </para>
             </glossdef>
         </glossentry>
 
@@ -1519,6 +1547,30 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
             </glossdef>
          </glossentry>
 
+        <glossentry id='var-MACHINE_FEATURES_BACKFILL'><glossterm>MACHINE_FEATURES_BACKFILL</glossterm>
+            <glossdef>
+                <para>Features to be added to 
+                    <filename><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES</link></filename>
+                    if not also present in 
+                    <filename><link linkend='var-MACHINE_FEATURES_BACKFILL_CONSIDERED'>MACHINE_FEATURES_BACKFILL_CONSIDERED</link></filename>.
+                    See the <link linkend='ref-features-backfill'>Feature backfilling</link> section for 
+                    more information.
+                    </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-MACHINE_FEATURES_BACKFILL_CONSIDERED'><glossterm>MACHINE_FEATURES_BACKFILL_CONSIDERED</glossterm>
+            <glossdef>
+                <para>Features from
+                    <filename><link linkend='var-MACHINE_FEATURES_BACKFILL'>MACHINE_FEATURES_BACKFILL</link></filename>
+                    that should not be added to
+                    <filename><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES</link></filename>.
+                    See the <link linkend='ref-features-backfill'>Feature backfilling</link> section for 
+                    more information.
+                    </para>
+            </glossdef>
+        </glossentry>
+
         <glossentry id='var-MAINTAINER'><glossterm>MAINTAINER</glossterm>
             <glossdef>
                 <para>The email address of the distribution maintainer.</para>
-- 
1.7.9.5

[yocto-docs][PATCH 08/11] documentation: poky-ref-manual: fix description of SUMMARY variable

[Paul Eggleton]

* Use correct/up-to-date names of package systems
* SUMMARY does not default to the value of DESCRIPTION, it's the other
  way around (although the logic may be improved in future so that this
  is the effect).

Signed-off-by: Paul Eggleton <paul.eggleton@linux.intel.com>
---
 documentation/poky-ref-manual/ref-variables.xml |    6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/documentation/poky-ref-manual/ref-variables.xml b/documentation/poky-ref-manual/ref-variables.xml
index c71a959..ccdb0e8 100644
--- a/documentation/poky-ref-manual/ref-variables.xml
+++ b/documentation/poky-ref-manual/ref-variables.xml
@@ -2217,9 +2217,9 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
         <glossentry id='var-SUMMARY'><glossterm>SUMMARY</glossterm>
             <glossdef>
                 <para>The short (72 characters or less) summary of the binary package for packaging 
-                    systems such as <filename>ipkg</filename>, <filename>rpm</filename> or 
-                    <filename>debian</filename>.
-                    By default, this variable inherits <filename>DESCRIPTION</filename>.</para>
+                    systems such as <filename>opkg</filename>, <filename>rpm</filename> or 
+                    <filename>dpkg</filename>.
+                </para>
             </glossdef>
         </glossentry>
 
-- 
1.7.9.5

[yocto-docs][PATCH 09/11] documentation: poky-ref-manual: remove references to ipkg

[Paul Eggleton]

We haven't supported ipkg for some time now - it was replaced by opkg
(whilst still using the ipk package format).

Signed-off-by: Paul Eggleton <paul.eggleton@linux.intel.com>
---
 documentation/poky-ref-manual/faq.xml           |    2 +-
 documentation/poky-ref-manual/ref-variables.xml |    4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/documentation/poky-ref-manual/faq.xml b/documentation/poky-ref-manual/faq.xml
index 943d22a..945c7f1 100644
--- a/documentation/poky-ref-manual/faq.xml
+++ b/documentation/poky-ref-manual/faq.xml
@@ -166,7 +166,7 @@
         <answer>
             <para>
                 The OpenEmbedded build system can build packages in various formats such as
-                <filename>ipk</filename> for <filename>ipkg</filename>/<filename>opkg</filename>, 
+                <filename>ipk</filename> for <filename>opkg</filename>, 
                 Debian package (<filename>.deb</filename>), or RPM. 
                 The packages can then be upgraded using the package tools on the device, much like 
                 on a desktop distribution such as Ubuntu or Fedora.
diff --git a/documentation/poky-ref-manual/ref-variables.xml b/documentation/poky-ref-manual/ref-variables.xml
index ccdb0e8..dd858d3 100644
--- a/documentation/poky-ref-manual/ref-variables.xml
+++ b/documentation/poky-ref-manual/ref-variables.xml
@@ -114,8 +114,8 @@
             <glossdef>
                 <para>
                     A list of packages not to install despite being recommended by a recipe.
-                    Support for this variable exists only for images that use the 
-                    <filename>ipkg</filename> packaging system.
+                    Support for this variable exists only when using the 
+                    <filename>ipk</filename> packaging backend.
                 </para>
             </glossdef>
         </glossentry>
-- 
1.7.9.5

[yocto-docs][PATCH 11/11] documentation: poky-ref-manual: update directory structure information

[Paul Eggleton]

* Add meta-yocto, meta-yocto-bsp and meta-hob
* Remove meta-rt - this was merged into OE-Core (meta)
* Remove meta-demoapps - this was dropped

Signed-off-by: Paul Eggleton <paul.eggleton@linux.intel.com>
---
 documentation/poky-ref-manual/ref-structure.xml |   30 ++++++++++++++++-------
 1 file changed, 21 insertions(+), 9 deletions(-)

diff --git a/documentation/poky-ref-manual/ref-structure.xml b/documentation/poky-ref-manual/ref-structure.xml
index fcdf7b1..75bc2eb 100644
--- a/documentation/poky-ref-manual/ref-structure.xml
+++ b/documentation/poky-ref-manual/ref-structure.xml
@@ -93,25 +93,37 @@
 
         <para>
             This directory contains the OpenEmbedded Core metadata. 
-            The directory holds machine definitions, the Yocto Project distribution, 
-            and the packages that make up a given system.
+            The directory holds recipes, common classes, and machine
+            configuration for emulated targets (qemux86, qemuarm,
+            and so on.)
         </para>
     </section>
 
-    <section id='structure-core-meta-demoapps'>
-        <title><filename>meta-demoapps/</filename></title>
+    <section id='structure-core-meta-yocto'>
+        <title><filename>meta-yocto/</filename></title>
 
         <para>
-            This directory contains recipes for applications and demos that are not part of the 
-            OpenEmbedded core.
+            This directory contains the configuration for the Poky
+            reference distribution.
         </para>
     </section>
 
-    <section id='structure-core-meta-rt'>
-        <title><filename>meta-rt/</filename></title>
+    <section id='structure-core-meta-yocto-bsp'>
+        <title><filename>meta-yocto-bsp/</filename></title>
 
         <para>
-            This directory contains recipes for real-time kernels. 
+            This directory contains the Yocto Project reference
+            hardware BSPs.
+        </para>
+    </section>
+
+    <section id='structure-meta-hob'>
+        <title><filename>meta-hob/</filename></title>
+
+        <para>
+            This directory contains template recipes used by the
+            <ulink url='&YOCTO_HOME_URL;/projects/hob'>Hob</ulink>
+            build UI.
         </para>
     </section>
 
-- 
1.7.9.5

[yocto-docs][PATCH 10/11] documentation: poky-ref-manual: replace "package" with "recipe" where appropriate

[Paul Eggleton]

We have to take care when using "package" to avoid confusion, even when
referring to variables with a historical package association (PV, PN
etc.).

Signed-off-by: Paul Eggleton <paul.eggleton@linux.intel.com>
---
 documentation/poky-ref-manual/ref-variables.xml |   25 ++++++++++++-----------
 1 file changed, 13 insertions(+), 12 deletions(-)

diff --git a/documentation/poky-ref-manual/ref-variables.xml b/documentation/poky-ref-manual/ref-variables.xml
index dd858d3..7153731 100644
--- a/documentation/poky-ref-manual/ref-variables.xml
+++ b/documentation/poky-ref-manual/ref-variables.xml
@@ -200,14 +200,14 @@
         <glossentry id='var-BBFILE_PRIORITY'><glossterm>BBFILE_PRIORITY</glossterm>
             <glossdef>
                 <para>Assigns the priority for recipe files in each layer.</para>
-                <para>This variable is useful in situations where the same package appears in
+                <para>This variable is useful in situations where the same recipe appears in
                     more than one layer. 
                     Setting this variable allows you to prioritize a
-                    layer against other layers that contain the same package - effectively
+                    layer against other layers that contain the same recipe - effectively
                     letting you control the precedence for the multiple layers. 
                     The precedence established through this variable stands regardless of a
-                    layer's package version (<filename>PV</filename> variable). 
-                    For example, a layer that has a package with a higher <filename>PV</filename> value but for 
+                    recipe's version (<filename>PV</filename> variable). 
+                    For example, a layer that has a recipe with a higher <filename>PV</filename> value but for 
                     which the <filename>BBFILE_PRIORITY</filename> is set to have a lower precedence still has a 
                     lower precedence.</para>
                 <para>A larger value for the <filename>BBFILE_PRIORITY</filename> variable results in a higher
@@ -269,7 +269,7 @@
         <glossentry id='var-BP'><glossterm>BP</glossterm>
             <glossdef>
                 <para>The base recipe name and version but without any special 
-                    package name suffix (i.e. <filename>-native</filename>, <filename>lib64-</filename>,
+                    recipe name suffix (i.e. <filename>-native</filename>, <filename>lib64-</filename>,
                     and so forth).
                     <filename>BP</filename> is comprised of the following:
                     <literallayout class="monospaced">
@@ -280,7 +280,7 @@
 
         <glossentry id='var-BPN'><glossterm>BPN</glossterm>
             <glossdef>
-                <para>Bare name of package with any suffixes like -cross -native removed.</para>
+                <para>Bare name of recipe with any suffixes like -cross -native removed.</para>
             </glossdef>
         </glossentry>
 
@@ -825,7 +825,8 @@ FILESPATH = "${@base_set_filespath([ "${FILE_DIRNAME}/${PF}", \
 
         <glossentry id='var-HOMEPAGE'><glossterm>HOMEPAGE</glossterm>
             <glossdef>
-                <para>Website where more info about package can be found</para>
+                <para>Website where more information about the software the recipe is building
+                    can be found.</para>
             </glossdef>
         </glossentry>
 
@@ -2356,7 +2357,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
             <glossdef>
                 <para>
                     The pathname of the working directory in which the OpenEmbedded build system  
-                    builds packages.
+                    builds a recipe.
                     This directory is located within the
                     <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link> directory structure and changes
                     as different packages are built.
@@ -2369,9 +2370,9 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
                         <listitem>The package architecture - <link linkend='var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></link></listitem>
                         <listitem>The target machine - <link linkend='var-MACHINE'><filename>MACHINE</filename></link></listitem>
                         <listitem>The target operating system - <link linkend='var-TARGET_OS'><filename>TARGET_OS</filename></link></listitem>
-                        <listitem>The package name - <link linkend='var-PN'><filename>PN</filename></link></listitem>
-                        <listitem>The package version - <link linkend='var-PV'><filename>PV</filename></link></listitem>
-                        <listitem>The package revision - <link linkend='var-PR'><filename>PR</filename></link></listitem>
+                        <listitem>The recipe name - <link linkend='var-PN'><filename>PN</filename></link></listitem>
+                        <listitem>The recipe version - <link linkend='var-PV'><filename>PV</filename></link></listitem>
+                        <listitem>The recipe revision - <link linkend='var-PR'><filename>PR</filename></link></listitem>
                     </itemizedlist>
                 </para>
 
@@ -2403,7 +2404,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
                     named <filename>poky</filename> and a default build directory 
                     at <filename>poky/build</filename>.
                     In this case, the working directory the build system uses to build
-                    the <filename>acl</filename> package, which is dependent on a 
+                    the <filename>acl</filename> recipe, which is being built for a 
                     MIPS-based device, is the following:
                     <literallayout class='monospaced'>
      ~/poky/build/tmp/work/mips-poky-linux/acl-2.2.51-r2
-- 
1.7.9.5

Re: [yocto-docs][PATCH 00/11] Documentation improvements

[Paul Eggleton]

On Monday 08 October 2012 16:38:06 Paul Eggleton wrote:
> Add some missing variables to the variable reference and improve
> the descriptions of others. Also fix references to "package" where
> we mean "recipe" and a couple of other issues I noticed at the same
> time.
> 
> 
> The following changes since commit 821162221818f5ce53bb903aeef57c85314f5083:
> 
>   documentation: dev-manual - mentioned SRC_URI in the kernel example
> (2012-10-05 11:25:03 -0700)
> 
> are available in the git repository at:
> 
>   git://git.yoctoproject.org/poky-contrib paule/doc-fixes-5
>   http://git.yoctoproject.org/cgit.cgi/poky-contrib/log/?h=paule/doc-fixes-5
> 
> Paul Eggleton (11):
>   documentation: dev-manual: fix spelling
>   documentation: poky-ref-manual: correct LICENSE_DIR -> LICENSE_PATH
>   documentation: poky-ref-manual: improve MACHINE_* variable
>     descriptions
>   documentation: poky-ref-manual: extend description of MACHINE
>     variable
>   documentation: poky-ref-manual: add PACKAGECONFIG variable
>   documentation: poky-ref-manual: extend DISTRO description
>   documentation: poky-ref-manual: add information on
>     *_FEATURES_BACKFILL
>   documentation: poky-ref-manual: fix description of SUMMARY variable
>   documentation: poky-ref-manual: remove references to ipkg
>   documentation: poky-ref-manual: replace "package" with "recipe" where
>     appropriate
>   documentation: poky-ref-manual: update directory structure
>     information
> 
>  documentation/dev-manual/dev-manual-newbie.xml  |    2 +-
>  documentation/poky-ref-manual/faq.xml           |    2 +-
>  documentation/poky-ref-manual/ref-features.xml  |   46 ++++
>  documentation/poky-ref-manual/ref-structure.xml |   30 ++-
>  documentation/poky-ref-manual/ref-variables.xml |  267
> +++++++++++++++-------- 5 files changed, 249 insertions(+), 98 deletions(-)

Apologies if 10/11 comes through twice, there was some kind of issue with 
getting the original mail through to the mailing list server so I resent it.

Cheers,
Paul

-- 

Paul Eggleton
Intel Open Source Technology Centre