path: root/documentation/sdk-manual/sdk-using.xml

<!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='sdk-using-the-standard-sdk'>

<title>Using the Standard SDK</title>

<para>
    This chapter describes the standard SDK and how to use it.
    Information covers the pieces of the SDK, how to install it, and presents
    several task-based procedures common for developing with a standard SDK.
    <note>
        The tasks you can perform using a standard SDK are also applicable
        when you are using an extensible SDK.
        For information on the differences when using an extensible SDK as
        compared to an extensible SDK, see the
        "<link linkend='sdk-extensible'>Using the Extensible SDK</link>"
        chapter.
    </note>
</para>

<section id='sdk-standard-sdk-intro'>
    <title>Why use the Standard SDK and What is in It?</title>

    <para role='writernotes'>
        <emphasis>MANUAL DEVELOPMENT NOTES:</emphasis>
        This paragraph describes why you use the Standard SDK.
        Probably need to compare that against why you would not be interested
        in the extensible SDK here as well.
        According to Paul, the most interest lies in the extensible SDK.
        So providing this comparison would be helpful.
        Currently, my understanding boils down to this: The only reason to use
        the Standard SDK is if you want to build and debug source code that
        you have.
        That pretty much sums it up.
        If there is more detail, I need to know about it.
    </para>

    <para role='writernotes'>
        <emphasis>MANUAL DEVELOPMENT NOTES:</emphasis>
        Here is a list of items I think need addressed in these early
        sections:
        <itemizedlist>
            <listitem><para role='writernotes'><emphasis>What is your situation?</emphasis></para>
                <para role='writernotes'>In other words, is the developer on a machine that
                has YP on it?
                Are they on a machine that does not?
                Is the image they are developing against available as a
                pre-built, down-loadable image and can they get it?</para>
                <para role='writernotes'>Depending on the scenario, there are different ways
                to make sure the machine they are using is ready to use a
                standard SDK.
                I think we need to cover the various situations in this
                section.
                </para></listitem>
            <listitem><para role='writernotes'><emphasis>What are the recommendations?</emphasis></para>
                <para role='writernotes'>What is the most common development scenario?
                Is there a recommended development flow we want to present
                when using a standard SDK?
                What conditions in a development scenario warrant use of
                just the standard SDK as compared to the extensible SDK?
                </para></listitem>
            <listitem><para role='writernotes'><emphasis>What procedures do we want to cover to set up
                the standard SDK?</emphasis></para>
                <para role='writernotes'>There is a ton of setup information in the
                current ADT manual regarding getting, building, and installing
                an SDK.
                We would ignore the stuff about the ADT installer script
                since I presume that is going away.
                But, there are steps to download and existing
                <filename>.sh</filename> install script, build out the
                toolchains assuming your system has YP on it and you can run
                BitBake, getting the root filesystem, getting an image so you
                run QEMU on your system, etc.
                </para></listitem>
        </itemizedlist>
    </para>

    <para>
        The installed Standard SDK consists of several files and directories.
        Basically, it contains an SDK environment setup script, some
        configuration files, and host and target root filesystems to support
        usage.
        You can see the directory structure in the
        "<link linkend='sdk-installed-standard-sdk-directory-structure'>Installed Standard SDK Directory Structure</link>"
        section.
        <note>
            You can also find information on how the Yocto Project
            OpenEmbedded build system creates an SDK image by looking at the
            "<ulink url='&YOCTO_DOCS_REF_URL;#sdk-generation-dev-environment'>SDK Generation</ulink>"
            section in the Yocto Project Reference Manual.
        </note>
    </para>
</section>

