summaryrefslogtreecommitdiffstats
path: root/handbook/extendpoky.xml
diff options
context:
space:
mode:
authorJoshua Lock <josh@linux.intel.com>2010-06-08 17:18:29 +0100
committerJoshua Lock <josh@linux.intel.com>2010-06-08 17:29:56 +0100
commit3a6948a2af25c1094b22a70c923dfecc296dad8b (patch)
tree8a1a8353e71d8a7a168f84773efd7fa2f4049311 /handbook/extendpoky.xml
parent6a9312ccccd744fd61e5fbb843093e236383c740 (diff)
downloadpoky-3a6948a2af25c1094b22a70c923dfecc296dad8b.tar.gz
handbook: add documentation for layers
Collections and overlays are deprecated in favour of layers, a much cleaner and non-intrusive way of extending Poky with custom recipes, classes and configuration. This patch updates the Extending Poky section of the handbook to show how to use layers to tailor Poky while dropping the existing section on using collections. Signed-off-by: Joshua Lock <josh@linux.intel.com>
Diffstat (limited to 'handbook/extendpoky.xml')
-rw-r--r--handbook/extendpoky.xml148
1 files changed, 78 insertions, 70 deletions
diff --git a/handbook/extendpoky.xml b/handbook/extendpoky.xml
index f072fe5032..b437c77fa3 100644
--- a/handbook/extendpoky.xml
+++ b/handbook/extendpoky.xml
@@ -518,85 +518,93 @@ bitbake poky-image-sato
518 </para> 518 </para>
519 <para> 519 <para>
520 Poky supports the idea of <link 520 Poky supports the idea of <link
521 linkend='usingpoky-changes-collections'>"collections"</link> which when used 521 linkend='usingpoky-changes-layers'>"layers"</link> which when used
522 properly can massively ease future upgrades and allow segregation 522 properly can massively ease future upgrades and allow segregation
523 between the Poky core and a given developer's changes. Some other advice on 523 between the Poky core and a given developer's changes. Some other advice on
524 managing changes to Poky is also given in the following section. 524 managing changes to Poky is also given in the following section.
525 </para> 525 </para>
526 526
527 <section id="usingpoky-changes-collections"> 527 <section id="usingpoky-changes-layers">
528 <title>Bitbake Collections</title> 528 <title>Bitbake Layers</title>
529 529
530 <para> 530 <para>
531 Often, people want to extend Poky either through adding packages 531 Often, people want to extend Poky either through adding packages
532 or overriding files contained within Poky to add their own 532 or overriding files contained within Poky to add their own
533 functionality. Bitbake has a powerful mechanism called 533 functionality. Bitbake has a powerful mechanism called
534 collections which provide a way to handle this which is fully 534 layers which provides a way to handle this extension in a fully
535 supported and actively encouraged within Poky. 535 supported and non-invasive fashion.
536 </para> 536 </para>
537 <para> 537
538 In the standard tree, meta-extras is an example of how you can 538 <para>
539 do this. As standard the data in meta-extras is not used on a 539 The Poky tree includes two additional layers which demonstrate
540 Poky build but local.conf.sample shows how to enable it: 540 this functionality, meta-moblin and meta-extras.
541 </para> 541 The meta-extras repostory is not enabled by default but enabling
542 <para> 542 it is as easy as adding the layers path to the BBLAYERS variable in
543 <literallayout class='monospaced'> 543 your bblayers.conf, this is how all layers are enabled in Poky builds:
544BBFILES := "${OEROOT}/meta/packages/*/*.bb ${OEROOT}/meta-extras/packages/*/*.bb" 544 </para>
545BBFILE_COLLECTIONS = "normal extras" 545 <para>
546BBFILE_PATTERN_normal = "^${OEROOT}/meta/" 546 <literallayout class='monospaced'>LCONF_VERSION = "1"
547BBFILE_PATTERN_extras = "^${OEROOT}/meta-extras/" 547
548BBFILE_PRIORITY_normal = "5" 548BBFILES ?= ""
549BBFILE_PRIORITY_extras = "5"</literallayout> 549BBLAYERS = " \
550 </para> 550 ${OEROOT}/meta \
551 <para> 551 ${OEROOT}/meta-moblin \
552 As can be seen, the extra recipes are added to BBFILES. The 552 ${OEROOT}/meta-extras \
553 BBFILE_COLLECTIONS variable is then set to contain a list of 553 "
554 collection names. The BBFILE_PATTERN variables are regular 554</literallayout>
555 expressions used to match files from BBFILES into a particular 555 </para>
556 collection in this case by using the base pathname. 556
557 The BBFILE_PRIORITY variable then assigns the different 557 <para>
558 priorities to the files in different collections. This is useful 558 Bitbake parses the conf/layer.conf of each of the layers in BBLAYERS
559 in situations where the same package might appear in both 559 to add the layers packages, classes and configuration to Poky.
560 repositories and allows you to choose which collection should 560 To create your own layer, independent of the main Poky repository,
561 'win'. 561 you need only create a directory with a conf/layer.conf file and
562 </para> 562 add the directory to your bblayers.conf.
563 <para> 563 </para>
564 This works well for recipes. For bbclasses and configuration 564
565 files, you can use the BBPATH environment variable. In this 565 <para>
566 case, the first file with the matching name found in BBPATH is 566 The meta-extras layer.conf demonstrates the required syntax:
567 the one that is used, just like the PATH variable for binaries. 567 <literallayout class='monospaced'># We have a conf and classes directory, add to BBPATH
568 </para> 568BBPATH := "${BBPATH}${LAYERDIR}"
569 </section> 569
570 570# We have a packages directory, add to BBFILES
571 <section id="usingpoky-changes-supplement"> 571BBFILES := "${BBFILES} ${LAYERDIR}/packages/*/*.bb"
572 <title>Supplementry Metadata Repositories</title> 572
573 573BBFILE_COLLECTIONS += "extras"
574 <para> 574BBFILE_PATTERN_extras := "^${LAYERDIR}/"
575 Often when developing a project based on Poky there will be components 575BBFILE_PRIORITY_extras = "5"
576 that are not ready for public consumption for whatever reason. By making 576
577 use of the collections mechanism and other functionality within Poky, it 577require conf/distro/include/poky-extras-src-revisions.inc
578 is possible to have a public repository which is supplemented by a private 578 </literallayout>
579 one just containing the pieces that need to be kept private. 579 </para>
580 </para> 580
581 <para> 581 <para>
582 The usual approach with these is to create a separate git repository called 582 As can be seen, the layers recipes are added to BBFILES. The
583 "meta-prvt-XXX" which is checked out alongside the other meta-* 583 BBFILE_COLLECTIONS variable is then appended to with the
584 directories included in Poky. Under this directory there can be several 584 layer name. The BBFILE_PATTERN variable is immediately expanded
585 different directories such as classes, conf and packages which all 585 with a regular expression used to match files from BBFILES into a
586 function as per the usual Poky directory structure. 586 particular layer, in this case by using the base pathname.
587 </para> 587 The BBFILE_PRIORITY variable then assigns different
588 <para> 588 priorities to the files in different layers. This is useful
589 If extra meta-* directories are found, Poky will automatically add them 589 in situations where the same package might appear in multiple
590 into the BBPATH variable so the conf and class files contained there 590 layers and allows you to choose which layer should 'win'.
591 are found. If a file called poky-extra-environment is found within the 591 </para>
592 meta-* directory, this will be sourced as the environment is setup, 592
593 allowing certain configuration to be overridden such as the location of the 593 <para>
594 local.conf.sample file that is used. 594 Extra bbclasses and configuration are added to the BBPATH
595 </para> 595 environment variable. In this case, the first file with the
596 <para> 596 matching name found in BBPATH is the one that is used, just
597 Note that at present, BBFILES is not automatically changed and this needs 597 like the PATH variable for binaries. It is therefore recommended
598 to be adjusted to find files in the packages/ directory. Usually a custom 598 that you use unique bbclass and configuration file names in your
599 local.conf.sample file will be used to handle this instead. 599 custom layer.
600 </para>
601
602 <para>
603 The recommended approach for custom layers is to store them in a
604 git repository of the format meta-prvt-XXXX and have this repository
605 cloned alongside the other meta directories in the Poky tree.
606 This way you can keep your Poky tree and it's configuration entirely
607 inside OEROOT.
600 </para> 608 </para>
601 </section> 609 </section>
602 610