summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--documentation/ref-manual/ref-structure.xml116
-rw-r--r--documentation/ref-manual/ref-variables.xml53
2 files changed, 135 insertions, 34 deletions
diff --git a/documentation/ref-manual/ref-structure.xml b/documentation/ref-manual/ref-structure.xml
index 3133e8dc6d..13803f5a41 100644
--- a/documentation/ref-manual/ref-structure.xml
+++ b/documentation/ref-manual/ref-structure.xml
@@ -334,48 +334,124 @@
334 <title><filename>build/conf/local.conf</filename></title> 334 <title><filename>build/conf/local.conf</filename></title>
335 335
336 <para> 336 <para>
337 This file contains all the local user configuration for your build environment. 337 This configuration file contains all the local user configurations
338 If there is no <filename>local.conf</filename> present, it is created from 338 for your build environment.
339 <filename>local.conf.sample</filename>. 339 The <filename>local.conf</filename> file contains documentation on
340 The <filename>local.conf</filename> file contains documentation on the various configuration options. 340 the various configuration options.
341 Any variable set here overrides any variable set elsewhere within the environment unless 341 Any variable set here overrides any variable set elsewhere within
342 that variable is hard-coded within a file (e.g. by using '=' instead of '?='). 342 the environment unless that variable is hard-coded within a file
343 Some variables are hard-coded for various reasons but these variables are 343 (e.g. by using '=' instead of '?=').
344 relatively rare. 344 Some variables are hard-coded for various reasons but these
345 variables are relatively rare.
345 </para> 346 </para>
346 347
347 <para> 348 <para>
348 Edit this file to set the <filename><link linkend='var-MACHINE'>MACHINE</link></filename> 349 Edit this file to set the
350 <filename><link linkend='var-MACHINE'>MACHINE</link></filename>
349 for which you want to build, which package types you wish to use 351 for which you want to build, which package types you wish to use
350 (<link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>), 352 (<link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>),
351 the location from which you want to downloaded files 353 the location from which you want to downloaded files
352 (<filename><link linkend='var-DL_DIR'>DL_DIR</link></filename>), 354 (<filename><link linkend='var-DL_DIR'>DL_DIR</link></filename>),
353 and how you want your host machine to use resources 355 and how you want your host machine to use resources
354 (<link linkend='var-BB_NUMBER_THREADS'><filename>BB_NUMBER_THREADS</filename></link> and 356 (<link linkend='var-BB_NUMBER_THREADS'><filename>BB_NUMBER_THREADS</filename></link>
357 and
355 <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link>). 358 <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link>).
356 </para> 359 </para>
360
361 <para>
362 If <filename>local.conf</filename> is not present when you
363 start the build, the OpenEmbedded build system creates it from
364 <filename>local.conf.sample</filename> when
365 you <filename>source</filename> the top-level build environment
366 setup script (i.e.
367 <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>
368 or
369 <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>).
370 </para>
371
372 <para>
373 The source <filename>local.conf.sample</filename> file used
374 depends on the <filename>$TEMPLATECONF</filename> script variable,
375 which defaults to <filename>/meta-yocto/conf</filename>
376 when you are building from the Yocto Project development
377 environment and defaults to <filename>/meta/conf</filename> when
378 you are building from the OpenEmbedded Core environment.
379 Because the script variable points to the source of the
380 <filename>local.conf.sample</filename> file, this implies that
381 you can configure your build environment from any layer by setting
382 the variable in the top-level build environment setup script as
383 follows:
384 <literallayout class='monospaced'>
385 TEMPLATECONF=&lt;your_layer&gt;/conf
386 </literallayout>
387 Once the build process gets the sample file, it uses
388 <filename>sed</filename> to substitute final
389 <filename>${</filename><link linkend='var-OEROOT'><filename>OEROOT</filename></link><filename>}</filename>
390 values for all <filename>##OEROOT##</filename> values.
391 <note>
392 You can see how the <filename>TEMPLATECONF</filename> variable
393 is used by looking at the
394 <filename>/scripts/oe-setup-builddir</filename> script in the
395 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
396 You can find the Yocto Project version of the
397 <filename>local.conf.sample</filename> file in the
398 <filename>/meta-yocto/conf</filename> directory.
399 </note>
400 </para>
357 </section> 401 </section>
358 402
359 <section id='structure-build-conf-bblayers.conf'> 403 <section id='structure-build-conf-bblayers.conf'>
360 <title><filename>build/conf/bblayers.conf</filename></title> 404 <title><filename>build/conf/bblayers.conf</filename></title>
361 405
362 <para> 406 <para>
363 This file defines 407 This configuration file defines
364 <ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>layers</ulink>, 408 <ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>layers</ulink>,
365 which are directory trees, traversed (or walked) by BitBake. 409 which are directory trees, traversed (or walked) by BitBake.
366 If <filename>bblayers.conf</filename>
367 is not present, it is created from <filename>bblayers.conf.sample</filename> when
368 you <filename>source</filename> the environment setup script.
369 </para>
370
371 <para>
372 The <filename>bblayers.conf</filename> file uses the 410 The <filename>bblayers.conf</filename> file uses the
373 <link linkend='var-BBLAYERS'><filename>BBLAYERS</filename></link> variable to 411 <link linkend='var-BBLAYERS'><filename>BBLAYERS</filename></link>
374 list the layers BitBake tries to find. 412 variable to list the layers BitBake tries to find, and uses the
375 The file uses the
376 <link linkend='var-BBLAYERS_NON_REMOVABLE'><filename>BBLAYERS_NON_REMOVABLE</filename></link> 413 <link linkend='var-BBLAYERS_NON_REMOVABLE'><filename>BBLAYERS_NON_REMOVABLE</filename></link>
377 variable to list layers that must not be removed. 414 variable to list layers that must not be removed.
378 </para> 415 </para>
416
417 <para>
418 If <filename>bblayers.conf</filename> is not present when you
419 start the build, the OpenEmbedded build system creates it from
420 <filename>bblayers.conf.sample</filename> when
421 you <filename>source</filename> the top-level build environment
422 setup script (i.e.
423 <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>
424 or
425 <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>).
426 </para>
427
428 <para>
429 The source <filename>bblayers.conf.sample</filename> file used
430 depends on the <filename>$TEMPLATECONF</filename> script variable,
431 which defaults to <filename>/meta-yocto/conf</filename>
432 when you are building from the Yocto Project development
433 environment and defaults to <filename>/meta/conf</filename> when
434 you are building from the OpenEmbedded Core environment.
435 Because the script variable points to the source of the
436 <filename>bblayers.conf.sample</filename> file, this implies that
437 you can base your build from any layer by setting the variable in
438 the top-level build environment setup script as follows:
439 <literallayout class='monospaced'>
440 TEMPLATECONF=&lt;your_layer&gt;/conf
441 </literallayout>
442 Once the build process gets the sample file, it uses
443 <filename>sed</filename> to substitute final
444 <filename>${</filename><link linkend='var-OEROOT'><filename>OEROOT</filename></link><filename>}</filename>
445 values for all <filename>##OEROOT##</filename> values.
446 <note>
447 You can see how the <filename>TEMPLATECONF</filename> variable
448 <filename>/scripts/oe-setup-builddir</filename> script in the
449 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
450 You can find the Yocto Project version of the
451 <filename>bblayers.conf.sample</filename> file in the
452 <filename>/meta-yocto/conf</filename> directory.
453 </note>
454 </para>
379 </section> 455 </section>
380 456
381 <section id='structure-build-conf-sanity_info'> 457 <section id='structure-build-conf-sanity_info'>
diff --git a/documentation/ref-manual/ref-variables.xml b/documentation/ref-manual/ref-variables.xml
index b3562db578..764c8072da 100644
--- a/documentation/ref-manual/ref-variables.xml
+++ b/documentation/ref-manual/ref-variables.xml
@@ -1230,37 +1230,40 @@ Core layer for images cannot be removed
1230 <glossentry id='var-DL_DIR'><glossterm>DL_DIR</glossterm> 1230 <glossentry id='var-DL_DIR'><glossterm>DL_DIR</glossterm>
1231 <glossdef> 1231 <glossdef>
1232 <para> 1232 <para>
1233 The central download directory used by the build process to store downloads. 1233 The central download directory used by the build process to
1234 You can set this directory by defining the <filename>DL_DIR</filename> 1234 store downloads.
1235 variable in the <filename>/conf/local.conf</filename> file. 1235 You can set this directory by defining the
1236 <filename>DL_DIR</filename> variable in the
1237 <filename>/conf/local.conf</filename> file.
1236 This directory is self-maintaining and you should not have 1238 This directory is self-maintaining and you should not have
1237 to touch it. 1239 to touch it.
1238 By default, the directory is <filename>downloads</filename> in the 1240 By default, the directory is <filename>downloads</filename>
1241 in the
1239 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>. 1242 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
1240 <literallayout class='monospaced'> 1243 <literallayout class='monospaced'>
1241 #DL_DIR ?= "${TOPDIR}/downloads" 1244 #DL_DIR ?= "${TOPDIR}/downloads"
1242 </literallayout> 1245 </literallayout>
1243 To specify a different download directory, simply uncomment the line 1246 To specify a different download directory, simply remove
1244 and provide your directory. 1247 the comment from the line and provide your directory.
1245 </para> 1248 </para>
1246 1249
1247 <para> 1250 <para>
1248 During a first build, the system downloads many different source code 1251 During a first build, the system downloads many different
1249 tarballs from various upstream projects. 1252 source code tarballs from various upstream projects.
1250 Downloading can take a while, particularly if your network 1253 Downloading can take a while, particularly if your network
1251 connection is slow. 1254 connection is slow.
1252 Tarballs are all stored in the directory defined by 1255 Tarballs are all stored in the directory defined by
1253 <filename>DL_DIR</filename> and the build system looks there first 1256 <filename>DL_DIR</filename> and the build system looks there
1254 to find source tarballs. 1257 first to find source tarballs.
1255 <note> 1258 <note>
1256 When wiping and rebuilding, you can preserve this directory to speed 1259 When wiping and rebuilding, you can preserve this
1257 up this part of subsequent builds. 1260 directory to speed up this part of subsequent builds.
1258 </note> 1261 </note>
1259 </para> 1262 </para>
1260 1263
1261 <para> 1264 <para>
1262 You can safely share this directory between multiple builds on the 1265 You can safely share this directory between multiple builds
1263 same development machine. 1266 on the same development machine.
1264 For additional information on how the build process gets 1267 For additional information on how the build process gets
1265 source files when working behind a firewall or proxy server, 1268 source files when working behind a firewall or proxy server,
1266 see this specific question in the 1269 see this specific question in the
@@ -3353,6 +3356,28 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
3353 </glossdef> 3356 </glossdef>
3354 </glossentry> 3357 </glossentry>
3355 3358
3359 <glossentry id='var-OEROOT'><glossterm>OEROOT</glossterm>
3360 <glossdef>
3361 <para>
3362 The directory from which the top-level build environment
3363 setup script is sourced.
3364 The Yocto Project makes two top-level build environment
3365 setup scripts available:
3366 <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>
3367 and
3368 <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>.
3369 When you run one of these scripts, the
3370 <filename>OEROOT</filename> variable resolves to the
3371 directory that holds the script.
3372 </para>
3373
3374 <para>
3375 For additional information on how this variable is used,
3376 see the initialization scripts.
3377 </para>
3378 </glossdef>
3379 </glossentry>
3380
3356 <glossentry id='var-OLDEST_KERNEL'><glossterm>OLDEST_KERNEL</glossterm> 3381 <glossentry id='var-OLDEST_KERNEL'><glossterm>OLDEST_KERNEL</glossterm>
3357 <glossdef> 3382 <glossdef>
3358 <para> 3383 <para>