<section id='sdk-installing-the-sdk'>
    <title>Installing the SDK</title>

    <para>
        The first thing you need to do is install the SDK on your host
        development machine by running the <filename>.sh</filename>
        installation script.
    </para>

    <para>
        You can download a tarball installer, which includes the
        pre-built toolchain, the <filename>runqemu</filename>
        script, and support files from the appropriate directory under
        <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'></ulink>.
        Toolchains are available for 32-bit and 64-bit x86 development
        systems from the <filename>i686</filename> and
        <filename>x86_64</filename> directories, respectively.
        The toolchains the Yocto Project provides are based off the
        <filename>core-image-sato</filename> image and contain
        libraries appropriate for developing against that image.
        Each type of development system supports five or more target
        architectures.
    </para>

    <para>
        The names of the tarball installer scripts are such that a
        string representing the host system appears first in the
        filename and then is immediately followed by a string
        representing the target architecture.
        <literallayout class='monospaced'>
     poky-glibc-<replaceable>host_system</replaceable>-<replaceable>image_type</replaceable>-<replaceable>arch</replaceable>-toolchain-<replaceable>release_version</replaceable>.sh

     Where:
         <replaceable>host_system</replaceable> is a string representing your development system:

                    i686 or x86_64.

         <replaceable>image_type</replaceable> is a string representing the image you wish to
                develop a SDK for use against. The Yocto Project builds
                installers for standard SDKs using the following BitBake
                command:

                    bitbake core-image-sato -c populate_sdk

         <replaceable>arch</replaceable> is a string representing the tuned target architecture:

                    i586, x86_64, powerpc, mips, armv7a or armv5te

         <replaceable>release_version</replaceable> is a string representing the release number of the
                Yocto Project:

                    &DISTRO;, &DISTRO;+snapshot
        </literallayout>
        For example, the following toolchain installer is for a 64-bit
        development host system and a i586-tuned target architecture
        based off the SDK for <filename>core-image-sato</filename> and
        using the current &DISTRO; snapshot:
        <literallayout class='monospaced'>
     poky-glibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh
        </literallayout>
    </para>

    <para>
        The SDK and toolchains are self-contained and by default are installed
        into <filename>/opt/poky</filename>.
        However, when you run the SDK installer, you can choose an
        installation directory.
    </para>

    <para>
        The following command shows how to run the installer given a
        toolchain tarball for a 64-bit x86 development host system and
        a 32-bit x86 target architecture.
        When you run the installer, the script prompts you for a
        system password so that you permissions can change enabling
        you to run the installer script.
        The example assumes the toolchain installer is located in
        <filename>~/Downloads/</filename>.
        <note>
            If you do not have write permissions for the directory
            into which you are installing the SDK, the installer
            notifies you and exits.
            Be sure you have write permissions in the directory and
            run the installer again.
        </note>
        <literallayout class='monospaced'>
     $ ~/Downloads/poky-glibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh
     Poky (Yocto Project Reference Distro) SDK installer version 2.1+snapshot
     ========================================================================
     Enter target directory for SDK (default: /opt/poky/2.1+snapshot):
     You are about to install the SDK to "/opt/poky/2.1+snapshot". Proceed[Y/n]? Y
     [sudo] password for scottrif:
     Extracting SDK.......................done
     Setting it up...done
     SDK has been successfully set up and is ready to be used.
     Each time you wish to use the SDK in a new shell session, you need to source the environment setup script e.g.
      $ . /opt/poky/2.1+snapshot/environment-setup-i586-poky-linux
        </literallayout>
    </para>

    <para>
        Again, reference the
        "<link linkend='sdk-installed-standard-sdk-directory-structure'>Installed Standard SDK Directory Structure</link>"
        section for more details on the resulting directory structure of
        the installed SDK.
    </para>
</section>

