summaryrefslogtreecommitdiffstats
path: root/documentation/dev-manual/dev-manual-common-tasks.xml
diff options
context:
space:
mode:
authorScott Rifenbark <scott.m.rifenbark@intel.com>2012-03-02 17:21:55 -0600
committerRichard Purdie <richard.purdie@linuxfoundation.org>2012-03-08 12:08:06 -0800
commitc38b2de6305ea192096c0c9cad04bd12237f2fc1 (patch)
treebb82e78addfa128fbc1eeb9f90146aebd46340c6 /documentation/dev-manual/dev-manual-common-tasks.xml
parenteb829f27688bdfbf0e223a18f07f7098341324dc (diff)
downloadpoky-c38b2de6305ea192096c0c9cad04bd12237f2fc1.tar.gz
documentation/dev-manual: New Layer section and metadata link anchor
The change to the dev-manual-newbie.xml file was minor. I added a link anchor for the term "metadata." The change to the dev-manual-common-tasks.xml was extensive. I have added an entirely new section on layers called "Understanding and Using Layers." The new material has several sub-sections. Information was based on emails from Paul Eggleton. (From yocto-docs rev: 4fb34abd60180fc2482ddb9f62e476763cee7679) Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/dev-manual/dev-manual-common-tasks.xml')
-rw-r--r--documentation/dev-manual/dev-manual-common-tasks.xml392
1 files changed, 303 insertions, 89 deletions
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index ab140207aa..ad4a7613a9 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -16,58 +16,87 @@
16 16
17 <section id="understanding-and-creating-layers"> 17 <section id="understanding-and-creating-layers">
18 <title>Understanding and Creating Layers</title> 18 <title>Understanding and Creating 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 19
28 <para> 20 <para>
29 The Yocto Project files include several additional layers such as 21 The Yocto Project build system supports organizing <link linkend='metadata'>metadata</link>
30 <filename>meta-rt</filename> and <filename>meta-yocto</filename> 22 into multiple layers.
31 that demonstrate this functionality. 23 Layers allow you to isolate different types of customizations from each other.
32 The <filename>meta-rt</filename> layer is not enabled by default. 24 You might find it tempting to keep everything in one layer when working on a single project.
33 However, the <filename>meta-yocto</filename> layer is. 25 However, the more modular you organize your metadata, the easier it is to cope with future changes.
34 </para> 26 </para>
35 27
36 <para> 28 <para>
37 To enable a layer, you simply add the layer's path to the 29 To illustrate how layers are used to keep things modular, consider machine customizations.
38 <filename><ulink url='http://www.yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html#var-BBLAYERS'>BBLAYERS</ulink></filename> 30 These types of customizations typically reside in a BSP Layer.
39 variable in your 31 Furthermore, the machine customizations should be isolated from recipes and metadata that support
40 <filename>conf/bblayers.conf</filename> file, which is found in the 32 a new GUI environment, for example.
41 <link linkend='yocto-project-build-directory'>Yocto Project Build Directory</link>. 33 This situation gives you a couple a layers: one for the machine configurations, and one for the
42 The following example shows how to enable the <filename>meta-rt</filename>: 34 GUI environment.
43 <literallayout class='monospaced'> 35 It is important to understand, however, that the BSP layer can still make machine-specific
44 LCONF_VERSION = "1" 36 additions to recipes within the GUI environment layer without polluting the GUI layer itself
45 37 with those machine-specific changes.
46 BBFILES ?= "" 38 You can accomplish this through an appending recipe (a <filename>.bbappend</filename> file),
47 BBLAYERS = " \ 39 which is described later in this section.
48 /path/to/poky/meta \
49 /path/to/poky/meta-yocto \
50 /path/to/poky/meta-rt \
51 "
52 </literallayout>
53 </para> 40 </para>
54 41
55 <para> 42 <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> 43 </para>
64 44
65 <para> 45 <section id='yocto-project-layers'>
66 The <filename>meta-yocto/conf/layer.conf</filename> file demonstrates the 46 <title>Yocto Project Layers</title>
67 required syntax: 47
68 <literallayout class='monospaced'> 48 <para>
49 The Yocto Project contains several layers right out of the box.
50 You can easily identify a layer in the Yocto Project by the name of its folder.
51 Folders that are layers begin with the string <filename>meta</filename>.
52 For example, when you set up the <link linkend='yocto-project-files'>Yocto Project Files</link>
53 structure, you will see several layers: <filename>meta</filename>, <filename>meta-demoapps</filename>,
54 <filename>meta-skeleton</filename>, and <filename>meta-yocto</filename>.
55 Each of these folders is a layer.
56 </para>
57
58 <para>
59 Furthermore, if you set up a local copy of the <filename>meta-intel</filename> Git repository
60 and then explore that folder, you will discover many BSP layers within the
61 <filename>meta-intel</filename> layer.
62 For more information on BSP layers, see the
63 "<ulink url='http://www.yoctoproject.org/docs/latest/bsp-guide/bsp-guide.html#bsp-layers'>BSP Layers</ulink>"
64 section in the Yocto Project Development Manual.
65 </para>
66 </section>
67
68 <section id='creating-your-own-layer'>
69 <title>Creating Your Own Layer</title>
70
71 <para>
72 It is very easy to create your own layer to use with the Yocto Project.
73 Follow these general steps to create your layer:
74 <orderedlist>
75 <listitem><para><emphasis>Check Existing Layers:</emphasis> Before creating a new layer,
76 you should be sure someone has not already created a layer containing the metadata
77 you need.
78 You can see the
79 <ulink url='http://www.openembedded.org/wiki/LayerIndex'><filename>LayerIndex</filename></ulink>
80 to determine what types of layers already exist in the Yocto Project.</para></listitem>
81 <listitem><para><emphasis>Create a Directory:</emphasis> Create the directory
82 for your layer.
83 Traditionally, prepend the name of the folder with the string
84 <filename>meta</filename>.
85 For example:
86 <literallayout class='monospaced'>
87 meta-mylayer
88 meta-GUI_xyz
89 meta-mymachine
90 </literallayout></para></listitem>
91 <listitem><para><emphasis>Create a Layer Configuration File:</emphasis> Inside your new
92 layer folder, you need to create a <filename>conf/layer.conf</filename> file.
93 It is easiest to take an existing layer configuration file and copy that to your
94 layer's <filename>conf</filename> directory and then modify the file as needed.</para>
95 <para>The <filename>meta-yocto/conf/layer.conf</filename> file demonstrates the
96 required syntax:
97 <literallayout class='monospaced'>
69 # We have a conf and classes directory, add to BBPATH 98 # We have a conf and classes directory, add to BBPATH
70 BBPATH := "${BBPATH}:${LAYERDIR}" 99 BBPATH := "${LAYERDIR}:${BBPATH}"
71 100
72 # We have a packages directory, add to BBFILES 101 # We have a packages directory, add to BBFILES
73 BBFILES := "${BBFILES} ${LAYERDIR}/recipes-*/*/*.bb \ 102 BBFILES := "${BBFILES} ${LAYERDIR}/recipes-*/*/*.bb \
@@ -76,58 +105,243 @@
76 BBFILE_COLLECTIONS += "yocto" 105 BBFILE_COLLECTIONS += "yocto"
77 BBFILE_PATTERN_yocto := "^${LAYERDIR}/" 106 BBFILE_PATTERN_yocto := "^${LAYERDIR}/"
78 BBFILE_PRIORITY_yocto = "5" 107 BBFILE_PRIORITY_yocto = "5"
79 </literallayout> 108 </literallayout></para>
80 </para> 109 <para>In the previous example, the recipes for the layers are added to
110 <filename><ulink url='http://www.yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html#var-BBFILES'>BBFILES</ulink></filename>.
111 The
112 <filename><ulink url='http://www.yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html#var-BBFILE_COLLECTIONS'>BBFILE_COLLECTIONS</ulink></filename>
113 variable is then appended with the layer name.
114 The
115 <filename><ulink url='http://www.yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html#var-BBFILE_PATTERN'>BBFILE_PATTERN</ulink></filename>
116 variable immediately expands with a regular expression used to match files from
117 <filename>BBFILES</filename> into a particular layer, in this case by using
118 the base pathname.
119 The
120 <filename><ulink url='http://www.yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html#var-BBFILE_PRIORITY'>BBFILE_PRIORITY</ulink></filename>
121 variable then assigns different priorities to the files in different layers.
122 Applying priorities is useful in situations where the same package might appear in multiple
123 layers and allows you to choose what layer should take precedence.</para>
124 <para>Note the use of the
125 <filename><ulink url='http://www.yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html#var-LAYERDIR'>LAYERDIR</ulink></filename>
126 variable with the immediate expansion operator.
127 The <filename>LAYERDIR</filename> variable expands to the directory of the current layer and
128 requires the immediate expansion operator so that BitBake does not wait to expand the variable
129 when it's parsing a different directory.</para>
130 <para>BitBake can locate where other <filename>.bbclass</filename> and configuration files
131 are applied through the <filename>BBPATH</filename> environment variable.
132 For these cases, BitBake uses the first file with the matching name found in
133 <filename>BBPATH</filename>.
134 This is similar to the way the <filename>PATH</filename> variable is used for binaries.
135 We recommend, therefore, that you use unique <filename>.bbclass</filename>
136 and configuration file names in your custom layer.</para></listitem>
137 <listitem><para><emphasis>Add Content:</emphasis> Depending on the type of layer,
138 add the content.
139 If the layer adds support for a machine, add the machine configuration in
140 a <filename>conf/machine/</filename> file within the layer.
141 If the layer adds distro policy, add the distro configuration in a
142 <filename>conf/distro/</filename> file with the layer.
143 If the layer introduces new recipes, put the recipes you need in
144 <filename>recipes-*</filename> subdirectories within the layer.</para></listitem>
145 </orderedlist>
146 </para>
81 147
82 <para> 148 <para>
83 In the previous example, the recipes for the layers are added to 149 To create layers that are easier to maintain, you should consider the following:
84 <filename><ulink url='http://www.yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html#var-BBFILES'>BBFILES</ulink></filename>. 150 <itemizedlist>
85 The 151 <listitem><para>Avoid "overlaying" entire recipes from other layers in your
86 <filename><ulink url='http://www.yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html#var-BBFILE_COLLECTIONS'>BBFILE_COLLECTIONS</ulink></filename> 152 configuration.
87 variable is then appended with the layer name. 153 In other words, don't copy an entire recipe into your layer and then modify it.
88 The 154 Use <filename>.bbappend</filename> files to override the parts of 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> 155 recipe you need to modify.</para></listitem>
90 variable immediately expands with a regular expression used to match files from 156 <listitem><para>Avoid duplicating include files.
91 <filename>BBFILES</filename> into 157 Use <filename>.bbappend</filename> files for each recipe that uses an include
92 a particular layer, in this case by using the base pathname. 158 file.
93 The 159 Or, if you are introducing a new recipe that requires the inc file, use 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> 160 full path to refer to the original.
95 variable 161 For example, use <filename>require recipes-core/somepackage/somefile.inc</filename>
96 then assigns different priorities to the files in different layers. 162 instead of <filename>require somefile.inc</filename>.
97 Applying priorities is useful in situations where the same package might appear in multiple 163 If you're finding you have to overlay the include file, it could indicate a
98 layers and allows you to choose what layer should take precedence. 164 deficiency in the include file in the layer to which it originally belongs.
99 </para> 165 If this is the case, you need to address that deficiency instead of overlaying
166 the include file.
167 For example, consider how Qt 4 database support plugins are configured.
168 The Yocto Project does not have MySQL or PostgreSQL, however OpenEmbedded's
169 layer <filename>meta-oe</filename> does.
170 Consequently, <filename>meta-oe</filename> uses <filename>.bbappend</filename>
171 files to modify the <filename>QT_SQL_DRIVER_FLAGS</filename> variable to enable
172 the appropriate plugins.
173 This variable was added to the <filename>qt4.inc</filename> include file in
174 The Yocto Project specifically to allow the <filename>meta-oe</filename> layer
175 to be able to control which plugins are built.</para></listitem>
176 </itemizedlist>
177 </para>
178
179 <para>
180 We also recommend the following:
181 <itemizedlist>
182 <listitem><para>Store custom layers in a Git repository that uses the
183 <filename>meta-prvt-XXXX</filename> format.</para></listitem>
184 <listitem><para>Clone the repository alongside other <filename>meta</filename>
185 directories in the Yocto Project source files area.</para></listitem>
186 </itemizedlist>
187 Following these recommendations keeps your Yocto Project files area and
188 its configuration entirely inside the Yocto Project's core base.
189 </para>
190 </section>
100 191
101 <para> 192 <section id='enabling-your-layer'>
102 Note the use of the 193 <title>Enabling Your Layer</title>
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 194
110 <para> 195 <para>
111 BitBake can locate where other <filename>.bbclass</filename> and configuration files 196 Before the Yocto Project build system can use your new layer, you need to enable it.
112 are applied through the <filename>BBPATH</filename> environment variable. 197 To enable your layer, simply add your layer's path to the
113 For these cases, BitBake uses the first file with the matching name found in 198 <filename><ulink url='http://www.yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html#var-BBLAYERS'>BBLAYERS</ulink></filename>
114 <filename>BBPATH</filename>. 199 variable in your <filename>conf/bblayers.conf</filename> file, which is found in the
115 This is similar to the way the <filename>PATH</filename> variable is used for binaries. 200 <link linkend='yocto-project-build-directory'>Yocto Project Build Directory</link>.
116 We recommend, therefore, that you use unique <filename>.bbclass</filename> 201 The following example shows how to enable a layer named <filename>meta-mylayer</filename>:
117 and configuration file names in your custom layer. 202 <literallayout class='monospaced'>
118 </para> 203 LCONF_VERSION = "1"
119 204
120 <para> 205 BBFILES ?= ""
121 We also recommend the following: 206 BBLAYERS = " \
122 <itemizedlist> 207 /path/to/poky/meta \
123 <listitem><para>Store custom layers in a Git repository that uses the 208 /path/to/poky/meta-yocto \
124 <filename>meta-prvt-XXXX</filename> format.</para></listitem> 209 /path/to/poky/meta-mylayer \
125 <listitem><para>Clone the repository alongside other <filename>meta</filename> 210 "
126 directories in the Yocto Project source files area.</para></listitem> 211 </literallayout>
127 </itemizedlist> 212 </para>
128 Following these recommendations keeps your Yocto Project files area and 213
129 its configuration entirely inside the Yocto Project's core base. 214 <para>
130 </para> 215 BitBake parses each <filename>conf/layer.conf</filename> file as specified in the
216 <filename>BBLAYERS</filename> variable within the <filename>conf/bblayers.conf</filename>
217 file.
218 During the processing of each <filename>conf/layer.conf</filename> file, BitBake adds the
219 recipes, classes and configurations contained within the particular layer to the Yocto
220 Project.
221 To create your own layer, independent of the Yocto Project files,
222 simply create a directory with a <filename>conf/layer.conf</filename> file and
223 add the directory to your <filename>bblayers.conf</filename> file.
224 </para>
225 </section>
226
227 <section id='using-bbappend-files'>
228 <title>Using .bbappend Files</title>
229
230 <para>
231 Recipe append files (<filename>.bbappend</filename> type) allow your layer to make additions or
232 changes to the content of another layer's recipe without having to copy the other recipe into
233 your layer.
234 Your <filename>.bbappend</filename> file resides in your layer, while the underlying recipe
235 to which you are appending resides in a different layer.
236 </para>
237
238 <para>
239 Append files files must have the same name as the underlying recipe.
240 For example, the append file <filename>someapp_1.1.bbappend</filename> must
241 apply to <filename>someapp_1.1.bb</filename>.
242 This means the original recipe and append file names are version number specific.
243 If the underlying recipe is renamed to update to a newer version, the
244 corresponding <filename>.bbappend</filename> file must be renamed as well.
245 During the build process, BitBake displays warnings on starting if it detects a
246 <filename>.bbappend</filename> file that does not have an underlying recipe
247 with the proper name.
248 </para>
249
250 <para>
251 Being able to append information to an existing recipe not only avoids duplication,
252 but also automatically applies recipe changes in a different layer to your layer.
253 If you were copying recipes, you would have to manually merge changes as they occur.
254 </para>
255
256 <para>
257 As an example, consider the main formfactor recipe and a corresponding formfactor
258 append file both from the Yocto Project Files.
259 Here is the main formfactor recipe, which is named <filename>formfactor_0.0.bb</filename> and
260 located in the meta layer at <filename>meta/bsp-recipes/formfactor</filename>:
261 <literallayout class='monospaced'>
262 DESCRIPTION = "Device formfactor information"
263 SECTION = "base"
264 LICENSE = "MIT"
265 LIC_FILES_CHKSUM = "file://${COREBASE}/LICENSE;md5=3f40d7994397109285ec7b81fdeb3b58 \
266 file://${COREBASE}/meta/COPYING.MIT;md5=3da9cfbcb788c80a0384361b4de20420"
267 PR = "r19"
268
269 SRC_URI = "file://config file://machconfig"
270 S = "${WORKDIR}"
271
272 PACKAGE_ARCH = "${MACHINE_ARCH}"
273 INHIBIT_DEFAULT_DEPS = "1"
274
275 do_install() {
276 # Only install file if it has a contents
277 install -d ${D}${sysconfdir}/formfactor/
278 install -m 0644 ${S}/config ${D}${sysconfdir}/formfactor/
279 if [ -s "${S}/machconfig" ]; then
280 install -m 0644 ${S}/machconfig ${D}${sysconfdir}/formfactor/
281 fi
282 }
283 </literallayout>
284 Here is the append file, which is named <filename>formfactor_0.0.bbappend</filename> and is from the
285 Crown Bay BSP Layer named <filename>meta-intel/meta-crownbay</filename>:
286 <literallayout class='monospaced'>
287 FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
288
289 PRINC = "1"
290 </literallayout>
291 This example adds or overrides files in
292 <ulink url='http://www.yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html#var-SRC_URI'><filename>SRC_URI</filename></ulink>
293 within a bbappend by extending the path BitBake uses to search for files.
294 The most reliable way to do this is by prepending the
295 <filename>FILESEXTRAPATHS</filename> variable.
296 For example, if you have your files in a directory that is named the same as your package
297 (<ulink url='http://www.yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html#var-PN'><filename>PN</filename></ulink>),
298 you can add this directory by adding the following to your bbappend file:
299 <literallayout class='monospaced'>
300 FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
301 </literallayout>
302 Using the immediate expansion assignment operator <filename>:=</filename> and the trailing colon
303 are important so that the resulting list of pathnames is syntactically correct.
304 <note>BitBake automatically defines the <filename>THISDIR</filename> variable.
305 You should never set this variable yourself.
306 Using <filename>_prepend</filename> ensures your path will be searched prior to other
307 paths in the final list.
308 </note>
309 </para>
310 </section>
311
312 <section id='prioritizing-your-layer'>
313 <title>Prioritizing Your Layer</title>
314
315 <para>
316 Each layer is assigned a priority value.
317 Priority values control which layer takes precedence if there are recipe files with
318 the same name in multiple layers.
319 For these cases, the recipe file from the layer with a higher priority number taking precedence.
320 Priority values also affect the order in which multiple <filename>.bbappend</filename> files
321 for the same recipe are applied.
322 You can either specify the priority manually, or allow the build system to calculate it
323 based on the layer's dependencies.
324 </para>
325
326 <para>
327 To specify the layer's priority manually, use the
328 <ulink url='http://yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html#var-BBFILE_PRIORITY'><filename>BBFILE_PRIORITY</filename></ulink>
329 variable.
330 For example:
331 <literallayout class='monospaced'>
332 BBFILE_PRIORITY := "1"
333 </literallayout>
334 </para>
335
336 <note>
337 <para>It is possible for a recipe with a lower version number
338 <ulink url='http://yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html#var-PV'><filename>PV</filename></ulink>
339 in a layer that has a higher priority to take precedence.</para>
340 <para>Also, the layer priority does not currently affect the precedence order of
341 <filename>.conf</filename> or <filename>.bbclass</filename> files.
342 Future versions of BitBake might address this.</para>
343 </note>
344 </section>
131 </section> 345 </section>
132 346
133 <section id='usingpoky-extend-addpkg'> 347 <section id='usingpoky-extend-addpkg'>
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-11-12 12:19:35 +0000