ref-manual: 13 new variables added to the glossary.

Added descriptions for the following variables:

 EXTRA_AUTORECONF
 KERNEL_IMAGE_MAXSIZE
 UPDATERCPN
 AUTO_LIBNAME_PKGS
 DEBIANNAME
 DEBIAN_NOAUTONAME
 TCLIBCAPPEND
 PACKAGEGROUP_DISABLE_COMPLEMENTARY
 CLEANBROKEN
 DISTRO_CODENAME
 BASE_WORKDIR
 DISTRO_FEATURES_DEFAULT
 DISTRO_FEATURES_LIBC

Part of adding new variables is checking to see if a previously
undocumented variable is used elsewhere in the manual.  One
occurrence was spotted and turned into a link for this list.

(From yocto-docs rev: bb75387b7aa4fcb0b594d300772952d81a651644)

Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

2 files changed, 272 insertions, 1 deletions

diff --git a/documentation/ref-manual/ref-tasks.xml b/documentation/ref-manual/ref-tasks.xml
index f325f0e233..2b3031538f 100644
--- a/documentation/ref-manual/ref-tasks.xml
+++ b/documentation/ref-manual/ref-tasks.xml
@@ -628,7 +628,8 @@
 
         <para>
             Checks the size of the kernel image against
-            <filename>KERNEL_IMAGE_MAXSIZE</filename> when set.
+            <link linkend='var-KERNEL_IMAGE_MAXSIZE'><filename>KERNEL_IMAGE_MAXSIZE</filename></link>
+            when set.
         </para>
     </section>
 
diff --git a/documentation/ref-manual/ref-variables.xml b/documentation/ref-manual/ref-variables.xml
index e3272fec79..da7a986b68 100644
--- a/documentation/ref-manual/ref-variables.xml
+++ b/documentation/ref-manual/ref-variables.xml
@@ -293,6 +293,28 @@
             </glossdef>
         </glossentry>
 
+        <glossentry id='var-AUTO_LIBNAME_PKGS'><glossterm><imagedata fileref="figures/define-generic.png" />AUTO_LIBNAME_PKGS</glossterm>
+            <info>
+                AUTO_LIBNAME_PKGS[doc] = "Specifies which packages should be checked for libraries and renamed according to Debian library package naming."
+            </info>
+            <glossdef>
+                <para>
+                    When the
+                    <link linkend='ref-classes-debian'><filename>debian</filename></link>
+                    class is inherited, which is the default behavior,
+                    <filename>AUTO_LIBNAME_PKGS</filename> specifies which
+                    packages should be checked for libraries and renamed
+                    according to Debian library package naming.
+                </para>
+
+                <para>
+                    The default value is "${PACKAGES}", which causes the
+                    OpenEmbedded build system to act on all packages that are
+                    explicitly generated by the recipe.
+                </para>
+            </glossdef>
+        </glossentry>
+
         <glossentry id='var-AUTO_SYSLINUXMENU'><glossterm><imagedata fileref="figures/define-generic.png" />AUTO_SYSLINUXMENU</glossterm>
             <info>
                 AUTO_SYSLINUXMENU[doc] = "Enables creating an automatic menu for the syslinux bootloader."
@@ -461,6 +483,18 @@
             </glossdef>
         </glossentry>
 
+        <glossentry id='var-BASE_WORKDIR'><glossterm><imagedata fileref="figures/define-generic.png" />BASE_WORKDIR</glossterm>
+            <info>
+                BASE_WORKDIR[doc] = "Points to the base of the work directory for all recipes."
+            </info>
+            <glossdef>
+                <para>
+                    Points to the base of the work directory for all recipes.
+                    The default value is "${TMPDIR}/work".
+                </para>
+            </glossdef>
+        </glossentry>
+
         <glossentry id='var-BB_DANGLINGAPPENDS_WARNONLY'><glossterm><imagedata fileref="figures/define-generic.png" />BB_DANGLINGAPPENDS_WARNONLY</glossterm>
             <info>
                 BB_DANGLINGAPPENDS_WARNONLY[doc] = "Defines how BitBake handles situations where an append file (.bbappend) has no corresponding recipe file (.bb)."
@@ -1578,6 +1612,24 @@
             </glossdef>
         </glossentry>
 
