agl-basesystem

1 files changed, 564 insertions, 0 deletions

diff --git a/external/poky/documentation/brief-yoctoprojectqs/brief-yoctoprojectqs.xml b/external/poky/documentation/brief-yoctoprojectqs/brief-yoctoprojectqs.xml
new file mode 100644
index 00000000..f261deed
--- /dev/null
+++ b/external/poky/documentation/brief-yoctoprojectqs/brief-yoctoprojectqs.xml
@@ -0,0 +1,564 @@
+<!DOCTYPE article 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; ] >
+
+<article id='brief-yocto-project-qs-intro'>
+    <articleinfo>
+        <title>Yocto Project Quick Build</title>
+
+        <copyright>
+            <year>&COPYRIGHT_YEAR;</year>
+            <holder>Linux Foundation</holder>
+        </copyright>
+
+        <legalnotice>
+            <para>
+                Permission is granted to copy, distribute and/or modify this document under
+                the terms of the <ulink type="http" url="http://creativecommons.org/licenses/by-sa/2.0/uk/">Creative Commons Attribution-Share Alike 2.0 UK: England &amp; Wales</ulink> as published by Creative Commons.
+            </para>
+        </legalnotice>
+
+
+        <abstract>
+            <imagedata fileref="figures/yocto-project-transp.png"
+                        width="6in" depth="1in"
+                        align="right" scale="25" />
+        </abstract>
+    </articleinfo>
+
+    <section id='brief-welcome'>
+        <title>Welcome!</title>
+
+        <para>
+            Welcome!
+            This short document steps you through the process for a typical
+            image build using the Yocto Project.
+            The document also introduces how to configure a build for specific
+            hardware.
+            You will use Yocto Project to build a reference embedded OS
+            called Poky.
+            <note><title>Notes</title>
+                <itemizedlist>
+                    <listitem><para>
+                        The examples in this paper assume you are using a
+                        native Linux system running a recent Ubuntu Linux
+                        distribution.
+                        If the machine you want to use Yocto Project on to
+                        build an image
+                        (<ulink url='&YOCTO_DOCS_REF_URL;#hardware-build-system-term'>build host</ulink>)
+                        is not a native Linux system, you can
+                        still perform these steps by using CROss PlatformS
+                        (CROPS) and setting up a Poky container.
+                        See the
+                        <ulink url='&YOCTO_DOCS_DEV_URL;#setting-up-to-use-crops'>Setting Up to Use CROss PlatformS (CROPS)</ulink>"
+                        section in the Yocto Project Development Tasks Manual for more
+                        information.
+                        </para></listitem>
+                    <listitem><para>
+                        You cannot use a build host that is using the
+                        <ulink url='https://en.wikipedia.org/wiki/Windows_Subsystem_for_Linux'>Windows Subsystem for Linux</ulink>
+                        (WSL).
+                        The Yocto Project is not compatible with WSL.
+                        </para></listitem>
+                </itemizedlist>
+            </note>
+        </para>
+
+        <para>
+            If you want more conceptual or background information on the
+            Yocto Project, see the
+            <ulink url='&YOCTO_DOCS_OM_URL;'>Yocto Project Overview and Concepts Manual</ulink>.
+        </para>
+    </section>
+
+    <section id='brief-compatible-distro'>
+        <title>Compatible Linux Distribution</title>
+
+        <para>
+            Make sure your
+            <ulink url='&YOCTO_DOCS_REF_URL;#hardware-build-system-term'>build host</ulink>
+            meets the following requirements:
+            <itemizedlist>
+                <listitem><para>
+                    50 Gbytes of free disk space
+                    </para></listitem>
+                <listitem><para>
+                    Runs a supported Linux distribution (i.e. recent releases of
+                    Fedora, openSUSE, CentOS, Debian, or Ubuntu). For a list of
+                    Linux distributions that support the Yocto Project, see the
+                    "<ulink url='&YOCTO_DOCS_REF_URL;#detailed-supported-distros'>Supported Linux Distributions</ulink>"
+                    section in the Yocto Project Reference Manual.
+                    For detailed information on preparing your build host, see
+                    the
+                    "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-preparing-the-build-host'>Preparing the Build Host</ulink>"
+                    section in the Yocto Project Development Tasks Manual.
+                    </para></listitem>
+                <listitem><para>
+                    <itemizedlist>
+                        <listitem><para>
+                            Git 1.8.3.1 or greater
+                            </para></listitem>
+                        <listitem><para>
+                            tar 1.27 or greater
+                            </para></listitem>
+                        <listitem><para>
+                            Python 3.4.0 or greater.
+                            </para></listitem>
+                    </itemizedlist>
+                    If your build host does not meet any of these three listed
+                    version requirements, you can take steps to prepare the
+                    system so that you can still use the Yocto Project.
+                    See the
+                    "<ulink url='&YOCTO_DOCS_REF_URL;#required-git-tar-and-python-versions'>Required Git, tar, and Python Versions</ulink>"
+                    section in the Yocto Project Reference Manual for information.
+                    </para></listitem>
+            </itemizedlist>
+        </para>
+    </section>
+
+    <section id='brief-build-system-packages'>
+        <title>Build Host Packages</title>
+
+        <para>
+            You must install essential host packages on your
+            build host.
+            The following command installs the host packages based on an
+            Ubuntu distribution:
+            <note>
+                For host package requirements on all supported Linux
+                distributions, see the
+                "<ulink url='&YOCTO_DOCS_REF_URL;#required-packages-for-the-build-host'>Required Packages for the Build Host</ulink>"
+                section in the Yocto Project Reference Manual.
+            </note>
+            <literallayout class='monospaced'>
+     $ sudo apt-get install &UBUNTU_HOST_PACKAGES_ESSENTIAL; libsdl1.2-dev xterm
+            </literallayout>
+        </para>
+    </section>
+
+    <section id='brief-use-git-to-clone-poky'>
+        <title>Use Git to Clone Poky</title>
+
+        <para>
+            Once you complete the setup instructions for your machine,
+            you need to get a copy of the Poky repository on your build
+            host.
+            Use the following commands to clone the Poky
+            repository.
+            <literallayout class='monospaced'>
+     $ git clone git://git.yoctoproject.org/poky
+     Cloning into 'poky'...
+     remote: Counting objects: 445141, done.
+     remote: Compressing objects: 100% (105214/105214), done.
+     remote: Total 445141 (delta 333098), reused 444745 (delta 332720)
+     Receiving objects: 100% (445141/445141), 156.60 MiB | 5.13 MiB/s, done.
+     Resolving deltas: 100% (333098/333098), done.
+     Checking connectivity... done.
+            </literallayout>
+            Move to the <filename>poky</filename> directory and take a look
+            at the tags:
+            <literallayout class='monospaced'>
+     $ cd poky
+     $ git fetch --tags
+     $ git tag
+     1.1_M1.final
+     1.1_M1.rc1
+     1.1_M1.rc2
+     1.1_M2.final
+     1.1_M2.rc1
+        .
+        .
+        .
+     yocto-2.5
+     yocto-2.5.1
+     yocto-2.5.2
+     yocto-2.5.3
+     yocto-2.6
+     yocto-2.6.1
+     yocto-2.6.2
+     yocto-2.6.3
+     yocto-2.7
+     yocto_1.5_M5.rc8
+            </literallayout>
+            For this example, check out the branch based on the
+            &DISTRO_REL_TAG; release:
+            <literallayout class='monospaced'>
+     $ git checkout tags/&DISTRO_REL_TAG; -b my-&DISTRO_REL_TAG;
+     Switched to a new branch 'my-&DISTRO_REL_TAG;'
+            </literallayout>
+            The previous Git checkout command creates a local branch
+            named my-&DISTRO_REL_TAG;. The files available to you in that
+            branch exactly match the repository's files in the
+            "&DISTRO_NAME_NO_CAP;" development branch at the time of the
+            Yocto Project &DISTRO_REL_TAG; release.
+        </para>
+
+        <para>
+            For more options and information about accessing Yocto
+            Project related repositories, see the
+            "<ulink url='&YOCTO_DOCS_DEV_URL;#locating-yocto-project-source-files'>Locating Yocto Project Source Files</ulink>"
+            section in the Yocto Project Development Tasks Manual.
+        </para>
+    </section>
+
+    <section id='brief-building-your-image'>
+        <title>Building Your Image</title>
+
+        <para>
+            Use the following steps to build your image.
+            The build process creates an entire Linux distribution, including
+            the toolchain, from source.
+            <note>
+                <itemizedlist>
+                    <listitem><para>
+                        If you are working behind a firewall and your build
+                        host is not set up for proxies, you could encounter
+                        problems with the build process when fetching source
+                        code (e.g. fetcher failures or Git failures).
+                        </para></listitem>
+                    <listitem><para>
+                        If you do not know your proxy settings, consult your
+                        local network infrastructure resources and get that
+                        information.
+                        A good starting point could also be to check your
+                        web browser settings.
+                        Finally, you can find more information on the
+                        "<ulink url='https://wiki.yoctoproject.org/wiki/Working_Behind_a_Network_Proxy'>Working Behind a Network Proxy</ulink>"
+                        page of the Yocto Project Wiki.
+                        </para></listitem>
+                </itemizedlist>
+            </note>
+        </para>
+
+        <para>
+            <orderedlist>
+                <listitem><para>
+                    <emphasis>Initialize the Build Environment:</emphasis>
+                    From within the <filename>poky</filename> directory, run the
+                    <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
+                    environment setup script to define Yocto Project's
+                    build environment on your build host.
+                    <literallayout class='monospaced'>
+     $ cd ~/poky
+     $ source &OE_INIT_FILE;
+     You had no conf/local.conf file. This configuration file has therefore been
+     created for you with some default values. You may wish to edit it to, for
+     example, select a different MACHINE (target hardware). See conf/local.conf
+     for more information as common configuration options are commented.
+
+     You had no conf/bblayers.conf file. This configuration file has therefore been
+     created for you with some default values. To add additional metadata layers
+     into your configuration please add entries to conf/bblayers.conf.
+
+     The Yocto Project has extensive documentation about OE including a reference
+     manual which can be found at:
+         http://yoctoproject.org/documentation
+
+     For more information about OpenEmbedded see their website:
+         http://www.openembedded.org/
+
+
+     ### Shell environment set up for builds. ###
+
+     You can now run 'bitbake &lt;target&gt;'
+
+     Common targets are:
+         core-image-minimal
+         core-image-sato
+         meta-toolchain
+         meta-ide-support
+
+     You can also run generated qemu images with a command like 'runqemu qemux86'
+                    </literallayout>
+                    Among other things, the script creates the
+                    <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>,
+                    which is <filename>build</filename> in this case
+                    and is located in the
+                    <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>.
+                    After the script runs, your current working directory
+                    is set to the Build Directory.
+                    Later, when the build completes, the Build Directory
+                    contains all the files created during the build.
+                    </para></listitem>
+                <listitem><para id='conf-file-step'>
+                    <emphasis>Examine Your Local Configuration File:</emphasis>
+                    When you set up the build environment, a local
+                    configuration file named
+                    <filename>local.conf</filename> becomes available in
+                    a <filename>conf</filename> subdirectory of the
+                    Build Directory.
+                    For this example, the defaults are set to build
+                    for a <filename>qemux86</filename> target, which is
+                    suitable for emulation.
+                    The package manager used is set to the RPM package
+                    manager.
+                    <tip>
+                        You can significantly speed up your build and guard
+                        against fetcher failures by using mirrors.
+                        To use mirrors, add these lines to your
+                        <filename>local.conf</filename> file in the Build
+                        directory:
+                        <literallayout class='monospaced'>
+     SSTATE_MIRRORS = "\
+     file://.* http://sstate.yoctoproject.org/dev/PATH;downloadfilename=PATH \n \
+     file://.* http://sstate.yoctoproject.org/&YOCTO_DOC_VERSION_MINUS_ONE;/PATH;downloadfilename=PATH \n \
+     file://.* http://sstate.yoctoproject.org/&YOCTO_DOC_VERSION;/PATH;downloadfilename=PATH \n \
+     "
+                        </literallayout>
+                        The previous examples showed how to add sstate
+                        paths for Yocto Project &YOCTO_DOC_VERSION_MINUS_ONE;,
+                        &YOCTO_DOC_VERSION;, and a development area.
+                        For a complete index of sstate locations, see
+                        <ulink url='http://sstate.yoctoproject.org/'></ulink>.
+                    </tip>
+                    </para></listitem>
+                <listitem><para>
+                    <emphasis>Start the Build:</emphasis>
+                    Continue with the following command to build an OS image
+                    for the target, which is
+                    <filename>core-image-sato</filename> in this example:
+                    <literallayout class='monospaced'>
+     $ bitbake core-image-sato
+                    </literallayout>
+                    For information on using the
+                    <filename>bitbake</filename> command, see the
+                    "<ulink url='&YOCTO_DOCS_OM_URL;#usingpoky-components-bitbake'>BitBake</ulink>"
+                    section in the Yocto Project Overview and Concepts Manual,
+                    or see the
+                    "<ulink url='&YOCTO_DOCS_BB_URL;#bitbake-user-manual-command'>BitBake Command</ulink>"
+                    section in the BitBake User Manual.
+                    </para></listitem>
+                <listitem><para>
+                    <emphasis>Simulate Your Image Using QEMU:</emphasis>
+                    Once this particular image is built, you can start
+                    QEMU, which is a Quick EMUlator that ships with
+                    the Yocto Project:
+                    <literallayout class='monospaced'>
+     $ runqemu qemux86
+                    </literallayout>
+                    If you want to learn more about running QEMU, see the
+                    "<ulink url="&YOCTO_DOCS_DEV_URL;#dev-manual-qemu">Using the Quick EMUlator (QEMU)</ulink>"
+                    chapter in the Yocto Project Development Tasks Manual.
+                    </para></listitem>
+                <listitem><para>
+                    <emphasis>Exit QEMU:</emphasis>
+                    Exit QEMU by either clicking on the shutdown icon or by
+                    typing <filename>Ctrl-C</filename> in the QEMU
+                    transcript window from which you evoked QEMU.
+                    </para></listitem>
+            </orderedlist>
+        </para>
+    </section>
+
+    <section id='customizing-your-build-for-specific-hardware'>
+        <title>Customizing Your Build for Specific Hardware</title>
+
+        <para>
+            So far, all you have done is quickly built an image suitable
+            for emulation only.
+            This section shows you how to customize your build for specific
+            hardware by adding a hardware layer into the Yocto Project
+            development environment.
+        </para>
+
+        <para>
+            In general, layers are repositories that contain related sets of
+            instructions and configurations that tell the Yocto Project what
+            to do.
+            Isolating related metadata into functionally specific layers
+            facilitates modular development and makes it easier to reuse the
+            layer metadata.
+            <note>
+                By convention, layer names start with the string "meta-".
+            </note>
+        </para>
+
+        <para>
+            Follow these steps to add a hardware layer:
+            <orderedlist>
+                <listitem><para>
+                    <emphasis>Find a Layer:</emphasis>
+                    Lots of hardware layers exist.
+                    The Yocto Project
+                    <ulink url='&YOCTO_GIT_URL;'>Source Repositories</ulink>
+                    has many hardware layers.
+                    This example adds the
+                    <ulink url='https://github.com/kraj/meta-altera'>meta-altera</ulink>
+                    hardware layer.
+                    </para></listitem>
+                <listitem><para>
+                    <emphasis>Clone the Layer</emphasis>
+                    Use Git to make a local copy of the layer on your machine.
+                    You can put the copy in the top level of the copy of the
+                    Poky repository created earlier:
+                    <literallayout class='monospaced'>
+     $ git clone https://github.com/kraj/meta-altera.git
+     Cloning into 'meta-altera'...
+     remote: Enumerating objects: 219, done.
+     remote: Counting objects: 100% (219/219), done.
+     remote: Compressing objects: 100% (116/116), done.
+     remote: Total 1463 (delta 111), reused 172 (delta 79), pack-reused 1244
+     Receiving objects: 100% (1463/1463), 211.60 KiB | 0 bytes/s, done.
+     Resolving deltas: 100% (706/706), done.
+     Checking connectivity... done.                    </literallayout>
+                    The hardware layer now exists with other layers inside
+                    the Poky reference repository on your build host as
+                    <filename>meta-altera</filename> and contains all the
+                    metadata needed to support hardware from Altera, which
+                    is owned by Intel.
+                    </para></listitem>
+                <listitem><para>
+                    <emphasis>Change the Configuration to Build for a Specific Machine:</emphasis>
+                    The
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
+                    variable in the <filename>local.conf</filename> file
+                    specifies the machine for the build.
+                    For this example, set the <filename>MACHINE</filename>
+                    variable to "cyclone5".
+                    These configurations are used:
+                    <ulink url='https://github.com/kraj/meta-altera/blob/master/conf/machine/cyclone5.conf'></ulink>.
+                    <note>
+                        See the
+                        "<link linkend='conf-file-step'>Examine Your Local Configuration File</link>"
+                        step earlier for more information on configuring the
+                        build.
+                    </note>
+                    </para></listitem>
+                <listitem><para>
+                    <emphasis>Add Your Layer to the Layer Configuration File:</emphasis>
+                    Before you can use a layer during a build, you must add it
+                    to your <filename>bblayers.conf</filename> file, which
+                    is found in the
+                    <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory's</ulink>
+                    <filename>conf</filename> directory.</para>
+
+                    <para>Use the <filename>bitbake-layers add-layer</filename>
+                    command to add the layer to the configuration file:
+                    <literallayout class='monospaced'>
+     $ cd ~/poky/build
+     $ bitbake-layers add-layer ../meta-altera
+     NOTE: Starting bitbake server...
+                    </literallayout>
+                    You can find more information on adding layers in the
+                    "<ulink url='&YOCTO_DOCS_DEV_URL;#adding-a-layer-using-the-bitbake-layers-script'>Adding a Layer Using the <filename>bitbake-layers</filename> Script</ulink>"
+                    section.
+                    </para></listitem>
+            </orderedlist>
+            Completing these steps has added the
+            <filename>meta-altera</filename> layer to your Yocto Project
+            development environment and configured it to build for the
+            "cyclone5" machine.
+            <note>
+                The previous steps are for demonstration purposes only.
+                If you were to attempt to build an image for the
+                "cyclone5" build, you should read the Altera
+                <filename>README</filename>.
+            </note>
+        </para>
+    </section>
+
+    <section id='creating-your-own-general-layer'>
+        <title>Creating Your Own General Layer</title>
+
+        <para>
+            Maybe you have an application or specific set of behaviors you
+            need to isolate.
+            You can create your own general layer using the
+            <filename>bitbake-layers create-layer</filename> command.
+            The tool automates layer creation by setting up a
+            subdirectory with a <filename>layer.conf</filename>
+            configuration file, a <filename>recipes-example</filename>
+            subdirectory that contains an <filename>example.bb</filename>
+            recipe, a licensing file, and a <filename>README</filename>.
+        </para>
+
+        <para>
+            The following commands run the tool to create a layer named
+            <filename>meta-mylayer</filename> in the
+            <filename>poky</filename> directory:
+            <literallayout class='monospaced'>
+     $ cd ~/poky
+     $ bitbake-layers create-layer meta-mylayer
+     NOTE: Starting bitbake server...
+     Add your new layer with 'bitbake-layers add-layer meta-mylayer'
+            </literallayout>
+            For more information on layers and how to create them, see the
+            "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-general-layer-using-the-bitbake-layers-script'>Creating a General Layer Using the <filename>bitbake-layers</filename> Script</ulink>"
+            section in the Yocto Project Development Tasks Manual.
+        </para>
+    </section>
+
+    <section id='brief-where-to-go-next'>
+        <title>Where To Go Next</title>
+
+        <para>
+            Now that you have experienced using the Yocto Project, you might
+            be asking yourself "What now?"
+            The Yocto Project has many sources of information including
+            the website, wiki pages, and user manuals:
+            <itemizedlist>
+                <listitem><para>
+                    <emphasis>Website:</emphasis>
+                    The
+                    <ulink url='&YOCTO_HOME_URL;'>Yocto Project Website</ulink>
+                    provides background information, the latest builds,
+                    breaking news, full development documentation, and
+                    access to a rich Yocto Project Development Community
+                    into which you can tap.
+                    </para></listitem>
+                <listitem><para>
+                    <emphasis>Developer Screencast:</emphasis>
+                    The
+                    <ulink url='http://vimeo.com/36450321'>Getting Started with the Yocto Project - New Developer Screencast Tutorial</ulink>
+                    provides a 30-minute video created for users unfamiliar
+                    with the Yocto Project but familiar with Linux build
+                    hosts.
+                    While this screencast is somewhat dated, the
+                    introductory and fundamental concepts are useful for
+                    the beginner.
+                    </para></listitem>
+                <listitem><para>
+                    <emphasis>Yocto Project Overview and Concepts Manual:</emphasis>
+                    The
+                    <ulink url='&YOCTO_DOCS_OM_URL;'>Yocto Project Overview and Concepts Manual</ulink>
+                    is a great place to start to learn about the
+                    Yocto Project.
+                    This manual introduces you to the Yocto Project and its
+                    development environment.
+                    The manual also provides conceptual information for
+                    various aspects of the Yocto Project.
+                    </para></listitem>
+                <listitem><para>
+                    <emphasis>Yocto Project Wiki:</emphasis>
+                    The
+                    <ulink url='&YOCTO_WIKI_URL;'>Yocto Project Wiki</ulink>
+                    provides additional information on where to go next
+                    when ramping up with the Yocto Project, release
+                    information, project planning, and QA information.
+                    </para></listitem>
+                <listitem><para>
+                    <emphasis>Yocto Project Mailing Lists:</emphasis>
+                    Related mailing lists provide a forum for discussion,
+                    patch submission and announcements.
+                    Several mailing lists exist and are grouped according
+                    to areas of concern.
+                    See the
+                    "<ulink url='&YOCTO_DOCS_REF_URL;#resources-mailinglist'>Mailing lists</ulink>"
+                    section in the Yocto Project Reference Manual for a
+                    complete list of Yocto Project mailing lists.
+                    </para></listitem>
+                <listitem><para>
+                    <emphasis>Comprehensive List of Links and Other Documentation:</emphasis>
+                    The
+                    "<ulink url='&YOCTO_DOCS_REF_URL;#resources-links-and-related-documentation'>Links and Related Documentation</ulink>"
+                    section in the Yocto Project Reference Manual provides a
+                    comprehensive list of all related links and other
+                    user documentation.
+                    </para></listitem>
+            </itemizedlist>
+        </para>
+    </section>
+</article>
+<!--
+vim: expandtab tw=80 ts=4
+-->