path: root/documentation/dev-manual/dev-manual-start.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='dev-manual-start'>

<title>Getting Started with the Yocto Project</title>

<para>
    This chapter introduces the Yocto Project and gives you an idea of what you need to get started.
    You can find enough information to set up your development host and build or use images for
    hardware supported by the Yocto Project by reading the
    <ulink url='&YOCTO_DOCS_QS_URL;'>Yocto Project Quick Start</ulink>.
</para>

<para>
    The remainder of this chapter summarizes what is in the Yocto Project Quick Start and provides
    some higher-level concepts you might want to consider.
</para>

<section id='introducing-the-yocto-project'>
    <title>Introducing the Yocto Project</title>

    <para>
        The Yocto Project is an open-source collaboration project focused on embedded Linux development.
        The project currently provides a build system that is
        referred to as the OpenEmbedded build system in the Yocto Project documentation.
        The Yocto Project provides various ancillary tools for the embedded developer
        and also features the Sato reference User Interface, which is optimized for
        stylus driven, low-resolution screens.
    </para>

    <para>
        You can use the OpenEmbedded build system, which uses
        BitBake to develop complete Linux
        images and associated user-space applications for architectures based
        on ARM, MIPS, PowerPC, x86 and x86-64.
        <note>
            By default, using the Yocto Project creates a Poky distribution.
            However, you can create your own distribution by providing key
            <link linkend='metadata'>Metadata</link>.
            See the "<link linkend='creating-your-own-distribution'>Creating Your Own Distribution</link>"
            section for more information.
        </note>
        While the Yocto Project does not provide a strict testing framework,
        it does provide or generate for you artifacts that let you perform target-level and
        emulated testing and debugging.
        Additionally, if you are an <trademark class='trade'>Eclipse</trademark>
        IDE user, you can install an Eclipse Yocto Plug-in to allow you to
        develop within that familiar environment.
    </para>
</section>

