<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

<chapter id='adt-prepare'>

<title>Preparing to Use the Application Development Toolkit (ADT)</title>

<para>
    In order to use the ADT it must be installed, the environment setup script must be 
    sourced, and the kernel and filesystem image specific to the target architecture must exist.  
    This section describes how to install the ADT, set up the environment, and provides 
    some reference information on kernels and filesystem images.
</para>

<section id='installing-the-adt'>
    <title>Installing the ADT</title>
    <para>
        You can install the ADT three ways.  
        However, we recommend configuring and running the ADT Installer script.  
        Running this script automates much of the process for you.  
        For example, the script allows you to install the QEMU emulator and 
        user-space NFS, define which root filesystem profiles to download, 
        and allows you to define the target sysroot location.
    </para>
    <note>
        If you need to generate the ADT tarball you can do so using the following command:
        <literallayout class='monospaced'>
     $ bitbake adt-installer
        </literallayout>
        This command generates the file <filename>adt-installer.tar.bz2</filename>
        in the <filename>../build/tmp/deploy/sdk</filename> directory.
    </note>

    <section id='configuring-and-running-the-adt-installer'>
        <title>Configuring and Running the ADT Installer</title>
        <para>
            The ADT Installer is contained in a tarball that can be built using 
            <filename>bitbake adt-installer</filename>. 
            Yocto Project has a pre-built ADT Installer tarball that you can download 
            from <filename>tmp/deploy/sdk</filename> located in the build directory.
        </para>

        <note>
            You can install and run the ADT Installer tarball in any directory you want.
        </note>

        <para>
            Before running the ADT Installer you need to configure it by editing 
            the <filename>adt-installer.conf</filename> file, which is located in the 
            directory where the ADT Installer tarball was installed.  
            Your configurations determine which kernel and filesystem image are downloaded.  
            The following list describes the variables you can define for the ADT Installer.  
            For configuration values and restrictions see the comments in  
            the <filename>adt-installer.conf</filename> file:

            <itemizedlist>
                <listitem><para><filename>YOCTOADT_IPKG_REPO</filename> – This area 
                includes the IPKG-based packages and the root filesystem upon which 
                the installation is based.  
                If you want to set up your own IPKG repository pointed to by 
                <filename>YOCTOADT_IPKG_REPO</filename>, you need to be sure that the 
                directory structure follows the same layout as the reference directory 
                set up at <ulink url='http://adtrepo.yoctoproject.org'></ulink>.  
                Also, your repository needs to be accessible through HTTP.
                </para></listitem>
                <listitem><para><filename>YOCTOADT-TARGETS</filename> – The machine 
                target architectures for which you want to set up cross-development 
                environments.
                </para></listitem>
                <listitem><para><filename>YOCTOADT_QEMU</filename> – Indicates whether 
                or not to install the emulator QEMU.
                </para></listitem>
                <listitem><para><filename>YOCTOADT_NFS_UTIL</filename> – Indicates whether 
                or not to install user-mode NFS.  
                If you plan to use the Yocto Eclipse IDE plug-in against QEMU, 
                you should install NFS.
                    <note>
                    To boot QEMU images using our userspace NFS server, you need 
                    to be running portmap or rpcbind. 
                    If you are running rpcbind, you will also need to add the -i 
                    option when rpcbind starts up. 
                    Please make sure you understand the security implications of doing this. 
                    Your firewall settings may also have to be modified to allow 
                    NFS booting to work.
                    </note>
                </para></listitem>
                <listitem><para><filename>YOCTOADT_ROOTFS_&lt;arch&gt;</filename> - The root 
                filesystem images you want to download.
                </para></listitem>
                <listitem><para><filename>YOCTOADT_TARGET_SYSROOT_IMAGE_&lt;arch&gt;</filename> - The 
                root filesystem used to extract and create the target sysroot.
                </para></listitem>
                <listitem><para><filename>YOCTOADT_TARGET_SYSROOT_LOC_&lt;arch&gt;</filename> - The 
                location of the target sysroot that will be set up on the development machine.
                </para></listitem>
            </itemizedlist>
        </para>

        <para>
            After you have configured the <filename>adt-installer.conf</filename> file, 
            run the installer using the following command:
            <literallayout class='monospaced'>
     $ adt_installer
            </literallayout>
        </para>

        <para>
            Once the installer begins to run you are asked whether you want to run in 
            interactive or silent mode.  
            If you want to closely monitor the installation then choose “I” for interactive 
            mode rather than “S” for silent mode.  
            Follow the prompts from the script to complete the installation.
        </para>

        <para>
            Once the installation completes, the cross-toolchain is installed in 
            <filename>/opt/poky/$SDKVERSION</filename>.
        </para>

        <para>
            Before using the ADT you need to run the environment setup script for 
            your target architecture also located in <filename>/opt/poky/$SDKVERSION</filename>.
            See the <xref linkend='setting-up-the-environment'>“Setting Up the Environment”</xref> 
            section for information.
        </para>
    </section>

    <section id='using-an-existing-toolchain-tarball'>
        <title>Using an Existing Toolchain Tarball</title>
        <para>
            If you do not want to use the ADT Installer you can install the toolchain 
            and the sysroot by hand.  
            Follow these steps:
            <orderedlist>
                <listitem><para>Locate and download the architecture-specific toolchain 
                tarball from <ulink url='http://autobuilder.yoctoproject.org/downloads/yocto-1.0'></ulink>.
                Look in the ‘toolchain’ folder and then open up the folder that matches your 
                host development system (i.e. 'i686' for 32-bit machines or 'x86_64' 
                for 64-bit machines).  
                Then, select the toolchain tarball whose name includes the appropriate 
                target architecture.
                <note>
                    If you need to build the toolchain tarball use the 
                    <filename>bitbake meta-toolchain</filename> command after you have 
                    sourced the poky-build-init script.  
                    The tarball will be located in the build directory at 
                    <filename>tmp/deploy/sdk</filename> after the build.
                </note>
                </para></listitem>
                <listitem><para>Make sure you are in the root directory and then expand 
                the tarball.  
                The tarball expands into the <filename>/opt/poky/$SDKVERSION</filename> directory.
                </para></listitem>
                <listitem><para>Set up the environment by sourcing the environment set up 
                script.  
                See the <xref linkend='setting-up-the-environment'>“Setting Up the Environment”</xref>
                for information.
                </para></listitem>
            </orderedlist>
        </para>
    </section>

    <section id='using-the-toolchain-from-within-the-build-tree'>
        <title>Using the Toolchain from Within the Build Tree</title>
        <para>
            A final way of accessing the toolchain is from the build tree.  
            The build tree can be set up to contain the architecture-specific cross toolchain.  
            To populate the build tree with the toolchain you need to run the following command:
            <literallayout class='monospaced'>  
     $ bitbake meta-ide-support
            </literallayout>
        </para>
 
        <para>
            Before running the command you need to be sure that the 
            <filename>conf/local.conf</filename> file in the build directory has 
            the desired architecture specified for the <filename>MACHINE</filename> 
            variable.
            See the <filename>local.conf</filename> file for a list of values you 
            can supply for this variable.  
            You can populate the build tree with the cross-toolchains for more 
            than a single architecture.  
            You just need to edit the <filename>local.conf</filename> file and re-run 
            the BitBake command.
        </para>

        <para>
            Once the build tree has the toolchain you need to source the environment 
            setup script so that you can run the cross-tools without having to locate them.  
            See the <xref linkend='setting-up-the-environment'>“Setting Up the Environment”</xref>
            for information.
        </para>
    </section>
