diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index 4372769c1c..e9555e6168 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -295,7 +295,7 @@
- Append files must have the same name as the corresponding recipe.
+ Append files must have the same root name as the corresponding recipe.
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.
@@ -304,6 +304,9 @@
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.
+ See the
+ BB_DANGLINGAPPENDS_WARNONLY
+ variable for information on how to handle this error.
@@ -317,7 +320,7 @@
append file both from the
Source Directory.
Here is the main formfactor recipe, which is named formfactor_0.0.bb and
- located in the meta layer at meta/recipes-bsp/formfactor:
+ located in the "meta" layer at meta/recipes-bsp/formfactor:
DESCRIPTION = "Device formfactor information"
SECTION = "base"
@@ -364,10 +367,16 @@
of the reference to THISDIR.
The trailing colon character is important as it ensures that items in the list remain
colon-separated.
- BitBake automatically defines the THISDIR variable.
+ BitBake automatically defines the
+ THISDIR variable.
You should never set this variable yourself.
- Using _prepend ensures your path will be searched prior to other
- paths in the final list.
+ Using _prepend ensures your path will
+ be searched prior to other paths in the final list.
+ Also, not all append files add extra files.
+ Many append files simply exist to add build options
+ (e.g. systemd).
+ For these cases, it is not necessary to use the
+ "_prepend" part of the statement.