<section id='getting-setup'>
    <title>Getting Set Up</title>

    <para>
        Here is what you need to get set up to use the Yocto Project:
        <itemizedlist>
            <listitem><para><emphasis>Host System:</emphasis>  You should have a reasonably current
                Linux-based host system.
                You will have the best results with a recent release of Fedora,
                OpenSUSE, Debian, Ubuntu, or CentOS as these releases are frequently tested against the Yocto Project
                and officially supported.
                For a list of the distributions under validation and their status, see the
                "<ulink url='&YOCTO_DOCS_REF_URL;#detailed-supported-distros'>Supported Linux Distributions</ulink>" section
                in the Yocto Project Reference Manual and the wiki page at
                <ulink url='&YOCTO_WIKI_URL;/wiki/Distribution_Support'>Distribution Support</ulink>.</para>
                <para>
                You should also have about 100 gigabytes of free disk space for building images.
                </para></listitem>
            <listitem><para><emphasis>Packages:</emphasis>  The OpenEmbedded build system
                requires certain packages exist on your development system (e.g. Python 2.6 or 2.7).
                See "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Packages</ulink>"
                section in the Yocto Project Quick Start and the
                "<ulink url='&YOCTO_DOCS_REF_URL;#required-packages-for-the-host-development-system'>Required Packages for the Host Development System</ulink>"
                section in the Yocto Project Reference Manual for the exact
                package requirements and the installation commands to install
                them for the supported distributions.
                </para></listitem>
            <listitem id='local-yp-release'><para><emphasis>Yocto Project Release:</emphasis>
                You need a release of the Yocto Project.
                You set that up with a local <link linkend='source-directory'>Source Directory</link>
                one of two ways depending on whether you
                are going to contribute back into the Yocto Project or not.
                <note>
                    Regardless of the method you use, this manual refers to the resulting local
                    hierarchical set of files as the "Source Directory."
                </note>
                <itemizedlist>
                    <listitem><para><emphasis>Tarball Extraction:</emphasis>
                        If you are not going to contribute back into the Yocto
                        Project, you can simply go to the
                        <ulink url='&YOCTO_HOME_URL;'>Yocto Project Website</ulink>,
                        select the "Downloads" tab, and choose what you want.
                        Once you have the tarball, just extract it into a
                        directory of your choice.</para>
                        <para>For example, the following command extracts the
                        Yocto Project &DISTRO; release tarball
                        into the current working directory and sets up the local Source Directory
                        with a top-level folder named <filename>&YOCTO_POKY;</filename>:
                        <literallayout class='monospaced'>
     $ tar xfj &YOCTO_POKY_TARBALL;
                        </literallayout></para>
                        <para>This method does not produce a local Git repository.
                        Instead, you simply end up with a snapshot of the release.</para></listitem>
                    <listitem><para><emphasis>Git Repository Method:</emphasis>  If you are going to be contributing
                        back into the Yocto Project or you simply want to keep up
                        with the latest developments, you should use Git commands to set up a local
                        Git repository of the upstream <filename>poky</filename> source repository.
                        Doing so creates a repository with a complete history of changes and allows
                        you to easily submit your changes upstream to the project.
                        Because you clone the repository, you have access to all the Yocto Project development
                        branches and tag names used in the upstream repository.</para>
                        <note>You can view the Yocto Project Source Repositories at
                        <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink></note>
                        <para>The following transcript shows how to clone the <filename>poky</filename>
                        Git repository into the current working directory.
                        The command creates the local repository in a directory named <filename>poky</filename>.
                        For information on Git used within the Yocto Project, see the
                        "<link linkend='git'>Git</link>" section.
                        <literallayout class='monospaced'>
     $ git clone git://git.yoctoproject.org/poky
     Cloning into 'poky'...
     remote: Counting objects: 183981, done.
     remote: Compressing objects: 100% (47428/47428), done.
     remote: Total 183981 (delta 132271), reused 183703 (delta 132044)
     Receiving objects: 100% (183981/183981), 89.71 MiB | 2.93 MiB/s, done.
     Resolving deltas: 100% (132271/132271), done.
                        </literallayout></para>
                        <para>For another example of how to set up your own local Git repositories, see this
                        <ulink url='&YOCTO_WIKI_URL;/wiki/Transcript:_from_git_checkout_to_meta-intel_BSP'>
                        wiki page</ulink>, which describes how to create both <filename>poky</filename>
                        and <filename>meta-intel</filename> Git repositories.</para></listitem>
                </itemizedlist></para></listitem>
            <listitem id='local-kernel-files'><para><emphasis>Yocto Project Kernel:</emphasis>
                If you are going to be making modifications to a supported Yocto Project kernel, you
                need to establish local copies of the source.
                You can find Git repositories of supported Yocto Project Kernels organized under
                "Yocto Linux Kernel" in the Yocto Project Source Repositories at
                <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>.</para>
                <para>This setup can involve creating a bare clone of the Yocto Project kernel and then
                copying that cloned repository.
                You can create the bare clone and the copy of the bare clone anywhere you like.
                For simplicity, it is recommended that you create these structures outside of the
                Source Directory (usually <filename>poky</filename>).</para>
                <para>As an example, the following transcript shows how to create the bare clone
                of the <filename>linux-yocto-3.8</filename> kernel and then create a copy of
                that clone.
                <note>When you have a local Yocto Project kernel Git repository, you can
                reference that repository rather than the upstream Git repository as
                part of the <filename>clone</filename> command.
                Doing so can speed up the process.</note></para>
                <para>In the following example, the bare clone is named
                <filename>linux-yocto-3.8.git</filename>, while the
                copy is named <filename>my-linux-yocto-3.8-work</filename>:
                <literallayout class='monospaced'>
     $ git clone --bare git://git.yoctoproject.org/linux-yocto-3.8 linux-yocto-3.8.git
     Cloning into bare repository 'linux-yocto-3.8.git'...
     remote: Counting objects: 2847090, done.
     remote: Compressing objects: 100% (454675/454675), done.
     remote: Total 2847090 (delta 2386170), reused 2825793 (delta 2364886)
     Receiving objects: 100% (2847090/2847090), 603.19 MiB | 3.54 MiB/s, done.
     Resolving deltas: 100% (2386170/2386170), done.                </literallayout></para>
                <para>Now create a clone of the bare clone just created:
                <literallayout class='monospaced'>
     $ git clone linux-yocto-3.8.git my-linux-yocto-3.8-work
     Cloning into 'my-linux-yocto-3.8-work'...
     done.
                </literallayout></para></listitem>
            <listitem id='meta-yocto-kernel-extras-repo'><para><emphasis>
                The <filename>meta-yocto-kernel-extras</filename> Git Repository</emphasis>:
                The <filename>meta-yocto-kernel-extras</filename> Git repository contains Metadata needed
                only if you are modifying and building the kernel image.
                In particular, it contains the kernel BitBake append (<filename>.bbappend</filename>)
                files that you
                edit to point to your locally modified kernel source files and to build the kernel
                image.
                Pointing to these local files is much more efficient than requiring a download of the
                kernel's source files from upstream each time you make changes to the kernel.</para>
                <para>You can find the <filename>meta-yocto-kernel-extras</filename> Git Repository in the
                "Yocto Metadata Layers" area of the Yocto Project Source Repositories at
                <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>.
                It is good practice to create this Git repository inside the Source Directory.</para>
                <para>Following is an example that creates the <filename>meta-yocto-kernel-extras</filename> Git
                repository inside the Source Directory, which is named <filename>poky</filename>
                in this case:
                <literallayout class='monospaced'>
     $ cd ~/poky
     $ git clone git://git.yoctoproject.org/meta-yocto-kernel-extras meta-yocto-kernel-extras
     Cloning into 'meta-yocto-kernel-extras'...
     remote: Counting objects: 690, done.
     remote: Compressing objects: 100% (431/431), done.
     remote: Total 690 (delta 238), reused 690 (delta 238)
     Receiving objects: 100% (690/690), 532.60 KiB, done.
     Resolving deltas: 100% (238/238), done.                </literallayout></para></listitem>
           <listitem><para id='supported-board-support-packages-(bsps)'><emphasis>Supported Board
                Support Packages (BSPs):</emphasis>
                The Yocto Project provides a layer called <filename>meta-intel</filename> and
                it is maintained in its own separate Git repository.
                The <filename>meta-intel</filename> layer contains many supported
                <ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>.</para>
                <para>Similar considerations exist for setting up the <filename>meta-intel</filename>
                layer.
                You can get set up for BSP development one of two ways: tarball extraction or
                with a local Git repository.
                It is a good idea to use the same method that you used to set up the Source Directory.
                Regardless of the method you use, the Yocto Project uses the following BSP layer
                naming scheme:
                <literallayout class='monospaced'>
     meta-&lt;BSP_name&gt;
                </literallayout>
                where <filename>&lt;BSP_name&gt;</filename> is the recognized BSP name.
                Here are some examples:
                <literallayout class='monospaced'>
     meta-crownbay
     meta-emenlow
     meta-n450
                </literallayout>
                See the
                "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>"
                section in the Yocto Project Board Support Package (BSP) Developer's Guide for more
                information on BSP Layers.
                <itemizedlist>
                    <listitem><para><emphasis>Tarball Extraction:</emphasis>  You can download any released
                        BSP tarball from the same "Downloads" page of the
                        <ulink url='&YOCTO_HOME_URL;'>Yocto Project Website</ulink>
                        to get the Yocto Project release.
                        Once on the "Download" page, look for "BSP" under the
                        "Type" heading.</para>
                        <para>Once you have the tarball, just extract it into a directory of your choice.
                        Again, this method just produces a snapshot of the BSP layer in the form
                        of a hierarchical directory structure.</para></listitem>
                    <listitem><para><emphasis>Git Repository Method:</emphasis>  If you are working
                        with a local Git repository for your Source Directory, you should also use this method
                        to set up the <filename>meta-intel</filename> Git repository.
                        You can locate the <filename>meta-intel</filename> Git repository in the
                        "Yocto Metadata Layers" area of the Yocto Project Source Repositories at
                        <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>.</para>
                        <para>Typically, you set up the <filename>meta-intel</filename> Git repository inside
                        the Source Directory.
                        For example, the following transcript shows the steps to clone the
                        <filename>meta-intel</filename>
                        Git repository inside the local <filename>poky</filename> Git repository.
                        <literallayout class='monospaced'>
     $ cd ~/poky
     $ git clone git://git.yoctoproject.org/meta-intel.git
     Cloning into 'meta-intel'...
     remote: Counting objects: 6264, done.
     remote: Compressing objects: 100% (2135/2135), done.
     remote: Total 6264 (delta 3321), reused 6235 (delta 3293)
     Receiving objects: 100% (6264/6264), 2.17 MiB | 2.63 MiB/s, done.
     Resolving deltas: 100% (3321/3321), done.
                        </literallayout></para>
                        <para>The same
                        <ulink url='&YOCTO_WIKI_URL;/wiki/Transcript:_from_git_checkout_to_meta-intel_BSP'>
                        wiki page</ulink> referenced earlier covers how to
                        set up the <filename>meta-intel</filename> Git repository.</para></listitem>
                </itemizedlist></para></listitem>
            <listitem><para><emphasis>Eclipse Yocto Plug-in:</emphasis>  If you are developing
                applications using the Eclipse Integrated Development Environment (IDE),
                you will need this plug-in.
                See the
                "<link linkend='setting-up-the-eclipse-ide'>Setting up the Eclipse IDE</link>"
                section for more information.</para></listitem>
        </itemizedlist>
    </para>
