documentation/dev-manual: Moved temp source code mod into dev model

The section "Modifying Temporary Source Code" that was in the chapter
for "Common Tasks" was moved to the "Common Development Models" chapter.
After discussion with Darren Hart, modifying temporary source code
is a valid develop model.  So, rather than isolate it in the common
tasks chapter it has been placed in the development model chapter,
which now has four types of development.

Changes were made to update the introductory text of all the concerned
areas of the manual.

(From yocto-docs rev: 8b07ee3bcda9c13e576b54b0079b0656cd8fcc32)

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

1 files changed, 347 insertions, 27 deletions

diff --git a/documentation/dev-manual/dev-manual-model.xml b/documentation/dev-manual/dev-manual-model.xml
index bbedf6b5bd..69e09e6466 100644
--- a/documentation/dev-manual/dev-manual-model.xml
+++ b/documentation/dev-manual/dev-manual-model.xml
@@ -8,32 +8,35 @@
 
 <para>
     Many development models exist for which you can use the Yocto Project. 
-    However, for the purposes of this manual we are going to focus on two common models:  
-    System Development and User Application Development.
-    System Development covers Board Support Package (BSP) development and kernel modification
-    or configuration.  
-    User Application Development covers development of applications that you intend to run on some 
-    target hardware.  
-</para>
-
-<para>
-    This chapter presents overviews of both system and application models.
-    If you want to examine specific examples of the system development models, 
-    see the "<link linkend='dev-manual-bsp-appendix'>BSP Development Example</link>" 
-    appendix and the 
-    "<link linkend='dev-manual-kernel-appendix'>Kernel Modification Example</link>" appendix.
-    For a user-space application development example that uses the 
-    <trademark class='trade'>Eclipse</trademark> IDE,
-    see the 
-    <ulink url='&YOCTO_DOCS_ADT_URL;'>
-    The Yocto Project Application Development Toolkit (ADT) User's Guide</ulink>.
-</para>
-
-<para>
-    Aside from these two models, this chapter will also briefly introduce and discuss
-    development using 
-    <ulink url='&YOCTO_HOME_URL;/projects/hob'>Hob</ulink>, which is a graphical interface 
-    to the Yocto Project build system.
+    This chapter overviews the following methods:
+    <itemizedlist>
+        <listitem><para><emphasis>System Development:</emphasis>
+             System Development covers Board Support Package (BSP) development and kernel 
+             modification or configuration.
+             If you want to examine specific examples of the system development models, 
+             see the "<link linkend='dev-manual-bsp-appendix'>BSP Development Example</link>" 
+             appendix and the 
+             "<link linkend='dev-manual-kernel-appendix'>Kernel Modification Example</link>" appendix.
+             </para></listitem>
+         <listitem><para><emphasis>User Application Development:</emphasis>
+             User Application Development covers development of applications that you intend 
+             to run on some target hardware.
+             For a user-space application development example that uses the 
+             <trademark class='trade'>Eclipse</trademark> IDE,
+             see the 
+             <ulink url='&YOCTO_DOCS_ADT_URL;'>
+             The Yocto Project Application Development Toolkit (ADT) User's Guide</ulink>.
+             </para></listitem>
+         <listitem><para><emphasis>Temporary Source Code Modification:</emphasis>
+             Direct modification of temporary source code is a convenient development model
+             to quickly iterate and develop towards a solution.
+             Once the solution has been implemented, you should of course take steps to 
+             get the changes upstream and applied in the affected recipes.</para></listitem>
+         <listitem><para><emphasis>Image Development using Hob:</emphasis>
+             You can use the <ulink url='&YOCTO_HOME_URL;/projects/hob'>Hob</ulink> to build 
+             custom operating system images within the Yocto Project build environment.
+             Hob provides an efficient interface to the Yocto Project build system.</para></listitem>
+     </itemizedlist>
 </para>
 
 <section id='system-development-model'>
@@ -58,7 +61,7 @@
         <title>Developing a Board Support Package (BSP)</title>
 
         <para>
-            A BSP is a package of recipes that, when applied, during a build results in 
+            A BSP is a packageof recipes that, when applied, during a build results in 
             an image that you can run on a particular board.  
             Thus, the package, when compiled into the new image, supports the operation of the board.  
         </para>
@@ -700,6 +703,323 @@ WRITER NOTE:  The areas to get the kernel and root filesystem are located in the
     </section>
 </section>
 
