summaryrefslogtreecommitdiffstats
path: root/documentation/dev-manual
diff options
context:
space:
mode:
authorScott Rifenbark <srifenbark@gmail.com>2017-08-07 16:59:41 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2017-08-09 09:25:24 +0100
commit07514c9003565e8e9b11d5550851cf31f4159241 (patch)
tree03a19d4f0cc6b6542ea5e658ce3e4ff780eb91a9 /documentation/dev-manual
parent7d7eb04b9c0cf5d8460f67f2d1c44f2c242bd755 (diff)
downloadpoky-07514c9003565e8e9b11d5550851cf31f4159241.tar.gz
dev-manual: Converted sections for following best layer practices
The section about following best practices was more of a reference section the way it was written. I recast the section and the sub-sections such that it is a list of items to consider. Also renamed the section to be more of an action section rather than passive. (From yocto-docs rev: 8b050a46c67a3d3e89d905cf028eec6ae370388a) Signed-off-by: Scott Rifenbark <srifenbark@gmail.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/dev-manual')
-rw-r--r--documentation/dev-manual/dev-manual-common-tasks.xml349
1 files changed, 167 insertions, 182 deletions
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index 7464172fc6..e4cfdcdef2 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -255,197 +255,182 @@
255 </section> 255 </section>
256 256
257 <section id='best-practices-to-follow-when-creating-layers'> 257 <section id='best-practices-to-follow-when-creating-layers'>
258 <title>Best Practices to Follow When Creating Layers</title> 258 <title>Following Best Practices When Creating Layers</title>
259 259
260 <para> 260 <para>
261 To create layers that are easier to maintain and that will 261 To create layers that are easier to maintain and that will
262 not impact builds for other machines, you should consider the 262 not impact builds for other machines, you should consider the
263 information in the following sections. 263 information in the following list:
264 </para> 264 <itemizedlist>
265 265 <listitem><para>
266 <section id='avoid-overlaying-entire-recipes'> 266 <emphasis>Avoid "Overlaying" Entire Recipes from Other Layers in Your Configuration:</emphasis>
267 <title>Avoid "Overlaying" Entire Recipes</title> 267 In other words, do not copy an entire recipe into your
268 268 layer and then modify it.
269 <para> 269 Rather, use an append file
270 Avoid "overlaying" entire recipes from other layers in your 270 (<filename>.bbappend</filename>) to override only those
271 configuration. 271 parts of the original recipe you need to modify.
272 In other words, do not copy an entire recipe into your 272 </para></listitem>
273 layer and then modify it. 273 <listitem><para>
274 Rather, use an append file (<filename>.bbappend</filename>) 274 <emphasis>Avoid Duplicating Include Files:</emphasis>
275 to override 275 Use append files (<filename>.bbappend</filename>)
276 only those parts of the original recipe you need to modify. 276 for each recipe that uses an include file.
277 </para> 277 Or, if you are introducing a new recipe that requires
278 </section> 278 the included file, use the path relative to the
279 279 original layer directory to refer to the file.
280 <section id='avoid-duplicating-include-files'> 280 For example, use
281 <title>Avoid Duplicating Include Files</title> 281 <filename>require recipes-core/</filename><replaceable>package</replaceable><filename>/</filename><replaceable>file</replaceable><filename>.inc</filename>
282 282 instead of
283 <para> 283 <filename>require </filename><replaceable>file</replaceable><filename>.inc</filename>.
284 Avoid duplicating include files. 284 If you're finding you have to overlay the include file,
285 Use append files (<filename>.bbappend</filename>) 285 it could indicate a deficiency in the include file in
286 for each recipe 286 the layer to which it originally belongs.
287 that uses an include file. 287 If this is the case, you should try to address that
288 Or, if you are introducing a new recipe that requires 288 deficiency instead of overlaying the include file.
289 the included file, use the path relative to the original 289 For example, you could address this by getting the
290 layer directory to refer to the file. 290 maintainer of the include file to add a variable or
291 For example, use 291 variables to make it easy to override the parts needing
292 <filename>require recipes-core/</filename><replaceable>package</replaceable><filename>/</filename><replaceable>file</replaceable><filename>.inc</filename> 292 to be overridden.
293 instead of <filename>require </filename><replaceable>file</replaceable><filename>.inc</filename>. 293 </para></listitem>
294 If you're finding you have to overlay the include file, 294 <listitem><para>
295 it could indicate a deficiency in the include file in 295 <emphasis>Structure Your Layers:</emphasis>
296 the layer to which it originally belongs. 296 Proper use of overrides within append files and
297 If this is the case, you should try to address that 297 placement of machine-specific files within your layer
298 deficiency instead of overlaying the include file. 298 can ensure that a build is not using the wrong Metadata
299 For example, you could address this by getting the 299 and negatively impacting a build for a different
300 maintainer of the include file to add a variable or 300 machine.
301 variables to make it easy to override the parts needing 301 Following are some examples:
302 to be overridden. 302 <itemizedlist>
303 </para> 303 <listitem><para>
304 </section> 304 <emphasis>Modify Variables to Support a
305 305 Different Machine:</emphasis>
306 <section id='structure-your-layers'> 306 Suppose you have a layer named
307 <title>Structure Your Layers</title> 307 <filename>meta-one</filename> that adds support
308 308 for building machine "one".
309 <para> 309 To do so, you use an append file named
310 Proper use of overrides within append files and placement 310 <filename>base-files.bbappend</filename> and
311 of machine-specific files within your layer can ensure that 311 create a dependency on "foo" by altering the
312 a build is not using the wrong Metadata and negatively 312 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink>
313 impacting a build for a different machine. 313 variable:
314 Following are some examples: 314 <literallayout class='monospaced'>
315 <itemizedlist>
316 <listitem><para><emphasis>Modifying Variables to Support
317 a Different Machine:</emphasis>
318 Suppose you have a layer named
319 <filename>meta-one</filename> that adds support
320 for building machine "one".
321 To do so, you use an append file named
322 <filename>base-files.bbappend</filename> and
323 create a dependency on "foo" by altering the
324 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink>
325 variable:
326 <literallayout class='monospaced'>
327 DEPENDS = "foo" 315 DEPENDS = "foo"
328 </literallayout> 316 </literallayout>
329 The dependency is created during any build that 317 The dependency is created during any build that
330 includes the layer 318 includes the layer
331 <filename>meta-one</filename>. 319 <filename>meta-one</filename>.
332 However, you might not want this dependency 320 However, you might not want this dependency
333 for all machines. 321 for all machines.
334 For example, suppose you are building for 322 For example, suppose you are building for
335 machine "two" but your 323 machine "two" but your
336 <filename>bblayers.conf</filename> file has the 324 <filename>bblayers.conf</filename> file has the
337 <filename>meta-one</filename> layer included. 325 <filename>meta-one</filename> layer included.
338 During the build, the 326 During the build, the
339 <filename>base-files</filename> for machine 327 <filename>base-files</filename> for machine
340 "two" will also have the dependency on 328 "two" will also have the dependency on
341 <filename>foo</filename>.</para> 329 <filename>foo</filename>.</para>
342 <para>To make sure your changes apply only when 330 <para>To make sure your changes apply only when
343 building machine "one", use a machine override 331 building machine "one", use a machine override
344 with the <filename>DEPENDS</filename> statement: 332 with the <filename>DEPENDS</filename> statement:
345 <literallayout class='monospaced'> 333 <literallayout class='monospaced'>
346 DEPENDS_one = "foo" 334 DEPENDS_one = "foo"
347 </literallayout> 335 </literallayout>
348 You should follow the same strategy when using 336 You should follow the same strategy when using
349 <filename>_append</filename> and 337 <filename>_append</filename> and
350 <filename>_prepend</filename> operations: 338 <filename>_prepend</filename> operations:
351 <literallayout class='monospaced'> 339 <literallayout class='monospaced'>
352 DEPENDS_append_one = " foo" 340 DEPENDS_append_one = " foo"
353 DEPENDS_prepend_one = "foo " 341 DEPENDS_prepend_one = "foo "
354 </literallayout> 342 </literallayout>
355 As an actual example, here's a line from the recipe 343 As an actual example, here's a line from the recipe
356 for gnutls, which adds dependencies on 344 for gnutls, which adds dependencies on
357 "argp-standalone" when building with the musl C 345 "argp-standalone" when building with the musl C
358 library: 346 library:
359 <literallayout class='monospaced'> 347 <literallayout class='monospaced'>
360 DEPENDS_append_libc-musl = " argp-standalone" 348 DEPENDS_append_libc-musl = " argp-standalone"
361 </literallayout> 349 </literallayout>
362 <note> 350 <note>
363 Avoiding "+=" and "=+" and using 351 Avoiding "+=" and "=+" and using
364 machine-specific 352 machine-specific
365 <filename>_append</filename> 353 <filename>_append</filename>
366 and <filename>_prepend</filename> operations 354 and <filename>_prepend</filename> operations
367 is recommended as well. 355 is recommended as well.
368 </note></para></listitem> 356 </note>
369 <listitem><para><emphasis>Place Machine-Specific Files 357 </para></listitem>
370 in Machine-Specific Locations:</emphasis> 358 <listitem><para>
371 When you have a base recipe, such as 359 <emphasis>Place Machine-Specific Files in
372 <filename>base-files.bb</filename>, that 360 Machine-Specific Locations:</emphasis>
373 contains a 361 When you have a base recipe, such as
374 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> 362 <filename>base-files.bb</filename>, that
375 statement to a file, you can use an append file 363 contains a
376 to cause the build to use your own version of 364 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
377 the file. 365 statement to a file, you can use an append file
378 For example, an append file in your layer at 366 to cause the build to use your own version of
379 <filename>meta-one/recipes-core/base-files/base-files.bbappend</filename> 367 the file.
380 could extend 368 For example, an append file in your layer at
381 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESPATH'><filename>FILESPATH</filename></ulink> 369 <filename>meta-one/recipes-core/base-files/base-files.bbappend</filename>
382 using 370 could extend
383 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink> 371 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESPATH'><filename>FILESPATH</filename></ulink>
384 as follows: 372 using
385 <literallayout class='monospaced'> 373 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
374 as follows:
375 <literallayout class='monospaced'>
386 FILESEXTRAPATHS_prepend := "${THISDIR}/${BPN}:" 376 FILESEXTRAPATHS_prepend := "${THISDIR}/${BPN}:"
387 </literallayout> 377 </literallayout>
388 The build for machine "one" will pick up your 378 The build for machine "one" will pick up your
389 machine-specific file as long as you have the 379 machine-specific file as long as you have the
390 file in 380 file in
391 <filename>meta-one/recipes-core/base-files/base-files/</filename>. 381 <filename>meta-one/recipes-core/base-files/base-files/</filename>.
392 However, if you are building for a different 382 However, if you are building for a different
393 machine and the 383 machine and the
394 <filename>bblayers.conf</filename> file includes 384 <filename>bblayers.conf</filename> file includes
395 the <filename>meta-one</filename> layer and 385 the <filename>meta-one</filename> layer and
396 the location of your machine-specific file is 386 the location of your machine-specific file is
397 the first location where that file is found 387 the first location where that file is found
398 according to <filename>FILESPATH</filename>, 388 according to <filename>FILESPATH</filename>,
399 builds for all machines will also use that 389 builds for all machines will also use that
400 machine-specific file.</para> 390 machine-specific file.</para>
401 <para>You can make sure that a machine-specific 391 <para>You can make sure that a machine-specific
402 file is used for a particular machine by putting 392 file is used for a particular machine by putting
403 the file in a subdirectory specific to the 393 the file in a subdirectory specific to the
404 machine. 394 machine.
405 For example, rather than placing the file in 395 For example, rather than placing the file in
406 <filename>meta-one/recipes-core/base-files/base-files/</filename> 396 <filename>meta-one/recipes-core/base-files/base-files/</filename>
407 as shown above, put it in 397 as shown above, put it in
408 <filename>meta-one/recipes-core/base-files/base-files/one/</filename>. 398 <filename>meta-one/recipes-core/base-files/base-files/one/</filename>.
409 Not only does this make sure the file is used 399 Not only does this make sure the file is used
410 only when building for machine "one", but the 400 only when building for machine "one", but the
411 build process locates the file more quickly.</para> 401 build process locates the file more quickly.</para>
412 <para>In summary, you need to place all files 402 <para>In summary, you need to place all files
413 referenced from <filename>SRC_URI</filename> 403 referenced from <filename>SRC_URI</filename>
414 in a machine-specific subdirectory within the 404 in a machine-specific subdirectory within the
415 layer in order to restrict those files to 405 layer in order to restrict those files to
416 machine-specific builds.</para></listitem> 406 machine-specific builds.
417 </itemizedlist> 407 </para></listitem>
418 </para> 408 </itemizedlist>
419 </section> 409 </para></listitem>
420 410 <listitem><para>
421 <section id='other-recommendations'> 411 <emphasis>Perform Steps to Apply for Yocto Project Compatibility:</emphasis>
422 <title>Other Recommendations</title> 412 If you want permission to use the
423 413 Yocto Project Compatibility logo with your layer
424 <para> 414 or application that uses your layer, perform the
425 We also recommend the following: 415 steps to apply for compatibility.
426 <itemizedlist> 416 See the
427 <listitem><para>If you want permission to use the 417 "<link linkend='making-sure-your-layer-is-compatible-with-yocto-project'>Making Sure Your Layer is Compatible With Yocto Project</link>"
428 Yocto Project Compatibility logo with your layer 418 section for more information.
429 or application that uses your layer, perform the 419 </para></listitem>
430 steps to apply for compatibility. 420 <listitem><para>
431 See the 421 <emphasis>Follow the Layer Naming Convention:</emphasis>
432 "<link linkend='making-sure-your-layer-is-compatible-with-yocto-project'>Making Sure Your Layer is Compatible With Yocto Project</link>" 422 Store custom layers in a Git repository that use the
433 section for more information. 423 <filename>meta-<replaceable>layer_name</replaceable></filename>
434 </para></listitem> 424 format.
435 <listitem><para>Store custom layers in a Git repository 425 </para></listitem>
436 that uses the 426 <listitem><para>
437 <filename>meta-<replaceable>layer_name</replaceable></filename> format. 427 <emphasis>Group Your Layers Locally:</emphasis>
438 </para></listitem> 428 Clone your repository alongside other cloned
439 <listitem><para>Clone the repository alongside other 429 <filename>meta</filename> directories from the
440 <filename>meta</filename> directories in the 430 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>.
441 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>. 431 </para></listitem>
442 </para></listitem> 432 </itemizedlist>
443 </itemizedlist> 433 </para>
444 Following these recommendations keeps your Source Directory and
445 its configuration entirely inside the Yocto Project's core
446 base.
447 </para>
448 </section>
449 </section> 434 </section>
450 435
451 <section id='making-sure-your-layer-is-compatible-with-yocto-project'> 436 <section id='making-sure-your-layer-is-compatible-with-yocto-project'>
@@ -7617,7 +7602,7 @@ Some notes from Cal:
7617 on how to add recipes to your layer, see the 7602 on how to add recipes to your layer, see the
7618 "<link linkend='creating-your-own-layer'>Creating Your Own Layer</link>" 7603 "<link linkend='creating-your-own-layer'>Creating Your Own Layer</link>"
7619 and 7604 and
7620 "<link linkend='best-practices-to-follow-when-creating-layers'>Best Practices to Follow When Creating Layers</link>" 7605 "<link linkend='best-practices-to-follow-when-creating-layers'>Following Best Practices When Creating Layers</link>"
7621 sections.</para></listitem> 7606 sections.</para></listitem>
7622 <listitem><para>Add any image recipes that are specific 7607 <listitem><para>Add any image recipes that are specific
7623 to your distribution.</para></listitem> 7608 to your distribution.</para></listitem>
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-05-09 00:28:51 +0000