</section>

<section id='building-images'>
    <title>Building Images</title>

    <para>
        The build process creates an entire Linux distribution, including the toolchain, from source.
        For more information on this topic, see the
        "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>"
        section in the Yocto Project Quick Start.
    </para>

    <para>
        The build process is as follows:
        <orderedlist>
            <listitem><para>Make sure you have set up the Source Directory described in the
                previous section.</para></listitem>
            <listitem><para>Initialize the build environment by sourcing a build environment
                script.</para></listitem>
            <listitem><para>Optionally ensure the <filename>conf/local.conf</filename> configuration file,
                which is found in the
                <link linkend='build-directory'>Build Directory</link>,
                is set up how you want it.
                This file defines many aspects of the build environment including
                the target machine architecture through the
                <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'>MACHINE</ulink></filename> variable,
                the development machine's processor use through the
                <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BB_NUMBER_THREADS'>BB_NUMBER_THREADS</ulink></filename> and
                <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKE'>PARALLEL_MAKE</ulink></filename> variables, and
                a centralized tarball download directory through the
                <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-DL_DIR'>DL_DIR</ulink></filename> variable.</para></listitem>
            <listitem><para>Build the image using the <filename>bitbake</filename> command.
                If you want information on BitBake, see the user manual included in the
                <filename>bitbake/doc/manual</filename> directory of the
                <link linkend='source-directory'>Source Directory</link>.</para></listitem>
            <listitem><para>Run the image either on the actual hardware or using the QEMU
                emulator.</para></listitem>
        </orderedlist>
    </para>
