[yocto] [PATCH] yocto-docs: Various formatting/clarification adjustments to BSP Guide
Robert P. J. Day
rpjday at crashcourse.ca
Sat Mar 4 09:38:27 PST 2017
Collection of aesthetic/formatting/clarification fixes to BSP Guide,
including:
* Adjust some directory names to have trailing slash
* Reword some paragraphs for clarity
* Add <para>s inside <note>s for consistency
and other minor tweaks.
Signed-off-by: Robert P. J. Day <rpjday at crashcourse.ca>
---
diff --git a/documentation/bsp-guide/bsp.xml b/documentation/bsp-guide/bsp.xml
index 4d0ace0..d189ee0 100644
--- a/documentation/bsp-guide/bsp.xml
+++ b/documentation/bsp-guide/bsp.xml
@@ -956,28 +956,28 @@
<listitem><para>Instructions on how to boot the BSP build from
the BSP layer.</para></listitem>
<listitem><para>Instructions on how to boot the binary images
- contained in the <filename>binary</filename> directory,
+ contained in the <filename>binary/</filename> directory,
if present.</para></listitem>
<listitem><para>Information on any known bugs or issues that users
should know about when either building or booting the BSP
binaries.</para></listitem>
</itemizedlist></para></listitem>
<listitem><para><emphasis>README.sources File:</emphasis>
- You must include a <filename>README.sources</filename> in the
- <filename>meta-<replaceable>bsp_name</replaceable></filename> directory.
- This file specifies exactly where you can find the sources used to
- generate the binary images contained in the
- <filename>binary</filename> directory, if present.
+ If your BSP layer includes a <filename>binary/</filename> directory
+ with at least one binary image, then it must also include a top-level
+ <filename>README.sources</filename> file that explains exactly
+ where you can find the sources used to generate those binary images.
</para></listitem>
<listitem><para><emphasis>Layer Configuration File:</emphasis>
- You must include a <filename>conf/layer.conf</filename> in the
+ You must include a <filename>conf/layer.conf</filename> file in the
<filename>meta-<replaceable>bsp_name</replaceable></filename> directory.
This file identifies the <filename>meta-<replaceable>bsp_name</replaceable></filename>
BSP layer as a layer to the build system.</para></listitem>
<listitem><para><emphasis>Machine Configuration File:</emphasis>
You must include one or more
- <filename>conf/machine/<replaceable>bsp_name</replaceable>.conf</filename>
- files in the <filename>meta-<replaceable>bsp_name</replaceable></filename> directory.
+ <filename>conf/machine/<replaceable>machine</replaceable>.conf</filename>
+ machine definition files in the
+ <filename>meta-<replaceable>bsp_name</replaceable></filename> directory.
These configuration files define machine targets that can be built
using the BSP layer.
Multiple machine configuration files define variations of machine
@@ -989,12 +989,22 @@
hardware.
If you do have very different targets, you should create separate
BSP layers for each target.
- <note>It is completely possible for a developer to structure the
- working repository as a conglomeration of unrelated BSP
- files, and to possibly generate BSPs targeted for release
- from that directory using scripts or some other mechanism
- (e.g. <filename>meta-yocto-bsp</filename> layer).
- Such considerations are outside the scope of this document.</note>
+ <note>
+ <para>
+ It is completely possible for a developer to structure the
+ working repository as a conglomeration of unrelated BSP
+ files, and to possibly generate BSPs targeted for release
+ from that directory using scripts or some other mechanism
+ (e.g. <filename>meta-yocto-bsp</filename> layer).
+ Such considerations are outside the scope of this document.
+ </para>
+ <para>
+ In any event, the <filename>meta-yocto-bsp</filename> layer should be
+ considered a special case as it defines the family of Yocto Project
+ reference boards, which necessarily cover the set of supported
+ architectures.
+ </para>
+ </note>
</para></listitem>
</itemizedlist>
</para>
@@ -1025,16 +1035,20 @@
purposes, you should put the images and artifacts within a
<filename>binary/</filename> subdirectory located in the
<filename>meta-<replaceable>bsp_name</replaceable></filename> directory.
- <note>If you do include a bootable image as part of the BSP and the image
- was built by software covered by the GPL or other open source licenses,
- it is your responsibility to understand
- and meet all licensing requirements, which could include distribution
- of source files.</note></para></listitem>
+ <note>
+ <para>
+ If you do include a bootable image as part of the BSP and the image
+ was built by software covered by the GPL or other open source licenses,
+ it is your responsibility to understand and meet all licensing
+ requirements, which could include distribution of source files.
+ </para>
+ </note>
+ </para></listitem>
<listitem><para><emphasis>Use a Yocto Linux Kernel:</emphasis>
Kernel recipes in the BSP should be based on a Yocto Linux kernel.
Basing your recipes on these kernels reduces the costs for maintaining
the BSP and increases its scalability.
- See the <filename>Yocto Linux Kernel</filename> category in the
+ See the "Yocto Linux Kernel" category in the
<ulink url='&YOCTO_GIT_URL;/cgit.cgi'>Source Repositories</ulink>
for these kernels.</para></listitem>
</itemizedlist>
@@ -1056,7 +1070,7 @@
section in the Yocto Project Development Manual.
</para></listitem>
<listitem><para>
- Ensure your directory structure in the BSP layer
+ Ensure that the directory structure in the BSP layer
that supports your machine is such that it can be found
by the build system.
See the example later in this section for more information.
@@ -1083,40 +1097,40 @@
<para>
Following is a specific example to help you better understand the process.
- Consider an example that customizes a recipe by adding
+ Consider an example that customizes a single recipe by adding
a BSP-specific configuration file named <filename>interfaces</filename> to the
- <filename>init-ifupdown_1.0.bb</filename> recipe for machine "xyz" where the
- BSP layer also supports several other machines.
+ <filename>init-ifupdown_1.0.bb</filename> recipe exclusively for machine "xyz",
+ where the BSP layer supports several other machines.
+ </para>
+ <para>
Do the following:
<orderedlist>
- <listitem><para>Edit the <filename>init-ifupdown_1.0.bbappend</filename> file so that it
- contains the following:
+ <listitem><para>In the <filename>meta-xyz/recipes-core/init-ifupdown/</filename>
+ directory, create the <filename>init-ifupdown_1.0.bbappend</filename> file
+ so that it contains the following:
<literallayout class='monospaced'>
FILESEXTRAPATHS_prepend := "${THISDIR}/files:"
</literallayout>
- The append file needs to be in the
- <filename>meta-xyz/recipes-core/init-ifupdown</filename> directory.
</para></listitem>
<listitem><para>Create and place the new <filename>interfaces</filename>
- configuration file in the BSP's layer here:
- <literallayout class='monospaced'>
- meta-xyz/recipes-core/init-ifupdown/files/xyz-machine-one/interfaces
- </literallayout>
+ configuration file in the BSP layer at
+ <filename>meta-xyz/recipes-core/init-ifupdown/files/xyz-machine-one/interfaces</filename>.
<note>
+ <para>
If the <filename>meta-xyz</filename> layer did not support
- multiple machines, you would place the
+ multiple machines, or this customization applied to all of the
+ machines defined by this BSP layer, you could place the
<filename>interfaces</filename> configuration file in the
- layer here:
- <literallayout class='monospaced'>
- meta-xyz/recipes-core/init-ifupdown/files/interfaces
- </literallayout>
+ layer at
+ <filename>meta-xyz/recipes-core/init-ifupdown/files/interfaces</filename>.
+ </para>
</note>
The
<ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
variable in the append files extends the search path
the build system uses to find files during the build.
Consequently, for this example you need to have the
- <filename>files</filename> directory in the same location
+ <filename>files/</filename> directory in the same location
as your append file.</para></listitem>
</orderedlist>
</para>
@@ -1227,6 +1241,7 @@
</para>
<note>
+ <para>
Pre-compiled images are bundled with
a time-limited kernel that runs for a
predetermined amount of time (10 days) before it forces
@@ -1234,6 +1249,7 @@
This limitation is meant to discourage direct redistribution
of the image.
You must eventually rebuild the image if you want to remove this restriction.
+ </para>
</note>
</section>
@@ -1367,11 +1383,13 @@
necessary to create a BSP and perform basic kernel maintenance on that BSP using
the tools.
<note>
+ <para>
You can also use the <filename>yocto-layer</filename> tool to create
a "generic" layer.
For information on this tool, see the
"<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-general-layer-using-the-yocto-layer-script'>Creating a General Layer Using the yocto-layer Script</ulink>"
section in the Yocto Project Development Guide.
+ </para>
</note>
</para>
--
========================================================================
Robert P. J. Day Ottawa, Ontario, CANADA
http://crashcourse.ca
Twitter: http://twitter.com/rpjday
LinkedIn: http://ca.linkedin.com/in/rpjday
========================================================================
More information about the yocto
mailing list