1 files changed, 138 insertions, 7 deletions
diff --git a/documentation/ref-manual/ref-classes.xml b/documentation/ref-manual/ref-classes.xml
index 3d9fbf695d..8f25c521c6 100644
--- a/documentation/ref-manual/ref-classes.xml
+++ b/documentation/ref-manual/ref-classes.xml
@@ -3190,13 +3190,144 @@
    <title><filename>staging.bbclass</filename></title>
    <para>
-        The <filename>staging</filename> class provides the
+        The <filename>staging</filename> class installs files into individual
-        <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link>
+        recipe work directories for sysroots.
-        task, which stages files into the sysroot to make them available to
+        The class contains the following key tasks:
-        other recipes at build time.
+        <itemizedlist>
-        The class is enabled by default because it is inherited by the
+            <listitem><para>
-        <link linkend='ref-classes-base'><filename>base</filename></link>
+                The
-        class.
+                <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link>
+                task, which is responsible for handing the files that end up
+                in the recipe sysroots.
+                </para></listitem>
+            <listitem><para>
+                The
+                <link linkend='ref-tasks-prepare_recipe_sysroot'><filename>do_prepare_recipe_sysroot</filename></link>
+                task (a "partner" task to the
+                <filename>populate_sysroot</filename> task), which installs
+                the files into the individual recipe work directories (i.e.
+                <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>).
+                </para></listitem>
+        </itemizedlist>
+    </para>
+    <para>
+        The code in the <filename>staging</filename> class is complex and
+        basically works in two stages:
+        <itemizedlist>
+            <listitem><para>
+                <emphasis>Stage One:</emphasis>
+                The first stage addresses recipes that have files they want
+                to share with other recipes that have dependencies on the
+                originating recipe.
+                Normally these dependencies are installed through the
+                <link linkend='ref-tasks-install'><filename>do_install</filename></link>
+                task into
+                <filename>${</filename><link linkend='var-D'><filename>D</filename></link><filename>}</filename>.
+                The <filename>do_populate_sysroot</filename> task copies
+                a subset of these files into
+                <filename>${SYSROOT_DESTDIR}</filename>.
+                This subset of files is controlled by the
+                <link linkend='var-SYSROOT_DIRS'><filename>SYSROOT_DIRS</filename></link>,
+                <link linkend='var-SYSROOT_DIRS_NATIVE'><filename>SYSROOT_DIRS_NATIVE</filename></link>,
+                and
+                <link linkend='var-SYSROOT_DIRS_BLACKLIST'><filename>SYSROOT_DIRS_BLACKLIST</filename></link>
+                variables.
+                <note>
+                    Additionally, a recipe can customize the files further by
+                declaring a processing function in the
+                    <link linkend='var-SYSROOT_PREPROCESS_FUNCS'><filename>SYSROOT_PREPROCESS_FUNCS</filename></link>
+                    variable.
+                </note>
+                </para>
+                <para>
+                A shared state (sstate) object is built from these files
+                and the files are placed into a subdirectory of
+                <filename>tmp/sysroot-components/</filename>.
+                The files are scanned for hardcoded paths to the original
+                installation location.
+                If the location is found in text files, the hardcoded
+                locations are replaced by tokens and a list of the files
+                needing such replacements is created.
+                These adjustments are referred to as "FIXMEs".
+                The list of files that are scanned for paths is controlled by
+                the
+                <link linkend='var-SSTATE_SCAN_FILES'><filename>SSTATE_SCAN_FILES</filename></link>
+                variable.
+                </para></listitem>
+            <listitem><para>
+                <emphasis>Stage Two:</emphasis>
+                The second stage addresses recipes that want to use something
+                from another recipe and declare a dependency on that recipe
+                through the
+                <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>
+                variable.
+                The recipe will have a
+                <link linkend='ref-tasks-prepare_recipe_sysroot'><filename>do_prepare_recipe_sysroot</filename></link>
+                task and when
+                this task executes, it creates the
+                <filename>recipe-sysroot</filename> and
+                <filename>recipe-sysroot-native</filename> in the recipe
+                work directory (i.e.
+                <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>.
+                The OpenEmbedded build system creates hard links to copies of the
+                relevant files from <filename>sysroot-components</filename>
+                into the recipe work directory.
+                <note>
+                    If hard links are not possible, the build system uses
+                    actual copies.
+                </note>
+                The build system then addresses any "FIXMEs" to paths as
+                defined from the list created in the first stage.
+                </para>
+                <para>
+                Finally, any files in <filename>${bindir}</filename>
+                within the sysroot that have the prefix
+                "<filename>postinst-</filename>" are executed.
+                <note>
+                    Although these files are not recommended for general use,
+                    the files do allow some issues such as user creation
+                    and module indexes to be addressed.
+                </note>
+                </para>
+                <para>
+                Because recipes can have other dependencies outside of
+                <filename>DEPENDS</filename> (e.g.
+                <filename>do_unpack[depends] += "tar-native:do_populate_sysroot"</filename>),
+                the sysroot creation function
+                <filename>extend_recipe_sysroot</filename> is also added as
+                a pre-function for those tasks whose dependencies are not
+                through <filename>DEPENDS</filename> but operate similarly.
+                </para>
+                <para>
+                When installing dependencies into the sysroot, the code
+                traverses the dependency graph and processes dependencies
+                in exactly the same way as the dependencies would or would not
+                be when installed from sstate.
+                This processing means, for example, a native tool would have
+                its native dependencies added but a target library would not
+                have its dependencies traversed or installed.
+                The same sstate dependency code is used so that
+                builds should be identical regardless of whether sstate
+                was used or not.
+                For a closer look, see the
+                <filename>setscene_depvalid()</filename> function in the
+                <link linkend='ref-classes-sstate'><filename>sstate</filename></link>
+                class.
+                </para>
+                <para>
+                The build system is careful to maintain manifests of the files
+                it installs so that any given dependency can be installed as
+                needed.
+                The sstate hash of the installed item is also stored so that
+                if it changes, the build system can reinstall it.
+                </para></listitem>
+        </itemizedlist>
    </para>
 </section>

diff --git a/documentation/ref-manual/ref-classes.xml b/documentation/ref-manual/ref-classes.xml index 3d9fbf695d..8f25c521c6 100644 --- a/documentation/ref-manual/ref-classes.xml +++ b/documentation/ref-manual/ref-classes.xml
@@ -3190,13 +3190,144 @@
3190	<title><filename>staging.bbclass</filename></title>	3190	<title><filename>staging.bbclass</filename></title>
3191		3191
3192	<para>	3192	<para>
3193	The <filename>staging</filename> class provides the	3193	The <filename>staging</filename> class installs files into individual
3194	<link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link>	3194	recipe work directories for sysroots.
3195	task, which stages files into the sysroot to make them available to	3195	The class contains the following key tasks:
3196	other recipes at build time.	3196	<itemizedlist>
3197	The class is enabled by default because it is inherited by the	3197	<listitem><para>
3198	<link linkend='ref-classes-base'><filename>base</filename></link>	3198	The
3199	class.	3199	<link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link>
		3200	task, which is responsible for handing the files that end up
		3201	in the recipe sysroots.
		3202	</para></listitem>
		3203	<listitem><para>
		3204	The
		3205	<link linkend='ref-tasks-prepare_recipe_sysroot'><filename>do_prepare_recipe_sysroot</filename></link>
		3206	task (a "partner" task to the
		3207	<filename>populate_sysroot</filename> task), which installs
		3208	the files into the individual recipe work directories (i.e.
		3209	<link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>).
		3210	</para></listitem>
		3211	</itemizedlist>
		3212	</para>
		3213
		3214	<para>
		3215	The code in the <filename>staging</filename> class is complex and
		3216	basically works in two stages:
		3217	<itemizedlist>
		3218	<listitem><para>
		3219	<emphasis>Stage One:</emphasis>
		3220	The first stage addresses recipes that have files they want
		3221	to share with other recipes that have dependencies on the
		3222	originating recipe.
		3223	Normally these dependencies are installed through the
		3224	<link linkend='ref-tasks-install'><filename>do_install</filename></link>
		3225	task into
		3226	<filename>${</filename><link linkend='var-D'><filename>D</filename></link><filename>}</filename>.
		3227	The <filename>do_populate_sysroot</filename> task copies
		3228	a subset of these files into
		3229	<filename>${SYSROOT_DESTDIR}</filename>.
		3230	This subset of files is controlled by the
		3231	<link linkend='var-SYSROOT_DIRS'><filename>SYSROOT_DIRS</filename></link>,
		3232	<link linkend='var-SYSROOT_DIRS_NATIVE'><filename>SYSROOT_DIRS_NATIVE</filename></link>,
		3233	and
		3234	<link linkend='var-SYSROOT_DIRS_BLACKLIST'><filename>SYSROOT_DIRS_BLACKLIST</filename></link>
		3235	variables.
		3236	<note>
		3237	Additionally, a recipe can customize the files further by
		3238	declaring a processing function in the
		3239	<link linkend='var-SYSROOT_PREPROCESS_FUNCS'><filename>SYSROOT_PREPROCESS_FUNCS</filename></link>
		3240	variable.
		3241	</note>
		3242	</para>
		3243
		3244	<para>
		3245	A shared state (sstate) object is built from these files
		3246	and the files are placed into a subdirectory of
		3247	<filename>tmp/sysroot-components/</filename>.
		3248	The files are scanned for hardcoded paths to the original
		3249	installation location.
		3250	If the location is found in text files, the hardcoded
		3251	locations are replaced by tokens and a list of the files
		3252	needing such replacements is created.
		3253	These adjustments are referred to as "FIXMEs".
		3254	The list of files that are scanned for paths is controlled by
		3255	the
		3256	<link linkend='var-SSTATE_SCAN_FILES'><filename>SSTATE_SCAN_FILES</filename></link>
		3257	variable.
		3258	</para></listitem>
		3259	<listitem><para>
		3260	<emphasis>Stage Two:</emphasis>
		3261	The second stage addresses recipes that want to use something
		3262	from another recipe and declare a dependency on that recipe
		3263	through the
		3264	<link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>
		3265	variable.
		3266	The recipe will have a
		3267	<link linkend='ref-tasks-prepare_recipe_sysroot'><filename>do_prepare_recipe_sysroot</filename></link>
		3268	task and when
		3269	this task executes, it creates the
		3270	<filename>recipe-sysroot</filename> and
		3271	<filename>recipe-sysroot-native</filename> in the recipe
		3272	work directory (i.e.
		3273	<link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>.
		3274	The OpenEmbedded build system creates hard links to copies of the
		3275	relevant files from <filename>sysroot-components</filename>
		3276	into the recipe work directory.
		3277	<note>
		3278	If hard links are not possible, the build system uses
		3279	actual copies.
		3280	</note>
		3281	The build system then addresses any "FIXMEs" to paths as
		3282	defined from the list created in the first stage.
		3283	</para>
		3284
		3285	<para>
		3286	Finally, any files in <filename>${bindir}</filename>
		3287	within the sysroot that have the prefix
		3288	"<filename>postinst-</filename>" are executed.
		3289	<note>
		3290	Although these files are not recommended for general use,
		3291	the files do allow some issues such as user creation
		3292	and module indexes to be addressed.
		3293	</note>
		3294	</para>
		3295
		3296	<para>
		3297	Because recipes can have other dependencies outside of
		3298	<filename>DEPENDS</filename> (e.g.
		3299	<filename>do_unpack[depends] += "tar-native:do_populate_sysroot"</filename>),
		3300	the sysroot creation function
		3301	<filename>extend_recipe_sysroot</filename> is also added as
		3302	a pre-function for those tasks whose dependencies are not
		3303	through <filename>DEPENDS</filename> but operate similarly.
		3304	</para>
		3305
		3306	<para>
		3307	When installing dependencies into the sysroot, the code
		3308	traverses the dependency graph and processes dependencies
		3309	in exactly the same way as the dependencies would or would not
		3310	be when installed from sstate.
		3311	This processing means, for example, a native tool would have
		3312	its native dependencies added but a target library would not
		3313	have its dependencies traversed or installed.
		3314	The same sstate dependency code is used so that
		3315	builds should be identical regardless of whether sstate
		3316	was used or not.
		3317	For a closer look, see the
		3318	<filename>setscene_depvalid()</filename> function in the
		3319	<link linkend='ref-classes-sstate'><filename>sstate</filename></link>
		3320	class.
		3321	</para>
		3322
		3323	<para>
		3324	The build system is careful to maintain manifests of the files
		3325	it installs so that any given dependency can be installed as
		3326	needed.
		3327	The sstate hash of the installed item is also stored so that
		3328	if it changes, the build system can reinstall it.
		3329	</para></listitem>
		3330	</itemizedlist>
3200	</para>	3331	</para>
3201	</section>	3332	</section>
3202		3333