[yocto-docs][PATCH 0/5] Documentation updates

[yocto-docs][PATCH 0/5] Documentation updates

[Paul Eggleton]

The following changes since commit 3b1c5858527cba908a5acff1ddc924630cc954b0:

  dev-manual: merged "updating images" into the "working with packages" (2013-04-03 09:12:49 -0700)

are available in the git repository at:

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

Paul Eggleton (5):
  ref-manual: add buildhistory SDK contents collection
  ref-manual: add info on buildhistory SRCREV value collection
  ref-manual: add preamble to buildhistory section on top-level
    contents
  Update layer.conf examples to reflect current practice
  dev-manual: add new bitbake-layers show-cross-depends subcommand

 documentation/bsp-guide/bsp.xml                    |   10 +-
 .../dev-manual/dev-manual-common-tasks.xml         |   30 ++---
 documentation/ref-manual/ref-variables.xml         |    6 +-
 documentation/ref-manual/usingpoky.xml             |  122 ++++++++++++++++++++
 4 files changed, 144 insertions(+), 24 deletions(-)

-- 
1.7.10.4

[yocto-docs][PATCH 1/5] ref-manual: add buildhistory SDK contents collection

[Paul Eggleton]

Buildhistory can now collect information on SDK contents, so add this to
the appropriate section.

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

diff --git a/documentation/ref-manual/usingpoky.xml b/documentation/ref-manual/usingpoky.xml
index de672b5..c8bee36 100644
--- a/documentation/ref-manual/usingpoky.xml
+++ b/documentation/ref-manual/usingpoky.xml
@@ -631,6 +631,68 @@
             </para>
         </section>
 
+        <section id='build-history-sdk-information'>
+            <title>Build History SDK Information</title>
+            <para>
+                Build history collects similar information on the contents
+                of SDKs (for example, <filename>meta-toolchain</filename>
+                or <filename>bitbake -c populate_sdk imagename</filename>)
+                to that which it collects for images.
+                The files produced for each SDK are as follows:
+                <itemizedlist>
+                    <listitem><para><filename>files-in-sdk.txt:</filename>
+                        A list of files in the SDK with permissions,
+                        owner, group, size, and symlink information.
+                        This includes both the host and target parts
+                        of the SDK.
+                        </para></listitem>
+                    <listitem><para><filename>sdk-info.txt:</filename>
+                        A text file containing name-value pairs with information
+                        about the SDK.
+                        See the following listing example for more information.
+                        </para></listitem>
+                    <listitem><para>Under each of the <filename>host</filename> and 
+                        <filename>target</filename> directories (for the portions of the
+                        SDK that run on the host and on the target respectively):
+                        <itemizedlist>
+                            <listitem><para><filename>depends.dot:</filename>
+                                Dependency graph for the SDK that is
+                                compatible with <filename>graphviz</filename>.
+                                </para></listitem>
+                            <listitem><para><filename>installed-package-names.txt:</filename>
+                                A list of installed packages by name only.</para></listitem>
+                            <listitem><para><filename>installed-package-sizes.txt:</filename>
+                                A list of installed packages ordered by size.
+                                </para></listitem>
+                            <listitem><para><filename>installed-packages.txt:</filename>
+                                A list of installed packages with full package
+                                filenames.</para></listitem>
+                            </itemizedlist>
+                        </para></listitem>
+                </itemizedlist>
+            </para>
+
+            <para>
+                Here is an example of <filename>sdk-info.txt</filename>:
+                <literallayout class='monospaced'>
+DISTRO = poky
+DISTRO_VERSION = 1.3+snapshot-20130327
+SDK_NAME = poky-eglibc-i686-arm
+SDK_VERSION = 1.3+snapshot
+SDKMACHINE = 
+SDKIMAGE_FEATURES = dev-pkgs dbg-pkgs
+BAD_RECOMMENDATIONS = 
+SDKSIZE = 352712
+                </literallayout>
+                Other than <filename>SDKSIZE</filename>, which is the
+                total size of the files in the SDK in Kbytes, the
+                name-value pairs are variables that may have influenced the
+                content of the SDK.
+                This information is often useful when you are trying to determine
+                why a change in the package or file listings has occurred.
+            </para>
+        </section>
+
         <section id='examining-build-history-information'>
             <title>Examining Build History Information</title>
 
-- 
1.7.10.4

