diff options
Diffstat (limited to 'documentation/ref-manual/ref-structure.xml')
-rw-r--r-- | documentation/ref-manual/ref-structure.xml | 116 |
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=<your_layer>/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=<your_layer>/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'> |