From 8a8349be290e9b13bc400013b094e05d3a716ecb Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Thu, 22 Sep 2016 14:27:04 -0700 Subject: [PATCH] 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 Signed-off-by: Richard Purdie --- .../dev-manual/dev-manual-common-tasks.xml | 50 +++++++++++++ documentation/ref-manual/ref-variables.xml | 70 +++++++++++++++++++ 2 files changed, 120 insertions(+) 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 @@ +
+ Sharing Files Between Recipes + + + 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. + + 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. + + + + + Recipes should never populate the sysroot directly (i.e. write + files into sysroot). + Instead, files should be installed into standard locations + during the + do_install + task within the + ${D} + 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. + + + + For information on variables you can use to help control how + files sysroot is populated, see the + SYSROOT_DIRS, + SYSROOT_DIRS_NATIVE, + and + SYSROOT_DIRS_BLACKLIST + variables. + +
+
Properly Versioning Pre-Release Recipes 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" + SYSROOT_DIRS + + SYSROOT_DIRS[doc] = "Directories that are staged in the sysroot." + + + + + Directories that are staged in the sysroot. + By default, the following directories are staged: + + SYSROOT_DIRS = " \ + ${includedir} \ + ${libdir} \ + ${base_libdir} \ + ${nonarch_base_libdir} \ + ${datadir} \ + " + + + + + + SYSROOT_DIRS_BLACKLIST + + SYSROOT_DIRS_BLACKLIST[doc] = "Directories that should not be staged into sysroot." + + + + + Directories that should not be staged into sysroot. + By default, the following directories are not staged: + + SYSROOT_DIRS_BLACKLIST = " \ + ${mandir} \ + ${docdir} \ + ${infodir} \ + ${datadir}/locale \ + ${datadir}/applications \ + ${datadir}/fonts \ + ${datadir}/pixmaps \ + " + + + + + + SYSROOT_DIRS_NATIVE + + SYSROOT_DIRS_NATIVE[doc] = "Extra directories staged for native into sysroot." + + + + + Extra directories staged for native into sysroot. + By default, the following directories are staged: + + SYSROOT_DIRS_NATIVE = " \ + ${bindir} \ + ${sbindir} \ + ${base_bindir} \ + ${base_sbindir} \ + ${libexecdir} \ + ${sysconfdir} \ + ${localstatedir} \ + " + + + + + SYSROOT_PREPROCESS_FUNCS 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."