dev-manual: Moved "Finding Temporary Source Code"

Fixes [YOCTO #11630]

This section can stand as a separate task.  I have moved it to the
Common Tasks chapter.

(From yocto-docs rev: e4fb1ce8b160528aae0f192add614a595b2560a3)

Signed-off-by: Scott Rifenbark <srifenbark@gmail.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

1 files changed, 103 insertions, 2 deletions

diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index 0879d0d3e0..2510d6e2d4 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -3967,6 +3967,107 @@
         </section>
     </section>
 
+    <section id='finding-the-temporary-source-code'>
+        <title>Finding Temporary Source Code</title>
+
+        <para>
+            You might find it helpful during development to modify the
+            temporary source code used by recipes to build packages.
+            For example, suppose you are developing a patch and you need to
+            experiment a bit to figure out your solution.
+            After you have initially built the package, you can iteratively
+            tweak the source code, which is located in the
+            <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>,
+            and then you can force a re-compile and quickly test your altered
+            code.
+            Once you settle on a solution, you can then preserve your changes
+            in the form of patches.
+        </para>
+
+        <para>
+            During a build, the unpacked temporary source code used by recipes
+            to build packages is available in the Build Directory as
+            defined by the
+            <ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink>
+            variable.
+            Below is the default value for the <filename>S</filename> variable
+            as defined in the
+            <filename>meta/conf/bitbake.conf</filename> configuration file
+            in the
+            <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>:
+            <literallayout class='monospaced'>
+     S = "${WORKDIR}/${BP}"
+            </literallayout>
+            You should be aware that many recipes override the
+            <filename>S</filename> variable.
+            For example, recipes that fetch their source from Git usually set
+            <filename>S</filename> to <filename>${WORKDIR}/git</filename>.
+            <note>
+                The
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-BP'><filename>BP</filename></ulink>
+                represents the base recipe name, which consists of the name
+                and version:
+                <literallayout class='monospaced'>
+     BP = "${BPN}-${PV}"
+                </literallayout>
+            </note>
+        </para>
+
+        <para>
+            The path to the work directory for the recipe
+            (<ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink>)
+            is defined as follows:
+            <literallayout class='monospaced'>
+     ${TMPDIR}/work/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR}
+            </literallayout>
+            The actual directory depends on several things:
+            <itemizedlist>
+                <listitem><para>
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>:
+                    The top-level build output directory.
+                    </para></listitem>
+                <listitem><para>
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-MULTIMACH_TARGET_SYS'><filename>MULTIMACH_TARGET_SYS</filename></ulink>:
+                    The target system identifier.
+                    </para></listitem>
+                <listitem><para>
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink>:
+                    The recipe name.
+                    </para></listitem>
+                <listitem><para>
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTENDPE'><filename>EXTENDPE</filename></ulink>:
+                    The epoch - (if
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-PE'><filename>PE</filename></ulink>
+                    is not specified, which is usually the case for most
+                    recipes, then <filename>EXTENDPE</filename> is blank).
+                    </para></listitem>
+                <listitem><para>
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>:
+                    The recipe version.
+                    </para></listitem>
+                <listitem><para>
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>:
+                    The recipe revision.
+                    </para></listitem>
+            </itemizedlist>
+        </para>
+
+        <para>
+            As an example, assume a Source Directory top-level folder
+            named <filename>poky</filename>, a default Build Directory at
+            <filename>poky/build</filename>, and a
+            <filename>qemux86-poky-linux</filename> machine target
+            system.
+            Furthermore, suppose your recipe is named
+            <filename>foo_1.3.0.bb</filename>.
+            In this case, the work directory the build system uses to
+            build the package would be as follows:
+            <literallayout class='monospaced'>
+     poky/build/tmp/work/qemux86-poky-linux/foo/1.3.0-r0
+            </literallayout>
+        </para>
+    </section>
+
     <section id='platdev-building-targets-with-multiple-configurations'>
         <title>Building Targets with Multiple Configurations</title>
 
@@ -6532,8 +6633,8 @@
             <title>Finding the Kernel Source Code</title>
 
             <para>
-                Each time you build a kernel image, the kernel source code is fetched
-                and unpacked into the following directory:
+                Each time you build a kernel image, the kernel source code
+                is fetched and unpacked into the following directory:
                 <literallayout class='monospaced'>
      ${S}/linux
                 </literallayout>