summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorScott Rifenbark <scott.m.rifenbark@intel.com>2012-03-06 10:37:59 -0600
committerRichard Purdie <richard.purdie@linuxfoundation.org>2012-03-08 12:08:08 -0800
commitae647f6032f6f637829adb2eba896ec924eacb29 (patch)
tree1dd9ce45dc15bd0b4642f27e67c84b45f60a5fa2
parent1084bc5d77c430e8fd8c3d26a5c5ec0cda24aca3 (diff)
downloadpoky-ae647f6032f6f637829adb2eba896ec924eacb29.tar.gz
documentation/dev-manual/dev-manual-common-tasks.xml: Review comments
Applied the review comments from Paul Eggleton for the new section on "Understanding and Using Layers." (From yocto-docs rev: 6bf5854dd355afdbc01c4c4fb94a4062bd9eae20) Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
-rw-r--r--documentation/dev-manual/dev-manual-common-tasks.xml90
1 files changed, 48 insertions, 42 deletions
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index 9f7d04244a..4702ae94e3 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -77,7 +77,8 @@
77 you need. 77 you need.
78 You can see the 78 You can see the
79 <ulink url='http://www.openembedded.org/wiki/LayerIndex'><filename>LayerIndex</filename></ulink> 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> 80 for a list of layers from the OpenEmbedded community that can be used in the
81 Yocto Project.</para></listitem>
81 <listitem><para><emphasis>Create a Directory:</emphasis> Create the directory 82 <listitem><para><emphasis>Create a Directory:</emphasis> Create the directory
82 for your layer. 83 for your layer.
83 Traditionally, prepend the name of the folder with the string 84 Traditionally, prepend the name of the folder with the string
@@ -113,12 +114,14 @@
113 variable is then appended with the layer name. 114 variable is then appended with the layer name.
114 The 115 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 <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 variable is set to a regular expression and is used to match files
117 <filename>BBFILES</filename> into a particular layer, in this case by using 118 from <filename>BBFILES</filename> into a particular layer.
118 the base pathname. 119 In this case, immediate expansion of
120 <filename><ulink url='http://www.yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html#var-LAYERDIR'>LAYERDIR</ulink></filename>
121 sets <filename>BBFILES_PATTERN</filename> to the layer's path.
119 The 122 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> 123 <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. 124 variable then assigns a priority to the layer.
122 Applying priorities is useful in situations where the same package might appear in multiple 125 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> 126 layers and allows you to choose what layer should take precedence.</para>
124 <para>Note the use of the 127 <para>Note the use of the
@@ -127,8 +130,9 @@
127 The <filename>LAYERDIR</filename> variable expands to the directory of the current layer and 130 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 131 requires the immediate expansion operator so that BitBake does not wait to expand the variable
129 when it's parsing a different directory.</para> 132 when it's parsing a different directory.</para>
130 <para>BitBake can locate where other <filename>.bbclass</filename> and configuration files 133 <para>BitBake locates included <filename>.bbclass</filename>, configuration,
131 are applied through the <filename>BBPATH</filename> environment variable. 134 and other files using the <filename>include</filename> and <filename>require</filename>
135 statements by way of the <filename>BBPATH</filename> environment variable.
132 For these cases, BitBake uses the first file with the matching name found in 136 For these cases, BitBake uses the first file with the matching name found in
133 <filename>BBPATH</filename>. 137 <filename>BBPATH</filename>.
134 This is similar to the way the <filename>PATH</filename> variable is used for binaries. 138 This is similar to the way the <filename>PATH</filename> variable is used for binaries.
@@ -218,9 +222,6 @@
218 During the processing of each <filename>conf/layer.conf</filename> file, BitBake adds the 222 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 223 recipes, classes and configurations contained within the particular layer to the Yocto
220 Project. 224 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 </para>
225 </section> 226 </section>
226 227
@@ -242,9 +243,9 @@
242 This means the original recipe and append file names are version number specific. 243 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 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 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 During the build process, BitBake displays an error on starting if it detects a
246 <filename>.bbappend</filename> file that does not have an underlying recipe 247 <filename>.bbappend</filename> file that does not have an underlying recipe
247 with the proper name. 248 with a matching name.
248 </para> 249 </para>
249 250
250 <para> 251 <para>
@@ -299,8 +300,10 @@
299 <literallayout class='monospaced'> 300 <literallayout class='monospaced'>
300 FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" 301 FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
301 </literallayout> 302 </literallayout>
302 Using the immediate expansion assignment operator <filename>:=</filename> and the trailing colon 303 Using the immediate expansion assignment operator <filename>:=</filename> is important because
303 are important so that the resulting list of pathnames is syntactically correct. 304 of the reference to <filename>THISDIR</filename>.
305 The trailing colon character is important as it ensures that items in the list remain
306 colon-separated.
304 <note>BitBake automatically defines the <filename>THISDIR</filename> variable. 307 <note>BitBake automatically defines the <filename>THISDIR</filename> variable.
305 You should never set this variable yourself. 308 You should never set this variable yourself.
306 Using <filename>_prepend</filename> ensures your path will be searched prior to other 309 Using <filename>_prepend</filename> ensures your path will be searched prior to other
@@ -358,37 +361,40 @@
358 Use the following form when running the layer management tool. 361 Use the following form when running the layer management tool.
359 <literallayout class='monospaced'> 362 <literallayout class='monospaced'>
360 $ bitbake-layers &lt;command&gt; [arguments] 363 $ bitbake-layers &lt;command&gt; [arguments]
361
362 Available commands:
363 flatten
364 flattens layer configuration into a separate output directory.
365 help
366 display general help or help on a specified command
367 show_appends
368 list bbappend files and recipe files they apply to
369 show_layers
370 show current configured layers
371 show_overlayed
372 list overlayed recipes (where there is a recipe in another layer that has a higher layer priority)
373 help
374 display general help or help on a specified command
375 </literallayout> 364 </literallayout>
376 </para> 365 The following list describes the available commands:
377
378 <para>
379 Flattening your layer configuration builds a "flattened" directory that contains
380 the contents of all layers, with any overlayed recipes removed and any
381 recipe append files (<filename>.bbappend</filename>) appended to the corresponding recipes.
382 You might have to perform some manual cleanup of the flattened layer as follows:
383 <itemizedlist> 366 <itemizedlist>
384 <listitem><para>Non-recipe files (such as patches) are overwritten. 367 <listitem><para><filename><emphasis>flatten:</emphasis></filename>
385 The flatten command shows a warning for these files.</para></listitem> 368 Flattens the layer configuration into a separate output directory.
386 <listitem><para>Anything beyond the normal layer setup has been added to 369 Flattening your layer configuration builds a "flattened" directory that contains
387 the <filename>layer.conf</filename> file. 370 the contents of all layers, with any overlayed recipes removed and any
388 Only the lowest priority layer's <filename>layer.conf</filename> is used. 371 recipe append files (<filename>.bbappend</filename>) appended to the corresponding recipes.
372 You might have to perform some manual cleanup of the flattened layer as follows:
373 <itemizedlist>
374 <listitem><para>Non-recipe files (such as patches) are overwritten.
375 The flatten command shows a warning for these files.</para></listitem>
376 <listitem><para>Anything beyond the normal layer setup has been added to
377 the <filename>layer.conf</filename> file.
378 Only the lowest priority layer's <filename>layer.conf</filename> is used.
379 </para></listitem>
380 <listitem><para>Overridden and appended items from <filename>.bbappend</filename>
381 files need to be cleaned up.
382 For example, the contents of each <filename>.bbappend</filename> end up in the
383 flattened recipe.
384 However, if there are appended or changed variable values, you need to tidy
385 these up yourself.</para></listitem>
386 </itemizedlist></para></listitem>
387 <listitem><para><filename><emphasis>help:</emphasis></filename>
388 Displays general help or help on a specified command.</para></listitem>
389 <listitem><para><filename><emphasis>show_appends:</emphasis></filename>
390 Lists <filename>.bbappend</filename> files and the recipe files to which
391 they apply.</para></listitem>
392 <listitem><para><filename><emphasis>show_layers:</emphasis></filename>
393 Show the current configured layers.</para></listitem>
394 <listitem><para><filename><emphasis>show_overlayed:</emphasis></filename>
395 Lists overlayed recipes.
396 Overlayed recipes appear in another layer that has a higher layer priority.
389 </para></listitem> 397 </para></listitem>
390 <listitem><para>Overridden and appended items from <filename>.bbappend</filename>
391 files never need to be cleaned up.</para></listitem>
392 </itemizedlist> 398 </itemizedlist>
393 </para> 399 </para>
394 </section> 400 </section>