From 7d7eb04b9c0cf5d8460f67f2d1c44f2c242bd755 Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Mon, 7 Aug 2017 15:30:38 -0700 Subject: dev-manual: Updates to "Using .bbappend Files in Your Layer" I did some rewriting for clarity in the "Using .bbappend Files in Your Layer" section. The section needed to be retitled so focus on the layer aspect of .bbappend files. Also, while I was in there, I did more work on the prose in general. Also had to fix some links in the bsp, kernel, and ref manuals that linked into the section whose name I changes. (From yocto-docs rev: a82bcc9fe0f909135434ee1bd36b4414f6c046c9) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- documentation/bsp-guide/bsp.xml | 2 +- .../dev-manual/dev-manual-common-tasks.xml | 71 +++++++++++----------- documentation/kernel-dev/kernel-dev-faq.xml | 2 +- documentation/ref-manual/introduction.xml | 2 +- 4 files changed, 39 insertions(+), 38 deletions(-) diff --git a/documentation/bsp-guide/bsp.xml b/documentation/bsp-guide/bsp.xml index dacd077f2d..71ae2c36cd 100644 --- a/documentation/bsp-guide/bsp.xml +++ b/documentation/bsp-guide/bsp.xml @@ -1150,7 +1150,7 @@ Create a .bbappend file for the modified recipe. For information on using append files, see the - "Using .bbappend Files" + "Using .bbappend Files in Your Layer" section in the Yocto Project Development Manual. diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml index 3fc76b2ee1..7464172fc6 100644 --- a/documentation/dev-manual/dev-manual-common-tasks.xml +++ b/documentation/dev-manual/dev-manual-common-tasks.xml @@ -686,37 +686,46 @@
- Using .bbappend Files + Using .bbappend Files in Your Layer - Recipes used to append Metadata to other recipes are called - BitBake append files. - BitBake append files use the .bbappend file - type suffix, while the corresponding recipes to which Metadata - is being appended use the .bb file type - suffix. + A recipe that appends Metadata to another recipe is called a + BitBake append file. + A BitBake append file uses the .bbappend + file type suffix, while the corresponding recipe to which + Metadata is being appended uses the .bb + file type suffix. - A .bbappend file allows your layer to make - additions or changes to the content of another layer's recipe - without having to copy the other recipe into your layer. + You can use a .bbappend file in your + layer to make additions or changes to the content of another + layer's recipe without having to copy the other layer's + recipe into your layer. Your .bbappend file resides in your layer, while the main .bb recipe file to which you are appending Metadata resides in a different layer. - Append files must have the same root names as their corresponding - recipes. + Being able to append information to an existing recipe not only + avoids duplication, but also automatically applies recipe + changes from a different layer into your layer. + If you were copying recipes, you would have to manually merge + changes as they occur. + + + + When you create an append file, you must use the same root + name as the corresponding recipe file. For example, the append file someapp_&DISTRO;.bbappend must apply to someapp_&DISTRO;.bb. - This means the original recipe and append file names are version - number-specific. + This means the original recipe and append file names are + version number-specific. If the corresponding recipe is renamed to update to a newer - version, the corresponding .bbappend file must - be renamed (and possibly updated) as well. + version, you must also rename and possibly update + the corresponding .bbappend as well. During the build process, BitBake displays an error on starting if it detects a .bbappend file that does not have a corresponding recipe with a matching name. @@ -725,14 +734,6 @@ variable for information on how to handle this error. - - Being able to append information to an existing recipe not only - avoids duplication, but also automatically applies recipe - changes in a different layer to your layer. - If you were copying recipes, you would have to manually merge - changes as they occur. - - As an example, consider the main formfactor recipe and a corresponding formfactor append file both from the @@ -745,8 +746,7 @@ SUMMARY = "Device formfactor information" SECTION = "base" LICENSE = "MIT" - LIC_FILES_CHKSUM = "file://${COREBASE}/LICENSE;md5=4d92cd373abda3937c2bc47fbc49d690 \ - file://${COREBASE}/meta/COPYING.MIT;md5=3da9cfbcb788c80a0384361b4de20420" + LIC_FILES_CHKSUM = "file://${COREBASE}/meta/COPYING.MIT;md5=3da9cfbcb788c80a0384361b4de20420" PR = "r45" SRC_URI = "file://config file://machconfig" @@ -762,8 +762,7 @@ if [ -s "${S}/machconfig" ]; then install -m 0644 ${S}/machconfig ${D}${sysconfdir}/formfactor/ fi - } - + } In the main recipe, note the SRC_URI variable, which tells the OpenEmbedded build system where to @@ -775,7 +774,8 @@ formfactor_0.0.bbappend and is from the Raspberry Pi BSP Layer named meta-raspberrypi. - The file is in recipes-bsp/formfactor: + The file is in the layer at + recipes-bsp/formfactor: FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" @@ -795,12 +795,13 @@ - The statement in this example extends the directories to include + The statement in this example extends the directories to + include ${THISDIR}/${PN}, which resolves to a directory named formfactor in the same directory in which the append file resides (i.e. - meta-raspberrypi/recipes-bsp/formfactor/formfactor. + meta-raspberrypi/recipes-bsp/formfactor. This implies that you must have the supporting directory structure set up that will contain any files or patches you will be including from the layer. @@ -808,8 +809,8 @@ Using the immediate expansion assignment operator - := is important because of the reference to - THISDIR. + := is important because of the reference + to THISDIR. The trailing colon character is important as it ensures that items in the list remain colon-separated. @@ -7144,7 +7145,7 @@ Some notes from Cal: and SRC_URI statements enable the OpenEmbedded build system to find the patch file. For more information on using append files, see the - "Using .bbappend Files" + "Using .bbappend Files in Your Layer" section. Put the patch file in your layer: @@ -7623,7 +7624,7 @@ Some notes from Cal: Add a psplash append file for a branded splash screen. For information on append files, see the - "Using .bbappend Files" + "Using .bbappend Files in Your Layer" section. Add any other append files to make custom changes that are specific to individual diff --git a/documentation/kernel-dev/kernel-dev-faq.xml b/documentation/kernel-dev/kernel-dev-faq.xml index 2b99ad2dde..9e0517d4af 100644 --- a/documentation/kernel-dev/kernel-dev-faq.xml +++ b/documentation/kernel-dev/kernel-dev-faq.xml @@ -72,7 +72,7 @@ RDEPENDS_kernel-base to include or not include "kernel-image". See the - "Using .bbappend Files" + "Using .bbappend Files in Your Layer" section in the Yocto Project Development Manual for information on how to use an append file to override metadata. diff --git a/documentation/ref-manual/introduction.xml b/documentation/ref-manual/introduction.xml index 4fd1e95a61..163ea925f1 100644 --- a/documentation/ref-manual/introduction.xml +++ b/documentation/ref-manual/introduction.xml @@ -689,7 +689,7 @@ Information in append files extends or overrides the information in the similarly-named recipe file. For an example of an append file in use, see the - "Using .bbappend Files" + "Using .bbappend Files in Your Layer" section in the Yocto Project Development Manual. Append files can also use wildcard patterns in their -- cgit v1.2.3-54-g00ecf