Documentation updates
cover Documentation updates
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(-)
Signature · 1 line
1.7.10.4
PATCH 1/5 ref-manual: add buildhistory SDK contents collection
Buildhistory can now collect information on SDK contents, so add this to the appropriate section.
--- documentation/ref-manual/usingpoky.xml | 62 ++++++++++++++++++++++++++++++++ 1 file changed, 62 insertions(+)
documentation/ref-manual/usingpoky.xml +62 -0
@@ -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>
Signature · 1 line
1.7.10.4
PATCH 2/5 ref-manual: add info on buildhistory SRCREV value collection
In reply to Paul EggletonBuildhistory 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.
--- documentation/ref-manual/usingpoky.xml | 52 ++++++++++++++++++++++++++++++++ 1 file changed, 52 insertions(+)
documentation/ref-manual/usingpoky.xml +52 -0
@@ -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'>
Signature · 1 line
1.7.10.4
PATCH 3/5 ref-manual: add preamble to buildhistory section on top-level contents
In reply to Paul EggletonAdd a paragraph to the top of the section on buildhistory mentioning the metadata-revs file and the top-level directories.
--- documentation/ref-manual/usingpoky.xml | 8 ++++++++ 1 file changed, 8 insertions(+)
documentation/ref-manual/usingpoky.xml +8 -0
@@ -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>
Signature · 1 line
1.7.10.4
PATCH 4/5 Update layer.conf examples to reflect current practice
In reply to 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")
--- 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(-)
documentation/bsp-guide/bsp.xml +5 -5
@@ -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>
documentation/dev-manual/dev-manual-common-tasks.xml +12 -15
@@ -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
documentation/ref-manual/ref-variables.xml +2 -4
@@ -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>
Signature · 1 line
1.7.10.4
PATCH 5/5 dev-manual: add new bitbake-layers show-cross-depends subcommand
In reply to Paul Eggleton--- documentation/dev-manual/dev-manual-common-tasks.xml | 3 +++ 1 file changed, 3 insertions(+)
documentation/dev-manual/dev-manual-common-tasks.xml +3 -0
@@ -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
Signature · 1 line
1.7.10.4