+        <glossentry id='var-CLEANBROKEN'><glossterm><imagedata fileref="figures/define-generic.png" />CLEANBROKEN</glossterm>
+            <info>
+                CLEANBROKEN[doc] = "Prevents the build system from running 'make clean' during the do_configure task."
+            </info>
+            <glossdef>
+                <para>
+                    If set to "1" within a recipe,
+                    <filename>CLEANBROKEN</filename> specifies that
+                    the <filename>make clean</filename> command does
+                    not work for the software being built.
+                    Consequently, the OpenEmbedded build system will not try
+                    to run <filename>make clean</filename> during the
+                    <link linkend='ref-tasks-configure'><filename>do_configure</filename></link>
+                    task, which is the default behavior.
+                </para>
+            </glossdef>
+        </glossentry>
+
         <glossentry id='var-COMBINED_FEATURES'><glossterm><imagedata fileref="figures/define-generic.png" />COMBINED_FEATURES</glossterm>
             <info>
                 COMBINED_FEATURES[doc] = "A set of features common between MACHINE_FEATURES and DISTRO_FEATURES."
@@ -1995,6 +2047,52 @@
             </glossdef>
         </glossentry>
 
+        <glossentry id='var-DEBIAN_NOAUTONAME'><glossterm><imagedata fileref="figures/define-generic.png" />DEBIAN_NOAUTONAME</glossterm>
+            <info>
+                DEBIAN_NOAUTONAME[doc] = "Prevents a particular package from being renamed according to Debian package naming."
+            </info>
+            <glossdef>
+                <para>
+                    When the
+                    <link linkend='ref-classes-debian'><filename>debian</filename></link>
+                    class is inherited, which is the default behavior,
+                    <filename>DEBIAN_NOAUTONAME</filename> specifies a
+                    particular package should not be renamed according to
+                    Debian library package naming.
+                    You must use the package name as an override when you
+                    set this variable.
+                    Here is an example from the <filename>fontconfig</filename>
+                    recipe:
+                    <literallayout class='monospaced'>
+     DEBIAN_NOAUTONAME_fontconfig-utils = "1"
+                    </literallayout>
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-DEBIANNAME'><glossterm><imagedata fileref="figures/define-generic.png" />DEBIANNAME</glossterm>
+            <info>
+                DEBIANNAME[doc] = "Allows you to override the library name for an individual package."
+            </info>
+            <glossdef>
+                <para>
+                    When the
+                    <link linkend='ref-classes-debian'><filename>debian</filename></link>
+                    class is inherited, which is the default behavior,
+                    <filename>DEBIANNAME</filename> allows you to override the
+                    library name for an individual package.
+                    Overriding the library name in these cases is rare.
+                    You must use the package name as an override when you
+                    set this variable.
+                    Here is an example from the <filename>dbus</filename>
+                    recipe:
+                    <literallayout class='monospaced'>
+     DEBIANNAME_${PN} = "dbus-1"
+                    </literallayout>
+                </para>
+            </glossdef>
+        </glossentry>
+
         <glossentry id='var-DEBUG_BUILD'><glossterm><imagedata fileref="figures/define-generic.png" />DEBUG_BUILD</glossterm>
             <info>
                 DEBUG_BUILD[doc] = "Specifies to build packages with debugging information. This influences the value of the SELECTED_OPTIMIZATION variable."
@@ -2307,6 +2405,17 @@
             </glossdef>
         </glossentry>
 
+        <glossentry id='var-DISTRO_CODENAME'><glossterm><imagedata fileref="figures/define-generic.png" />DISTRO_CODENAME</glossterm>
+            <info>
+                DISTRO_CODENAME[doc] = "Specifies a codename for the distribution being built."
+            </info>
+            <glossdef>
+                <para>
+                    Specifies a codename for the distribution being built.
+                </para>
+            </glossdef>
+        </glossentry>
+
         <glossentry id='var-DISTRO_EXTRA_RDEPENDS'><glossterm><imagedata fileref="figures/define-generic.png" />DISTRO_EXTRA_RDEPENDS</glossterm>
             <info>
                 DISTRO_EXTRA_RDEPENDS[doc] = "Specifies a list of distro-specific packages to add to all images. The variable only applies to the images that include packagegroup-base."
@@ -2415,6 +2524,49 @@
             </glossdef>
         </glossentry>
 
