sysmo-bts
/
generic-poky
9
0
Fork 0
Code Pull Requests Releases Activity

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 <scott.m.rifenbark@intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
This commit is contained in:
Scott Rifenbark 2013-09-12 15:34:48 -07:00 committed by Richard Purdie
parent b1b9f43ca4
commit dcefb7cccf
1 changed files with 188 additions and 58 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

246
documentation/dev-manual/dev-manual-common-tasks.xml
View File

@ -228,65 +228,192 @@
</note></para></listitem>
</orderedlist>
</para>
</section>
<section id='best-practices-to-follow-when-creating-layers'>
<title>Best Practices to Follow When Creating Layers</title>
<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>
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>
We also recommend the following:
<itemizedlist>
<listitem><para>Store custom layers in a Git repository
that uses the
<filename>meta-&lt;layer_name&gt;</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>
<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-&lt;layer_name&gt;</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'>
@ -2469,9 +2596,12 @@
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>