summaryrefslogtreecommitdiffstats
path: root/documentation
diff options
context:
space:
mode:
authorScott Rifenbark <scott.m.rifenbark@intel.com>2012-03-02 09:34:18 -0600
committerRichard Purdie <richard.purdie@linuxfoundation.org>2012-03-08 12:08:06 -0800
commit99d5ff01946695d9583f81f7dabb9f81bdc15883 (patch)
tree13ad2737cba58152f868e180bc0f099cfcb1771d /documentation
parent70186548537242477c379e364e4d7ac27f0f5c0c (diff)
downloadpoky-99d5ff01946695d9583f81f7dabb9f81bdc15883.tar.gz
documentation/dev-manual/dev-manual-common-tasks.xml: Moved Layer section
The "BitBake Layers" section was grossly mis-positioned. It appeared in the "Making and Maintaining Changes" section. I have moved the layer section to the very front of this chapter. It is fundamental to know about layers and how to create your own custom layers. (From yocto-docs rev: 410154f6e0a1e1f3ebc05d3f45ed2ce6f71cc618) Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation')
-rw-r--r--documentation/dev-manual/dev-manual-common-tasks.xml232
1 files changed, 116 insertions, 116 deletions
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index 80c47b0f64..9cdecb9f94 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -14,6 +14,122 @@
14 Yocto Project to achieve the best results. 14 Yocto Project to achieve the best results.
15 </para> 15 </para>
16 16
17 <section id="usingpoky-changes-layers">
18 <title>BitBake Layers</title>
19 <para>
20 Often, developers want to extend the Yocto Project either by adding packages
21 or by overriding files contained within the Yocto Project to add their own
22 functionality.
23 BitBake has a powerful mechanism called
24 "layers", which provides a way to handle this extension in a fully
25 supported and non-invasive fashion.
26 </para>
27
28 <para>
29 The Yocto Project files include several additional layers such as
30 <filename>meta-rt</filename> and <filename>meta-yocto</filename>
31 that demonstrate this functionality.
32 The <filename>meta-rt</filename> layer is not enabled by default.
33 However, the <filename>meta-yocto</filename> layer is.
34 </para>
35
36 <para>
37 To enable a layer, you simply add the layer's path to the
38 <filename><ulink url='http://www.yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html#var-BBLAYERS'>BBLAYERS</ulink></filename>
39 variable in your
40 <filename>conf/bblayers.conf</filename> file, which is found in the
41 <link linkend='yocto-project-build-directory'>Yocto Project Build Directory</link>.
42 The following example shows how to enable the <filename>meta-rt</filename>:
43 <literallayout class='monospaced'>
44 LCONF_VERSION = "1"
45
46 BBFILES ?= ""
47 BBLAYERS = " \
48 /path/to/poky/meta \
49 /path/to/poky/meta-yocto \
50 /path/to/poky/meta-rt \
51 "
52 </literallayout>
53 </para>
54
55 <para>
56 BitBake parses each <filename>conf/layer.conf</filename> file for each layer in
57 <filename>BBLAYERS</filename>
58 and adds the recipes, classes and configurations contained within the layer to
59 the Yocto Project.
60 To create your own layer, independent of the Yocto Project files,
61 simply create a directory with a <filename>conf/layer.conf</filename> file and
62 add the directory to your <filename>bblayers.conf</filename> file.
63 </para>
64
65 <para>
66 The <filename>meta-yocto/conf/layer.conf</filename> file demonstrates the
67 required syntax:
68 <literallayout class='monospaced'>
69 # We have a conf and classes directory, add to BBPATH
70 BBPATH := "${BBPATH}:${LAYERDIR}"
71
72 # We have a packages directory, add to BBFILES
73 BBFILES := "${BBFILES} ${LAYERDIR}/recipes-*/*/*.bb \
74 ${LAYERDIR}/recipes-*/*/*.bbappend"
75
76 BBFILE_COLLECTIONS += "yocto"
77 BBFILE_PATTERN_yocto := "^${LAYERDIR}/"
78 BBFILE_PRIORITY_yocto = "5"
79 </literallayout>
80 </para>
81
82 <para>
83 In the previous example, the recipes for the layers are added to
84 <filename><ulink url='http://www.yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html#var-BBFILES'>BBFILES</ulink></filename>.
85 The
86 <filename><ulink url='http://www.yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html#var-BBFILE_COLLECTIONS'>BBFILE_COLLECTIONS</ulink></filename>
87 variable is then appended with the layer name.
88 The
89 <filename><ulink url='http://www.yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html#var-BBFILE_PATTERN'>BBFILE_PATTERN</ulink></filename>
90 variable immediately expands with a regular expression used to match files from
91 <filename>BBFILES</filename> into
92 a particular layer, in this case by using the base pathname.
93 The
94 <filename><ulink url='http://www.yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html#var-BBFILE_PRIORITY'>BBFILE_PRIORITY</ulink></filename>
95 variable
96 then assigns different priorities to the files in different layers.
97 Applying priorities is useful in situations where the same package might appear in multiple
98 layers and allows you to choose what layer should take precedence.
99 </para>
100
101 <para>
102 Note the use of the
103 <filename><ulink url='http://www.yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html#var-LAYERDIR'>LAYERDIR</ulink></filename>
104 variable with the immediate expansion operator.
105 The <filename>LAYERDIR</filename> variable expands to the directory of the current layer and
106 requires the immediate expansion operator so that BitBake does not wait to expand the variable
107 when it's parsing a different directory.
108 </para>
109
110 <para>
111 BitBake can locate where other <filename>.bbclass</filename> and configuration files
112 are applied through the <filename>BBPATH</filename> environment variable.
113 For these cases, BitBake uses the first file with the matching name found in
114 <filename>BBPATH</filename>.
115 This is similar to the way the <filename>PATH</filename> variable is used for binaries.
116 We recommend, therefore, that you use unique <filename>.bbclass</filename>
117 and configuration file names in your custom layer.
118 </para>
119
120 <para>
121 We also recommend the following:
122 <itemizedlist>
123 <listitem><para>Store custom layers in a Git repository that uses the
124 <filename>meta-prvt-XXXX</filename> format.</para></listitem>
125 <listitem><para>Clone the repository alongside other <filename>meta</filename>
126 directories in the Yocto Project source files area.</para></listitem>
127 </itemizedlist>
128 Following these recommendations keeps your Yocto Project files area and
129 its configuration entirely inside the Yocto Project's core base.
130 </para>
131 </section>
132
17 <section id='usingpoky-extend-addpkg'> 133 <section id='usingpoky-extend-addpkg'>
18 <title>Adding a Package</title> 134 <title>Adding a Package</title>
19 135
@@ -1508,122 +1624,6 @@ so that there are some definite steps on how to do this. I need more detail her
1508 The following section provides more advice on managing changes to the Yocto Project. 1624 The following section provides more advice on managing changes to the Yocto Project.
1509 </para> 1625 </para>
1510 1626
1511 <section id="usingpoky-changes-layers">
1512 <title>BitBake Layers</title>
1513 <para>
1514 Often, developers want to extend the Yocto Project either by adding packages
1515 or by overriding files contained within the Yocto Project to add their own
1516 functionality.
1517 BitBake has a powerful mechanism called
1518 "layers", which provides a way to handle this extension in a fully
1519 supported and non-invasive fashion.
1520 </para>
1521
1522 <para>
1523 The Yocto Project files include several additional layers such as
1524 <filename>meta-rt</filename> and <filename>meta-yocto</filename>
1525 that demonstrate this functionality.
1526 The <filename>meta-rt</filename> layer is not enabled by default.
1527 However, the <filename>meta-yocto</filename> layer is.
1528 </para>
1529
1530 <para>
1531 To enable a layer, you simply add the layer's path to the
1532 <filename><ulink url='http://www.yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html#var-BBLAYERS'>BBLAYERS</ulink></filename>
1533 variable in your
1534 <filename>conf/bblayers.conf</filename> file, which is found in the
1535 <link linkend='yocto-project-build-directory'>Yocto Project Build Directory</link>.
1536 The following example shows how to enable the <filename>meta-rt</filename>:
1537 <literallayout class='monospaced'>
1538 LCONF_VERSION = "1"
1539
1540 BBFILES ?= ""
1541 BBLAYERS = " \
1542 /path/to/poky/meta \
1543 /path/to/poky/meta-yocto \
1544 /path/to/poky/meta-rt \
1545 "
1546 </literallayout>
1547 </para>
1548
1549 <para>
1550 BitBake parses each <filename>conf/layer.conf</filename> file for each layer in
1551 <filename>BBLAYERS</filename>
1552 and adds the recipes, classes and configurations contained within the layer to
1553 the Yocto Project.
1554 To create your own layer, independent of the Yocto Project files,
1555 simply create a directory with a <filename>conf/layer.conf</filename> file and
1556 add the directory to your <filename>bblayers.conf</filename> file.
1557 </para>
1558
1559 <para>
1560 The <filename>meta-yocto/conf/layer.conf</filename> file demonstrates the
1561 required syntax:
1562 <literallayout class='monospaced'>
1563 # We have a conf and classes directory, add to BBPATH
1564 BBPATH := "${BBPATH}:${LAYERDIR}"
1565
1566 # We have a packages directory, add to BBFILES
1567 BBFILES := "${BBFILES} ${LAYERDIR}/recipes-*/*/*.bb \
1568 ${LAYERDIR}/recipes-*/*/*.bbappend"
1569
1570 BBFILE_COLLECTIONS += "yocto"
1571 BBFILE_PATTERN_yocto := "^${LAYERDIR}/"
1572 BBFILE_PRIORITY_yocto = "5"
1573 </literallayout>
1574 </para>
1575
1576 <para>
1577 In the previous example, the recipes for the layers are added to
1578 <filename><ulink url='http://www.yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html#var-BBFILES'>BBFILES</ulink></filename>.
1579 The
1580 <filename><ulink url='http://www.yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html#var-BBFILE_COLLECTIONS'>BBFILE_COLLECTIONS</ulink></filename>
1581 variable is then appended with the layer name.
1582 The
1583 <filename><ulink url='http://www.yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html#var-BBFILE_PATTERN'>BBFILE_PATTERN</ulink></filename>
1584 variable immediately expands with a regular expression used to match files from
1585 <filename>BBFILES</filename> into
1586 a particular layer, in this case by using the base pathname.
1587 The
1588 <filename><ulink url='http://www.yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html#var-BBFILE_PRIORITY'>BBFILE_PRIORITY</ulink></filename>
1589 variable
1590 then assigns different priorities to the files in different layers.
1591 Applying priorities is useful in situations where the same package might appear in multiple
1592 layers and allows you to choose what layer should take precedence.
1593 </para>
1594
1595 <para>
1596 Note the use of the
1597 <filename><ulink url='http://www.yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html#var-LAYERDIR'>LAYERDIR</ulink></filename>
1598 variable with the immediate expansion operator.
1599 The <filename>LAYERDIR</filename> variable expands to the directory of the current layer and
1600 requires the immediate expansion operator so that BitBake does not wait to expand the variable
1601 when it's parsing a different directory.
1602 </para>
1603
1604 <para>
1605 BitBake can locate where other <filename>.bbclass</filename> and configuration files
1606 are applied through the <filename>BBPATH</filename> environment variable.
1607 For these cases, BitBake uses the first file with the matching name found in
1608 <filename>BBPATH</filename>.
1609 This is similar to the way the <filename>PATH</filename> variable is used for binaries.
1610 We recommend, therefore, that you use unique <filename>.bbclass</filename>
1611 and configuration file names in your custom layer.
1612 </para>
1613
1614 <para>
1615 We also recommend the following:
1616 <itemizedlist>
1617 <listitem><para>Store custom layers in a Git repository that uses the
1618 <filename>meta-prvt-XXXX</filename> format.</para></listitem>
1619 <listitem><para>Clone the repository alongside other <filename>meta</filename>
1620 directories in the Yocto Project source files area.</para></listitem>
1621 </itemizedlist>
1622 Following these recommendations keeps your Yocto Project files area and
1623 its configuration entirely inside the Yocto Project's core base.
1624 </para>
1625 </section>
1626
1627 <section id="usingpoky-changes-commits"> 1627 <section id="usingpoky-changes-commits">
1628 <title>Committing Changes</title> 1628 <title>Committing Changes</title>
1629 1629
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-05-06 11:27:10 +0000