+        <glossentry id='var-DISTRO_FEATURES_DEFAULT'><glossterm><imagedata fileref="figures/define-generic.png" />DISTRO_FEATURES_DEFAULT</glossterm>
+            <info>
+                DISTRO_FEATURES_DEFAULT[doc] = "Provides the default list of distro features with the exception of any libc-specific features."
+            </info>
+            <glossdef>
+                <para>
+                    A convenience variable that gives you the default
+                    list of distro features with the exception of any
+                    features specific to the C library
+                    (<filename>libc</filename>).
+                </para>
+
+                <para>
+                    When creating a custom distribution, you might find it
+                    useful to be able to reuse the default
+                    <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>
+                    options without the need to write out the full set.
+                    Here is an example that uses
+                    <filename>DISTRO_FEATURES_DEFAULT</filename> from a
+                    custom distro configuration file:
+                    <literallayout class='monospaced'>
+     DISTRO_FEATURES ?= "${DISTRO_FEATURES_DEFAULT} ${DISTRO_FEATURES_LIBC} myfeature"
+                    </literallayout>
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-DISTRO_FEATURES_LIBC'><glossterm><imagedata fileref="figures/define-generic.png" />DISTRO_FEATURES_LIBC</glossterm>
+            <info>
+                DISTRO_FEATURES_LIBC[doc] = "Specifies the list of distro features that are specific to the C library (libc)."
+            </info>
+            <glossdef>
+                <para>
+                    A convenience variable that specifies the list of distro
+                    features that are specific to the C library
+                    (<filename>libc</filename>).
+                    Typically, these features are prefixed with "libc-" and
+                    control which features are enabled at during the build
+                    within the C library itself.
+                </para>
+            </glossdef>
+        </glossentry>
+
         <glossentry id='var-DISTRO_NAME'><glossterm><imagedata fileref="figures/define-generic.png" />DISTRO_NAME</glossterm>
             <info>
                 DISTRO_NAME[doc] = "The long name of the distribution."
@@ -2766,6 +2918,27 @@
             </glossdef>
         </glossentry>
 
+        <glossentry id='var-EXTRA_AUTORECONF'><glossterm><imagedata fileref="figures/define-generic.png" />EXTRA_AUTORECONF</glossterm>
+            <info>
+                EXTRA_AUTORECONF[doc] = "Extra options passed to the autoreconf command, which is executed during do_configure."
+            </info>
+            <glossdef>
+                <para>
+                    For recipes inheriting the <filename>autoconf</filename>
+                    class, you can use <filename>EXTRA_AUTORECONF</filename> to
+                    specify extra options to pass to the
+                    <filename>autoreconf</filename> command that is
+                    executed during the
+                    <link linkend='ref-tasks-configure'><filename>do_configure</filename></link>
+                    task.
+                </para>
+
+                <para>
+                    The default value is "--exclude=autopoint".
+                </para>
+            </glossdef>
+        </glossentry>
+
         <glossentry id='var-EXTRA_IMAGE_FEATURES'><glossterm><imagedata fileref="figures/define-generic.png" />EXTRA_IMAGE_FEATURES</glossterm>
             <info>
                 EXTRA_IMAGE_FEATURES[doc] = "The list of additional features to include in an image. Configure this variable in the conf/local.conf file in the Build Directory."
@@ -5172,6 +5345,36 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
             </glossdef>
         </glossentry>
 
+        <glossentry id='var-KERNEL_IMAGE_MAXSIZE'><glossterm><imagedata fileref="figures/define-generic.png" />KERNEL_IMAGE_MAXSIZE</glossterm>
+            <info>
+                KERNEL_IMAGE_MAXSIZE[doc] = "The maximum allowable size in kilobytes of the kernel image file."
+            </info>
+            <glossdef>
+                <para>
+                    Specifies the maximum size of the kernel image file in
+                    kilobytes.
+                    If <filename>KERNEL_IMAGE_MAXSIZE</filename> is set,
+                    the size of the kernel image file is checked against
+                    the set value during the
+                    <link linkend='ref-tasks-sizecheck'><filename>do_sizecheck</filename></link>
+                    task.
+                    The task fails if the kernel image file is larger than
+                    the setting.
+                </para>
+
+                <para>
+                    <filename>KERNEL_IMAGE_MAXSIZE</filename> is useful for
+                    target devices that have a limited amount of space in
+                    which the kernel image file must be stored.
+                </para>
+
+                <para>
+                    By default, this variable is not set, which means the
+                    size of the kernel image is not checked.
+                </para>
+            </glossdef>
+        </glossentry>
+
         <glossentry id='var-KERNEL_IMAGETYPE'><glossterm><imagedata fileref="figures/define-generic.png" />KERNEL_IMAGETYPE</glossterm>
             <info>
                 KERNEL_IMAGETYPE[doc] = "The type of kernel to build for a device, usually set by the machine configuration files and defaults to 'zImage'."
