</note></para></listitem>
</orderedlist>
</para>
+ </section>
- <para>
- To create layers that are easier to maintain, you should
- consider the following:
- <itemizedlist>
- <listitem><para>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 <filename>.bbappend</filename> files to override the
- parts of the recipe you need to modify.
- </para></listitem>
- <listitem><para>Avoid duplicating include files.
- Use <filename>.bbappend</filename> 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
- <filename>require recipes-core/somepackage/somefile.inc</filename>
- instead of <filename>require somefile.inc</filename>.
- 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
- <filename>meta-oe</filename> does.
- Consequently, <filename>meta-oe</filename> uses
- <filename>.bbappend</filename> files to modify the
- <filename>QT_SQL_DRIVER_FLAGS</filename> variable to
- enable the appropriate plugins.
- This variable was added to the
- <filename>qt4.inc</filename> include file in the Source
- Directory specifically to allow the
- <filename>meta-oe</filename> layer to be able to control
- which plugins are built.</para></listitem>
- </itemizedlist>
- </para>
+ <section id='best-practices-to-follow-when-creating-layers'>
+ <title>Best Practices to Follow When Creating Layers</title>
<para>
- We also recommend the following:
- <itemizedlist>
- <listitem><para>Store custom layers in a Git repository
- that uses the
- <filename>meta-<layer_name></filename> format.
- </para></listitem>
- <listitem><para>Clone the repository alongside other
- <filename>meta</filename> directories in the
- <link linkend='source-directory'>Source Directory</link>.
- </para></listitem>
- </itemizedlist>
- Following these recommendations keeps your Source Directory and
- its configuration entirely inside the Yocto Project's core
- base.
+ 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.
</para>
+
+ <section id='avoid-overlaying-entire-recipes'>
+ <title>Avoid "Overlaying" Entire Recipes</title>
+
+ <para>
+ 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 <filename>.bbappend</filename> files to override the
+ parts of the recipe you need to modify.
+ </para>
+ </section>
+
+ <section id='avoid-duplicating-include-files'>
+ <title>Avoid Duplicating Include Files</title>
+
+ <para>
+ Avoid duplicating include files.
+ Use <filename>.bbappend</filename> 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
+ <filename>require recipes-core/somepackage/somefile.inc</filename>
+ instead of <filename>require somefile.inc</filename>.
+ 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 <filename>meta-oe</filename>
+ does.
+ Consequently, <filename>meta-oe</filename> uses
+ <filename>.bbappend</filename> files to modify the
+ <filename>QT_SQL_DRIVER_FLAGS</filename> variable to
+ enable the appropriate plugins.
+ This variable was added to the <filename>qt4.inc</filename>
+ include file in the Source Directory specifically to allow
+ the <filename>meta-oe</filename> layer to be able to control
+ which plugins are built.
+ </para>
+ </section>
+
+ <section id='structure-your-layers'>
+ <title>Structure Your Layers</title>
+
+ <para>
+ 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:
+ <itemizedlist>
+ <listitem><para><emphasis>Modifying Variables to support
+ a different machine:</emphasis>
+ Suppose you have a layer named
+ <filename>meta-one</filename> that adds support
+ for building machine "one".
+ To do so, you use an append file named
+ <filename>base-files.bbappend</filename> and
+ create a dependency on a file named
+ <filename>foo</filename> that contains the
+ altered variables:
+ <literallayout class='monospaced'>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink> = "foo"
+ </literallayout>
+ The dependency is created during any build that
+ includes the layer
+ <filename>meta-one</filename>.
+ However, you might not want this dependency
+ for all machines.
+ For example, suppose you are building for
+ machine "two" but your
+ <filename>bblayers.conf</filename> file has the
+ <filename>meta-one</filename> layer included.
+ During the build, the
+ <filename>base-files</filename> for machine
+ "two" will also have the dependency on
+ <filename>foo</filename>.</para>
+ <para>To make sure your changes apply only when
+ building machine "one", use a machine override
+ with the <filename>DEPENDS</filename> statement:
+ <literallayout class='monospaced'>
+ DEPENDS_one = "foo"
+ </literallayout>
+ You should follow the same strategy when using
+ <filename>_append</filename> and
+ <filename>_prepend</filename> overrides:
+ <literallayout class='monospaced'>
+ DEPENDS_append_one = " foo"
+ DEPENDS_prepend_one = "foo "
+ </literallayout>
+ <note>
+ Avoiding "+=" and "=+" and using
+ machine-specific
+ <filename>_append</filename>
+ and <filename>_prepend</filename> overrides
+ is recommended as well.
+ </note></para></listitem>
+ <listitem><para><emphasis>Place Machine-Specific Files
+ in Machine-Specific Locations:</emphasis>
+ When you have a base recipe, such as
+ <filename>base-files.bb</filename>, that
+ contains a
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
+ 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
+ <filename>/meta-one/recipes-core/base-files/base-files.bbappend</filename>
+ could extend
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESPATH'><filename>FILESPATH</filename></ulink>
+ using
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
+ as follows:
+ <literallayout class='monospaced'>
+ FILESEXTRAPATHS_prepend := "${THISDIR}/${BPN}:"
+ </literallayout>
+ The build for machine "one" will pick up your
+ machine-specific file as long as you have the
+ file in
+ <filename>/meta-one/recipes-core/base-files/base-files/</filename>.
+ However, if you are building for a different
+ machine and the
+ <filename>bblayers.conf</filename> file includes
+ the <filename>meta-one</filename> layer and
+ the location of your machine-specific file is
+ the first location where that file is found
+ according to <filename>FILESPATH</filename>,
+ builds for all machines will also use that
+ machine-specific file.</para>
+ <para>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
+ <filename>/meta-one/recipes-core/base-files/base-files/</filename>
+ as shown above, put it in
+ <filename>/meta-one/recipes-core/base-files/base-files/one/</filename>.
+ 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.</para>
+ <para>In summary, you need to place all files
+ referenced from <filename>SRC_URI</filename>
+ in a machine-specific subdirectory within the
+ layer in order to restrict those files to
+ machine-specific builds.</para></listitem>
+ </itemizedlist>
+ </para>
+ </section>
+
+ <section id='other-recommendations'>
+ <title>Other Recommendations</title>
+
+ <para>
+ We also recommend the following:
+ <itemizedlist>
+ <listitem><para>Store custom layers in a Git repository
+ that uses the
+ <filename>meta-<layer_name></filename> format.
+ </para></listitem>
+ <listitem><para>Clone the repository alongside other
+ <filename>meta</filename> directories in the
+ <link linkend='source-directory'>Source Directory</link>.
+ </para></listitem>
+ </itemizedlist>
+ Following these recommendations keeps your Source Directory and
+ its configuration entirely inside the Yocto Project's core
+ base.
+ </para>
+ </section>
</section>
<section id='enabling-your-layer'>
If you have distro-specific configuration files
that are included by an existing recipe, you should
add a <filename>.bbappend</filename> for those.
- For general information on how to add recipes to
- your layer, see the "<link linkend='creating-your-own-layer'>Creating Your Own Layer</link>"
- section.</para></listitem>
+ For general information and recommendations
+ on how to add recipes to your layer, see the
+ "<link linkend='creating-your-own-layer'>Creating Your Own Layer</link>"
+ and
+ "<link linkend='best-practices-to-follow-when-creating-layers'>Best Practices to Follow When Creating Layers</link>"
+ sections.</para></listitem>
<listitem><para>Add any image recipes that are specific
to your distribution.</para></listitem>
<listitem><para>Add a <filename>psplash</filename>
projects / thirdparty / openembedded / openembedded-core-contrib.git / commitdiff