</section>

<section id='using-pre-built-binaries-and-qemu'>
    <title>Using Pre-Built Binaries and QEMU</title>

    <para>
        Another option you have to get started is to use pre-built binaries.
        The Yocto Project provides many types of binaries with each release.
        See the "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>"
        chapter in the Yocto Project Reference Manual
        for descriptions of the types of binaries that ship with a Yocto Project
        release.
    </para>

    <para>
        Using a pre-built binary is ideal for developing software applications to run on your
        target hardware.
        To do this, you need to be able to access the appropriate cross-toolchain tarball for
        the architecture on which you are developing.
        If you are using an SDK type image, the image ships with the complete toolchain native to
        the architecture.
        If you are not using an SDK type image, you need to separately download and
        install the stand-alone Yocto Project cross-toolchain tarball.
    </para>

    <para>
        Regardless of the type of image you are using, you need to download the pre-built kernel
        that you will boot in the QEMU emulator and then download and extract the target root
        filesystem for your target machine’s architecture.
        You can get architecture-specific binaries and file systems from
        <ulink url='&YOCTO_MACHINES_DL_URL;'>machines</ulink>.
        You can get installation scripts for stand-alone toolchains from
        <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'>toolchains</ulink>.
        Once you have all your files, you set up the environment to emulate the hardware
        by sourcing an environment setup script.
        Finally, you start the QEMU emulator.
        You can find details on all these steps in the
        "<ulink url='&YOCTO_DOCS_QS_URL;#using-pre-built'>Using Pre-Built Binaries and QEMU</ulink>"
        section of the Yocto Project Quick Start.
    </para>

    <para>
        Using QEMU to emulate your hardware can result in speed issues
        depending on the target and host architecture mix.
        For example, using the <filename>qemux86</filename> image in the emulator
        on an Intel-based 32-bit (x86) host machine is fast because the target and
        host architectures match.
        On the other hand, using the <filename>qemuarm</filename> image on the same Intel-based
        host can be slower.
        But, you still achieve faithful emulation of ARM-specific issues.
    </para>

    <para>
        To speed things up, the QEMU images support using <filename>distcc</filename>
        to call a cross-compiler outside the emulated system.
        If you used <filename>runqemu</filename> to start QEMU, and the
        <filename>distccd</filename> application is present on the host system, any
        BitBake cross-compiling toolchain available from the build system is automatically
        used from within QEMU simply by calling <filename>distcc</filename>.
        You can accomplish this by defining the cross-compiler variable
        (e.g. <filename>export CC="distcc"</filename>).
        Alternatively, if you are using a suitable SDK image or the appropriate
        stand-alone toolchain is present,
        the toolchain is also automatically used.
    </para>

    <note>
        Several mechanisms exist that let you connect to the system running on the
        QEMU emulator:
        <itemizedlist>
            <listitem><para>QEMU provides a framebuffer interface that makes standard
                consoles available.</para></listitem>
            <listitem><para>Generally, headless embedded devices have a serial port.
                If so, you can configure the operating system of the running image
                to use that port to run a console.
                The connection uses standard IP networking.</para></listitem>
            <listitem><para>SSH servers exist in some QEMU images.
                The <filename>core-image-sato</filename> QEMU image has a Dropbear secure
                shell (SSH) server that runs with the root password disabled.
                The <filename>core-image-basic</filename> and <filename>core-image-lsb</filename> QEMU images
                have OpenSSH instead of Dropbear.
                Including these SSH servers allow you to use standard <filename>ssh</filename> and
                <filename>scp</filename> commands.
                The <filename>core-image-minimal</filename> QEMU image, however, contains no SSH
                server.</para></listitem>
            <listitem><para>You can use a provided, user-space NFS server to boot the QEMU session
                using a local copy of the root filesystem on the host.
                In order to make this connection, you must extract a root filesystem tarball by using the
                <filename>runqemu-extract-sdk</filename> command.
                After running the command, you must then point the <filename>runqemu</filename>
                script to the extracted directory instead of a root filesystem image file.</para></listitem>
        </itemizedlist>
    </note>
</section>
</chapter>
<!--
vim: expandtab tw=80 ts=4
-->