summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorScott Rifenbark <scott.m.rifenbark@intel.com>2013-04-05 15:03:39 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2013-04-10 16:20:54 +0100
commit64a5bec85013f6fa1614d820a22031060dafc67b (patch)
treece93868c686bbe9b3b2070aeae5a7a3abe20e7a5
parent7f21c57770121bfdfa90080d8448fd75c9174669 (diff)
downloadpoky-64a5bec85013f6fa1614d820a22031060dafc67b.tar.gz
dev-manual: Initial draft of the new yocto-layer section
Rough text for a section within the layer section that introduces and describes a bit how the new yocto-layer script works. (From yocto-docs rev: ee56a264600df9fe250e73b60c8dadd6f8e55009) Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat
-rw-r--r--documentation/dev-manual/dev-manual-common-tasks.xml575
1 files changed, 402 insertions, 173 deletions
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index 24faf8bd76..02d1dd22b4 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -17,25 +17,34 @@
17 <title>Understanding and Creating Layers</title> 17 <title>Understanding and Creating Layers</title>
18 18
19 <para> 19 <para>
20 The OpenEmbedded build system supports organizing <link linkend='metadata'>metadata</link> 20 The OpenEmbedded build system supports organizing
21 into multiple layers. 21 <link linkend='metadata'>Metadata</link> into multiple layers.
22 Layers allow you to isolate different types of customizations from each other. 22 Layers allow you to isolate different types of customizations from
23 You might find it tempting to keep everything in one layer when working on a single project. 23 each other.
24 However, the more modular you organize your metadata, the easier it is to cope with future changes. 24 You might find it tempting to keep everything in one layer when
25 working on a single project.
26 However, the more modular you organize your Metadata, the easier
27 it is to cope with future changes.
25 </para> 28 </para>
26 29
27 <para> 30 <para>
28 To illustrate how layers are used to keep things modular, consider machine customizations. 31 To illustrate how layers are used to keep things modular, consider
29 These types of customizations typically reside in a BSP Layer. 32 machine customizations.
30 Furthermore, the machine customizations should be isolated from recipes and metadata that support 33 These types of customizations typically reside in a special layer,
31 a new GUI environment, for example. 34 rather than a general layer, called a Board Specific Package (BSP)
32 This situation gives you a couple of layers: one for the machine configurations, and one for the 35 Layer.
33 GUI environment. 36 Furthermore, the machine customizations should be isolated from
34 It is important to understand, however, that the BSP layer can still make machine-specific 37 recipes and Metadata that support a new GUI environment,
35 additions to recipes within the GUI environment layer without polluting the GUI layer itself 38 for example.
39 This situation gives you a couple of layers: one for the machine
40 configurations, and one for the GUI environment.
41 It is important to understand, however, that the BSP layer can
42 still make machine-specific additions to recipes within the GUI
43 environment layer without polluting the GUI layer itself
36 with those machine-specific changes. 44 with those machine-specific changes.
37 You can accomplish this through a recipe that is a BitBake append 45 You can accomplish this through a recipe that is a BitBake append
38 (<filename>.bbappend</filename>) file, which is described later in this section. 46 (<filename>.bbappend</filename>) file, which is described later
47 in this section.
39 </para> 48 </para>
40 49
41 <para> 50 <para>
@@ -45,8 +54,8 @@
45 <title>Layers</title> 54 <title>Layers</title>
46 55
47 <para> 56 <para>
48 The Source Directory contains several layers right out of the 57 The Source Directory contains both general layers and BSP
49 box. 58 layers right out of the box.
50 You can easily identify layers that ship with a 59 You can easily identify layers that ship with a
51 Yocto Project release in the Source Directory by their 60 Yocto Project release in the Source Directory by their
52 folder names. 61 folder names.
@@ -56,20 +65,25 @@
56 It is not a requirement that a layer begins with the 65 It is not a requirement that a layer begins with the
57 string <filename>meta</filename>. 66 string <filename>meta</filename>.
58 </note> 67 </note>
59 For example, when you set up the <link linkend='source-directory'>Source Directory</link> 68 For example, when you set up the
60 structure, you will see several layers: <filename>meta</filename>, 69 <link linkend='source-directory'>Source Directory</link>
61 <filename>meta-hob</filename>, <filename>meta-skeleton</filename>, 70 structure, you will see several layers:
62 <filename>meta-yocto</filename>, and <filename>meta-yocto-bsp</filename>. 71 <filename>meta</filename>, <filename>meta-hob</filename>,
72 <filename>meta-skeleton</filename>,
73 <filename>meta-yocto</filename>, and
74 <filename>meta-yocto-bsp</filename>.
63 Each of these folders is a layer. 75 Each of these folders is a layer.
64 </para> 76 </para>
65 77
66 <para> 78 <para>
67 Furthermore, if you set up a local copy of the <filename>meta-intel</filename> Git repository 79 Furthermore, if you set up a local copy of the
68 and then explore that folder, you will discover many BSP layers within the 80 <filename>meta-intel</filename> Git repository
69 <filename>meta-intel</filename> layer. 81 and then explore the folder of that general layer,
82 you will discover many BSP layers inside.
70 For more information on BSP layers, see the 83 For more information on BSP layers, see the
71 "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>" 84 "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>"
72 section in the Yocto Project Board Support Package (BSP) Developer's Guide. 85 section in the Yocto Project Board Support Package (BSP)
86 Developer's Guide.
73 </para> 87 </para>
74 </section> 88 </section>
75 89
@@ -77,32 +91,54 @@
77 <title>Creating Your Own Layer</title> 91 <title>Creating Your Own Layer</title>
78 92
79 <para> 93 <para>
80 It is very easy to create your own layer to use with the OpenEmbedded build system. 94 It is very easy to create your own layers to use with the
95 OpenEmbedded build system.
96 The Yocto Project ships with scripts that speed up creating
97 general layers and BSP layers.
98 This section describes the steps you perform by hand to create
99 a layer so that you can better understand them.
100 For information about the layer-creation scripts, see the
101 "<ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-yocto-bsp-script'>Creating a New BSP Layer Using the yocto-bsp Script</ulink>"
102 section in the Yocto Project Board Support Package (BSP)
103 Developer's Guide and the
104 "<link linkend='creating-a-general-layer-using-the-yocto-layer-script'>Creating a General Layer Using the yocto-layer Script</link>"
105 section further down in this manual.
106 </para>
107
108 <para>
81 Follow these general steps to create your layer: 109 Follow these general steps to create your layer:
82 <orderedlist> 110 <orderedlist>
83 <listitem><para><emphasis>Check Existing Layers:</emphasis> Before creating a new layer, 111 <listitem><para><emphasis>Check Existing Layers:</emphasis>
84 you should be sure someone has not already created a layer containing the metadata 112 Before creating a new layer, you should be sure someone
113 has not already created a layer containing the Metadata
85 you need. 114 you need.
86 You can see the 115 You can see the
87 <ulink url='http://layers.openembedded.org/layerindex/layers/'><filename>OpenEmbedded metadata index</filename></ulink> 116 <ulink url='http://layers.openembedded.org/layerindex/layers/'><filename>OpenEmbedded Metadata Index</filename></ulink>
88 for a list of layers from the OpenEmbedded community that can be used in the 117 for a list of layers from the OpenEmbedded community
89 Yocto Project.</para></listitem> 118 that can be used in the Yocto Project.
119 </para></listitem>
90 <listitem><para><emphasis>Create a Directory:</emphasis> 120 <listitem><para><emphasis>Create a Directory:</emphasis>
91 Create the directory for your layer. 121 Create the directory for your layer.
92 While not strictly required, prepend the name of the 122 While not strictly required, prepend the name of the
93 folder with the string <filename>meta</filename>. 123 folder with the string <filename>meta-</filename>.
94 For example: 124 For example:
95 <literallayout class='monospaced'> 125 <literallayout class='monospaced'>
96 meta-mylayer 126 meta-mylayer
97 meta-GUI_xyz 127 meta-GUI_xyz
98 meta-mymachine 128 meta-mymachine
99 </literallayout></para></listitem> 129 </literallayout>
100 <listitem><para><emphasis>Create a Layer Configuration File:</emphasis> Inside your new 130 </para></listitem>
101 layer folder, you need to create a <filename>conf/layer.conf</filename> file. 131 <listitem><para><emphasis>Create a Layer Configuration
102 It is easiest to take an existing layer configuration file and copy that to your 132 File:</emphasis>
103 layer's <filename>conf</filename> directory and then modify the file as needed.</para> 133 Inside your new layer folder, you need to create a
104 <para>The <filename>meta-yocto-bsp/conf/layer.conf</filename> file demonstrates the 134 <filename>conf/layer.conf</filename> file.
105 required syntax: 135 It is easiest to take an existing layer configuration
136 file and copy that to your layer's
137 <filename>conf</filename> directory and then modify the
138 file as needed.</para>
139 <para>The
140 <filename>meta-yocto-bsp/conf/layer.conf</filename> file
141 demonstrates the required syntax:
106 <literallayout class='monospaced'> 142 <literallayout class='monospaced'>
107 # We have a conf and classes directory, add to BBPATH 143 # We have a conf and classes directory, add to BBPATH
108 BBPATH .= ":${LAYERDIR}" 144 BBPATH .= ":${LAYERDIR}"
@@ -161,73 +197,95 @@
161 </itemizedlist></para> 197 </itemizedlist></para>
162 <para>Note the use of the 198 <para>Note the use of the
163 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-LAYERDIR'>LAYERDIR</ulink></filename> 199 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-LAYERDIR'>LAYERDIR</ulink></filename>
164 variable, which expands to the directory of the current layer.</para> 200 variable, which expands to the directory of the current
165 <para>Through the use of the <filename>BBPATH</filename> variable, 201 layer.</para>
166 BitBake locates <filename>.bbclass</filename> files, configuration 202 <para>Through the use of the <filename>BBPATH</filename>
167 files, and files that are included with <filename>include</filename> 203 variable, BitBake locates <filename>.bbclass</filename>
168 and <filename>require</filename> statements. 204 files, configuration files, and files that are included
169 For these cases, BitBake uses the first file with the matching name found in 205 with <filename>include</filename> and
170 <filename>BBPATH</filename>. 206 <filename>require</filename> statements.
171 This is similar to the way the <filename>PATH</filename> variable is used for binaries. 207 For these cases, BitBake uses the first file that
172 We recommend, therefore, that you use unique <filename>.bbclass</filename> 208 matches the name found in <filename>BBPATH</filename>.
173 and configuration file names in your custom layer.</para></listitem> 209 This is similar to the way the <filename>PATH</filename>
174 <listitem><para><emphasis>Add Content:</emphasis> Depending on the type of layer, 210 variable is used for binaries.
175 add the content. 211 We recommend, therefore, that you use unique
176 If the layer adds support for a machine, add the machine configuration in 212 <filename>.bbclass</filename> and configuration
177 a <filename>conf/machine/</filename> file within the layer. 213 filenames in your custom layer.</para></listitem>
178 If the layer adds distro policy, add the distro configuration in a 214 <listitem><para><emphasis>Add Content:</emphasis> Depending
179 <filename>conf/distro/</filename> file with the layer. 215 on the type of layer, add the content.
180 If the layer introduces new recipes, put the recipes you need in 216 If the layer adds support for a machine, add the machine
181 <filename>recipes-*</filename> subdirectories within the layer. 217 configuration in a <filename>conf/machine/</filename>
182 <note>In order to be compliant with the Yocto Project, a layer must contain 218 file within the layer.
183 a <ulink url='&YOCTO_DOCS_BSP_URL;#bsp-filelayout-readme'>README file.</ulink> 219 If the layer adds distro policy, add the distro
220 configuration in a <filename>conf/distro/</filename>
221 file with the layer.
222 If the layer introduces new recipes, put the recipes
223 you need in <filename>recipes-*</filename>
224 subdirectories within the layer.
225 <note>In order to be compliant with the Yocto Project,
226 a layer must contain a
227 <ulink url='&YOCTO_DOCS_BSP_URL;#bsp-filelayout-readme'>README file.</ulink>
184 </note></para></listitem> 228 </note></para></listitem>
185 </orderedlist> 229 </orderedlist>
186 </para> 230 </para>
187 231
188 <para> 232 <para>
189 To create layers that are easier to maintain, you should consider the following: 233 To create layers that are easier to maintain, you should
234 consider the following:
190 <itemizedlist> 235 <itemizedlist>
191 <listitem><para>Avoid "overlaying" entire recipes from other layers in your 236 <listitem><para>Avoid "overlaying" entire recipes from
192 configuration. 237 other layers in your configuration.
193 In other words, don't copy an entire recipe into your layer and then modify it. 238 In other words, don't copy an entire recipe into your
194 Use <filename>.bbappend</filename> files to override the parts of the 239 layer and then modify it.
195 recipe you need to modify.</para></listitem> 240 Use <filename>.bbappend</filename> files to override the
241 parts of the recipe you need to modify.
242 </para></listitem>
196 <listitem><para>Avoid duplicating include files. 243 <listitem><para>Avoid duplicating include files.
197 Use <filename>.bbappend</filename> files for each recipe that uses an include 244 Use <filename>.bbappend</filename> files for each recipe
198 file. 245 that uses an include file.
199 Or, if you are introducing a new recipe that requires the included file, use the 246 Or, if you are introducing a new recipe that requires
200 path relative to the original layer directory to refer to the file. 247 the included file, use the path relative to the original
201 For example, use <filename>require recipes-core/somepackage/somefile.inc</filename> 248 layer directory to refer to the file.
249 For example, use
250 <filename>require recipes-core/somepackage/somefile.inc</filename>
202 instead of <filename>require somefile.inc</filename>. 251 instead of <filename>require somefile.inc</filename>.
203 If you're finding you have to overlay the include file, it could indicate a 252 If you're finding you have to overlay the include file,
204 deficiency in the include file in the layer to which it originally belongs. 253 it could indicate a deficiency in the include file in
205 If this is the case, you need to address that deficiency instead of overlaying 254 the layer to which it originally belongs.
206 the include file. 255 If this is the case, you need to address that deficiency
207 For example, consider how Qt 4 database support plug-ins are configured. 256 instead of overlaying the include file.
208 The Source Directory does not have 257 For example, consider how Qt 4 database support plug-ins
209 MySQL or PostgreSQL, however OpenEmbedded's 258 are configured.
210 layer <filename>meta-oe</filename> does. 259 The Source Directory does not have MySQL or PostgreSQL,
211 Consequently, <filename>meta-oe</filename> uses <filename>.bbappend</filename> 260 however OpenEmbedded's layer
212 files to modify the <filename>QT_SQL_DRIVER_FLAGS</filename> variable to enable 261 <filename>meta-oe</filename> does.
213 the appropriate plugins. 262 Consequently, <filename>meta-oe</filename> uses
214 This variable was added to the <filename>qt4.inc</filename> include file in 263 <filename>.bbappend</filename> files to modify the
215 the Source Directory specifically to allow the <filename>meta-oe</filename> layer 264 <filename>QT_SQL_DRIVER_FLAGS</filename> variable to
216 to be able to control which plugins are built.</para></listitem> 265 enable the appropriate plugins.
266 This variable was added to the
267 <filename>qt4.inc</filename> include file in the Source
268 Directory specifically to allow the
269 <filename>meta-oe</filename> layer to be able to control
270 which plugins are built.</para></listitem>
217 </itemizedlist> 271 </itemizedlist>
218 </para> 272 </para>
219 273
220 <para> 274 <para>
221 We also recommend the following: 275 We also recommend the following:
222 <itemizedlist> 276 <itemizedlist>
223 <listitem><para>Store custom layers in a Git repository that uses the 277 <listitem><para>Store custom layers in a Git repository
224 <filename>meta-&lt;layer_name&gt;</filename> format.</para></listitem> 278 that uses the
225 <listitem><para>Clone the repository alongside other <filename>meta</filename> 279 <filename>meta-&lt;layer_name&gt;</filename> format.
226 directories in the 280 </para></listitem>
227 <link linkend='source-directory'>Source Directory</link>.</para></listitem> 281 <listitem><para>Clone the repository alongside other
282 <filename>meta</filename> directories in the
283 <link linkend='source-directory'>Source Directory</link>.
284 </para></listitem>
228 </itemizedlist> 285 </itemizedlist>
229 Following these recommendations keeps your Source Directory and 286 Following these recommendations keeps your Source Directory and
230 its configuration entirely inside the Yocto Project's core base. 287 its configuration entirely inside the Yocto Project's core
288 base.
231 </para> 289 </para>
232 </section> 290 </section>
233 291
@@ -235,12 +293,15 @@
235 <title>Enabling Your Layer</title> 293 <title>Enabling Your Layer</title>
236 294
237 <para> 295 <para>
238 Before the OpenEmbedded build system can use your new layer, you need to enable it. 296 Before the OpenEmbedded build system can use your new layer,
297 you need to enable it.
239 To enable your layer, simply add your layer's path to the 298 To enable your layer, simply add your layer's path to the
240 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BBLAYERS'>BBLAYERS</ulink></filename> 299 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BBLAYERS'>BBLAYERS</ulink></filename>
241 variable in your <filename>conf/bblayers.conf</filename> file, which is found in the 300 variable in your <filename>conf/bblayers.conf</filename> file,
301 which is found in the
242 <link linkend='build-directory'>Build Directory</link>. 302 <link linkend='build-directory'>Build Directory</link>.
243 The following example shows how to enable a layer named <filename>meta-mylayer</filename>: 303 The following example shows how to enable a layer named
304 <filename>meta-mylayer</filename>:
244 <literallayout class='monospaced'> 305 <literallayout class='monospaced'>
245 LCONF_VERSION = "6" 306 LCONF_VERSION = "6"
246 307
@@ -262,12 +323,13 @@
262 </para> 323 </para>
263 324
264 <para> 325 <para>
265 BitBake parses each <filename>conf/layer.conf</filename> file as specified in the 326 BitBake parses each <filename>conf/layer.conf</filename> file
266 <filename>BBLAYERS</filename> variable within the <filename>conf/bblayers.conf</filename> 327 as specified in the <filename>BBLAYERS</filename> variable
267 file. 328 within the <filename>conf/bblayers.conf</filename> file.
268 During the processing of each <filename>conf/layer.conf</filename> file, BitBake adds the 329 During the processing of each
269 recipes, classes and configurations contained within the particular layer to the source 330 <filename>conf/layer.conf</filename> file, BitBake adds the
270 directory. 331 recipes, classes and configurations contained within the
332 particular layer to the source directory.
271 </para> 333 </para>
272 </section> 334 </section>
273 335
@@ -275,48 +337,58 @@
275 <title>Using .bbappend Files</title> 337 <title>Using .bbappend Files</title>
276 338
277 <para> 339 <para>
278 Recipes used to append metadata to other recipes are called BitBake append files. 340 Recipes used to append Metadata to other recipes are called
279 BitBake append files use the <filename>.bbappend</filename> file type suffix, while 341 BitBake append files.
280 the corresponding recipes to which metadata is being appended use the 342 BitBake append files use the <filename>.bbappend</filename> file
281 <filename>.bb</filename> file type suffix. 343 type suffix, while the corresponding recipes to which Metadata
344 is being appended use the <filename>.bb</filename> file type
345 suffix.
282 </para> 346 </para>
283 347
284 <para> 348 <para>
285 A <filename>.bbappend</filename> file allows your layer to make additions or 349 A <filename>.bbappend</filename> file allows your layer to make
286 changes to the content of another layer's recipe without having to copy the other 350 additions or changes to the content of another layer's recipe
287 recipe into your layer. 351 without having to copy the other recipe into your layer.
288 Your <filename>.bbappend</filename> file resides in your layer, while the underlying 352 Your <filename>.bbappend</filename> file resides in your layer,
289 <filename>.bb</filename> recipe file to which you are appending metadata 353 while the main <filename>.bb</filename> recipe file to
290 resides in a different layer. 354 which you are appending Metadata resides in a different layer.
291 </para> 355 </para>
292 356
293 <para> 357 <para>
294 Append files must have the same root name as the corresponding recipe. 358 Append files must have the same root name as the corresponding
295 For example, the append file <filename>someapp_&DISTRO;.bbappend</filename> must 359 recipe.
296 apply to <filename>someapp_&DISTRO;.bb</filename>. 360 For example, the append file
297 This means the original recipe and append file names are version number-specific. 361 <filename>someapp_&DISTRO;.bbappend</filename> must apply to
298 If the corresponding recipe is renamed to update to a newer version, the 362 <filename>someapp_&DISTRO;.bb</filename>.
299 underlying <filename>.bbappend</filename> file must be renamed as well. 363 This means the original recipe and append file names are version
300 During the build process, BitBake displays an error on starting if it detects a 364 number-specific.
301 <filename>.bbappend</filename> file that does not have a corresponding recipe 365 If the corresponding recipe is renamed to update to a newer
302 with a matching name. 366 version, the underlying <filename>.bbappend</filename> file must
367 be renamed as well.
368 During the build process, BitBake displays an error on starting
369 if it detects a <filename>.bbappend</filename> file that does
370 not have a corresponding recipe with a matching name.
303 See the 371 See the
304 <ulink url='&YOCTO_DOCS_REF_URL;#var-BB_DANGLINGAPPENDS_WARNONLY'><filename>BB_DANGLINGAPPENDS_WARNONLY</filename></ulink> 372 <ulink url='&YOCTO_DOCS_REF_URL;#var-BB_DANGLINGAPPENDS_WARNONLY'><filename>BB_DANGLINGAPPENDS_WARNONLY</filename></ulink>
305 variable for information on how to handle this error. 373 variable for information on how to handle this error.
306 </para> 374 </para>
307 375
308 <para> 376 <para>
309 Being able to append information to an existing recipe not only avoids duplication, 377 Being able to append information to an existing recipe not only
310 but also automatically applies recipe changes in a different layer to your layer. 378 avoids duplication, but also automatically applies recipe
311 If you were copying recipes, you would have to manually merge changes as they occur. 379 changes in a different layer to your layer.
380 If you were copying recipes, you would have to manually merge
381 changes as they occur.
312 </para> 382 </para>
313 383
314 <para> 384 <para>
315 As an example, consider the main formfactor recipe and a corresponding formfactor 385 As an example, consider the main formfactor recipe and a
316 append file both from the 386 corresponding formfactor append file both from the
317 <link linkend='source-directory'>Source Directory</link>. 387 <link linkend='source-directory'>Source Directory</link>.
318 Here is the main formfactor recipe, which is named <filename>formfactor_0.0.bb</filename> and 388 Here is the main formfactor recipe, which is named
319 located in the "meta" layer at <filename>meta/recipes-bsp/formfactor</filename>: 389 <filename>formfactor_0.0.bb</filename> and located in the
390 "meta" layer at
391 <filename>meta/recipes-bsp/formfactor</filename>:
320 <literallayout class='monospaced'> 392 <literallayout class='monospaced'>
321 DESCRIPTION = "Device formfactor information" 393 DESCRIPTION = "Device formfactor information"
322 SECTION = "base" 394 SECTION = "base"
@@ -340,8 +412,10 @@
340 fi 412 fi
341 } 413 }
342 </literallayout> 414 </literallayout>
343 Here is the append file, which is named <filename>formfactor_0.0.bbappend</filename> and is from the 415 Here is the append file, which is named
344 Crown Bay BSP Layer named <filename>meta-intel/meta-crownbay</filename>. 416 <filename>formfactor_0.0.bbappend</filename> and is from the
417 Crown Bay BSP Layer named
418 <filename>meta-intel/meta-crownbay</filename>.
345 The file is in <filename>recipes-bsp/formfactor</filename>: 419 The file is in <filename>recipes-bsp/formfactor</filename>:
346 <literallayout class='monospaced'> 420 <literallayout class='monospaced'>
347 FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" 421 FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
@@ -350,20 +424,24 @@
350 </literallayout> 424 </literallayout>
351 This example adds or overrides files in 425 This example adds or overrides files in
352 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> 426 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
353 within a <filename>.bbappend</filename> by extending the path BitBake uses to search for files. 427 within a <filename>.bbappend</filename> by extending the path
428 BitBake uses to search for files.
354 The most reliable way to do this is by prepending the 429 The most reliable way to do this is by prepending the
355 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink> 430 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
356 variable. 431 variable.
357 For example, if you have your files in a directory that is named the same as your package 432 For example, if you have your files in a directory that is named
433 the same as your package
358 (<ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink>), 434 (<ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink>),
359 you can add this directory by adding the following to your <filename>.bbappend</filename> file: 435 you can add this directory by adding the following to your
436 <filename>.bbappend</filename> file:
360 <literallayout class='monospaced'> 437 <literallayout class='monospaced'>
361 FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" 438 FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
362 </literallayout> 439 </literallayout>
363 Using the immediate expansion assignment operator <filename>:=</filename> is important because 440 Using the immediate expansion assignment operator
364 of the reference to <filename>THISDIR</filename>. 441 <filename>:=</filename> is important because of the reference to
365 The trailing colon character is important as it ensures that items in the list remain 442 <filename>THISDIR</filename>.
366 colon-separated. 443 The trailing colon character is important as it ensures that
444 items in the list remain colon-separated.
367 <note><para>BitBake automatically defines the 445 <note><para>BitBake automatically defines the
368 <filename>THISDIR</filename> variable. 446 <filename>THISDIR</filename> variable.
369 You should never set this variable yourself. 447 You should never set this variable yourself.
@@ -383,13 +461,15 @@
383 461
384 <para> 462 <para>
385 Each layer is assigned a priority value. 463 Each layer is assigned a priority value.
386 Priority values control which layer takes precedence if there are recipe files with 464 Priority values control which layer takes precedence if there
387 the same name in multiple layers. 465 are recipe files with the same name in multiple layers.
388 For these cases, the recipe file from the layer with a higher priority number takes precedence. 466 For these cases, the recipe file from the layer with a higher
389 Priority values also affect the order in which multiple <filename>.bbappend</filename> files 467 priority number takes precedence.
390 for the same recipe are applied. 468 Priority values also affect the order in which multiple
391 You can either specify the priority manually, or allow the build system to calculate it 469 <filename>.bbappend</filename> files for the same recipe are
392 based on the layer's dependencies. 470 applied.
471 You can either specify the priority manually, or allow the
472 build system to calculate it based on the layer's dependencies.
393 </para> 473 </para>
394 474
395 <para> 475 <para>
@@ -406,8 +486,9 @@
406 <para>It is possible for a recipe with a lower version number 486 <para>It is possible for a recipe with a lower version number
407 <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink> 487 <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>
408 in a layer that has a higher priority to take precedence.</para> 488 in a layer that has a higher priority to take precedence.</para>
409 <para>Also, the layer priority does not currently affect the precedence order of 489 <para>Also, the layer priority does not currently affect the
410 <filename>.conf</filename> or <filename>.bbclass</filename> files. 490 precedence order of <filename>.conf</filename>
491 or <filename>.bbclass</filename> files.
411 Future versions of BitBake might address this.</para> 492 Future versions of BitBake might address this.</para>
412 </note> 493 </note>
413 </section> 494 </section>
@@ -416,11 +497,12 @@
416 <title>Managing Layers</title> 497 <title>Managing Layers</title>
417 498
418 <para> 499 <para>
419 You can use the BitBake layer management tool to provide a view into the structure of 500 You can use the BitBake layer management tool to provide a view
420 recipes across a multi-layer project. 501 into the structure of recipes across a multi-layer project.
421 Being able to generate output that reports on configured layers with their paths and 502 Being able to generate output that reports on configured layers
422 priorities and on <filename>.bbappend</filename> files and their applicable recipes 503 with their paths and priorities and on
423 can help to reveal potential problems. 504 <filename>.bbappend</filename> files and their applicable
505 recipes can help to reveal potential problems.
424 </para> 506 </para>
425 507
426 <para> 508 <para>
@@ -431,46 +513,64 @@
431 The following list describes the available commands: 513 The following list describes the available commands:
432 <itemizedlist> 514 <itemizedlist>
433 <listitem><para><filename><emphasis>help:</emphasis></filename> 515 <listitem><para><filename><emphasis>help:</emphasis></filename>
434 Displays general help or help on a specified command.</para></listitem> 516 Displays general help or help on a specified command.
517 </para></listitem>
435 <listitem><para><filename><emphasis>show-layers:</emphasis></filename> 518 <listitem><para><filename><emphasis>show-layers:</emphasis></filename>
436 Show the current configured layers.</para></listitem> 519 Show the current configured layers.
520 </para></listitem>
437 <listitem><para><filename><emphasis>show-recipes:</emphasis></filename> 521 <listitem><para><filename><emphasis>show-recipes:</emphasis></filename>
438 Lists available recipes and the layers that provide them. 522 Lists available recipes and the layers that provide them.
439 </para></listitem> 523 </para></listitem>
440 <listitem><para><filename><emphasis>show-overlayed:</emphasis></filename> 524 <listitem><para><filename><emphasis>show-overlayed:</emphasis></filename>
441 Lists overlayed recipes. 525 Lists overlayed recipes.
442 A recipe is overlayed when a recipe with the same name exists in another layer 526 A recipe is overlayed when a recipe with the same name
443 that has a higher layer priority. 527 exists in another layer that has a higher layer
528 priority.
444 </para></listitem> 529 </para></listitem>
445 <listitem><para><filename><emphasis>show-appends:</emphasis></filename> 530 <listitem><para><filename><emphasis>show-appends:</emphasis></filename>
446 Lists <filename>.bbappend</filename> files and the recipe files to which 531 Lists <filename>.bbappend</filename> files and the
447 they apply.</para></listitem> 532 recipe files to which they apply.
533 </para></listitem>
448 <listitem><para><filename><emphasis>show-cross-depends:</emphasis></filename> 534 <listitem><para><filename><emphasis>show-cross-depends:</emphasis></filename>
449 Lists dependency relationships between recipes that cross layer boundaries. 535 Lists dependency relationships between recipes that
536 cross layer boundaries.
450 </para></listitem> 537 </para></listitem>
451 <listitem><para><filename><emphasis>flatten:</emphasis></filename> 538 <listitem><para><filename><emphasis>flatten:</emphasis></filename>
452 Flattens the layer configuration into a separate output directory. 539 Flattens the layer configuration into a separate output
453 Flattening your layer configuration builds a "flattened" directory that contains 540 directory.
454 the contents of all layers, with any overlayed recipes removed and any 541 Flattening your layer configuration builds a "flattened"
455 <filename>.bbappend</filename> files appended to the corresponding recipes. 542 directory that contains the contents of all layers,
456 You might have to perform some manual cleanup of the flattened layer as follows: 543 with any overlayed recipes removed and any
544 <filename>.bbappend</filename> files appended to the
545 corresponding recipes.
546 You might have to perform some manual cleanup of the
547 flattened layer as follows:
457 <itemizedlist> 548 <itemizedlist>
458 <listitem><para>Non-recipe files (such as patches) are overwritten. 549 <listitem><para>Non-recipe files (such as patches)
459 The flatten command shows a warning for these files.</para></listitem> 550 are overwritten.
460 <listitem><para>Anything beyond the normal layer setup has been added to 551 The flatten command shows a warning for these
461 the <filename>layer.conf</filename> file. 552 files.
462 Only the lowest priority layer's <filename>layer.conf</filename> is used. 553 </para></listitem>
554 <listitem><para>Anything beyond the normal layer
555 setup has been added to the
556 <filename>layer.conf</filename> file.
557 Only the lowest priority layer's
558 <filename>layer.conf</filename> is used.
463 </para></listitem> 559 </para></listitem>
464 <listitem><para>Overridden and appended items from <filename>.bbappend</filename> 560 <listitem><para>Overridden and appended items from
465 files need to be cleaned up. 561 <filename>.bbappend</filename> files need to be
466 The contents of each <filename>.bbappend</filename> end up in the 562 cleaned up.
563 The contents of each
564 <filename>.bbappend</filename> end up in the
467 flattened recipe. 565 flattened recipe.
468 However, if there are appended or changed variable values, you need to tidy 566 However, if there are appended or changed
469 these up yourself. 567 variable values, you need to tidy these up
568 yourself.
470 Consider the following example. 569 Consider the following example.
471 Here, the <filename>bitbake-layers</filename> command adds the line 570 Here, the <filename>bitbake-layers</filename>
472 <filename>#### bbappended ...</filename> so that you know where the following 571 command adds the line
473 lines originate: 572 <filename>#### bbappended ...</filename> so that
573 you know where the following lines originate:
474 <literallayout class='monospaced'> 574 <literallayout class='monospaced'>
475 ... 575 ...
476 DESCRIPTION = "A useful utility" 576 DESCRIPTION = "A useful utility"
@@ -483,7 +583,8 @@
483 DESCRIPTION = "Customized utility" 583 DESCRIPTION = "Customized utility"
484 EXTRA_OECONF += "--enable-somethingelse" 584 EXTRA_OECONF += "--enable-somethingelse"
485 </literallayout> 585 </literallayout>
486 Ideally, you would tidy up these utilities as follows: 586 Ideally, you would tidy up these utilities as
587 follows:
487 <literallayout class='monospaced'> 588 <literallayout class='monospaced'>
488 ... 589 ...
489 DESCRIPTION = "Customized utility" 590 DESCRIPTION = "Customized utility"
@@ -495,6 +596,134 @@
495 </itemizedlist> 596 </itemizedlist>
496 </para> 597 </para>
497 </section> 598 </section>
599
600 <section id='creating-a-general-layer-using-the-yocto-layer-script'>
601 <title>Creating a General Layer Using the yocto-layer Script</title>
602
603 <para>
604 The <filename>yocto-layer</filename> script simplifies
605 creating a new general layer.
606 <note>
607 For information on BSP layers, see the
608 "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>"
609 section in the Yocto Project Board Specific (BSP)
610 Developer's Guide.
611 </note>
612 The default mode of the script's operation is to prompt you for
613 information needed to generate the layer:
614 <itemizedlist>
615 <listitem><para>The layer priority
616 </para></listitem>
617 <listitem><para>Whether or not to create a sample recipe.
618 </para></listitem>
619 <listitem><para>Whether or not to create a sample
620 append file.
621 </para></listitem>
622 </itemizedlist>
623 </para>
624
625 <para>
626 You use the <filename>yocto-layer create</filename> sub-command
627 to create a new general layer.
628 In its simplest form, you can create a layer as follows:
629 <literallayout class='monospaced'>
630 $ yocto-layer create mylayer
631 </literallayout>
632 The previous example creates a layer named
633 <filename>meta-mylayer</filename> in the current directory.
634 </para>
635
636 <para>
637 As the <filename>yocto-layer create</filename> command runs,
638 default values for the prompts appear in brackets.
639 Pressing enter without supplying anything on the command line
640 or pressing enter and providing an invalid response causes the
641 script to accept the default value.
642 Once the script completes, the new layer
643 is created in the current working directory.
644 The script names the layer according to the string you provide
645 and the prepended <filename>meta-</filename> string.
646 </para>
647
648 <para>
649 If you choose to not generate a sample recipe or append file,
650 the script creates the following within the layer:
651 <itemizedlist>
652 <listitem><para><emphasis>The <filename>conf</filename>
653 directory:</emphasis>
654 This directory contains the layers
655 <filename>.conf</filename>.
656 The root name for the file is the same as the root name
657 your provided for the layer.
658 </para></listitem>
659 <listitem><para><emphasis>The
660 <filename>COPYING.MIT</filename>:</emphasis>
661 The copyright and use notice for the software.
662 </para></listitem>
663 <listitem><para><emphasis>The <filename>README</filename>
664 file:</emphasis>
665 A file describing the contents of your new layer.
666 </para></listitem>
667 </itemizedlist>
668 </para>
669
670 <para>
671 If you choose to generate a sample recipe file, the script
672 prompts you for the name for the recipe and then creates it
673 in <filename>&lt;layer&gt;/recipes-example/example/</filename>.
674 in a directory named <filename>recipes-example</filename>.
675 The script creates a <filename>.bb</filename> file and a
676 directory, which contains a sample
677 <filename>helloworld.c</filename>source file and along with
678 a sample patch file.
679 If you do not provide a recipe name, the script uses
680 "example".
681 </para>
682
683 <para>
684 If you choose to generate a sample append file, the script
685 prompts you for the name for the file and then creates it
686 in <filename>&lt;layer&gt;/recipes-example-bbappend/example-bbappend/</filename>.
687 The script creates a <filename>.bbappend</filename> file and a
688 directory, which contains a sample patch file.
689 If you do not provide a recipe name, the script uses
690 "example".
691 The script also prompts you for the version of the append file.
692 The version should match the recipe to which the append file
693 is associated.
694 </para>
695
696 <para>
697 The easiest way to see how the <filename>yocto-layer</filename>
698 script works is to experiment with the script.
699 You can also read the usage information by entering the
700 following:
701 <literallayout class='monospaced'>
702 $ yocto-layer help
703 </literallayout>
704 </para>
705
706 <para>
707 Once you create your general layer, you must add it to your
708 <filename>bblayers.conf</filename> file.
709 Here is an example:
710 <literallayout class='monospaced'>
711 BBLAYERS = ?" \
712 /usr/local/src/yocto/meta \
713 /usr/local/src/yocto/meta-yocto \
714 /usr/local/src/yocto/meta-yocto-bsp \
715 /usr/local/src/yocto/meta-mylayer \
716 "
717
718 BBLAYERS_NON_REMOVABLE ?= " \
719 /usr/local/src/yocto/meta \
720 /usr/local/src/yocto/meta-yocto \
721 "
722 </literallayout>
723 Adding the layer to this file enables the build system to
724 the layer during the build.
725 </para>
726 </section>
498 </section> 727 </section>
499 728
500 <section id='usingpoky-extend-customimage'> 729 <section id='usingpoky-extend-customimage'>
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2025-01-16 17:35:00 +0000