summaryrefslogtreecommitdiffstats
path: root/documentation/ref-manual/ref-structure.xml
diff options
context:
space:
mode:
authorScott Rifenbark <scott.m.rifenbark@intel.com>2013-09-11 14:44:00 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2013-09-12 16:50:12 +0100
commit89ca97371d07f8516308597fbb21094389de3cb9 (patch)
treec94738e9868e3ac9a864b91dc381c51cb4077ade /documentation/ref-manual/ref-structure.xml
parent3c4f2a611861f2e8d7e7f0f2d25d6e120e9ba45b (diff)
downloadpoky-89ca97371d07f8516308597fbb21094389de3cb9.tar.gz
ref-manual: Added information for OEROOT and build environment
Fixes [YOCTO #4980] Added a new glossary entry for OEROOT. Added significant information to the local.conf and bblayers.conf reference sections to describe how the root build directory is derived. Also, some unrelated formatting to the DL_DIR variable description was mixed in here because I forgot to commit that separatey and it lives in the same variables.xml file. (From yocto-docs rev: c397a31f5b0d3f6257657119a4e81b4fbdc3800c) Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/ref-manual/ref-structure.xml')
-rw-r--r--documentation/ref-manual/ref-structure.xml116
1 files changed, 96 insertions, 20 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'>