[yocto-docs][PATCH 2/5] ref-manual: add info on buildhistory SRCREV value collection

[Paul Eggleton]

Buildhistory now collects information on SRCREV values for recipes
fetched from a version control system e.g. Git; additionally a
buildhistory-collect-srcrevs tool is provided to gather this and
convert it to a format suitable for inclusion in global configuration.
Add information on these new features to the appropriate section.

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

diff --git a/documentation/ref-manual/usingpoky.xml b/documentation/ref-manual/usingpoky.xml
index c8bee36..101411c 100644
--- a/documentation/ref-manual/usingpoky.xml
+++ b/documentation/ref-manual/usingpoky.xml
@@ -545,6 +545,58 @@
         busybox-staticdev busybox-locale
                 </literallayout>
             </para>
+
+            <para>
+                Finally, for those recipes that are fetched from a version control
+                system (such as Git) there is a file that lists the source revision(s)
+                specified in the recipe and the actual revision used when building
+                (which may be different when <filename>SRCREV</filename> is set to
+                <filename>${AUTOREV}</filename> for example). Here is an example
+                of one of these files:
+                <filename>buildhistory/packages/emenlow-poky-linux/linux-yocto/latest_srcrev</filename>):
+                <literallayout class='monospaced'>
+     # SRCREV_machine = "b5c37fe6e24eec194bb29d22fdd55d73bcc709bf"
+     SRCREV_machine = "b5c37fe6e24eec194bb29d22fdd55d73bcc709bf"
+     # SRCREV_emgd = "caea08c988e0f41103bbe18eafca20348f95da02"
+     SRCREV_emgd = "caea08c988e0f41103bbe18eafca20348f95da02"
+     # SRCREV_meta = "c2ed0f16fdec628242a682897d5d86df4547cf24"
+     SRCREV_meta = "c2ed0f16fdec628242a682897d5d86df4547cf24"
+                </literallayout>
+                You can use the <filename>buildhistory-collect-srcrevs</filename>
+                command to collect the stored <filename>SRCREV</filename> values
+                from build history and report them in a format suitable for use in
+                global configuration (for example, local.conf or a distro include
+                file) to override floating AUTOREV values to a fixed set of revisions.
+                Here is some example output from this command:
+                <literallayout class='monospaced'>
+     # emenlow-poky-linux
+     SRCREV_machine_pn-linux-yocto = "b5c37fe6e24eec194bb29d22fdd55d73bcc709bf"
+     SRCREV_emgd_pn-linux-yocto = "caea08c988e0f41103bbe18eafca20348f95da02"
+     SRCREV_meta_pn-linux-yocto = "c2ed0f16fdec628242a682897d5d86df4547cf24"
+     # core2-poky-linux
+     SRCREV_pn-kmod = "62081c0f68905b22f375156d4532fd37fa5c8d33"
+     SRCREV_pn-blktrace = "d6918c8832793b4205ed3bfede78c2f915c23385"
+     SRCREV_pn-opkg = "649"
+                </literallayout>
+                Some notes on using the <filename>buildhistory-collect-srcrevs</filename>
+                command:
+                <itemizedlist>
+                    <listitem><para>By default only values where the SRCREV was
+                        not hardcoded (usually when AUTOREV was used) are reported
+                        - use the <filename>-a</filename> option to see all SRCREV
+                        values.</para></listitem>
+                    <listitem><para>The output statements may not have any effect
+                        in the face of overrides applied elsewhere in the build system
+                        configuration; use the <filename>-f</filename> option to add the
+                        <filename>forcevariable</filename> override to each output line
+                        if you need to work around this.</para></listitem>
+                    <listitem><para>The script does not do any special handling for
+                        building for multiple machines; however it does place a
+                        comment before each set of values specifying which triplet
+                        (for example <filename>emenlow-poky-linux</filename>) that they
+                        belong to as shown above.</para></listitem>
+                </itemizedlist>
+            </para>
         </section>
 
         <section id='build-history-image-information'>
-- 
1.7.10.4

[yocto-docs][PATCH 3/5] ref-manual: add preamble to buildhistory section on top-level contents

[Paul Eggleton]

Add a paragraph to the top of the section on buildhistory mentioning the
metadata-revs file and the top-level directories.

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

