usermanual: Add some details in the usage section on how to bring up a devshell.

1 files changed, 123 insertions, 25 deletions

diff --git a/usermanual/chapters/usage.xml b/usermanual/chapters/usage.xml
index e4f056a764..4c58fc700a 100644
--- a/usermanual/chapters/usage.xml
+++ b/usermanual/chapters/usage.xml
@@ -136,7 +136,7 @@
     that this may not be exactly what see - there are a lot of options that
     can effect exactly how things are done, but it gives us a pretty good idea
     of whats going on. What we are looking at here is the tmp directory (as
-    specified by TMPDIR in your local.conf):<screen>%&gt; find tmp -maxdepth 2 -type d 
+    specified by TMPDIR in your local.conf):<screen>~%&gt; find tmp -maxdepth 2 -type d 
 tmp
 tmp/stamps
 tmp/cross
@@ -314,7 +314,7 @@ tmp/work/sh4-linux/arpwatch-2.1a15-r2</screen></para>
       distribution is using it.</para>
 
       <para>Using lzo 1.08 as an example we'll examine the contents of the
-      working directory for a typical recipe:<screen>%&gt; find tmp/work/lzo-1.08-r14 -maxdepth 1
+      working directory for a typical recipe:<screen>~%&gt; find tmp/work/lzo-1.08-r14 -maxdepth 1
 tmp/work/lzo-1.08-r14
 tmp/work/lzo-1.08-r14/temp
 tmp/work/lzo-1.08-r14/lzo-1.08
@@ -413,7 +413,7 @@ tmp/work/lzo-1.08-r14/image</screen></para>
       </variablelist>
 
       <para>So lets show some examples of the useful information you now have
-      access to. </para>
+      access to.</para>
 
       <para>How about checking out what happened during the configuration of
       lzo? Well that requires checking the log file for configure that is
@@ -748,7 +748,7 @@ NOTE: build 200705041709: completed</screen><note>
       <emphasis>x</emphasis> is implemented via a function called
       <emphasis>do_x</emphasis> in the class or recipe where it is defined.
       See places refer to the tasks via their name only and some with the
-      <emphasis>do</emphasis> prefix. </para>
+      <emphasis>do</emphasis> prefix.</para>
     </note>
 
     <para>You will almost certainly notice tasks beyond these ones - there are
@@ -760,7 +760,7 @@ NOTE: build 200705041709: completed</screen><note>
     <emphasis>configure</emphasis> and <emphasis>compile</emphasis> tasks and
     another new task called <emphasis>qa_staging</emphasis> between
     <emphasis>populate_staging</emphasis> and <emphasis>build</emphasis>
-    tasks. The format validates the result of the
+    tasks. The former validates the result of the
     <emphasis>configure</emphasis> task and the late the results of the
     <emphasis>populate_staging</emphasis> task.</para>
 
@@ -813,12 +813,12 @@ NOTE: package perl-5.8.8: completed
     by passing it via the <emphasis role="bold">-b</emphasis> parameter. This
     option takes the recipe as a parameter and instructs bitbake to process
     the named recipe only. Note that this ignores any dependencies that are in
-    the recipe, so these must have already been built previously. </para>
+    the recipe, so these must have already been built previously.</para>
 
     <para>Here's a typically example that cleans up the package (using the
     <emphasis>clean</emphasis> task) and the rebuilds it with debugging output
-    from bitbake enabled:<screen>%&gt; bitbake -b &lt;bb-file&gt; -c clean
-%&gt; bitbake -b &lt;bb-file&gt; -D</screen></para>
+    from bitbake enabled:<screen>~%&gt; bitbake -b &lt;bb-file&gt; -c clean
+~%&gt; bitbake -b &lt;bb-file&gt; -D</screen></para>
 
     <para>The options to bitbake that are most useful here are:</para>
 
@@ -958,28 +958,28 @@ NOTE: package perl-5.8.8: completed
     actions.</para>
 
     <para>A typically development session might involve editing files in the
