dev-manual: updates to how to use externalsrc.bbclass

I made sure all the usage information for this class is in this
section and not in the ref-manual.  Changes involved using
EXTERNALSRC and EXTERNALSRC_BUILD now to select the source
and build directories.

(From yocto-docs rev: f818d7013502d943517a99b84397e98f5f9dfd9a)

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

documentation/dev-manual/dev-manual-common-tasks.xml

@@ -3749,54 +3749,58 @@
         <title>Building Software from an External Source</title>
 
         <para>
-            By default, the OpenEmbedded build system does its work from within the
+            By default, the OpenEmbedded build system uses the
-            <link linkend='build-directory'>Build Directory</link>.
+            <link linkend='build-directory'>Build Directory</link> to
-            The build process involves fetching the source files, unpacking them, and then patching them
+            build source code.
-            if necessary before the build takes place.
+            The build process involves fetching the source files, unpacking
+            them, and then patching them if necessary before the build takes
+            place.
         </para>
 
         <para>
-            Situations exist where you might want to build software from source files that are external to
+            Situations exist where you might want to build software from source
-            and thus outside of the <link linkend='source-directory'>Source Directory</link>.
+            files that are external to and thus outside of the
-            For example, suppose you have a project that includes a new BSP with a heavily customized
+            OpenEmbedded build system.
-            kernel, a very minimal image, and some new user-space recipes.
+            For example, suppose you have a project that includes a new BSP with
+            a heavily customized kernel.
             And, you want to minimize exposing the build system to the
-            development team so that they can focus on their project and maintain everyone's workflow
+            development team so that they can focus on their project and
-            as much as possible.
+            maintain everyone's workflow as much as possible.
-            In this case, you want a kernel source directory on the development machine where the
+            In this case, you want a kernel source directory on the development
-            development occurs.
+            machine where the development occurs.
             You want the recipe's
             <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
-            variable to point to the external directory and use it as is, not copy it.
+            variable to point to the external directory and use it as is, not
+            copy it.
         </para>
 
         <para>
-            To build from software that comes from an external source, all you need to do is
+            To build from software that comes from an external source, all you
-            change your recipe so that it inherits the
+            need to do is change your recipe so that it inherits
             <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-externalsrc'><filename>externalsrc.bbclass</filename></ulink>
-            class and then sets the
+            and then sets the
-            <ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink>
+            <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTERNALSRC'><filename>EXTERNALSRC</filename></ulink>
             variable to point to your external source code.
-            Here are the statements to put in your recipe:
+            Here are the statements to put in your
+            <filename>local.conf</filename> file:
             <literallayout class='monospaced'>
-     inherit externalsrc
+     INHERIT += "externalsrc"
-     S = "/some/path/to/your/package/source"
+     EXTERNALSRC_pn-myrecipe = "/some/path/to/your/source/tree"
             </literallayout>
         </para>
 
         <para>
-            It is important to know that the <filename>externalsrc.bbclass</filename> assumes that the
+            By default, <filename>externalsrc.bbclass</filename> builds
-            source directory <filename>S</filename> and the Build Directory
+            the source code in a directory separate from the external source
-            <ulink url='&YOCTO_DOCS_REF_URL;#var-B'><filename>B</filename></ulink>
+            directory as specified by
-            are different even though these directories are the same by default.
+            <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTERNALSRC'><filename>EXTERNALSRC</filename></ulink>.
-            This assumption is important because it supports building different variants of the recipe
+            If you need to have the source built in the same directory in
-            by using the
+            which it resides, or some other nominated directory, you can set
-            <ulink url='&YOCTO_DOCS_REF_URL;#var-BBCLASSEXTEND'><filename>BBCLASSEXTEND</filename></ulink>
+            <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTERNALSRC_BUILD'><filename>EXTERNALSRC_BUILD</filename></ulink>
-            variable.
+            to point to that directory:
-            You could allow the Build Directory to be the same as the source directory but you would
+            <literallayout class='monospaced'>
-            not be able to build more than one variant of the recipe.
+     EXTERNALSRC_BUILD_pn-myrecipe = "/path/to/my/source/tree"
-            Consequently, if you are building multiple variants of the recipe, you need to establish a
+            </literallayout>
-            Build Directory that is different than the Source Directory.
         </para>
     </section>