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