| <!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; ] > |
| <!--SPDX-License-Identifier: CC-BY-2.0-UK--> |
| |
| <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><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 may use Windows Subsystem For Linux v2 to set up a build |
| host using Windows 10. |
| <note> |
| The Yocto Project is not compatible with WSLv1, it is |
| compatible but not officially supported nor validated |
| with WSLv2, if you still decide to use WSL please upgrade |
| to WSLv2. |
| </note> |
| See the |
| <ulink url='&YOCTO_DOCS_DEV_URL;#setting-up-to-use-wsl'>Setting Up to Use Windows Subsystem For Linux</ulink>" |
| section in the Yocto Project Development Tasks Manual for more |
| information. |
| </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.28 or greater |
| </para></listitem> |
| <listitem><para> |
| Python 3.5.0 or greater. |
| </para></listitem> |
| <listitem><para> |
| gcc 5.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-python-and-gcc-versions'>Required Git, tar, Python and gcc 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; |
| </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: 432160, done. |
| remote: Compressing objects: 100% (102056/102056), done. |
| remote: Total 432160 (delta 323116), reused 432037 (delta 323000) |
| Receiving objects: 100% (432160/432160), 153.81 MiB | 8.54 MiB/s, done. |
| Resolving deltas: 100% (323116/323116), 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.6 |
| yocto-2.6.1 |
| yocto-2.6.2 |
| 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 <target>' |
| |
| 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-64' |
| </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-64 |
| </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 |
| --> |