</section>

<section id='setting-up-the-environment'>
    <title>Setting Up the Environment</title>
    <para>
        Before you can use the cross-toolchain you need to set up the environment by 
        sourcing the environment setup script.  
        If you used adt_installer or used an existing ADT tarball to install the ADT,
        then you can find this script in the <filename>/opt/poky/$SDKVERSION</filename>
        directory.  
        If you are using the ADT from a Poky build tree, then look in the build 
        directory in <filename>tmp</filename> for the setup script.
    </para>

    <para> 
        Be sure to run the environment setup script that matches the architecture for 
        which you are developing.  
        Environment setup scripts begin with the string “environment-setup” and include as 
        part of their name the architecture.  
        For example, the environment setup script for a 64-bit IA-based architecture would 
        be the following: 
        <literallayout class='monospaced'>
     /opt/poky/environment-setup-x86_64-poky-linux
        </literallayout>
    </para>
</section>

<section id='kernels-and-filesystem-images'>
    <title>Kernels and Filesystem Images</title>
    <para>
        You will need to have a kernel and filesystem image to boot using your 
        hardware or the QEMU emulator.  
        That means you either have to build them or know where to get them.  
        You can find lots of details on how to get or build images and kernels for your 
        architecture in the "Yocto Project Quick Start" found at 
        <ulink url='http://www.yoctoproject.org/docs/yocto-quick-start/yocto-project-qs.html'></ulink>.
        <note> 
            Yocto Project provides basic kernels and filesystem images for several 
            architectures (x86, x86-64, mips, powerpc, and arm) that can be used 
            unaltered in the QEMU emulator.  
            These kernels and filesystem images reside in the Yocto Project release 
            area - <ulink url='http://autobuilder.yoctoproject.org/downloads/yocto-1.0/'></ulink>
            and are ideal for experimentation within Yocto Project.
        </note>
    </para>
</section>

</chapter>
<!--
vim: expandtab tw=80 ts=4
-->
