<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >

<chapter id="platdev">
<title>Platform Development with the Yocto Project</title>

    <section id="platdev-appdev">
    <title>Application Development Using the Yocto Project</title>
    <para>
        The Yocto Project supports several methods of application development through which 
        you can create user-space software designed to run on an embedded device that uses
        a Yocto Project image, which was developed with the OpenEmbedded build system. 
        This flexibility allows you to choose the method that works best for you.  
        This chapter describes each development method.
    </para>

        <section id="platdev-appdev-devshell">
        <title>Development Within a Development Shell</title>

        <para>
            When debugging certain commands or even when just editing packages, 
            <filename>devshell</filename> can be a useful tool.
            Using <filename>devshell</filename> differs from the example shown in the previous 
            section in that when you invoke <filename>devshell</filename> source files are 
            extracted into your working directory and patches are applied. 
            Then, a new terminal is opened and you are placed in the working directory.
            In the new terminal, all the OpenEmbedded build-related environment variables are 
            still defined so you can use commands such as <filename>configure</filename> and 
            <filename>make</filename>. 
            The commands execute just as if the OpenEmbedded build system were executing them. 
            Consequently, working this way can be helpful when debugging a build or preparing 
            software to be used with the OpenEmbedded build system.
        </para>

        <para>
            Following is an example that uses <filename>devshell</filename> on a target named
            <filename>matchbox-desktop</filename>:
        </para>

        <para>
            <literallayout class='monospaced'>
     $ bitbake matchbox-desktop -c devshell
            </literallayout>
        </para>

        <para>
            This command opens a terminal with a shell prompt within the Yocto Project 
            environment. 
            The following occurs:
            <itemizedlist>
                <listitem><para>The <filename>PATH</filename> variable includes the 
                    cross-toolchain.</para></listitem>
                <listitem><para>The <filename>pkgconfig</filename> variables find the correct 
                    <filename>.pc</filename> files.</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>
            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.
            As noted earlier, the working directory also automatically changes to the 
            source directory (<filename><link linkend='var-S'>S</link></filename>).
        </para>

        <para> 
            When you are finished, you just exit the shell or close the terminal window.
        </para>

        <para>
            The default shell used by <filename>devshell</filename> is xterm. 
            For examples of available options, see the "UI/Interaction Configuration"
            section of the  
            <filename>meta/conf/bitbake.conf</filename> configuration file in the 
            <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>source directory</ulink>. 
        </para>

        <para>
            Because an external shell is launched rather than opening directly into the 
            original terminal window, it allows easier interaction with BitBake's multiple
            threads as well as accomodates a future client/server split.
        </para>

        <note>
            <para>It is worth remembering that when using <filename>devshell</filename>
            you need to use the full compiler name such as <filename>arm-poky-linux-gnueabi-gcc</filename> 
            instead of just using <filename>gcc</filename>.
            The same applies to other applications such as <filename>binutils</filename>, 
            <filename>libtool</filename> and so forth.
            BitBake sets up environment variables such as <filename>CC</filename>
            to assist applications, such as <filename>make</filename> to find the correct tools.</para>
            <para>It is also worth noting that <filename>devshell</filename> still works over
            X11 forwarding and similar situations</para>
        </note>
        </section>

        <section id="platdev-appdev-srcrev">
        <title>Development Within Yocto Project for a Package that Uses an External SCM</title>

        <para>
            If you're working on a recipe that pulls from an external Source Code Manager (SCM), it 
            is possible to have the OpenEmbedded build system notice new changes added to the 
            SCM and then build the package that depends on them using the latest version. 
            This only works for SCMs from which it is possible to get a sensible revision number for changes.
            Currently, you can do this with Apache Subversion (SVN), Git, and Bazaar (BZR) repositories.
        </para>

        <para>
            To enable this behavior, simply add the following to the <filename>local.conf</filename>
            configuration file found in the 
            <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>build directory</ulink>:
            <literallayout class='monospaced'>
     SRCREV_pn-&lt;PN&gt; = "${AUTOREV}"
            </literallayout>
            where <filename>PN</filename> 
            is the name of the package for which you want to enable automatic source 
            revision updating.
        </para>
        </section>
    </section>
</chapter> 
<!-- 
vim: expandtab tw=80 ts=4 
-->
