diff options
-rw-r--r-- | documentation/dev-manual/dev-manual-common-tasks.xml | 50 | ||||
-rw-r--r-- | documentation/ref-manual/ref-variables.xml | 70 |
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." |