<section id='sdk-running-the-sdk-environment-setup-script'>
    <title>Running the SDK Environment Setup Script</title>

    <para>
        Once you have the SDK installed, you must run the SDK environment
        setup script before you can actually use it.
        This setup script resides in the directory you chose when you installed
        the SDK.
        For information on where this setup script can reside, see the
        "<link linkend='sdk-appendix-obtain'>Obtaining the SDK</link>"
        Appendix.
    </para>

    <para>
        Before running the script, be sure it is the one that matches the
        architecture for which you are developing.
        Environment setup scripts begin with the string
        "<filename>environment-setup</filename>" and include as part of their
        name the tuned target architecture.
        For example, the setup script for an IA-based target machine using
        i586 tuning and located in the default SDK installation
        directory is as follows:
        <literallayout class='monospaced'>
     $ source /opt/poky/&DISTRO;+snapshot/environment-setup-i586-poky-linux
        </literallayout>
        When you run the setup script, many environment variables are
        defined:
        <literallayout class='monospaced'>
     <ulink url='&YOCTO_DOCS_REF_URL;#var-SDKTARGETSYSROOT'><filename>SDKTARGETSYSROOT</filename></ulink> - The path to the sysroot used for cross-compilation
     <ulink url='&YOCTO_DOCS_REF_URL;#var-PKG_CONFIG_PATH'><filename>PKG_CONFIG_PATH</filename></ulink> - The path to the target pkg-config files
     <ulink url='&YOCTO_DOCS_REF_URL;#var-CONFIG_SITE'><filename>CONFIG_SITE</filename></ulink> - A GNU autoconf site file preconfigured for the target
     <ulink url='&YOCTO_DOCS_REF_URL;#var-CC'><filename>CC</filename></ulink> - The minimal command and arguments to run the C compiler
     <ulink url='&YOCTO_DOCS_REF_URL;#var-CXX'><filename>CXX</filename></ulink> - The minimal command and arguments to run the C++ compiler
     <ulink url='&YOCTO_DOCS_REF_URL;#var-CPP'><filename>CPP</filename></ulink> - The minimal command and arguments to run the C preprocessor
     <ulink url='&YOCTO_DOCS_REF_URL;#var-AS'><filename>AS</filename></ulink> - The minimal command and arguments to run the assembler
     <ulink url='&YOCTO_DOCS_REF_URL;#var-LD'><filename>LD</filename></ulink> - The minimal command and arguments to run the linker
     <ulink url='&YOCTO_DOCS_REF_URL;#var-GDB'><filename>GDB</filename></ulink> - The minimal command and arguments to run the GNU Debugger
     <ulink url='&YOCTO_DOCS_REF_URL;#var-STRIP'><filename>STRIP</filename></ulink> - The minimal command and arguments to run 'strip', which strips symbols
     <ulink url='&YOCTO_DOCS_REF_URL;#var-RANLIB'><filename>RANLIB</filename></ulink> - The minimal command and arguments to run 'ranlib'
     <ulink url='&YOCTO_DOCS_REF_URL;#var-OBJCOPY'><filename>OBJCOPY</filename></ulink> - The minimal command and arguments to run 'objcopy'
     <ulink url='&YOCTO_DOCS_REF_URL;#var-OBJDUMP'><filename>OBJDUMP</filename></ulink> - The minimal command and arguments to run 'objdump'
     <ulink url='&YOCTO_DOCS_REF_URL;#var-AR'><filename>AR</filename></ulink> - The minimal command and arguments to run 'ar'
     <ulink url='&YOCTO_DOCS_REF_URL;#var-NM'><filename>NM</filename></ulink> - The minimal command and arguments to run 'nm'
     <ulink url='&YOCTO_DOCS_REF_URL;#var-TARGET_PREFIX'><filename>TARGET_PREFIX</filename></ulink> - The toolchain binary prefix for the target tools
     <ulink url='&YOCTO_DOCS_REF_URL;#var-CROSS_COMPILE'><filename>CROSS_COMPILE</filename></ulink> - The toolchain binary prefix for the target tools
     <ulink url='&YOCTO_DOCS_REF_URL;#var-CONFIGURE_FLAGS'><filename>CONFIGURE_FLAGS</filename></ulink> - The minimal arguments for GNU configure
     <ulink url='&YOCTO_DOCS_REF_URL;#var-CFLAGS'><filename>CFLAGS</filename></ulink> - Suggested C flags
     <ulink url='&YOCTO_DOCS_REF_URL;#var-CXXFLAGS'><filename>CXXFLAGS</filename></ulink> - Suggested C++ flags
     <ulink url='&YOCTO_DOCS_REF_URL;#var-LDFLAGS'><filename>LDFLAGS</filename></ulink> - Suggested linker flags when you use CC to link
     <ulink url='&YOCTO_DOCS_REF_URL;#var-CPPFLAGS'><filename>CPPFLAGS</filename></ulink> - Suggested preprocessor flags
        </literallayout>
    </para>
</section>

<section id='sdk-using-the-sdk-to-task-1'>
    <title>Using the SDK to <replaceable>item 1</replaceable></title>

    <para role='writernotes'>
        Describe the specific task you are going to accomplish with the SDK.
        Provide a diagram showing the rough flow of the task.
        Provide specific steps using a real example that works through the
        task.
    </para>
</section>

<section id='sdk-using-the-sdk-to-task-2'>
    <title>Using the SDK to <replaceable>item-2</replaceable></title>

    <para role='writernotes'>
        Describe the specific task you are going to accomplish with the SDK.
        Provide a diagram showing the rough flow of the task.
        Provide specific steps using a real example that works through the
        task.
    </para>
</section>

<section id='sdk-using-the-sdk-to-task-3'>
    <title>Using the SDK to <replaceable>item-3</replaceable></title>

    <para role='writernotes'>
        Describe the specific task you are going to accomplish with the SDK.
        Provide a diagram showing the rough flow of the task.
        Provide specific steps using a real example that works through the
        task.
    </para>
</section>

<section id='sdk-using-the-sdk-to-task-x'>
    <title>Using the SDK to <replaceable>item-x</replaceable></title>

    <para role='writernotes'>
        Describe the specific task you are going to accomplish with the SDK.
        Provide a diagram showing the rough flow of the task.
        Provide specific steps using a real example that works through the
        task.
    </para>
</section>

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