aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorScott Rifenbark <srifenbark@gmail.com>2016-09-22 14:27:04 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2016-09-28 15:02:33 +0100
commit8a8349be290e9b13bc400013b094e05d3a716ecb (patch)
tree0327d89f98adc1428cb2d40d274da1f6dfad7fc0
parent1c594557f7369232ece6e7a2e471e9850a097fa7 (diff)
downloadopenembedded-core-contrib-8a8349be290e9b13bc400013b094e05d3a716ecb.tar.gz
openembedded-core-contrib-8a8349be290e9b13bc400013b094e05d3a716ecb.tar.bz2
openembedded-core-contrib-8a8349be290e9b13bc400013b094e05d3a716ecb.zip
ref-manual, dev-manual: Updates for "staging" discussion and variables.
Fixes [YOCTO #8631] These fixes cover the following: * New glossary entry for SYSROOT_DIRS * New glossary entry for SYSROOT_DIRS_NATIVE * New glossary entry for SYSROOT_DIRS_BLACKLIST * New section titled "Sharing Files Between Recipes" in the dev-manual's "Writing a New Recipe" section. (From yocto-docs rev: e541a3c8967f51b903d9dd7978009f4fa7c2f014) Signed-off-by: Scott Rifenbark <srifenbark@gmail.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
-rw-r--r--documentation/dev-manual/dev-manual-common-tasks.xml50
-rw-r--r--documentation/ref-manual/ref-variables.xml70
2 files changed, 120 insertions, 0 deletions
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index 3c2012cf19..5e77516144 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -2875,6 +2875,56 @@
</para>
</section>
+ <section id='new-sharing-files-between-recipes'>
+ <title>Sharing Files Between Recipes</title>
+
+ <para>
+ Recipes often need to use files provided by other recipes on
+ the build host.
+ For example, an application linking to a common library needs
+ access to the library itself and its associated headers.
+ The way this access is accomplished is by populating sysroot
+ with files.
+ One sysroot exists per "machine" for which the image is
+ being built.
+ In practical terms, this means a sysroot exists for the target
+ machine, and a sysroot exists for the build host.
+ <note>
+ You could find the term "staging" used within the Yocto
+ project regarding files populating sysroot.
+ The term "staging" was used for previous releases of
+ the Yocto Project.
+ </note>
+ </para>
+
+ <para>
+ Recipes should never populate the sysroot directly (i.e. write
+ files into sysroot).
+ Instead, files should be installed into standard locations
+ during the
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-install'><filename>do_install</filename></ulink>
+ task within the
+ <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-D'><filename>D</filename></ulink><filename>}</filename>
+ directory.
+ A subset of these files automatically populates the sysroot.
+ The reason for this limitation is that almost all files that
+ populate the sysroot are cataloged in manifests in order to
+ ensure the files can be removed later when a recipe is either
+ modified or removed.
+ Thus, the sysroot is able to remain free from stale files.
+ </para>
+
+ <para>
+ For information on variables you can use to help control how
+ files sysroot is populated, see the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-SYSROOT_DIRS'><filename>SYSROOT_DIRS</filename></ulink>,
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-SYSROOT_DIRS_NATIVE'><filename>SYSROOT_DIRS_NATIVE</filename></ulink>,
+ and
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-SYSROOT_DIRS_BLACKLIST'><filename>SYSROOT_DIRS_BLACKLIST</filename></ulink>
+ variables.
+ </para>
+ </section>
+
<section id='properly-versioning-pre-release-recipes'>
<title>Properly Versioning Pre-Release Recipes</title>
diff --git a/documentation/ref-manual/ref-variables.xml b/documentation/ref-manual/ref-variables.xml
index 99f3e03446..1ec804d100 100644
--- a/documentation/ref-manual/ref-variables.xml
+++ b/documentation/ref-manual/ref-variables.xml
@@ -13095,6 +13095,76 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
</glossdef>
</glossentry>
+ <glossentry id='var-SYSROOT_DIRS'><glossterm>SYSROOT_DIRS</glossterm>
+ <info>
+ SYSROOT_DIRS[doc] = "Directories that are staged in the sysroot."
+ </info>
+ <glossdef>
+ <para role="glossdeffirst">
+<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
+ Directories that are staged in the sysroot.
+ By default, the following directories are staged:
+ <literallayout class='monospaced'>
+ SYSROOT_DIRS = " \
+ ${includedir} \
+ ${libdir} \
+ ${base_libdir} \
+ ${nonarch_base_libdir} \
+ ${datadir} \
+ "
+ </literallayout>
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-SYSROOT_DIRS_BLACKLIST'><glossterm>SYSROOT_DIRS_BLACKLIST</glossterm>
+ <info>
+ SYSROOT_DIRS_BLACKLIST[doc] = "Directories that should not be staged into sysroot."
+ </info>
+ <glossdef>
+ <para role="glossdeffirst">
+<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
+ Directories that should not be staged into sysroot.
+ By default, the following directories are not staged:
+ <literallayout class='monospaced'>
+ SYSROOT_DIRS_BLACKLIST = " \
+ ${mandir} \
+ ${docdir} \
+ ${infodir} \
+ ${datadir}/locale \
+ ${datadir}/applications \
+ ${datadir}/fonts \
+ ${datadir}/pixmaps \
+ "
+ </literallayout>
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-SYSROOT_DIRS_NATIVE'><glossterm>SYSROOT_DIRS_NATIVE</glossterm>
+ <info>
+ SYSROOT_DIRS_NATIVE[doc] = "Extra directories staged for native into sysroot."
+ </info>
+ <glossdef>
+ <para role="glossdeffirst">
+<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
+ Extra directories staged for native into sysroot.
+ By default, the following directories are staged:
+ <literallayout class='monospaced'>
+ SYSROOT_DIRS_NATIVE = " \
+ ${bindir} \
+ ${sbindir} \
+ ${base_bindir} \
+ ${base_sbindir} \
+ ${libexecdir} \
+ ${sysconfdir} \
+ ${localstatedir} \
+ "
+ </literallayout>
+ </para>
+ </glossdef>
+ </glossentry>
+
<glossentry id='var-SYSROOT_PREPROCESS_FUNCS'><glossterm>SYSROOT_PREPROCESS_FUNCS</glossterm>
<info>
SYSROOT_PREPROCESS_FUNCS[doc] = "A list of functions to execute after files are staged into the sysroot. These functions are usually used to apply additional processing on the staged files, or to stage additional files."