summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--documentation/dev-manual/dev-manual-common-tasks.xml246
1 files changed, 188 insertions, 58 deletions
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index 4bdeedb8d7..a4d837216e 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -228,65 +228,192 @@
228 </note></para></listitem> 228 </note></para></listitem>
229 </orderedlist> 229 </orderedlist>
230 </para> 230 </para>
231 </section>
231 232
232 <para> 233 <section id='best-practices-to-follow-when-creating-layers'>
233 To create layers that are easier to maintain, you should 234 <title>Best Practices to Follow When Creating Layers</title>
234 consider the following:
235 <itemizedlist>
236 <listitem><para>Avoid "overlaying" entire recipes from
237 other layers in your configuration.
238 In other words, do not copy an entire recipe into your
239 layer and then modify it.
240 Use <filename>.bbappend</filename> files to override the
241 parts of the recipe you need to modify.
242 </para></listitem>
243 <listitem><para>Avoid duplicating include files.
244 Use <filename>.bbappend</filename> files for each recipe
245 that uses an include file.
246 Or, if you are introducing a new recipe that requires
247 the included file, use the path relative to the original
248 layer directory to refer to the file.
249 For example, use
250 <filename>require recipes-core/somepackage/somefile.inc</filename>
251 instead of <filename>require somefile.inc</filename>.
252 If you're finding you have to overlay the include file,
253 it could indicate a deficiency in the include file in
254 the layer to which it originally belongs.
255 If this is the case, you need to address that deficiency
256 instead of overlaying the include file.
257 For example, consider how Qt 4 database support plug-ins
258 are configured.
259 The Source Directory does not have MySQL or PostgreSQL,
260 however OpenEmbedded's layer
261 <filename>meta-oe</filename> does.
262 Consequently, <filename>meta-oe</filename> uses
263 <filename>.bbappend</filename> files to modify the
264 <filename>QT_SQL_DRIVER_FLAGS</filename> variable to
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>
271 </itemizedlist>
272 </para>
273 235
274 <para> 236 <para>
275 We also recommend the following: 237 To create layers that are easier to maintain and that will
276 <itemizedlist> 238 not impact builds for other machines, you should consider the
277 <listitem><para>Store custom layers in a Git repository 239 information in the following sections.
278 that uses the
279 <filename>meta-&lt;layer_name&gt;</filename> format.
280 </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>
285 </itemizedlist>
286 Following these recommendations keeps your Source Directory and
287 its configuration entirely inside the Yocto Project's core
288 base.
289 </para> 240 </para>
241
242 <section id='avoid-overlaying-entire-recipes'>
243 <title>Avoid "Overlaying" Entire Recipes</title>
244
245 <para>
246 Avoid "overlaying" entire recipes from other layers in your
247 configuration.
248 In other words, do not copy an entire recipe into your
249 layer and then modify it.
250 Use <filename>.bbappend</filename> files to override the
251 parts of the recipe you need to modify.
252 </para>
253 </section>
254
255 <section id='avoid-duplicating-include-files'>
256 <title>Avoid Duplicating Include Files</title>
257
258 <para>
259 Avoid duplicating include files.
260 Use <filename>.bbappend</filename> files for each recipe
261 that uses an include file.
262 Or, if you are introducing a new recipe that requires
263 the included file, use the path relative to the original
264 layer directory to refer to the file.
265 For example, use
266 <filename>require recipes-core/somepackage/somefile.inc</filename>
267 instead of <filename>require somefile.inc</filename>.
268 If you're finding you have to overlay the include file,
269 it could indicate a deficiency in the include file in
270 the layer to which it originally belongs.
271 If this is the case, you need to address that deficiency
272 instead of overlaying the include file.
273 For example, consider how support plugins for the Qt 4
274 database are configured.
275 The Source Directory does not have MySQL or PostgreSQL.
276 However, OpenEmbedded's layer <filename>meta-oe</filename>
277 does.
278 Consequently, <filename>meta-oe</filename> uses
279 <filename>.bbappend</filename> files to modify the
280 <filename>QT_SQL_DRIVER_FLAGS</filename> variable to
281 enable the appropriate plugins.
282 This variable was added to the <filename>qt4.inc</filename>
283 include file in the Source Directory specifically to allow
284 the <filename>meta-oe</filename> layer to be able to control
285 which plugins are built.
286 </para>
287 </section>
288
289 <section id='structure-your-layers'>
290 <title>Structure Your Layers</title>
291
292 <para>
293 Proper use of overrides within append files and placement
294 of machine-specific files within your layer can ensure that
295 a build is not using the wrong Metadata and negatively
296 impacting a build for a different machine.
297 Following are some examples:
298 <itemizedlist>
299 <listitem><para><emphasis>Modifying Variables to support
300 a different machine:</emphasis>
301 Suppose you have a layer named
302 <filename>meta-one</filename> that adds support
303 for building machine "one".
304 To do so, you use an append file named
305 <filename>base-files.bbappend</filename> and
306 create a dependency on a file named
307 <filename>foo</filename> that contains the
308 altered variables:
309 <literallayout class='monospaced'>
310 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink> = "foo"
311 </literallayout>
312 The dependency is created during any build that
313 includes the layer
314 <filename>meta-one</filename>.
315 However, you might not want this dependency
316 for all machines.
317 For example, suppose you are building for
318 machine "two" but your
319 <filename>bblayers.conf</filename> file has the
320 <filename>meta-one</filename> layer included.
321 During the build, the
322 <filename>base-files</filename> for machine
323 "two" will also have the dependency on
324 <filename>foo</filename>.</para>
325 <para>To make sure your changes apply only when
326 building machine "one", use a machine override
327 with the <filename>DEPENDS</filename> statement:
328 <literallayout class='monospaced'>
329 DEPENDS_one = "foo"
330 </literallayout>
331 You should follow the same strategy when using
332 <filename>_append</filename> and
333 <filename>_prepend</filename> overrides:
334 <literallayout class='monospaced'>
335 DEPENDS_append_one = " foo"
336 DEPENDS_prepend_one = "foo "
337 </literallayout>
338 <note>
339 Avoiding "+=" and "=+" and using
340 machine-specific
341 <filename>_append</filename>
342 and <filename>_prepend</filename> overrides
343 is recommended as well.
344 </note></para></listitem>
345 <listitem><para><emphasis>Place Machine-Specific Files
346 in Machine-Specific Locations:</emphasis>
347 When you have a base recipe, such as
348 <filename>base-files.bb</filename>, that
349 contains a
350 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
351 statement to a file, you can use an append file
352 to cause the build to use your own version of
353 the file.
354 For example, an append file in your layer at
355 <filename>/meta-one/recipes-core/base-files/base-files.bbappend</filename>
356 could extend
357 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESPATH'><filename>FILESPATH</filename></ulink>
358 using
359 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
360 as follows:
361 <literallayout class='monospaced'>
362 FILESEXTRAPATHS_prepend := "${THISDIR}/${BPN}:"
363 </literallayout>
364 The build for machine "one" will pick up your
365 machine-specific file as long as you have the
366 file in
367 <filename>/meta-one/recipes-core/base-files/base-files/</filename>.
368 However, if you are building for a different
369 machine and the
370 <filename>bblayers.conf</filename> file includes
371 the <filename>meta-one</filename> layer and
372 the location of your machine-specific file is
373 the first location where that file is found
374 according to <filename>FILESPATH</filename>,
375 builds for all machines will also use that
376 machine-specific file.</para>
377 <para>You can make sure that a machine-specific
378 file is used for a particular machine by putting
379 the file in a subdirectory specific to the
380 machine.
381 For example, rather than placing the file in
382 <filename>/meta-one/recipes-core/base-files/base-files/</filename>
383 as shown above, put it in
384 <filename>/meta-one/recipes-core/base-files/base-files/one/</filename>.
385 Not only does this make sure the file is used
386 only when building for machine "one" but the
387 build process locates the file more quickly.</para>
388 <para>In summary, you need to place all files
389 referenced from <filename>SRC_URI</filename>
390 in a machine-specific subdirectory within the
391 layer in order to restrict those files to
392 machine-specific builds.</para></listitem>
393 </itemizedlist>
394 </para>
395 </section>
396
397 <section id='other-recommendations'>
398 <title>Other Recommendations</title>
399
400 <para>
401 We also recommend the following:
402 <itemizedlist>
403 <listitem><para>Store custom layers in a Git repository
404 that uses the
405 <filename>meta-&lt;layer_name&gt;</filename> format.
406 </para></listitem>
407 <listitem><para>Clone the repository alongside other
408 <filename>meta</filename> directories in the
409 <link linkend='source-directory'>Source Directory</link>.
410 </para></listitem>
411 </itemizedlist>
412 Following these recommendations keeps your Source Directory and
413 its configuration entirely inside the Yocto Project's core
414 base.
415 </para>
416 </section>
290 </section> 417 </section>
291 418
292 <section id='enabling-your-layer'> 419 <section id='enabling-your-layer'>
@@ -2469,9 +2596,12 @@
2469 If you have distro-specific configuration files 2596 If you have distro-specific configuration files
2470 that are included by an existing recipe, you should 2597 that are included by an existing recipe, you should
2471 add a <filename>.bbappend</filename> for those. 2598 add a <filename>.bbappend</filename> for those.
2472 For general information on how to add recipes to 2599 For general information and recommendations
2473 your layer, see the "<link linkend='creating-your-own-layer'>Creating Your Own Layer</link>" 2600 on how to add recipes to your layer, see the
2474 section.</para></listitem> 2601 "<link linkend='creating-your-own-layer'>Creating Your Own Layer</link>"
2602 and
2603 "<link linkend='best-practices-to-follow-when-creating-layers'>Best Practices to Follow When Creating Layers</link>"
2604 sections.</para></listitem>
2475 <listitem><para>Add any image recipes that are specific 2605 <listitem><para>Add any image recipes that are specific
2476 to your distribution.</para></listitem> 2606 to your distribution.</para></listitem>
2477 <listitem><para>Add a <filename>psplash</filename> 2607 <listitem><para>Add a <filename>psplash</filename>