-    working directory and then recompiling until it all works:<screen>[... test ...]
-%&gt; bitbake -b packages/testapp/testapp_4.3.bb -c compile -D
+    working directory and then recompiling until it all works:<screen>[<emphasis>... test ...</emphasis>]
+~%&gt; bitbake -b packages/testapp/testapp_4.3.bb -c compile -D
 
-[... save a copy of main.c and make some changes ...]
-%&gt; vi tmp/work/testapp-4.3-r0/main.c
-%&gt; bitbake -b packages/testapp/testapp_4.3.bb -c compile -D -f
+[<emphasis>... save a copy of main.c and make some changes ...</emphasis>]
+~%&gt; vi tmp/work/testapp-4.3-r0/main.c
+~%&gt; bitbake -b packages/testapp/testapp_4.3.bb -c compile -D -f
 
-[... create a patch and add it to the recipe ...]
-%&gt; vi packages/testapp/testapp_4.3.bb
+[<emphasis>... create a patch and add it to the recipe ...</emphasis>]
+~%&gt; vi packages/testapp/testapp_4.3.bb
 
-[... test from clean ...]
-%&gt; bitbake -b packages/testapp/testapp_4.3.bb -c clean
-%&gt; bitbake -b packages/testapp/testapp_4.3.bb
+[<emphasis>... test from clean ...</emphasis>]
+~%&gt; bitbake -b packages/testapp/testapp_4.3.bb -c clean
+~%&gt; bitbake -b packages/testapp/testapp_4.3.bb
 
-[... NOTE: How to create the patch is not covered at this point ...]</screen></para>
+[<emphasis>... NOTE: How to create the patch is not covered at this point ...</emphasis>]</screen></para>
 
     <para>Here's another example showing how you might go about fixing up the
-    packaging in your recipe:<screen>%&gt; bitbake -b packages/testapp/testapp_4.3.bb -c install -f
-%&gt; bitbake -b packages/testapp/testapp_4.3.bb -c stage -f
-%&gt; find tmp/work/testapp_4.3/install
+    packaging in your recipe:<screen>~%&gt; bitbake -b packages/testapp/testapp_4.3.bb -c install -f
+~%&gt; bitbake -b packages/testapp/testapp_4.3.bb -c stage -f
+~%&gt; find tmp/work/testapp_4.3/install
 ...
-%&gt; vi packages/testapp/testapp_4.3.bb</screen>At this stage you play with
+~%&gt; vi packages/testapp/testapp_4.3.bb</screen>At this stage you play with
     the <emphasis role="bold">PACKAGE_</emphasis> and <emphasis
     role="bold">FILES_</emphasis> variables and then repeat the above
     sequence.</para>
@@ -1001,7 +1001,7 @@ NOTE: package perl-5.8.8: completed
   <section id="usage_interactive_bitbake" xreflabel="interactive bitbake">
     <title>Interactive bitbake</title>
 
-    <para>To interactively test things use:<screen>%&gt; bitbake -i</screen>this
+    <para>To interactively test things use:<screen>~%&gt; bitbake -i</screen>this
     will open the bitbake shell. From here there are a lot of commands
     available (try help).</para>
 
@@ -1023,7 +1023,105 @@ BB&gt;&gt; build net-snmp</screen>Note that you can use wildcards in the
   <section id="usage_devshell" xreflabel="devshell">
     <title>Devshell</title>
 