+<section id="modifying-temporary-source-code">
+    <title>Modifying Temporary Source Code</title>
+
+    <para>
+        Although the Yocto Project is typically used to build software, 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 
+        <link linkend='yocto-project-build-directory'>Yocto Project's Build Directory</link>, 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.
+        You can accomplish these steps all within either a 
+        <ulink url='http://savannah.nongnu.org/projects/quilt'>Quilt</ulink> or 
+        <link linkend='git'>Git</link> workflow.
+    </para>
+
+    <section id='finding-the-temporary-source-code'>
+        <title>Finding the Temporary Source Code</title>
+
+        <para>
+            During a build, the unpacked temporary source code used by recipes 
+            to build packages is available in the Yocto Project Build Directory as 
+            defined by the 
+            <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-S'>S</ulink></filename> 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 
+            <link linkend='yocto-project-files'>Yocto Project Files</link>:
+            <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>
+                <filename>BP</filename> represents the "Base Package", which is the base package
+                name and the package 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>) depends
+            on the package name and the architecture of the target device.
+            For example, here is the work directory for packages whose targets are not device-dependent:
+            <literallayout class='monospaced'>
+     ${TMPDIR}/work/${PACKAGE_ARCH}-poky-${TARGET_OS}/${PN}-${PV}-${PR}
+            </literallayout>
+            Let's look at an example without variables.
+            Assuming a Yocto Project Files top-level directory named <filename>poky</filename>
+            and a default Yocto Project Build Directory of <filename>poky/build</filename>, 
+            the following is the work directory for the <filename>acl</filename> package:
+            <literallayout class='monospaced'>
+     ~/poky/build/tmp/work/i586-poky-linux/acl-2.2.51-r3
+            </literallayout>
+        </para>
+
+        <para>
+            If your package is dependent on the target device, the work directory varies slightly:
+            <literallayout class='monospaced'>
+     ${TMPDIR}/work/${MACHINE}-poky-${TARGET_OS}/${PN}-${PV}-${PR}
+            </literallayout>
+            Again, assuming a Yocto Project Files top-level directory named <filename>poky</filename>
+            and a default Yocto Project Build Directory of <filename>poky/build</filename>, the 
+            following is the work directory for the <filename>acl</filename> package that is being 
+            built for a MIPS-based device:
+            <literallayout class='monospaced'>
+     ~/poky/build/tmp/work/mips-poky-linux/acl-2.2.51-r2
+            </literallayout>
+        </para>
+
+        <note>
+            To better understand how the Yocto Project build system resolves directories during the 
+            build process, see the glossary entries for the
+            <ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink>,
+            <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>,
+            <ulink url='&YOCTO_DOCS_REF_URL;#var-TOPDIR'><filename>TOPDIR</filename></ulink>,
+            <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></ulink>,
+            <ulink url='&YOCTO_DOCS_REF_URL;#var-TARGET_OS'><filename>TARGET_OS</filename></ulink>,
+            <ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink>,
+            <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>,
+            and
+            <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>
+            variables in the Yocto Project Reference Manual.
+        </note>
+
+        <para>
+            Now that you know where to locate the directory that has the temporary source code, you can use a 
+            Quilt or Git workflow to make your edits, test the changes, and preserve the 
+            changes in the form of patches.
+        </para>
+    </section>
+
+    <section id="using-a-quilt-workflow">
+        <title>Using a Quilt Workflow</title>
+            
+        <para>
+            <ulink url='http://savannah.nongnu.org/projects/quilt'>Quilt</ulink>
+            is a powerful tool that allows you to capture source code changes without having 
+            a clean source tree.
+            This section outlines the typical workflow you can use to modify temporary source code, 
+            test changes, and then preserve the changes in the form of a patch all using Quilt.
+        </para>
+
+        <para>
+            Follow these general steps:
+            <orderedlist>
+                <listitem><para><emphasis>Find the Source Code:</emphasis>
+                    The temporary source code used by the Yocto Project build system is kept in the 
+                    Yocto Project Build Directory.  
+                    See the 
+                    "<link linkend='finding-the-temporary-source-code'>Finding the Temporary Source Code</link>"
+                    section to learn how to locate the directory that has the temporary source code for a 
+                    particular package.</para></listitem>
+                <listitem><para><emphasis>Change Your Working Directory:</emphasis>
+                    You need to be in the directory that has the temporary source code.
+                    That directory is defined by the 
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-S'>S</ulink>
+                    variable.</para></listitem>
+                <listitem><para><emphasis>Create a New Patch:</emphasis>
+                    Before modifying source code, you need to create a new patch.
+                    To create a new patch file, use <filename>quilt new</filename> as below:
+                    <literallayout class='monospaced'>
+     $ quilt new my_changes.patch
+                    </literallayout></para></listitem>
+                <listitem><para><emphasis>Notify Quilt and Add Files:</emphasis>
+                    After creating the patch, you need to notify Quilt about the files you will 
+                    be changing.
+                    Add the files you will be modifying into the patch you just created:
+                    <literallayout class='monospaced'>
+     $ quilt add file1.c file2.c file3.c
+                    </literallayout></para></listitem>
+                <listitem><para><emphasis>Edit the Files:</emphasis>
+                    Make the changes to the temporary source code.</para></listitem>
+                <listitem><para><emphasis>Test Your Changes:</emphasis>
+                    Once you have modified the source code, the easiest way to test your changes 
+                    is by calling the <filename>compile</filename> task as shown in the following example:
+                    <literallayout class='monospaced'>
+     $ bitbake -c compile -f &lt;name_of_package&gt;
+                    </literallayout>
+                    The <filename>-f</filename> or <filename>--force</filename>
+                    option forces re-execution of the specified task.
+                    If you find problems with your code, you can just keep editing and 
+                    re-testing iteratively until things work as expected.
+                    <note>All the modifications you make to the temporary source code
+                    disappear once you <filename>-c clean</filename> or 
+                    <filename>-c cleanall</filename> with BitBake for the package.
+                    Modifications will also disappear if you use the <filename>rm_work</filename>
+                    feature as described in the
+                    "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>" 
+                    section of the Yocto Project Quick Start.
+                    </note></para></listitem>
+                <listitem><para><emphasis>Generate the Patch:</emphasis>
+                    Once your changes work as expected, you need to use Quilt to generate the final patch that 
+                    contains all your modifications.
+                    <literallayout class='monospaced'>
+     $ quilt refresh
+                    </literallayout>
+                    At this point the <filename>my_changes.patch</filename> file has all your edits made 
+                    to the <filename>file1.c</filename>, <filename>file2.c</filename>, and 
+                    <filename>file3.c</filename> files.</para>
+                    <para>You can find the resulting patch file in the <filename>patches/</filename> 
+                    subdirectory of the source (<filename>S</filename>) directory.</para></listitem>
+                <listitem><para><emphasis>Copy the Patch File:</emphasis> 
+                    For simplicity, copy the patch file into a directory named <filename>files</filename>,
+                    which you can create in the same directory as the recipe.
+                    Placing the patch here guarantees that the Yocto Project build system will find
+                    the patch.
+                    Next, add the patch into the  
+                    <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename> 
+                    of the recipe.  
+                    Here is an example:
+                    <literallayout class='monospaced'>
+     SRC_URI += "file://my_changes.patch"
+                    </literallayout></para></listitem>
+                <listitem><para><emphasis>Increment the Package Revision Number:</emphasis>
+                    Finally, don't forget to 'bump' the 
+                    <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PR'>PR</ulink></filename>
+                    value in the same recipe since the resulting packages have changed.</para></listitem>
+            </orderedlist>
+        </para>     </section>
+
+    <section id='using-a-git-workflow'>
+        <title>Using a Git Workflow</title>
+        <para>
+            Git is an even more powerful tool that allows you to capture source code changes without having 
+            a clean source tree.
+            This section outlines the typical workflow you can use to modify temporary source code, 
+            test changes, and then preserve the changes in the form of a patch all using Git.
+            For general information on Git as it is used in the Yocto Project, see the 
+            "<link linkend='git'>Git</link>" section.
+        </para>
+
+        <note>
+            This workflow uses Git only for its ability to manage local changes to the source code 
+            and produce patches independent of any version control used on the Yocto Project 
+            Files.
+        </note>
+
+        <para>
+            Follow these general steps:
+            <orderedlist>
+                <listitem><para><emphasis>Find the Source Code:</emphasis>
+                    The temporary source code used by the Yocto Project build system is kept in the 
+                    Yocto Project Build Directory.  
+                    See the 
+                    "<link linkend='finding-the-temporary-source-code'>Finding the Temporary Source Code</link>"
+                    section to learn how to locate the directory that has the temporary source code for a 
+                    particular package.</para></listitem>
+                <listitem><para><emphasis>Change Your Working Directory:</emphasis>
+                    You need to be in the directory that has the temporary source code.
+                    That directory is defined by the 
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-S'>S</ulink>
+                    variable.</para></listitem>
+                <listitem><para><emphasis>Initialize a Git Repository:</emphasis>
+                    Use the <filename>git init</filename> command to initialize a new local repository
+                    that is based on the work directory:
+                    <literallayout class='monospaced'>
+     $ git init
+                    </literallayout></para></listitem>
+                <listitem><para><emphasis>Stage all the files:</emphasis>
+                    Use the <filename>git add *</filename> command to stage all the files in the source
+                    code directory so that they can be committed:
+                    <literallayout class='monospaced'>
+     $ git add *
+                    </literallayout></para></listitem>
+                <listitem><para><emphasis>Commit the Source Files:</emphasis>
+                    Use the <filename>git commit</filename> command to initially commit all the files in 
+                    the work directory:
+                    <literallayout class='monospaced'>
+     $ git commit
+                    </literallayout>
+                    At this point, your Git repository is aware of all the source code files.
+                    Any edits you now make to files will be tracked by Git.</para></listitem>
+                <listitem><para><emphasis>Edit the Files:</emphasis>
+                    Make the changes to the temporary source code.</para></listitem>
+                <listitem><para><emphasis>Test Your Changes:</emphasis>
+                    Once you have modified the source code, the easiest way to test your changes 
+                    is by calling the <filename>compile</filename> task as shown in the following example:
+                    <literallayout class='monospaced'>
+     $ bitbake -c compile -f &lt;name_of_package&gt;
+                    </literallayout>
+                    The <filename>-f</filename> or <filename>--force</filename>
+                    option forces re-execution of the specified task.
+                    If you find problems with your code, you can just keep editing and 
+                    re-testing iteratively until things work as expected.
+                    <note>All the modifications you make to the temporary source code
+                    disappear once you <filename>-c clean</filename> or 
+                    <filename>-c cleanall</filename> with BitBake for the package.
+                    Modifications will also disappear if you use the <filename>rm_work</filename>
+                    feature as described in the
+                    "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>" 
+                    section of the Yocto Project Quick Start.
+                    </note></para></listitem>
+                <listitem><para><emphasis>See the List of Files You Changed:</emphasis>
+                    Use the <filename>git status</filename> command to see what files you have actually edited. 
+                    The ability to have Git track the files you have changed is an advantage that this
+                    workflow has over the Quilt workflow.
+                    Here is the Git command to list your changed files:
+                    <literallayout class='monospaced'>
+     $ git status
+                    </literallayout></para></listitem>
+                <listitem><para><emphasis>Stage the Modified Files:</emphasis>
+                    Use the <filename>git add</filename> command to stage the changed files so they
+                    can be committed as follows:
+                    <literallayout class='monospaced'>
+     $ git add file1.c file2.c file3.c
+                    </literallayout></para></listitem>
+                <listitem><para><emphasis>Commit the Staged Files and View Your Changes:</emphasis>
+                    Use the <filename>git commit</filename> command to commit the changes to the 
+                    local repository.  
+                    Once you have committed the files, you can use the <filename>git log</filename>
+                    command to see your changes:
+                    <literallayout class='monospaced'>
+     $ git commit
+     $ git log
+                    </literallayout></para></listitem>
+                <listitem><para><emphasis>Generate the Patch:</emphasis>
+                    Once the changes are committed, use the <filename>git format-patch</filename>
+                    command to generate a patch file:
+                    <literallayout class='monospaced'>
+     $ git format-patch HEAD~1
+                    </literallayout>
+                    The <filename>HEAD~1</filename> part of the command causes Git to generate the 
+                    patch file for the most recent commit.</para>
+                    <para>At this point, the patch file has all your edits made 
+                    to the <filename>file1.c</filename>, <filename>file2.c</filename>, and 
+                    <filename>file3.c</filename> files.
+                    You can find the resulting patch file in the current directory.
+                    The patch file ends with <filename>.patch</filename>.</para></listitem>
+                <listitem><para><emphasis>Copy the Patch File:</emphasis> 
+                    For simplicity, copy the patch file into a directory named <filename>files</filename>,
+                    which you can create in the same directory as the recipe.
+                    Placing the patch here guarantees that the Yocto Project build system will find
+                    the patch.
+                    Next, add the patch into the  
+                    <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename> 
+                    of the recipe.  
+                    Here is an example:
+                    <literallayout class='monospaced'>
+     SRC_URI += "file://my_changes.patch"
+                    </literallayout></para></listitem>
+                <listitem><para><emphasis>Increment the Package Revision Number:</emphasis>
+                    Finally, don't forget to 'bump' the 
+                    <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PR'>PR</ulink></filename>
+                    value in the same recipe since the resulting packages have changed.</para></listitem>
+            </orderedlist>
+        </para>
+    </section>
+</section>
+
 <section id='image-development-using-hob'>
     <title>Image Development Using Hob</title>