diff --git a/documentation/ref-manual/usingpoky.xml b/documentation/ref-manual/usingpoky.xml
index 101411c..25a2259 100644
--- a/documentation/ref-manual/usingpoky.xml
+++ b/documentation/ref-manual/usingpoky.xml
@@ -503,6 +503,14 @@
             <imagedata fileref="figures/buildhistory.png" align="center" width="6in" depth="4in" />
         </para>
 
+        <para>At the top level, there is a <filename>metadata-revs</filename> file
+            listing the revisions of the repositories for the layers enabled
+            when the build was produced. The rest of the data is split into separate
+            <filename>packages</filename>, <filename>images</filename> and
+            <filename>sdk</filename> directories, the contents of which are
+            described below.
+        </para>
+
         <section id='build-history-package-information'>
             <title>Build History Package Information</title>
 
-- 
1.7.10.4

[yocto-docs][PATCH 4/5] Update layer.conf examples to reflect current practice

[Paul Eggleton]

* BBFILES should be appended to with +=
* BBPATH should be appended to with .=
* Immediate expansion is not necessary for BBFILE_PRIORITY
* Immediate expansion is not necessary for references in layer.conf
  to LAYERDIR since these are automatically expanded at the end of
  parsing the file (and have been for some time).
* Add collection name override to BBFILE_PRIORITY example
* Fix comments referring to old structure ("packages directory" or
  "recipes directory")

Signed-off-by: Paul Eggleton <paul.eggleton@linux.intel.com>
---
 documentation/bsp-guide/bsp.xml                    |   10 ++++----
 .../dev-manual/dev-manual-common-tasks.xml         |   27 +++++++++-----------
 documentation/ref-manual/ref-variables.xml         |    6 ++---
 3 files changed, 19 insertions(+), 24 deletions(-)

diff --git a/documentation/bsp-guide/bsp.xml b/documentation/bsp-guide/bsp.xml
index 5c34bfd..8c0a344 100644
--- a/documentation/bsp-guide/bsp.xml
+++ b/documentation/bsp-guide/bsp.xml
@@ -312,14 +312,14 @@
             <para>
                <literallayout class='monospaced'>
      # We have a conf and classes directory, add to BBPATH
-     BBPATH := "${BBPATH}:${LAYERDIR}"
+     BBPATH .= ":${LAYERDIR}"
 
-     # We have a recipes directory, add to BBFILES
-     BBFILES := "${BBFILES} ${LAYERDIR}/recipes-*/*.bb \
+     # We have recipes-* directories, add to BBFILES
+     BBFILES += "${LAYERDIR}/recipes-*/*.bb \
                  ${LAYERDIR}/recipes-*/*.bbappend"
 
      BBFILE_COLLECTIONS += "bsp"
-     BBFILE_PATTERN_bsp := "^${LAYERDIR}/"
+     BBFILE_PATTERN_bsp = "^${LAYERDIR}/"
      BBFILE_PRIORITY_bsp = "6"
                 </literallayout>
             </para>
@@ -329,7 +329,7 @@
                 Bay <filename>conf/layer.conf</filename> file:
                <literallayout class='monospaced'>
      BBFILE_COLLECTIONS += "crownbay"
-     BBFILE_PATTERN_crownbay := "^${LAYERDIR}/"
+     BBFILE_PATTERN_crownbay = "^${LAYERDIR}/"
      BBFILE_PRIORITY_crownbay = "6"
                 </literallayout>
             </para>
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index 43dc61f..a697b8c 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -106,14 +106,14 @@
                        required syntax:
                        <literallayout class='monospaced'>
      # We have a conf and classes directory, add to BBPATH
-     BBPATH := "${BBPATH}:${LAYERDIR}"
+     BBPATH .= ":${LAYERDIR}"
 
