From dcefb7cccf9f9ff1d383299804504fc76397a8ab Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Thu, 12 Sep 2013 15:34:48 -0700 Subject: [PATCH] dev-manual: Added new section on "Best Practices" Fixes [YOCTO #5037] The information to fix this bug was very similar to some "best practices" and "recommendations" information that was currently buried in a section that described how to create a layer. So, since the new information for this bug fix increased the amount of information significantly, I have pulled out the existing "recommendations" and "best practices" information and combined it with this new information and placed it in its own section dedicated to just that. The information still resides in the main section that introduces and discusses layers and their creation. This is a first draft of the section. It is under review. (From yocto-docs rev: 066de04511afb0641278f3fda4e97718b3ed5c47) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- .../dev-manual/dev-manual-common-tasks.xml | 246 +++++++++++++----- 1 file 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 @@ + + +
+ Best Practices to Follow When Creating Layers - To create layers that are easier to maintain, you should - consider the following: - - Avoid "overlaying" entire recipes from - other layers in your configuration. - In other words, do not copy an entire recipe into your - layer and then modify it. - Use .bbappend files to override the - parts of the recipe you need to modify. - - Avoid duplicating include files. - Use .bbappend files for each recipe - that uses an include file. - Or, if you are introducing a new recipe that requires - the included file, use the path relative to the original - layer directory to refer to the file. - For example, use - require recipes-core/somepackage/somefile.inc - instead of require somefile.inc. - If you're finding you have to overlay the include file, - it could indicate a deficiency in the include file in - the layer to which it originally belongs. - If this is the case, you need to address that deficiency - instead of overlaying the include file. - For example, consider how Qt 4 database support plug-ins - are configured. - The Source Directory does not have MySQL or PostgreSQL, - however OpenEmbedded's layer - meta-oe does. - Consequently, meta-oe uses - .bbappend files to modify the - QT_SQL_DRIVER_FLAGS variable to - enable the appropriate plugins. - This variable was added to the - qt4.inc include file in the Source - Directory specifically to allow the - meta-oe layer to be able to control - which plugins are built. - + To create layers that are easier to maintain and that will + not impact builds for other machines, you should consider the + information in the following sections. + +
+ Avoid "Overlaying" Entire Recipes - - We also recommend the following: - - Store custom layers in a Git repository - that uses the - meta-<layer_name> format. - - Clone the repository alongside other - meta directories in the - Source Directory. - - - Following these recommendations keeps your Source Directory and - its configuration entirely inside the Yocto Project's core - base. - + + Avoid "overlaying" entire recipes from other layers in your + configuration. + In other words, do not copy an entire recipe into your + layer and then modify it. + Use .bbappend files to override the + parts of the recipe you need to modify. + +
+ +
+ Avoid Duplicating Include Files + + + Avoid duplicating include files. + Use .bbappend files for each recipe + that uses an include file. + Or, if you are introducing a new recipe that requires + the included file, use the path relative to the original + layer directory to refer to the file. + For example, use + require recipes-core/somepackage/somefile.inc + instead of require somefile.inc. + If you're finding you have to overlay the include file, + it could indicate a deficiency in the include file in + the layer to which it originally belongs. + If this is the case, you need to address that deficiency + instead of overlaying the include file. + For example, consider how support plugins for the Qt 4 + database are configured. + The Source Directory does not have MySQL or PostgreSQL. + However, OpenEmbedded's layer meta-oe + does. + Consequently, meta-oe uses + .bbappend files to modify the + QT_SQL_DRIVER_FLAGS variable to + enable the appropriate plugins. + This variable was added to the qt4.inc + include file in the Source Directory specifically to allow + the meta-oe layer to be able to control + which plugins are built. + +
+ +
+ Structure Your Layers + + + Proper use of overrides within append files and placement + of machine-specific files within your layer can ensure that + a build is not using the wrong Metadata and negatively + impacting a build for a different machine. + Following are some examples: + + Modifying Variables to support + a different machine: + Suppose you have a layer named + meta-one that adds support + for building machine "one". + To do so, you use an append file named + base-files.bbappend and + create a dependency on a file named + foo that contains the + altered variables: + + DEPENDS = "foo" + + The dependency is created during any build that + includes the layer + meta-one. + However, you might not want this dependency + for all machines. + For example, suppose you are building for + machine "two" but your + bblayers.conf file has the + meta-one layer included. + During the build, the + base-files for machine + "two" will also have the dependency on + foo. + To make sure your changes apply only when + building machine "one", use a machine override + with the DEPENDS statement: + + DEPENDS_one = "foo" + + You should follow the same strategy when using + _append and + _prepend overrides: + + DEPENDS_append_one = " foo" + DEPENDS_prepend_one = "foo " + + + Avoiding "+=" and "=+" and using + machine-specific + _append + and _prepend overrides + is recommended as well. + + Place Machine-Specific Files + in Machine-Specific Locations: + When you have a base recipe, such as + base-files.bb, that + contains a + SRC_URI + statement to a file, you can use an append file + to cause the build to use your own version of + the file. + For example, an append file in your layer at + /meta-one/recipes-core/base-files/base-files.bbappend + could extend + FILESPATH + using + FILESEXTRAPATHS + as follows: + + FILESEXTRAPATHS_prepend := "${THISDIR}/${BPN}:" + + The build for machine "one" will pick up your + machine-specific file as long as you have the + file in + /meta-one/recipes-core/base-files/base-files/. + However, if you are building for a different + machine and the + bblayers.conf file includes + the meta-one layer and + the location of your machine-specific file is + the first location where that file is found + according to FILESPATH, + builds for all machines will also use that + machine-specific file. + You can make sure that a machine-specific + file is used for a particular machine by putting + the file in a subdirectory specific to the + machine. + For example, rather than placing the file in + /meta-one/recipes-core/base-files/base-files/ + as shown above, put it in + /meta-one/recipes-core/base-files/base-files/one/. + Not only does this make sure the file is used + only when building for machine "one" but the + build process locates the file more quickly. + In summary, you need to place all files + referenced from SRC_URI + in a machine-specific subdirectory within the + layer in order to restrict those files to + machine-specific builds. + + +
+ +
+ Other Recommendations + + + We also recommend the following: + + Store custom layers in a Git repository + that uses the + meta-<layer_name> format. + + Clone the repository alongside other + meta directories in the + Source Directory. + + + Following these recommendations keeps your Source Directory and + its configuration entirely inside the Yocto Project's core + base. + +
@@ -2469,9 +2596,12 @@ If you have distro-specific configuration files that are included by an existing recipe, you should add a .bbappend for those. - For general information on how to add recipes to - your layer, see the "Creating Your Own Layer" - section. + For general information and recommendations + on how to add recipes to your layer, see the + "Creating Your Own Layer" + and + "Best Practices to Follow When Creating Layers" + sections. Add any image recipes that are specific to your distribution. Add a psplash