poky-handbook: Add screenshots, change development section order, tweak css for screenshots

git-svn-id: https://svn.o-hand.com/repos/poky/trunk@3877 311d38ba-8fff-0310-9ca6-ca027cbcb966

1 files changed, 177 insertions, 140 deletions

diff --git a/handbook/development.xml b/handbook/development.xml
index c56c69ca79..ee98265ca0 100644
--- a/handbook/development.xml
+++ b/handbook/development.xml
@@ -37,6 +37,172 @@
         </para>
     </section>
 
+    <section id="platdev-appdev-external-anjuta">
+        <title>Developing externally using the Anjuta plugin</title>
+
+        <para>
+            An Anjuta IDE plugin exists to make developing software within the Poky framework
+            easier for the application developer. It presents a graphical IDE from which the 
+            developer can cross compile an application then deploy and execute the output in a QEMU 
+            emulation session. It also supports cross debugging and profiling.
+        </para>
+
+        <screenshot>
+        <mediaobject>
+            <imageobject>
+                <imagedata fileref="screenshots/ss-anjuta-poky-1.png" format="PNG"/>
+            </imageobject>
+            <caption>
+                <para>The Anjuta Poky SDK plugin showing an active QEMU session running Sato</para>
+            </caption>
+         </mediaobject>
+         </screenshot>
+
+        <para>
+            To use the plugin, a toolchain and SDK built by Poky is required along with Anjuta and the Anjuta 
+            plugin. The Poky Anjuta plugin is available from the OpenedHand SVN repository located at
+            http://svn.o-hand.com/repos/anjuta-poky/trunk/anjuta-plugin-sdk/; a web interface
+            to the repository can be accessed at <ulink url='http://svn.o-hand.com/view/anjuta-poky/'/>.
+            See the README file contained in the project for more information
+            about the dependencies and how to get them along with details of
+            the prebuilt packages.
+        </para>
+
+        <section id="platdev-appdev-external-anjuta-setup">
+          <title>Setting up the Anjuta plugin</title>
+
+            <para>Extract the tarball for the toolchain into / as root. The
+              toolchain will be installed into
+              <filename class="directory">/usr/local/poky</filename>.</para>
+
+            <para>To use the plugin, first open or create an existing
+              project. If creating a new project the "C GTK+" project type
+              will allow itself to be cross-compiled.  However you should be
+              aware that this uses glade for the UI.</para>
+
+            <para>To activate the plugin go to
+              <menuchoice><guimenu>Edit</guimenu><guimenuitem>Preferences</guimenuitem></menuchoice>,
+              then choose <guilabel>General</guilabel> from the left hand side. Choose the
+              Installed plugins tab, scroll down to <guilabel>Poky
+                SDK</guilabel> and check the
+              box. The plugin is now activated but first it must be
+              configured.</para> 
+        </section>
+
+        <section id="platdev-appdev-external-anjuta-configuration">
+          <title>Configuring the Anjuta plugin</title>
+
+          <para>The configuration options for the SDK can be found by choosing
+            the <guilabel>Poky SDK</guilabel> icon from the left hand side. The following options
+            need to be set:</para>
+
+          <itemizedlist>
+            
+            <listitem><para><guilabel>SDK root</guilabel>: this is the root directory of the SDK
+                for an ARM EABI SDK this will be <filename
+                  class="directory">/usr/local/poky/eabi-glibc/arm</filename>.
+                This directory will contain directories named like "bin",
+                "include", "var", etc. With the file chooser it is important
+                to enter into the "arm" subdirectory for this
+                example.</para></listitem>
+
+            <listitem><para><guilabel>Toolchain triplet</guilabel>: this is the cross compile
+                triplet, e.g. "arm-poky-linux-gnueabi".</para></listitem>
+
+            <listitem><para><guilabel>Kernel</guilabel>: use the file chooser to select the kernel
+                to use with QEMU</para></listitem>
+
+            <listitem><para><guilabel>Root filesystem</guilabel>: use the file chooser to select
+                the root filesystem image, this should be an image (not a
+                tarball)</para></listitem>
+          </itemizedlist>
+
+        <screenshot>
+        <mediaobject>
+            <imageobject>
+                <imagedata fileref="screenshots/ss-anjuta-poky-2.png" format="PNG"/>
+            </imageobject>
+            <caption>
+                <para>Anjuta Preferences Dialog</para>
+            </caption>
+         </mediaobject>
+         </screenshot>
+
+
+        </section>
+
+        <section id="platdev-appdev-external-anjuta-usage">
+            <title>Using the Anjuta plugin</title>
+
+            <para>As an example, cross-compiling a project, deploying it into
+              QEMU and running a debugger against it and then doing a system
+              wide profile.</para>
+
+            <para>Choose <menuchoice><guimenu>Build</guimenu><guimenuitem>Run
+                  Configure</guimenuitem></menuchoice> or
+              <menuchoice><guimenu>Build</guimenu><guimenuitem>Run
+                  Autogenerate</guimenuitem></menuchoice> to run "configure"
+              (or to run "autogen") for the project. This passes command line
+              arguments to instruct it to cross-compile.</para>
+
+            <para>Next do
+              <menuchoice><guimenu>Build</guimenu><guimenuitem>Build
+                  Project</guimenuitem></menuchoice> to build and compile the
+              project. If you have previously built the project in the same
+              tree without using the cross-compiler you may find that your
+              project fails to link. Simply do
+              <menuchoice><guimenu>Build</guimenu><guimenuitem>Clean
+                  Project</guimenuitem></menuchoice> to remove the old
+              binaries. You may then try building again.</para>
+
+            <para>Next start QEMU by using
+              <menuchoice><guimenu>Tools</guimenu><guimenuitem>Start
+                  QEMU</guimenuitem></menuchoice>, this will start QEMU and
+              will show any error messages in the message view. Once Poky has
+              fully booted within QEMU you may now deploy into it.</para>
+
+            <para>Once built and QEMU is running, choose
+              <menuchoice><guimenu>Tools</guimenu><guimenuitem>Deploy</guimenuitem></menuchoice>,
+              this will install the package into a temporary directory and
+              then copy using rsync over SSH into the target.  Progress and
+              messages will be shown in the message view.</para>
+
+            <para>To debug a program installed into onto the target choose
+              <menuchoice><guimenu>Tools</guimenu><guimenuitem>Debug
+                  remote</guimenuitem></menuchoice>. This prompts for the
+              local binary to debug and also the command line to run on the
+              target. The command line to run should include the full path to
+              the to binary installed in the target. This will start a
+              gdbserver over SSH on the target and also an instance of a
+              cross-gdb in a local terminal. This will be preloaded to connect
+              to the server and use the <guilabel>SDK root</guilabel> to find
+              symbols. This gdb will connect to the target and load in
+              various libraries and the target program.  You should setup any
+              breakpoints or watchpoints now since you might not be able to
+              interrupt the execution later. You may stop
+              the debugger on the target using
+              <menuchoice><guimenu>Tools</guimenu><guimenuitem>Stop
+                  debugger</guimenuitem></menuchoice>.</para>
+
+            <para>It is also possible to execute a command in the target over
+              SSH, the appropriate environment will be be set for the
+              execution. Choose
+              <menuchoice><guimenu>Tools</guimenu><guimenuitem>Run
+                  remote</guimenuitem></menuchoice> to do this. This will open
+              a terminal with the SSH command inside.</para>
+
+            <para>To do a system wide profile against the system running in
+              QEMU choose
+              <menuchoice><guimenu>Tools</guimenu><guimenuitem>Profile
+                  remote</guimenuitem></menuchoice>. This will start up
+              OProfileUI with the appropriate parameters to connect to the
+              server running inside QEMU and will also supply the path to the
+              debug information necessary to get a useful profile.</para>
+
+        </section>
+    </section>
+
+
     <section id="platdev-appdev-qemu">
         <title>Developing externally in QEMU</title>
         <para>