@@ -7064,6 +7267,26 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
             </glossdef>
         </glossentry>
 
+        <glossentry id='var-PACKAGEGROUP_DISABLE_COMPLEMENTARY'><glossterm><imagedata fileref="figures/define-generic.png" />PACKAGEGROUP_DISABLE_COMPLEMENTARY</glossterm>
+            <info>
+                PACKAGEGROUP_DISABLE_COMPLEMENTARY[doc] = "Prevents the packagegroup recipe from automatically creating the normal complementary packages such as -dev and -dbg."
+            </info>
+            <glossdef>
+                <para>
+                    For recipes inheriting the
+                    <link linkend='ref-classes-packagegroup'><filename>packagegroup</filename></link>
+                    class, setting
+                    <filename>PACKAGEGROUP_DISABLE_COMPLEMENTARY</filename> to
+                    "1" specifies that the normal complementary packages
+                    (i.e. <filename>-dev</filename>,
+                    <filename>-dbg</filename>, and so forth) should not be
+                    automatically created by the
+                    <filename>packagegroup</filename> recipe, which is the
+                    default behavior.
+                </para>
+            </glossdef>
+        </glossentry>
+
         <glossentry id='var-PACKAGES'><glossterm><imagedata fileref="figures/define-generic.png" />PACKAGES</glossterm>
             <info>
                 PACKAGES[doc] = "The list of packages to be created from the recipe."
@@ -10107,6 +10330,31 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
             </glossdef>
         </glossentry>
 
+        <glossentry id='var-TCLIBCAPPEND'><glossterm><imagedata fileref="figures/define-generic.png" />TCLIBCAPPEND</glossterm>
+            <info>
+                TCLIBCAPPEND[doc] = "Specifies a suffix appended to TMPDIR that identifies the libc variant for the build."
+            </info>
+            <glossdef>
+                <para>
+                    Specifies a suffix to be appended onto the
+                    <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>
+                    value.
+                    The suffix identifies the <filename>libc</filename> variant
+                    for building.
+                </para>
+
+                <para>
+                    In the <filename>defaultsetup.conf</filename> file, the
+                    default value of <filename>TCLIBCAPPEND</filename> is
+                    "-${TCLIBC}".
+                    However, distros such as poky, which normally only support
+                    one <filename>libc</filename> variant, set
+                    <filename>TCLIBCAPPEND</filename> to "" in their distro
+                    configuration file resulting in no suffix being applied.
+                </para>
+            </glossdef>
+        </glossentry>
+
         <glossentry id='var-TCLIBC'><glossterm><imagedata fileref="figures/define-generic.png" />TCLIBC</glossterm>
             <info>
                 TCLIBC[doc] = "Specifies GNU standard C library (libc) variant to use during the build process. You can select 'glibc' or 'uclibc'."
@@ -11080,6 +11328,28 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
             </glossdef>
         </glossentry>
 
+        <glossentry id='var-UPDATERCPN'><glossterm><imagedata fileref="figures/define-generic.png" />UPDATERCPN</glossterm>
+            <info>
+               UPDATERCPN[doc] = "Specifies the package that contains the initscript that is to be enabled."
+            </info>
+            <glossdef>
+                <para>
+                    For recipes inheriting the
+                    <link linkend='ref-classes-update-rc.d'><filename>update-rc.d</filename></link>
+                    class, <filename>UPDATERCPN</filename> specifies
+                    the package that contains the initscript that is to be
+                    enabled.
+                </para>
+
+                <para>
+                    The default value is "${PN}".
+                    Given that almost all recipes that install initscripts
+                    package them in the main package for the recipe, you
+                    rarely need to set this variable in individual recipes.
+                </para>
+            </glossdef>
+        </glossentry>
+
         <glossentry id='var-UBOOT_ENTRYPOINT'><glossterm><imagedata fileref="figures/define-generic.png" />UBOOT_ENTRYPOINT</glossterm>
             <info>
                UBOOT_ENTRYPOINT[doc] = "Specifies the entry point for the U-Boot image."