summaryrefslogtreecommitdiffstats
path: root/documentation/ref-manual/ref-classes.xml
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/ref-manual/ref-classes.xml')
-rw-r--r--documentation/ref-manual/ref-classes.xml145
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 @@
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