@@ -233,146 +399,6 @@ $ bitbake matchbox-desktop -c devshell
         </para>
     </section>
 
-    <section id="platdev-appdev-external-anjuta">
-        <title>Developing externally using the Anjuta plugin</title>
-
-        <para>
-            An Anjuta IDE plugin exists to make developing software within the Poky framework
-            easier for the application developer. It presents a graphical IDE from which the 
-            developer can cross compile an application then deploy and execute the output in a QEMU 
-            emulation session. It also supports cross debugging and profiling.
-        </para>
-
-        <para>
-            To use the plugin, a toolchain and SDK built by Poky is required along with Anjuta and the Anjuta 
-            plugin. The Poky Anjuta plugin is available from the OpenedHand SVN repository located at
-            http://svn.o-hand.com/repos/anjuta-poky/trunk/anjuta-plugin-sdk/; a web interface
-            to the repository can be accessed at <ulink url='http://svn.o-hand.com/view/anjuta-poky/'/>.
-            See the README file contained in the project for more information
-            about the dependencies and how to get them along with details of
-            the prebuilt packages.
-        </para>
-
-        <section id="platdev-appdev-external-anjuta-setup">
-          <title>Setting up the Anjuta plugin</title>
-
-            <para>Extract the tarball for the toolchain into / as root. The
-              toolchain will be installed into
-              <filename class="directory">/usr/local/poky</filename>.</para>
-
-            <para>To use the plugin, first open or create an existing
-              project. If creating a new project the "C GTK+" project type
-              will allow itself to be cross-compiled.  However you should be
-              aware that this uses glade for the UI.</para>
-
-            <para>To activate the plugin go
-              <menuchoice><guimenu>Edit</guimenu><guimenuitem>Preferences</guimenuitem></menuchoice>,
-              then choose <guilabel>General</guilabel> from the left hand side. Choose the
-              Installed plugins tab, scroll down to <guilabel>Poky
-                SDK</guilabel> and check the
-              box. The plugin is now activated but first it must be
-              configured.</para> </section>
-
-        <section id="platdev-appdev-external-anjuta-configuration">
-          <title>Configuring the Anjuta plugin</title>
-
-          <para>The configuration options for the SDK can be found by choosing
-            the <guilabel>Poky SDK</guilabel> icon from the left hand side. The following options
-            need to be set:</para>
-
-          <itemizedlist>
-            
-            <listitem><para><guilabel>SDK root</guilabel>: this is the root directory of the SDK
-                for an ARM EABI SDK this will be <filename
-                  class="directory">/usr/local/poky/eabi-glibc/arm</filename>.
-                This directory will contain directories named like "bin",
-                "include", "var", etc. With the file chooser it is important
-                to enter into the "arm" subdirectory for this
-                example.</para></listitem>
-
-            <listitem><para><guilabel>Toolchain triplet</guilabel>: this is the cross compile
-                triplet, e.g. "arm-poky-linux-gnueabi".</para></listitem>
-
-            <listitem><para><guilabel>Kernel</guilabel>: use the file chooser to select the kernel
-                to use with QEMU</para></listitem>
-
-            <listitem><para><guilabel>Root filesystem</guilabel>: use the file chooser to select
-                the root filesystem image, this should be an image (not a
-                tarball)</para></listitem>
-          </itemizedlist>
-
-        </section>
-
-        <section id="platdev-appdev-external-anjuta-usage">
-            <title>Using the Anjuta plugin</title>
-
-            <para>As an example, cross-compiling a project, deploying it into
-              QEMU and running a debugger against it and then doing a system
-              wide profile.</para>
-
-            <para>Choose <menuchoice><guimenu>Build</guimenu><guimenuitem>Run
-                  Configure</guimenuitem></menuchoice> or
-              <menuchoice><guimenu>Build</guimenu><guimenuitem>Run
-                  Autogenerate</guimenuitem></menuchoice> to run "configure"
-              (or to run "autogen") for the project. This passes command line
-              arguments to instruct it to cross-compile.</para>
-
-            <para>Next do
-              <menuchoice><guimenu>Build</guimenu><guimenuitem>Build
-                  Project</guimenuitem></menuchoice> to build and compile the
-              project. If you have previously built the project in the same
-              tree without using the cross-compiler you may find that your
-              project fails to link. Simply do
-              <menuchoice><guimenu>Build</guimenu><guimenuitem>Clean
-                  Project</guimenuitem></menuchoice> to remove the old
-              binaries. You may then try building again.</para>
-
-            <para>Next start QEMU by using
-              <menuchoice><guimenu>Tools</guimenu><guimenuitem>Start
-                  QEMU</guimenuitem></menuchoice>, this will start QEMU and
-              will show any error messages in the message view. Once Poky has
-              fully booted within QEMU you may now deploy into it.</para>
-
-            <para>Once built and QEMU is running, choose
-              <menuchoice><guimenu>Tools</guimenu><guimenuitem>Deploy</guimenuitem></menuchoice>,
-              this will install the package into a temporary directory and
-              then copy using rsync over SSH into the target.  Progress and
-              messages will be shown in the message view.</para>
-
-            <para>To debug a program installed into onto the target choose
-              <menuchoice><guimenu>Tools</guimenu><guimenuitem>Debug
-                  remote</guimenuitem></menuchoice>. This prompts for the
-              local binary to debug and also the command line to run on the
-              target. The command line to run should include the full path to
-              the to binary installed in the target. This will start a
-              gdbserver over SSH on the target and also an instance of a
-              cross-gdb in a local terminal. This will be preloaded to connect
-              to the server and use the <guilabel>SDK root</guilabel> to find
-              symbols. This gdb will connect to the target and load in
-              various libraries and the target program.  You should setup any
-              breakpoints or watchpoints now since you might not be able to
-              interrupt the execution later. You may stop
-              the debugger on the target using
-              <menuchoice><guimenu>Tools</guimenu><guimenuitem>Stop
-                  debugger</guimenuitem></menuchoice>.</para>
-
-            <para>It is also possible to execute a command in the target over
-              SSH, the appropriate environment will be be set for the
-              execution. Choose
-              <menuchoice><guimenu>Tools</guimenu><guimenuitem>Run
-                  remote</guimenuitem></menuchoice> to do this. This will open
-              a terminal with the SSH command inside.</para>
-
-            <para>To do a system wide profile against the system running in
-              QEMU choose
-              <menuchoice><guimenu>Tools</guimenu><guimenuitem>Profile
-                  remote</guimenuitem></menuchoice>. This will start up
-              OProfileUI with the appropriate parameters to connect to the
-              server running inside QEMU and will also supply the path to the
-              debug information necessary to get a useful profile.</para>
-
-        </section>
-    </section>
   </section>
 
 <section id="platdev-gdb-remotedebug">
@@ -660,6 +686,17 @@ $ opreport -cl
             are installed onto the target device for OProfileUI interaction.
         </para>
 
+        <screenshot>
+        <mediaobject>
+            <imageobject>
+                <imagedata fileref="screenshots/ss-oprofile-viewer.png" format="PNG"/>
+            </imageobject>
+            <caption>
+                <para>OProfileUI Viewer showing an application being profiled on a remote device</para>
+            </caption>
+         </mediaobject>
+         </screenshot>
+
         <para>
             In order to convert the data in the sample format from the target
             to the host the <filename>opimport</filename> program is needed.