-     # We have a packages directory, add to BBFILES
-     BBFILES := "${BBFILES} ${LAYERDIR}/recipes-*/*/*.bb \
+     # We have recipes-* directories, add to BBFILES
+     BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \
                  ${LAYERDIR}/recipes-*/*/*.bbappend"
 
      BBFILE_COLLECTIONS += "yoctobsp"
-     BBFILE_PATTERN_yoctobsp := "^${LAYERDIR}/"
+     BBFILE_PATTERN_yoctobsp = "^${LAYERDIR}/"
      BBFILE_PRIORITY_yoctobsp = "5"
                         </literallayout></para>
                         <para>Here is an explanation of the example:
@@ -148,9 +148,9 @@
                                 used to match files from
                                 <filename>BBFILES</filename> into a particular
                                 layer.
-                                In this case, immediate expansion of
+                                In this case,
                                 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-LAYERDIR'>LAYERDIR</ulink></filename>
-                                sets <filename>BBFILE_PATTERN</filename> to the
+                                is used to make <filename>BBFILE_PATTERN</filename> match within the
                                 layer's path.</para></listitem>
                             <listitem><para>The
                                 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_PRIORITY'>BBFILE_PRIORITY</ulink></filename>
@@ -162,10 +162,7 @@
                         </itemizedlist></para>
                         <para>Note the use of the
                         <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-LAYERDIR'>LAYERDIR</ulink></filename>
-                        variable with the immediate expansion operator.
-                        The <filename>LAYERDIR</filename> variable expands to the directory of the current layer and
-                        requires the immediate expansion operator so that BitBake does not wait to expand the variable
-                        when it's parsing a different directory.</para>
+                        variable, which expands to the directory of the current layer.</para>
                         <para>Through the use of the <filename>BBPATH</filename> variable,
                         BitBake locates <filename>.bbclass</filename> files, configuration
                         files, and files that are included with <filename>include</filename>
@@ -402,7 +399,7 @@
                 variable.
                 For example:
                 <literallayout class='monospaced'>
-     BBFILE_PRIORITY := "1"
+     BBFILE_PRIORITY_mylayer = "1"
                 </literallayout>
             </para>
 
@@ -1938,14 +1935,14 @@
                         the <filename>layer.conf</filename> file as follows:
                         <literallayout class='monospaced'>
      # We have a conf and classes directory, add to BBPATH
-     BBPATH := "${BBPATH}:${LAYERDIR}"
+     BBPATH .= ":${LAYERDIR}"
 
-     # We have a packages directory, add to BBFILES
-     BBFILES := "${BBFILES} ${LAYERDIR}/recipes-*/*/*.bb \
+     # We have recipes-* directories, add to BBFILES
+     BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \
                  ${LAYERDIR}/recipes-*/*/*.bbappend"
 
      BBFILE_COLLECTIONS += "mylayer"
-     BBFILE_PATTERN_mylayer := "^${LAYERDIR}/"
+     BBFILE_PATTERN_mylayer = "^${LAYERDIR}/"
      BBFILE_PRIORITY_mylayer = "5"
                          </literallayout>
                          Notice <filename>mylayer</filename> as part of the last three
diff --git a/documentation/ref-manual/ref-variables.xml b/documentation/ref-manual/ref-variables.xml
index f81ab62..a56cdd8 100644
--- a/documentation/ref-manual/ref-variables.xml
+++ b/documentation/ref-manual/ref-variables.xml
@@ -1868,10 +1868,8 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
             <glossdef>
                 <para>When used inside the <filename>layer.conf</filename> configuration
                     file, this variable provides the path of the current layer.
-                    This variable requires immediate expansion
-                    (see the BitBake manual) as lazy expansion can result in
-                    the expansion happening in the wrong directory and therefore
-                    giving the wrong value.</para>
+                    This variable is not available outside of <filename>layer.conf</filename>
+                    and references are expanded immediately when parsing of the file completes.</para>
             </glossdef>
         </glossentry>
 
-- 
1.7.10.4

[yocto-docs][PATCH 5/5] dev-manual: add new bitbake-layers show-cross-depends subcommand

[Paul Eggleton]

Signed-off-by: Paul Eggleton <paul.eggleton@linux.intel.com>
---
 documentation/dev-manual/dev-manual-common-tasks.xml |    3 +++
 1 file changed, 3 insertions(+)

diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index a697b8c..66df375 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -446,6 +446,9 @@
                     <listitem><para><filename><emphasis>show-appends:</emphasis></filename>
                         Lists <filename>.bbappend</filename> files and the recipe files to which
                         they apply.</para></listitem>
+                    <listitem><para><filename><emphasis>show-cross-depends:</emphasis></filename>
+                        Lists dependency relationships between recipes that cross layer boundaries.
+                        </para></listitem>
                     <listitem><para><filename><emphasis>flatten:</emphasis></filename>
                         Flattens the layer configuration into a separate output directory.
                         Flattening your layer configuration builds a "flattened" directory that contains
-- 
1.7.10.4