documentation: poky-ref-manual, dev-manual - devshell behaviour

Fixes [YOCTO #2909]

Updated the section on using a development shell
(From yocto-docs rev: 37b43dcb19dda747b7e90ac2e393dad29e9d87a5)

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

2 files changed, 73 insertions, 6 deletions

diff --git a/documentation/dev-manual/dev-manual-model.xml b/documentation/dev-manual/dev-manual-model.xml
index c14c524aa5..8fc0d06830 100644
--- a/documentation/dev-manual/dev-manual-model.xml
+++ b/documentation/dev-manual/dev-manual-model.xml
@@ -1859,9 +1859,40 @@ directory.</para></listitem>
     </para>
 
     <para>
-        This command opens a terminal with a shell prompt within the OpenEmbedded build environment. 
-        The default shell is xterm.
-        The following occurs:
+        This command spawns a terminal with a shell prompt within the OpenEmbedded build environment. 
+        The <ulink url='&YOCTO_DOCS_REF_URL;#var-OE_TERMINAL'><filename>OE_TERMINAL</filename></ulink>
+        controls what type of shell is opened.
+        You can define the variable in the <filename>conf/local.conf</filename> 
+        configuration file in the <link linkend='build-directory'>Build Directory</link>.
+    </para>
+ 
+    <para>
+        Current available terminals are:
+        <literallayout class='monospaced'>
+     auto
+     gnome
+     xfce
+     rxvt
+     screen
+     konsole (KDE 3.x only)
+     none
+        </literallayout>
+        The default terminal type is "auto" and causes 
+        the OpenEmbedded build system to attempt to spawn terminals in a 
+        priority order until one is found that is available on the host 
+        development system.
+        For the case of an X terminal, <filename>DISPLAY</filename> must also 
+        be defined.
+    </para>
+
+    <para>
+        If <filename>OE_TERMINAL</filename> is set to "none", the system 
+        never spawns a terminal under any circumstances. 
+        Use this setting when you are doing automated builds.
+    </para>
+
+    <para>
+        For spawned terminals, the following occurs:
         <itemizedlist>
             <listitem><para>The <filename>PATH</filename> variable includes the 
                 cross-toolchain.</para></listitem>
@@ -1870,6 +1901,9 @@ directory.</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>
+    </para>
+
+    <para>
         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.
diff --git a/documentation/poky-ref-manual/ref-variables.xml b/documentation/poky-ref-manual/ref-variables.xml
index 869ff550d4..289057eaa3 100644
--- a/documentation/poky-ref-manual/ref-variables.xml
+++ b/documentation/poky-ref-manual/ref-variables.xml
@@ -30,7 +30,7 @@
        <link linkend='var-LAYERDIR'>L</link> 
        <link linkend='var-MACHINE'>M</link> 
 <!--               <link linkend='var-glossary-n'>N</link> -->
-<!--               <link linkend='var-glossary-o'>O</link> -->
+       <link linkend='var-OE_TERMINAL'>O</link>
        <link linkend='var-P'>P</link> 
 <!--               <link linkend='var-glossary-q'>Q</link> -->
        <link linkend='var-RCONFLICTS'>R</link> 
@@ -1943,8 +1943,41 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
 <!--            <glossdiv id='var-glossary-n'><title>N</title>-->
 <!--            </glossdiv>-->
 
-<!--            <glossdiv id='var-glossary-o'><title>O</title>-->
-<!--            </glossdiv>-->
+    <glossdiv id='var-glossary-o'><title>O</title>
+
+        <glossentry id='var-OE_TERMINAL'><glossterm>OE_TERMINAL</glossterm>
+            <glossdef>
+                <para>
+                    Controls how the OpenEmbedded build system spawns terminals
+                    on the host development system. 
+                    Because the build system needs to account for parallelism
+                    during the build, concurrently running processes might require
+                    attention (e.g. build cannot resove a patch).
+                    For such a case, the host system needs to spawn and launch
+                    an interactive shell.
+                 </para>
+ 
+                 <para>
+                    You can use the following values for the 
+                    <filename>OE_TERMINAL</filename> variable in the 
+                    <filename>conf/local.conf</filename> configuration file, which is found in 
+                    the <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>:
+                    <literallayout class='monospaced'>
+     auto
+     gnome
+     xfce
+     rxvt
+     screen
+     konsole
+     none 
+                    </literallayout>
+                    <note>Konsole support only works for KDE 3.x.
+                        Also, "none" is the default behavior for 
+                        <filename>OE_TERMINAL</filename></note>
+                </para>
+            </glossdef>
+        </glossentry>
+    </glossdiv>
 
     <glossdiv id='var-glossary-p'><title>P</title>