documentation/dev-manual/dev-manual-model.xml: Added devshell section

I inserted the section "Using a Development Shell" into the "Common
Development Models" chapter.  This information was formerly in the
YP Reference Manual and is being moved out to help the ref manual
become a truer reference manual.

(From yocto-docs rev: f4ca1c567afcebbae119f21c147e3c38c7ffd54e)

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

1 files changed, 77 insertions, 0 deletions

diff --git a/documentation/dev-manual/dev-manual-model.xml b/documentation/dev-manual/dev-manual-model.xml
index 87e10318a7..ef5c64b678 100644
--- a/documentation/dev-manual/dev-manual-model.xml
+++ b/documentation/dev-manual/dev-manual-model.xml
@@ -36,6 +36,11 @@
              You can use the <ulink url='&YOCTO_HOME_URL;/projects/hob'>Hob</ulink> to build 
              custom operating system images within the build environment.
              Hob provides an efficient interface to the OpenEmbedded build system.</para></listitem>
+         <listitem><para><emphasis>Using a Development Shell:</emphasis>
+             You can use a <filename>devshell</filename> to efficiently debug commands or simply 
+             edit packages.
+             Working inside a development shell is a quick way to set up the OpenEmbedded build 
+             environment to work on parts of a project.</para></listitem>
      </itemizedlist>
 </para>
 
@@ -1040,6 +1045,78 @@
     </para>
 </section>
 
+<section id="platdev-appdev-devshell">
+    <title>Using a Development Shell</title>
+
+    <para>
+        When debugging certain commands or even when just editing packages, 
+        <filename>devshell</filename> can be a useful tool.
+        When you invoke <filename>devshell</filename>, source files are 
+        extracted into your working directory and patches are applied. 
+        Then, a new terminal is opened and you are placed in the working directory.
+        In the new terminal, all the OpenEmbedded build-related environment variables are 
+        still defined so you can use commands such as <filename>configure</filename> and 
+        <filename>make</filename>. 
+        The commands execute just as if the OpenEmbedded build system were executing them. 
+        Consequently, working this way can be helpful when debugging a build or preparing 
+        software to be used with the OpenEmbedded build system.
+    </para>
+
+    <para>
+        Following is an example that uses <filename>devshell</filename> on a target named
+        <filename>matchbox-desktop</filename>:
+        <literallayout class='monospaced'>
+     $ bitbake matchbox-desktop -c devshell
+        </literallayout>
+    </para>
+
+    <para>
+        This command opens a terminal with a shell prompt within the OpenEmbedded build environment. 
+        The default shell is xterm.
+        The following occurs:
+        <itemizedlist>
+            <listitem><para>The <filename>PATH</filename> variable includes the 
+                cross-toolchain.</para></listitem>
+            <listitem><para>The <filename>pkgconfig</filename> variables find the correct 
+                <filename>.pc</filename> files.</para></listitem>
+                <listitem><para>The <filename>configure</filename> command finds the 
+                Yocto Project site files as well as any other necessary files.</para></listitem>
+        </itemizedlist>
+        Within this environment, you can run <filename>configure</filename>
+        or <filename>compile</filename> commands as if they were being run by 
+        the OpenEmbedded build system itself.
+        As noted earlier, the working directory also automatically changes to the 
+        source directory (<ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink>).
+    </para>
+
+    <para> 
+        When you are finished, you just exit the shell or close the terminal window.
+    </para>
+
+    <para>
+        Because an external shell is launched rather than opening directly into the 
+        original terminal window, it allows easier interaction with BitBake's multiple
+        threads as well as accomodates a future client/server split.
+    </para>
+
+    <note>
+        <para>
+            It is worth remembering that when using <filename>devshell</filename>
+            you need to use the full compiler name such as <filename>arm-poky-linux-gnueabi-gcc</filename> 
+            instead of just using <filename>gcc</filename>.
+            The same applies to other applications such as <filename>binutils</filename>, 
+            <filename>libtool</filename> and so forth.
+            BitBake sets up environment variables such as <filename>CC</filename>
+            to assist applications, such as <filename>make</filename> to find the correct tools.
+        </para>
+        
+        <para>
+            It is also worth noting that <filename>devshell</filename> still works over
+            X11 forwarding and similar situations
+        </para>
+    </note>
+</section>
+
 </chapter>
 <!--
 vim: expandtab tw=80 ts=4