diff options
Diffstat (limited to 'import-layers/yocto-poky/documentation/brief-yoctoprojectqs/brief-yoctoprojectqs.xml')
| -rw-r--r-- | import-layers/yocto-poky/documentation/brief-yoctoprojectqs/brief-yoctoprojectqs.xml | 491 |
1 files changed, 491 insertions, 0 deletions
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 000000000..62c4964f5 --- /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 +--> |
