path: root/handbook/development.xml

<!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-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>
<!-- DISBALED, TOO BIG!
        <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 it's development
            headers and the Anjuta plugin. The Poky Anjuta plugin is available to download as a tarball at the
            <ulink url='http://labs.o-hand.com/sources/anjuta-plugin-sdk/'>OpenedHand labs</ulink> page or
            directly from the Poky Git repository located at git://git.pokylinux.org/anjuta-poky; a web interface
            to the repository can be accessed at <ulink url='http://git.pokylinux.org/cgit.cgi/anjuta-poky/'/>.
        </para>
        <para>
            See the README file contained in the project for more information on dependencies and building
            the plugin. It's recommended you enable the experimental gdb integration by passing configure the
            --enable-gdb-integration switch.
        </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>
<!-- DISBALED, TOO BIG!
        <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>
            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