summaryrefslogtreecommitdiffstats
path: root/documentation
diff options
context:
space:
mode:
authorScott Rifenbark <srifenbark@gmail.com>2016-07-11 16:04:19 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2016-07-19 15:04:49 +0100
commit444a80a355acf8e3d7a0126506dc6ed65913b039 (patch)
tree0875b8757de27f3f9840c20d3943415dcca9f890 /documentation
parent4fb1961acf6f45df82e68aa7b6e5df83a2ff455e (diff)
downloadpoky-444a80a355acf8e3d7a0126506dc6ed65913b039.tar.gz
ref-manual: Added a new section on setscene task variants
Fixes [YOCTO #9251] I added a new section on the task variants for setscene, which uses the shared state cache. The section describes the BitBake processing that helps the build system to not have to build everything from scratch. (From yocto-docs rev: 6aa0e6b837de14dd7d6c5ef34328bbf268dd6d71) Signed-off-by: Scott Rifenbark <srifenbark@gmail.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation')
-rw-r--r--documentation/ref-manual/closer-look.xml125
1 files changed, 125 insertions, 0 deletions
diff --git a/documentation/ref-manual/closer-look.xml b/documentation/ref-manual/closer-look.xml
index 84ff584bad..e7b423f66f 100644
--- a/documentation/ref-manual/closer-look.xml
+++ b/documentation/ref-manual/closer-look.xml
@@ -1209,6 +1209,131 @@
1209 which includes the environment setup script. 1209 which includes the environment setup script.
1210 </para> 1210 </para>
1211 </section> 1211 </section>
1212
1213 <section id='setscene-tasks-and-shared-state'>
1214 <title>Setscene Tasks and Shared State</title>
1215
1216 <para>
1217 The description of tasks so far assumes that BitBake needs to
1218 build everything and there are no prebuilt objects available.
1219 BitBake does support skipping tasks if prebuilt objects are
1220 available.
1221 These objects are usually made available in the form of a
1222 shared state (sstate) cache.
1223 <note>
1224 For information on variables affecting sstate, see the
1225 <link linkend='var-SSTATE_DIR'><filename>SSTATE_DIR</filename></link>
1226 and
1227 <link linkend='var-SSTATE_MIRRORS'><filename>SSTATE_MIRRORS</filename></link>
1228 variables.
1229 </note>
1230 </para>
1231
1232 <para>
1233 The idea of a setscene task (i.e
1234 <filename>do_</filename><replaceable>taskname</replaceable><filename>_setscene</filename>)
1235 is a version of the task where
1236 instead of building something, BitBake can skip to the end
1237 result and simply place a set of files into specific locations
1238 as needed.
1239 In some cases, it makes sense to have a setscene task variant
1240 (e.g. generating package files in the
1241 <filename>do_package_write_*</filename> task).
1242 In other cases, it does not make sense, (e.g. a
1243 <link linkend='ref-tasks-patch'><filename>do_patch</filename></link>
1244 task or
1245 <link linkend='ref-tasks-unpack'><filename>do_unpack</filename></link>
1246 task) since the work involved would be equal to or greater than
1247 the underlying task.
1248 </para>
1249
1250 <para>
1251 In the OpenEmbedded build system, the common tasks that have
1252 setscene variants are <link linkend='ref-tasks-package'><filename>do_package</filename></link>,
1253 <filename>do_package_write_*</filename>,
1254 <link linkend='ref-tasks-deploy'><filename>do_deploy</filename></link>,
1255 <link linkend='ref-tasks-packagedata'><filename>do_packagedata</filename></link>,
1256 and
1257 <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link>.
1258 Notice that these are most of the tasks whose output is an
1259 end result.
1260 </para>
1261
1262 <para>
1263 The OpenEmbedded build system has knowledge of the relationship
1264 between these tasks and other tasks that precede them.
1265 For example, if BitBake runs
1266 <filename>do_populate_sysroot_setscene</filename> for
1267 something, there is little point in running any of the
1268 <filename>do_fetch</filename>, <filename>do_unpack</filename>,
1269 <filename>do_patch</filename>,
1270 <filename>do_configure</filename>,
1271 <filename>do_compile</filename>, and
1272 <filename>do_install</filename> tasks.
1273 However, if <filename>do_package</filename> needs to be run,
1274 BitBake would need to run those other tasks.
1275 </para>
1276
1277 <para>
1278 It becomes more complicated if everything can come from an
1279 sstate cache because some objects are simply not required at
1280 all.
1281 For example, you do not need a compiler or native tools, such
1282 as quilt, if there is nothing to compile or patch.
1283 If the <filename>do_package_write_*</filename> packages are
1284 available from sstate, BitBake does not need the
1285 <filename>do_package</filename> task data.
1286 </para>
1287
1288 <para>
1289 To handle all these complexities, BitBake runs in two phases.
1290 The first is the "setscene" stage.
1291 During this stage, BitBake first checks the sstate cache for
1292 any targets it is planning to build.
1293 BitBake does a fast check to see if the object exists rather
1294 than a complete download.
1295 If nothing exists, the second phase, which is the setscene
1296 stage, completes and the main build proceeds.
1297 </para>
1298
1299 <para>
1300 If objects are found in the sstate cache, the OpenEmbedded
1301 build system works backwards from the end targets specified
1302 by the user.
1303 For example, if an image is being built, the OpenEmbedded build
1304 system first looks for the packages needed for that image and
1305 the tools needed to construct an image.
1306 If those are available, the compiler is not needed.
1307 Thus, the compiler is not even downloaded.
1308 If something was found to be unavailable, or the download or
1309 setscene task fails, the OpenEmbedded build system then tries
1310 to install dependencies, such as the compiler, from the cache.
1311 </para>
1312
1313 <para>
1314 The availability of objects in the sstate cache is handled by
1315 the function specified by the
1316 <ulink url='&YOCTO_DOCS_BB_URL;#var-BB_HASHCHECK_FUNCTION'><filename>BB_HASHCHECK_FUNCTION</filename></ulink>
1317 variable and returns a list of the objects that are available.
1318 The function specified by the
1319 <ulink url='&YOCTO_DOCS_BB_URL;#var-BB_SETSCENE_DEPVALID'><filename>BB_SETSCENE_DEPVALID</filename></ulink>
1320 variable is the function that determines whether a given
1321 dependency needs to be followed, and whether for any given
1322 relationship the function needs to be passed.
1323 The function returns a True or False value.
1324 </para>
1325
1326 <para>
1327 Once the setscene process completes, the OpenEmbedded build
1328 system has a list of tasks that it believes it can "accelerate"
1329 and therefore does not need to run.
1330 There is a final function call to the function specified by the
1331 <ulink url='&YOCTO_DOCS_BB_URL;#var-BB_SETSCENE_VERIFY_FUNCTION'><filename>BB_SETSCENE_VERIFY_FUNCTION</filename></ulink>
1332 variable that is able to require the tasks to be run that
1333 that the OpenEmbedded build system initially was going to
1334 skip.
1335 </para>
1336 </section>
1212 </section> 1337 </section>
1213 1338
1214 <section id='images-dev-environment'> 1339 <section id='images-dev-environment'>