bitbake: user-manual-metadata.xml: Edits to "Sharing Functionality"

Applied some review edits from Paul to the section.

(Bitbake rev: f4dc71a3ff2c7f2ca6093b751883a1244f8d3847)

Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

bitbake/doc/user-manual/user-manual-metadata.xml

@@ -488,15 +488,16 @@
         <title>Sharing Functionality</title>
 
         <para>
-            BitBake allows for metadata sharing through include files and
+            BitBake allows for metadata sharing through include files
-            class files (<filename>.bbclass</filename>).
+            (<filename>.inc</filename>) and class files
+            (<filename>.bbclass</filename>).
             For example, suppose you have a piece of common functionality
             such as a task definition that you want to share between
             more than one recipe.
             In this case, creating a <filename>.bbclass</filename>
-            file that contains the common functionality and uses the
+            file that contains the common functionality and then using
-            <filename>inherit</filename> directive would be a common
+            the <filename>inherit</filename> directive in your recipes to
-            way to share the task.
+            inherit the class would be a common way to share the task.
         </para>
 
         <para>
@@ -504,19 +505,24 @@
             allow you to share functionality between recipes.
             Specifically, the mechanisms include <filename>include</filename>,
             <filename>inherit</filename>, <filename>INHERIT</filename>, and
-            <filename>require</filename> statements.
+            <filename>require</filename> directives.
         </para>
 
         <section id='locating-include-and-class-files'>
             <title>Locating Include and Class Files</title>
 
             <para>
-                BitBake uses the <filename>BBPATH</filename> variable
+                BitBake uses the
-                to locate needed class and configuration files.
+                <link linkend='var-BBPATH'><filename>BBPATH</filename></link>
+                variable to locate needed include and class files.
                 The <filename>BBPATH</filename> variable is analogous to
                 the environment variable <filename>PATH</filename>.
-                Use of <filename>BBPATH</filename> is specific to the build
+            </para>
-                environment (e.g. Yocto Project, OpenEmbedded, and so forth).
+
+            <para>
+                In order for include and class files to be found by BitBake,
+                they need to be located in a "classes" subdirectory that can
+                be found in <filename>BBPATH</filename>.
             </para>
         </section>
 
@@ -527,27 +533,36 @@
                 When writing a recipe or class file, you can use the
                 <filename>inherit</filename> directive to inherit the
                 functionality of a class (<filename>.bbclass</filename>).
-                BitBake only supports this directive when used within these
+                BitBake only supports this directive when used within recipe
-                two types of files (i.e. <filename>.bb</filename> and
+                and class files (i.e. <filename>.bb</filename> and
-                <filename>.bbclass</filename> files).
+                <filename>.bbclass</filename>).
             </para>
 
             <para>
                 The <filename>inherit</filename> directive is a rudimentary
                 means of specifying what classes of functionality your
-                recipe requires.
+                recipes require.
                 For example, you can easily abstract out the tasks involved in
                 building a package that uses Autoconf and Automake and put
                 those tasks into a class file that can be used by your package.
-                As an example, an <filename>autotools.bbclass</filename> file
+            </para>
-                could use the following directive to inherit needed
+
-                site information:
+            <para>
+                As an example, your recipes could use the following directive
+                to inherit an <filename>autotools.bbclass</filename> file.
+                The class file would contain common functionality for using
+                Autotools that could be shared across recipes:
                 <literallayout class='monospaced'>
-     inherit siteinfo
+     inherit autotools
                 </literallayout>
                 In this case, BitBake would search for the directory
-                <filename>classes/siteinfo.bbclass</filename>
+                <filename>classes/autotools.bbclass</filename>
                 in <filename>BBPATH</filename>.
+                <note>
+                    You can override any values and functions of the
+                    inherited class within your recipe by doing so
+                    after the "inherit" statement.
+                </note>
             </para>
         </section>
 
@@ -566,9 +581,9 @@
 
             <para>
                 As an example, suppose you needed a recipe to include some
-                self-test files:
+                self-test definitions:
                 <literallayout class='monospaced'>
-     include test_recipe.inc
+     include test_defs.inc
                 </literallayout>
                 <note>
                     The <filename>include</filename> directive does not
@@ -598,17 +613,28 @@
             </para>
 
             <para>
-                Similar to how BitBake uses <filename>include</filename>,
+                Similar to how BitBake uses
+                <link linkend='include-directive'><filename>include</filename></link>,
                 if the path specified
                 on the require line is a relative path, BitBake locates
                 the first file it can find within <filename>BBPATH</filename>.
             </para>
 
             <para>
-                As an example, suppose you needed a recipe to require some
+                As an example, suppose you have two versions of a recipe
-                self-test files:
+                (e.g. <filename>foo_1.2.2.bb</filename> and
+                <filename>foo_2.0.0.bb</filename>) where
+                each version contains some identical functionality that could be
+                shared.
+                You could create an include file named <filename>foo.inc</filename>
+                that contains the common definitions needed to build "foo".
+                You need to be sure <filename>foo.inc</filename> is located in the
+                same directory as your two recipe files as well.
+                Once these conditions are set up, you can share the functionality
+                using a <filename>require</filename> directive from within each
+                recipe:
                 <literallayout class='monospaced'>
-     require test_recipe.inc
+     require foo.inc
                 </literallayout>
             </para>
         </section>
@@ -625,12 +651,25 @@
             </para>
 
             <para>
-                Suppose you needed to inherit a multilib global class.
+                As an example, suppose you needed to inherit a class
+                file called <filename>abc.bbclass</filename> from a
+                configuration file as follows:
                 <literallayout class='monospaced'>
-     INHERIT += "multilib_global"
+     INHERIT += "abc"
                 </literallayout>
-                This configuration directive causes the named class to be inherited
+                This configuration directive causes the named
-                at the point of the directive during parsing.
+                class to be inherited at the point of the directive
+                during parsing.
+                As with the <filename>inherit</filename> directive, the
+                <filename>.bbclass</filename> file must be located in a
+                "classes" subdirectory in one of the directories specified
+                in <filename>BBPATH</filename>.
+                <note>
+                    Because <filename>.conf</filename> files are parsed
+                    first during BitBake's execution, using
+                    <filename>INHERIT</filename> to inherit a class effectively
+                    inherits the class globally (i.e. for all recipes).
+                </note>
             </para>
         </section>
     </section>