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 @@
- Best Practices to Follow When Creating Layers + Following Best Practices When Creating Layers 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 - - - 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. - Rather, use an append file (.bbappend) - to override - only those parts of the original recipe you need to modify. - -
- -
- Avoid Duplicating Include Files - - - Avoid duplicating include files. - Use append files (.bbappend) - 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/package/file.inc - instead of require file.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 should try to address that - deficiency instead of overlaying the include file. - For example, you could address this by getting the - maintainer of the include file to add a variable or - variables to make it easy to override the parts needing - to be overridden. - -
- -
- 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 "foo" by altering the - DEPENDS - variable: - + information in the following list: + + + 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. + Rather, use an append file + (.bbappend) to override only those + parts of the original recipe you need to modify. + + + Avoid Duplicating Include Files: + Use append files (.bbappend) + 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/package/file.inc + instead of + require file.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 should try to address that + deficiency instead of overlaying the include file. + For example, you could address this by getting the + maintainer of the include file to add a variable or + variables to make it easy to override the parts needing + to be overridden. + + + 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: + + + Modify 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 "foo" by altering the + DEPENDS + variable: + 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: - + + 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 operations: - + + You should follow the same strategy when using + _append and + _prepend operations: + DEPENDS_append_one = " foo" DEPENDS_prepend_one = "foo " - - As an actual example, here's a line from the recipe - for gnutls, which adds dependencies on - "argp-standalone" when building with the musl C - library: - + + As an actual example, here's a line from the recipe + for gnutls, which adds dependencies on + "argp-standalone" when building with the musl C + library: + DEPENDS_append_libc-musl = " argp-standalone" - - - Avoiding "+=" and "=+" and using - machine-specific - _append - and _prepend operations - 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: - + + + Avoiding "+=" and "=+" and using + machine-specific + _append + and _prepend operations + 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: - - If you want permission to use the - Yocto Project Compatibility logo with your layer - or application that uses your layer, perform the - steps to apply for compatibility. - See the - "Making Sure Your Layer is Compatible With Yocto Project" - section for more information. - - 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. - -
+ + 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. + + + + + Perform Steps to Apply for Yocto Project Compatibility: + If you want permission to use the + Yocto Project Compatibility logo with your layer + or application that uses your layer, perform the + steps to apply for compatibility. + See the + "Making Sure Your Layer is Compatible With Yocto Project" + section for more information. + + + Follow the Layer Naming Convention: + Store custom layers in a Git repository that use the + meta-layer_name + format. + + + Group Your Layers Locally: + Clone your repository alongside other cloned + meta directories from the + Source Directory. + + +
@@ -7617,7 +7602,7 @@ Some notes from Cal: on how to add recipes to your layer, see the "Creating Your Own Layer" and - "Best Practices to Follow When Creating Layers" + "Following Best Practices When Creating Layers" sections. Add any image recipes that are specific to your distribution.