-    <para>[To be done]</para>
+    <para>One of the areas in which OpenEmbedded helps you out is by setting
+    various environment variables, such as <emphasis role="bold">CC</emphasis>
+    and <emphasis role="bold">PATH</emphasis> etc, to values suitable for
+    cross-compiling. If you wish to manually run configure scripts and compile
+    file during development it would be nice to have all those values set for
+    you. This is what devshell does - it provides you with an interactive
+    shell with all the appropriate variables set for cross-compiling.</para>
+
+    <section>
+      <title>devshell via inherit</title>
+
+      <para>This is the newer method of obtaining a devshell and is the
+      recommended way for most users now. The newer method requires that the
+      devshell class be added to you configuration by inheriting it. This is
+      usually done in your <emphasis role="bold">local.conf</emphasis> or your
+      distributions conf file:<screen><emphasis role="bold">INHERIT +=</emphasis> "src_distribute_local insane multimachine <emphasis
+            role="bold">devshell</emphasis>"</screen></para>
+
+      <para>With the inclusion of this class you'll find that devshell is
+      added as a new task that you can use on recipes:<screen>~%&gt; bitbake -b packages/lzo/lzo_1.08.bb -c listtasks
+NOTE: package lzo-1.08: started
+NOTE: package lzo-1.08-r14: task do_listtasks: started
+<emphasis role="bold">do_devshell</emphasis>
+do_fetchall
+do_listtasks
+do_rebuild
+do_compile
+do_build
+do_mrproper
+do_fetch
+do_configure
+do_clean
+do_populate_staging
+do_package
+do_unpack
+do_install
+do_package_write
+do_distribute_sources
+do_showdata
+do_qa_staging
+do_qa_configure
+do_patch
+NOTE: package lzo-1.08-r14: task do_listtasks: completed
+NOTE: package lzo-1.08: completed</screen></para>
+
+      <para>To bring up the devshell you call bitbake on a recipe and ask it
+      for the devshell task:<screen>~%&gt; ./bb -b packages/lzo/lzo_1.08.bb -c devshell
+NOTE: package lzo-1.08: started
+NOTE: package lzo-1.08-r14: task do_devshell: started
+[<emphasis>... devshell will appear here ...</emphasis>]
+NOTE: package lzo-1.08-r14: task do_devshell: completed
+NOTE: package lzo-1.08: completed</screen></para>
+
+      <para>How the devshell appears depends on the settings of the <emphasis
+      role="bold">TERMCMD</emphasis> variable - you can see the default
+      settings and other possible values in <emphasis
+      role="bold">conf/bitbake.conf</emphasis>. Feel free to try settings this
+      to something else in your local.conf. Usually you will see a new
+      terminal window open which is the devshell window.</para>
+
+      <para>The devshell task is inserted after the patch task, so if you have
+      not already run bitbake on the recipe it will download the source and
+      apply any patches prior to opening the shell.</para>
+
+      <note>
+        <para>This method of obtaining a devshell works if you using <emphasis
+        role="bold">bash</emphasis> as your shell, it does not work if you are
+        using <emphasis role="bold">zsh</emphasis> as your shell. Other shells
+        may or may not work.</para>
+      </note>
+    </section>
+
+    <section>
+      <title>devshell addon</title>
+
+      <para>The devshell addon was the original method that was used to create
+      a devshell.</para>
+
+      <para>It requires no changes to your configuration, instead you simply
+      build the devshell recipe:<screen>bitabike devshell</screen></para>
+
+      <para>and then manually startup the shell. Once in the shell you'll
+      usually want to change into the working directory for the recipe you are
+      working on:<screen>~%&gt; ./tmp/deploy/addons/sh4-linux-erouter-titan-devshell
+bash: alias: `./configure': invalid alias name
+[OE::sh4-linux-erouter-titan]:~$ cd tmp/work/lzo-1.08-r14/lzo-1.08
+[OE::sh4-linux-erouter-titan]:~tmp/work/lzo-1.08-r14/lzo-1.08$</screen><note>
+          <para>The name of the devshell addon depends on the target
+          architecture, operating system and machine name. So you name will be
+          different - just check for the appropriate name ending in
+          -devshell.</para>
+        </note></para>
+    </section>
+
+    <section>
+      <title>Working in the devshell</title>
+
+      <para>[To be done]</para>
+    </section>
   </section>
 
   <section id="usage_patches" xreflabel="patching">