Yocto 2.5
Move OpenBMC to Yocto 2.5(sumo)
Signed-off-by: Brad Bishop <bradleyb@fuzziesquirrel.com>
Change-Id: I5c5ad6904a16e14c1c397f0baf10c9d465594a78
diff --git a/import-layers/yocto-poky/documentation/brief-yoctoprojectqs/brief-yoctoprojectqs.xml b/import-layers/yocto-poky/documentation/brief-yoctoprojectqs/brief-yoctoprojectqs.xml
new file mode 100644
index 0000000..62c4964f
--- /dev/null
+++ b/import-layers/yocto-poky/documentation/brief-yoctoprojectqs/brief-yoctoprojectqs.xml
@@ -0,0 +1,491 @@
+<!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>©RIGHT_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 & 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>
+ 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 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.
+ </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.
+ </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-host-development-system'>Required Packages for the Host Development System</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 and then checkout the &DISTRO_REL_TAG; release:
+ <literallayout class='monospaced'>
+ $ git clone git://git.yoctoproject.org/poky
+ Cloning into 'poky'...
+ remote: Counting objects: 361782, done.
+ remote: Compressing objects: 100% (87100/87100), done.
+ remote: Total 361782 (delta 268619), reused 361439 (delta 268277)
+ Receiving objects: 100% (361782/361782), 131.94 MiB | 6.88 MiB/s, done.
+ Resolving deltas: 100% (268619/268619), done.
+ Checking connectivity... done.
+ $ git checkout tags/yocto-2.5 -b my-yocto-2.5
+ </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; 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>
+ 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'>
+ $ source &OE_INIT_FILE;
+ </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'>
+ $ cd ~/poky
+ $ git clone https://github.com/kraj/meta-altera.git
+ Cloning into 'meta-altera'...
+ remote: Counting objects: 25170, done.
+ remote: Compressing objects: 100% (350/350), done.
+ remote: Total 25170 (delta 645), reused 719 (delta 538), pack-reused 24219
+ Receiving objects: 100% (25170/25170), 41.02 MiB | 1.64 MiB/s, done.
+ Resolving deltas: 100% (13385/13385), 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...
+ Parsing recipes: 100% |##################################################################| Time: 0:00:32
+ Parsing of 918 .bb files complete (0 cached, 918 parsed). 1401 targets, 123 skipped, 0 masked, 0 errors.
+ </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
+-->