Add Poky handbook

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

52 files changed, 10973 insertions, 0 deletions

diff --git a/handbook/ChangeLog b/handbook/ChangeLog
new file mode 100644
index 0000000000..2cff9f9967
--- /dev/null
+++ b/handbook/ChangeLog
@@ -0,0 +1,29 @@
+2008-02-15  Matthew Allum  <mallum@openedhand.com>
+
+	* introduction.xml:
+        Minor tweaks to 'What is Poky'
+
+2008-02-15  Matthew Allum  <mallum@openedhand.com>
+
+	* poky-handbook.xml:
+        * poky-handbook.png
+        * poky-beaver.png
+	* poky-logo.svg:
+	* style.css:
+        Add some title images.
+
+2008-02-14  Matthew Allum  <mallum@openedhand.com>
+
+	* development.xml:
+        remove uri's
+	* style.css:
+        Fix glossary
+
+2008-02-06  Matthew Allum  <mallum@openedhand.com>
+
+	* Makefile:
+        Add various xslto options for html.
+	* introduction.xml:
+        Remove link in title.
+	* style.css:
+        Add initial version
diff --git a/handbook/Makefile b/handbook/Makefile
new file mode 100644
index 0000000000..ff6cd89d41
--- /dev/null
+++ b/handbook/Makefile
@@ -0,0 +1,22 @@
+all: html pdf
+
+pdf:
+
+	poky-docbook-to-pdf poky-handbook.xml
+#       -- old way --
+#	dblatex poky-handbook.xml
+
+html:
+#       See http://www.sagehill.net/docbookxsl/HtmlOutput.html 
+	xsltproc --stringparam html.stylesheet style.css \
+	         --stringparam  chapter.autolabel 1 \
+                 --stringparam  appendix.autolabel 1 \
+	         --stringparam  section.autolabel 1 \
+                 -o poky-handbook.html \
+                 --xinclude /usr/share/xml/docbook/stylesheet/nwalsh/html/docbook.xsl                                 \
+                  poky-handbook.xml
+#       -- old way --
+#	xmlto xhtml-nochunks poky-handbook.xml
+
+validate:
+	xmllint --postvalid --xinclude --noout poky-handbook.xml
diff --git a/handbook/TODO b/handbook/TODO
new file mode 100644
index 0000000000..f3e843b8de
--- /dev/null
+++ b/handbook/TODO
@@ -0,0 +1,12 @@
+Handbook Todo List:
+
+  * Add instructions about using zaurus/openmoko emulation
+  * Add diagrams + oprofile screenshot
+  * Software Deevelopment intro should mention its software development for 
+    intended target and could be a different arch etc and thus special case. 
+
+Long Term:
+
+  * Expand insane.bbclass documentation to cover tests
+  * Document remaining classes (see list in ref-classes)
+
diff --git a/handbook/contactus.xml b/handbook/contactus.xml
new file mode 100644
index 0000000000..9ebccdec2d
--- /dev/null
+++ b/handbook/contactus.xml
@@ -0,0 +1,30 @@
+<!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<appendix id='contact'>
+    <title>OpenedHand Contact Information</title>
+
+    <literallayout>
+OpenedHand Ltd
+Unit R, Homesdale Business Center
+216-218 Homesdale Rd
+Bromley, BR1 2QZ
+England
++44 (0) 208 819 6559
+info@openedhand.com</literallayout>
+
+    <!-- Fop messes this up so we do like above
+    <address>
+        OpenedHand Ltd
+        Unit R, Homesdale Business Center
+        <street>216-218 Homesdale Rd</street>
+        <city>Bromley</city>, <postcode>BR1 2QZ</postcode>
+        <country>England</country>
+        <phone> +44 (0) 208 819 6559</phone>
+        <email>info@openedhand.com</email>
+    </address>
+    -->
+</appendix>
+<!-- 
+vim: expandtab tw=80 ts=4 
+-->
diff --git a/handbook/development.xml b/handbook/development.xml
new file mode 100644
index 0000000000..c56c69ca79
--- /dev/null
+++ b/handbook/development.xml
@@ -0,0 +1,815 @@
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<chapter id="platdev">
+<title>Platform Development with Poky</title>
+
+<section id="platdev-appdev">
+    <title>Software development</title>
+    <para>
+        Poky supports several methods of software development. These different
+        forms of development are explained below and can be switched
+        between as needed.
+    </para>
+
+    <section id="platdev-appdev-external-sdk">
+        <title>Developing externally using the Poky SDK</title>
+
+        <para>
+            The meta-toolchain and meta-toolchain-sdk targets (<link linkend='ref-images'>see
+            the images section</link>) build tarballs which contain toolchains and 
+            libraries suitable for application development outside Poky. These unpack into the 
+            <filename class="directory">/usr/local/poky</filename> directory and contain
+            a setup script, e.g. 
+            <filename>/usr/local/poky/eabi-glibc/arm/environment-setup</filename> which
+            can be sourced to initialise a suitable environment. After sourcing this, the 
+            compiler, QEMU scripts, QEMU binary, a special version of pkgconfig and other 
+            useful utilities are added to the PATH. Variables to assist pkgconfig and 
+            autotools are also set so that, for example, configure can find pre-generated test 
+            results for tests which need target hardware to run.
+        </para>
+
+        <para>
+            Using the toolchain with autotool enabled packages is straightforward, just pass the 
+            appropriate host option to configure e.g. "./configure --host=arm-poky-linux-gnueabi".
+            For other projects it is usually a case of ensuring the cross tools are used e.g.
+            CC=arm-poky-linux-gnueabi-gcc and LD=arm-poky-linux-gnueabi-ld.
+        </para>
+    </section>
+
+    <section id="platdev-appdev-qemu">
+        <title>Developing externally in QEMU</title>
+        <para>
+            Running Poky QEMU images is covered in the <link 
+            linkend='intro-quickstart-qemu'>Running an Image</link> section.
+        </para>
+        <para>
+            Poky's QEMU images contain a complete native toolchain. This means 
+            that applications can be developed within QEMU in the same was as a 
+            normal system. Using qemux86 on an x86 machine is fast since the 
+            guest and host architectures match, qemuarm is slower but gives 
+            faithful emulation of ARM specific issues. To speed things up these 
+            images support using distcc to call a cross-compiler outside the 
+            emulated system too. If <command>runqemu</command> was used to start
+            QEMU, and distccd is present on the host system, any bitbake cross 
+            compiling toolchain available from the build system will automatically
+            be used from within qemu simply by calling distcc 
+            (<command>export CC="distcc"</command> can be set in the enviroment).
+            Alterntatively, if a suitable SDK/toolchain is present in 
+            <filename class="directory">/usr/local/poky</filename> it will also
+            automatically be used.
+        </para>
+
+        <para>
+            There are several options for connecting into the emulated system. 
+            QEMU provides a framebuffer interface which has standard consoles 
+            available. There is also a serial connection available which has a 
+            console to the system running on it and IP networking as standard. 
+            The images have a dropbear ssh server running with the root password 
+            disabled allowing standard ssh and scp commands to work. The images
+            also contain an NFS server exporting the guest's root filesystem 
+            allowing that to be made available to the host.
+        </para>
+    </section>              
+
+    <section id="platdev-appdev-chroot">
+        <title>Developing externally in a chroot</title>
+        <para>
+            If you have a system that matches the architecture of the Poky machine you're using,
+            such as qemux86, you can run binaries directly from the image on the host system
+            using a chroot combined with tools like <ulink url='http://projects.o-hand.com/xephyr'>Xephyr</ulink>.
+        </para>
+        <para>
+            Poky has some scripts to make using its qemux86 images within a chroot easier. To use
+            these you need to install the poky-scripts package or otherwise obtain the 
+            <filename>poky-chroot-setup</filename> and <filename>poky-chroot-run</filename> scripts.
+            You also need Xephyr and chrootuid binaries available. To initialize a system use the setup script:
+        </para>
+        <para>
+            <literallayout class='monospaced'>
+# poky-chroot-setup &lt;qemux86-rootfs.tgz&gt; &lt;target-directory&gt;
+</literallayout>
+        </para>
+        <para>
+            which will unpack the specified qemux86 rootfs tarball into the target-directory. 
+            You can then start the system with:
+        </para>
+        <para>
+            <literallayout class='monospaced'>
+# poky-chroot-run &lt;target-directory&gt; &lt;command&gt;
+</literallayout>
+        </para>
+        <para>
+            where the target-directory is the place the rootfs was unpacked to and command is 
+            an optional command to run. If no command is specified, the system will drop you 
+            within a bash shell. A Xephyr window will be displayed containing the emulated 
+            system and you may be asked for a password since some of the commands used for 
+            bind mounting directories need to be run using sudo.
+        </para>
+        <para>
+            There are limits as to how far the the realism of the chroot environment extends.
+            It is useful for simple development work or quick tests but full system emulation 
+            with QEMU offers a much more realistic environment for more complex development 
+            tasks. Note that chroot support within Poky is still experimental.
+        </para>
+    </section>  
+
+    <section id="platdev-appdev-insitu">
+        <title>Developing in Poky directly</title>
+        <para>
+            Working directly in Poky is a fast and effective development technique.
+            The idea is that you can directly edit files in 
+            <glossterm><link linkend='var-WORKDIR'>WORKDIR</link></glossterm> 
+            or the source directory <glossterm><link linkend='var-S'>S</link></glossterm> 
+            and then force specific tasks to rerun in order to test the changes. 
+            An example session working on the matchbox-desktop package might 
+            look like this:
+        </para>
+
+        <para>
+            <literallayout class='monospaced'>
+$ bitbake matchbox-desktop
+$ sh
+$ cd tmp/work/armv5te-poky-linux-gnueabi/matchbox-desktop-2.0+svnr1708-r0/
+$ cd matchbox-desktop-2
+$ vi src/main.c
+$ exit
+$ bitbake matchbox-desktop -c compile -f
+$ bitbake matchbox-desktop
+</literallayout>
+        </para>
+
+        <para>
+            Here, we build the package, change into the work directory for the package,
+            change a file, then recompile the package. Instead of using sh like this,
+            you can also use two different terminals. The risk with working like this 
+            is that a command like unpack could wipe out the changes you've made to the
+            work directory so you need to work carefully.
+        </para>
+
+        <para>
+            It is useful when making changes directly to the work directory files to do
+            so using quilt as detailed in the <link linkend='usingpoky-modifying-packages-quilt'> 
+            modifying packages with quilt</link> section. The resulting patches can be copied 
+            into the recipe directory and used directly in the <glossterm><link 
+            linkend='var-SRC_URI'>SRC_URI</link></glossterm>.
+        </para>
+        <para>
+            For a review of the skills used in this section see Sections <link
+            linkend="usingpoky-components-bitbake">2.1.1</link> and <link 
+            linkend="usingpoky-debugging-taskrunning">2.4.2</link>.
+        </para>
+
+    </section>
+
+    <section id="platdev-appdev-devshell">
+        <title>Developing with 'devshell'</title>
+
+        <para>
+            When debugging certain commands or even to just edit packages, the
+            'devshell' can be a useful tool. To start it you run a command like:
+        </para>
+
+        <para>
+            <literallayout class='monospaced'>
+$ bitbake matchbox-desktop -c devshell
+</literallayout>
+        </para>
+
+        <para>
+            which will open a terminal with a shell prompt within the Poky 
+            environment. This means PATH is setup to include the cross toolchain, 
+            the pkgconfig variables are setup to find the right .pc files, 
+            configure will be able to find the Poky site files etc. Within this 
+            environment, you can run configure or compile command as if they 
+            were being run by Poky itself. You are also changed into the 
+            source (<glossterm><link linkend='var-S'>S</link></glossterm>) 
+            directory automatically. When finished with the shell just exit it
+            or close the terminal window.
+        </para>
+
+        <para>
+            The default shell used by devshell is the gnome-terminal. Other 
+            forms of terminal can also be used by setting the <glossterm>
+            <link linkend='var-TERMCMD'>TERMCMD</link></glossterm> and <glossterm>
+            <link linkend='var-TERMCMDRUN'>TERMCMDRUN</link></glossterm> variables 
+            in local.conf. For examples of the other options available, see 
+            <filename>meta/conf/bitbake.conf</filename>. An external shell is 
+            launched rather than opening directly into the original terminal 
+            window to make interaction with bitbakes multiple threads easier 
+            and also allow a client/server split of bitbake in the future 
+            (devshell will still work over X11 forwarding or similar).
+        </para>
+
+        <para>
+            It is worth remembering that inside devshell you need to use the full
+            compiler name such as <command>arm-poky-linux-gnueabi-gcc</command> 
+            instead of just <command>gcc</command> and the same applies to other 
+            applications from gcc, bintuils, libtool etc. Poky will have setup 
+            environmental variables such as CC to assist applications, such as make,
+            find the correct tools.
+        </para>
+
+    </section>
+
+    <section id="platdev-appdev-srcrev">
+        <title>Developing within Poky with an external SCM based package</title>
+
+        <para>
+            If you're working on a recipe which pulls from an external SCM it 
+            is possible to have Poky notice new changes added to the 
+            SCM and then build the latest version. This only works for SCMs
+            where its possible to get a sensible revision number for changes.
+            Currently it works for svn, git and bzr repositories.
+        </para>
+
+        <para>
+            To enable this behaviour it is simply a case of adding <glossterm>
+            <link linkend='var-SRCREV'>SRCREV</link></glossterm>_pn-<glossterm>
+            <link linkend='var-PN'>PN</link></glossterm> = "${AUTOREV}" to 
+            local.conf where <glossterm><link linkend='var-PN'>PN</link></glossterm> 
+            is the name of the package for which you want to enable automatic source 
+            revision updating.
+        </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>
+
+