| <!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='yocto-project-qs-intro'> |
| <articleinfo> |
| <title>Yocto Project Quick Start</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> |
| <note><title>Manual Notes</title> |
| <itemizedlist> |
| <listitem><para> |
| This version of the |
| <emphasis>Yocto Project Quick Start</emphasis> |
| is for the &YOCTO_DOC_VERSION; release of the |
| Yocto Project. |
| To be sure you have the latest version of the manual |
| for this release, use the manual from the |
| <ulink url='&YOCTO_HOME_URL;/documentation'>Yocto Project documentation page</ulink>. |
| </para></listitem> |
| <listitem><para> |
| For manuals associated with other releases of the Yocto |
| Project, go to the |
| <ulink url='&YOCTO_HOME_URL;/documentation'>Yocto Project documentation page</ulink> |
| and use the drop-down "Active Releases" button |
| and choose the manual associated with the desired |
| Yocto Project. |
| </para></listitem> |
| <listitem><para> |
| To report any inaccuracies or problems with this |
| manual, send an email to the Yocto Project |
| discussion group at |
| <filename>yocto@yoctoproject.com</filename> or log into |
| the freenode <filename>#yocto</filename> channel. |
| </para></listitem> |
| </itemizedlist> |
| </note> |
| </legalnotice> |
| |
| <abstract> |
| <imagedata fileref="figures/yocto-project-transp.png" |
| width="6in" depth="1in" |
| align="right" scale="25" /> |
| </abstract> |
| </articleinfo> |
| |
| <section id='welcome'> |
| <title>Welcome!</title> |
| <para> |
| Welcome to the Yocto Project! |
| The Yocto Project is an open-source collaboration project whose |
| focus is developers of embedded Linux systems. |
| Among other things, the Yocto Project uses a build host based |
| on the OpenEmbedded (OE) project, which uses the |
| <ulink url='&YOCTO_DOCS_REF_URL;#bitbake-term'>BitBake</ulink> |
| tool, to construct complete Linux images. |
| The BitBake and OE components combine together to form |
| a reference build host, historically known as |
| <ulink url='&YOCTO_DOCS_REF_URL;#poky'>Poky</ulink> |
| (<emphasis>Pah</emphasis>-kee). |
| </para> |
| |
| <para> |
| This quick start is written so that you can quickly get a |
| build host set up to use the Yocto Project and then build some |
| Linux images. |
| Rather than go into great detail about the Yocto Project and its |
| many capabilities, this quick start provides the minimal |
| information you need to try out the Yocto Project using either a |
| supported Linux build host or a build host set up to use |
| <ulink url='https://git.yoctoproject.org/cgit/cgit.cgi/crops/about/'>CROPS</ulink>, |
| which leverages |
| <ulink url='https://www.docker.com/'>Docker Containers</ulink>. |
| </para> |
| |
| <para> |
| Reading and using the quick start should result in you having a |
| basic understanding of what the Yocto Project is and how to use |
| some of its core components. |
| You will also have worked through steps to produce two images: |
| one that runs on the emulator (QEMU) and one that boots on actual |
| hardware (i.e. MinnowBoard Turbot). |
| The examples highlight the ease with which you can use the |
| Yocto Project to create images for multiple types of hardware. |
| </para> |
| |
| <para> |
| The following list directs you to key sections of this |
| quick start: |
| <itemizedlist> |
| <listitem><para> |
| <ulink url='http://www.yoctoproject.org/docs/2.4/yocto-project-qs/yocto-project-qs.html#yp-resources'>Setting Up to Use the Yocto Project</ulink> |
| </para></listitem> |
| <listitem><para> |
| <ulink url='http://www.yoctoproject.org/docs/2.4/yocto-project-qs/yocto-project-qs.html#building-an-image-for-emulation'>Building an Image for Emulation</ulink> |
| </para></listitem> |
| <listitem><para> |
| <ulink url='http://www.yoctoproject.org/docs/2.4/yocto-project-qs/yocto-project-qs.html#building-an-image-for-hardware'>Building an Image for Hardware</ulink> |
| </para></listitem> |
| </itemizedlist> |
| <!-- |
| <note> |
| If you do not have a system that runs Linux and you want to give |
| the Yocto Project a test run, you might consider using the Yocto |
| Project Build Appliance. |
| The Build Appliance allows you to build and boot a custom |
| embedded Linux image with the Yocto Project using a non-Linux |
| development system. |
| See the |
| <ulink url='https://www.yoctoproject.org/tools-resources/projects/build-appliance'>Yocto Project Build Appliance</ulink> |
| for more information. |
| </note> |
| --> |
| </para> |
| |
| <para> |
| For more detailed information on the Yocto Project, you can |
| reference these resources: |
| <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>Yocto Project Development Environment Overview:</emphasis> |
| The |
| "<ulink url='&YOCTO_DOCS_REF_URL;#yp-intro'>Introducing the Yocto Project Development Environment</ulink>" |
| section presents an overview of the Yocto Project |
| development environment. |
| </para></listitem> |
| <listitem><para> |
| <emphasis>FAQs:</emphasis> |
| Lists commonly asked Yocto Project questions and answers. |
| You can find two FAQs: |
| <ulink url='&YOCTO_WIKI_URL;/wiki/FAQ'>Yocto Project FAQ</ulink> |
| on a wiki, and the |
| "<ulink url='&YOCTO_DOCS_REF_URL;#faq'>FAQ</ulink>" |
| chapter in the Yocto Project Reference Manual. |
| </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>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 related links and documentation. |
| </para></listitem> |
| </itemizedlist> |
| </para> |
| </section> |
| |
| <section id='yp-resources'> |
| <title>Setting Up to Use the Yocto Project</title> |
| |
| <para> |
| Setting up to use the Yocto Project involves getting your build |
| host ready. |
| If you have a native Linux machine that runs a Yocto Project |
| supported distribution as described by the |
| "<ulink url='&YOCTO_DOCS_REF_URL;#detailed-supported-distros'>Supported Linux Distributions</ulink>" |
| section in the Yocto Project Reference Manual, you can prepare |
| that machine as your build host. |
| See the |
| "<link linkend='qs-native-linux-build-host'>Using a Native Linux Machine</link>" |
| section for more information. |
| </para> |
| |
| <para> |
| If you do not want to use the Yocto Project on a native Linux |
| machine, you can prepare your build host to use |
| <ulink url='https://git.yoctoproject.org/cgit/cgit.cgi/crops/about/'>CROPS</ulink>, |
| which leverages |
| <ulink url='https://www.docker.com/'>Docker Containers</ulink>. |
| You can set up a build host for Windows, Mac, and Linux |
| machines. |
| See the |
| "<link linkend='qs-crops-build-host'>Using CROPS and Containers</link>" |
| section for more information. |
| </para> |
| |
| <section id='qs-crops-build-host'> |
| <title>Using CROPS and Containers</title> |
| |
| <para> |
| Follow these steps to get your build host set up with a |
| Poky container that you can use to complete the build |
| examples further down in the Quick Start: |
| <orderedlist> |
| <listitem><para> |
| <emphasis>Set Up to use CROss PlatformS (CROPS):</emphasis> |
| Work through the first six steps of the procedure |
| in the |
| "<ulink url='&YOCTO_DOCS_DEV_URL;#setting-up-to-use-crops'>Setting Up to Use CROss PlatformS (CROPS)</ulink>" |
| section of the Yocto Project Development Tasks Manual. |
| </para></listitem> |
| <listitem><para> |
| <emphasis>Set Up the Poky Container to Use the Yocto Project:</emphasis> |
| Go to |
| <ulink url='https://github.com/crops/poky-container/blob/master/README.md'></ulink> |
| and follow the directions to set up the Poky container |
| on your build host.</para> |
| |
| <para>Once you complete the setup instructions for your |
| machine, you need to get a copy of the |
| <filename>poky</filename> repository on your build |
| host. |
| See the |
| "<link linkend='releases'>Yocto Project Release</link>" |
| section to continue. |
| </para></listitem> |
| </orderedlist> |
| </para> |
| </section> |
| |
| <section id='qs-native-linux-build-host'> |
| <title>Using a Native Linux Machine</title> |
| |
| <para> |
| The following list shows what you need in order to use a |
| Linux-based build host to use the Yocto Project to build images: |
| </para> |
| |
| <itemizedlist> |
| <listitem><para><emphasis>Build Host</emphasis> |
| A build host with a minimum of 50 Gbytes of free disk |
| space that is running a supported Linux distribution (i.e. |
| recent releases of Fedora, openSUSE, CentOS, Debian, or |
| Ubuntu). |
| </para></listitem> |
| <listitem><para><emphasis>Build Host Packages</emphasis> |
| Appropriate packages installed on the build host. |
| </para></listitem> |
| </itemizedlist> |
| |
| <section id='the-linux-distro'> |
| <title>The Linux Distribution</title> |
| |
| <para> |
| The Yocto Project team verifies each release against recent |
| versions of the most popular Linux distributions that |
| provide stable releases. |
| In general, if you have the current release minus one of the |
| following distributions, you should have no problems. |
| <itemizedlist> |
| <listitem><para> |
| Ubuntu |
| </para></listitem> |
| <listitem><para> |
| Fedora |
| </para></listitem> |
| <listitem><para> |
| openSUSE |
| </para></listitem> |
| <listitem><para> |
| CentOS |
| </para></listitem> |
| <listitem><para> |
| Debian |
| </para></listitem> |
| </itemizedlist> |
| For a more detailed list of 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> |
| |
| <para> |
| The OpenEmbedded build system should be able to run on any |
| modern distribution that has the following versions for |
| Git, tar, and Python. |
| <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> |
| </section> |
| |
| <section id='packages'> |
| <title>The Build Host Packages</title> |
| |
| <para> |
| Required build host packages vary depending on your |
| build machine and what you want to do with the Yocto Project. |
| For example, if you want to build an image that can run |
| on QEMU in graphical mode (a minimal, basic build |
| requirement), then the build host package requirements |
| are different than if you want to build an image on a headless |
| system or build out the Yocto Project documentation set. |
| </para> |
| |
| <para> |
| Collectively, the number of required packages is large |
| if you want to be able to cover all cases. |
| <note> |
| In general, you need to have root access and then install |
| the required packages. |
| Thus, the commands in the following section may or may |
| not work depending on whether or not your Linux |
| distribution has <filename>sudo</filename> installed. |
| </note> |
| </para> |
| |
| <para> |
| The following list shows the required packages needed to build |
| an image that runs on QEMU in graphical mode (e.g. essential |
| plus graphics support). |
| For lists of required packages for other scenarios, 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. |
| <itemizedlist> |
| <listitem><para><emphasis>Ubuntu and Debian</emphasis> |
| <literallayout class='monospaced'> |
| $ sudo apt-get install &UBUNTU_HOST_PACKAGES_ESSENTIAL; libsdl1.2-dev xterm |
| </literallayout> |
| </para></listitem> |
| <listitem><para><emphasis>Fedora</emphasis> |
| <literallayout class='monospaced'> |
| $ sudo dnf install &FEDORA_HOST_PACKAGES_ESSENTIAL; SDL-devel xterm |
| </literallayout> |
| </para></listitem> |
| <listitem><para><emphasis>OpenSUSE</emphasis> |
| <literallayout class='monospaced'> |
| $ sudo zypper install &OPENSUSE_HOST_PACKAGES_ESSENTIAL; libSDL-devel xterm |
| </literallayout> |
| </para></listitem> |
| <listitem><para><emphasis>CentOS</emphasis> |
| <literallayout class='monospaced'> |
| $ sudo yum install &CENTOS_HOST_PACKAGES_ESSENTIAL; SDL-devel xterm |
| </literallayout> |
| <note><title>Notes</title> |
| <itemizedlist> |
| <listitem><para> |
| Extra Packages for Enterprise Linux |
| (i.e. <filename>epel-release</filename>) |
| is a collection of packages from Fedora |
| built on RHEL/CentOS for easy installation |
| of packages not included in enterprise |
| Linux by default. |
| You need to install these packages |
| separately. |
| </para></listitem> |
| <listitem><para> |
| The <filename>makecache</filename> command |
| consumes additional Metadata from |
| <filename>epel-release</filename>. |
| </para></listitem> |
| </itemizedlist> |
| </note> |
| </para></listitem> |
| </itemizedlist> |
| </para> |
| </section> |
| |
| <para> |
| Once you complete the setup instructions for your |
| machine, you need to get a copy of the |
| <filename>poky</filename> repository on your build |
| host. |
| Continue with the |
| "<link linkend='releases'>Yocto Project Release</link>" |
| section. |
| </para> |
| </section> |
| |
| <section id='releases'> |
| <title>Yocto Project Release</title> |
| |
| <para> |
| Now that your build host has the right packages (native |
| Linux machine) or you have the Poky container set up |
| (CROPS), you need to get a copy of the Yocto Project. |
| It is recommended that you get the latest Yocto Project release |
| by setting up (cloning in |
| <ulink url='&YOCTO_DOCS_REF_URL;#git'>Git</ulink> terms) a |
| local copy of the <filename>poky</filename> Git repository on |
| your build host and then checking out the latest release. |
| Doing so allows you to easily update to newer Yocto Project |
| releases as well as contribute back to the Yocto Project. |
| </para> |
| |
| <para> |
| Here is an example from a native Linux machine that is |
| running Ubuntu. |
| <note> |
| If your build host is using a Poky container, you can |
| use the same Git commands. |
| </note> |
| The following example clones the <filename>poky</filename> |
| repository and then checks out the latest Yocto Project Release |
| by tag (i.e. <filename>&DISTRO_REL_TAG;</filename>): |
| <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/&DISTRO_REL_TAG; -b poky_&DISTRO; |
| </literallayout> |
| </para> |
| |
| <para> |
| The previous Git <filename>checkout</filename> command |
| creates a local branch named |
| <filename>poky_&DISTRO;</filename>. |
| The files available to you in that branch exactly match the |
| repository's files in the |
| <filename>&DISTRO_NAME_NO_CAP;</filename> |
| development branch at the time of the Yocto Project &DISTRO; |
| release. |
| <note> |
| Rather than checking out the entire development branch |
| of a release (i.e. the tip), which could be continuously |
| changing while you are doing your development, you would |
| check out a branch based on a release tag as shown in |
| the previous example. |
| Doing so provides you with an unchanging, stable set of |
| files. |
| </note> |
| </para> |
| |
| <para> |
| For more options and information about accessing Yocto |
| Project related repositories, see the |
| "<ulink url='&YOCTO_DOCS_DEV_URL;#working-with-yocto-project-source-files'>Working With Yocto Project Source Files</ulink>" |
| section in the Yocto Project Development Tasks Manual. |
| </para> |
| </section> |
| </section> |
| |
| <section id='qs-building-images'> |
| <title>Building Images</title> |
| |
| <para> |
| You are now ready to give the Yocto Project a try. |
| For this example, you will be using the command line to build |
| your images. |
| <note> |
| A graphical user interface to the Yocto Project is available |
| through |
| <ulink url='&YOCTO_DOCS_REF_URL;#toaster-term'>Toaster</ulink>. |
| See the |
| <ulink url='&YOCTO_DOCS_TOAST_URL;'>Toaster User Manual</ulink> |
| for more information. |
| </note> |
| </para> |
| |
| <para> |
| The remainder of this quick start steps you through the |
| following: |
| <itemizedlist> |
| <listitem><para> |
| Build a <filename>qemux86</filename> reference image |
| and run it in the QEMU emulator. |
| </para></listitem> |
| <listitem><para> |
| Easily change configurations so that you can quickly |
| create a second image that you can load onto bootable |
| media and actually boot target hardware. |
| This example uses the MinnowBoard |
| Turbot-compatible boards. |
| </para></listitem> |
| </itemizedlist> |
| <note> |
| The steps in the following two sections do not provide detail, |
| but rather provide minimal, working commands and examples |
| designed to just get you started. |
| For more details, see the appropriate manuals in the |
| <ulink url='&YOCTO_HOME_URL;/documentation'>Yocto Project manual set</ulink>. |
| </note> |
| </para> |
| |
| <section id='building-an-image-for-emulation'> |
| <title>Building an Image for Emulation</title> |
| |
| <para> |
| Use the following commands to build your image. |
| The OpenEmbedded build system creates an entire Linux |
| distribution, including the toolchain, from source. |
| <note><title>Notes about Network Proxies</title> |
| <itemizedlist> |
| <listitem><para> |
| By default, the build process searches for source |
| code using a pre-determined order through a set of |
| locations. |
| 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 using the |
| Yocto Project behind a firewall in the Yocto Project |
| Reference Manual |
| <ulink url='&YOCTO_DOCS_REF_URL;#how-does-the-yocto-project-obtain-source-code-and-will-it-work-behind-my-firewall-or-proxy-server'>FAQ</ulink> |
| and on the |
| "<ulink url='https://wiki.yoctoproject.org/wiki/Working_Behind_a_Network_Proxy'>Working Behind a Network Proxy</ulink>" |
| wiki page. |
| </para></listitem> |
| </itemizedlist> |
| </note> |
| </para> |
| |
| <para> |
| <orderedlist> |
| <listitem><para> |
| <emphasis>Be Sure Your Build Host is Set Up:</emphasis> |
| The steps to build an image in this section depend on |
| your build host being properly set up. |
| Be sure you have worked through the requirements |
| described in the |
| "<link linkend='yp-resources'>Setting Up to Use the Yocto Project</link>" |
| section. |
| </para></listitem> |
| <listitem><para> |
| <emphasis>Check Out Your Branch:</emphasis> |
| Be sure you are in the |
| <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink> |
| (e.g. <filename>poky</filename>) and then check out |
| the branch associated with the latest Yocto Project |
| Release: |
| <literallayout class='monospaced'> |
| $ cd ~/poky |
| $ git checkout -b &DISTRO_NAME_NO_CAP; origin/&DISTRO_NAME_NO_CAP; |
| </literallayout> |
| Git's <filename>checkout</filename> command checks out |
| the current Yocto Project release into a local branch |
| whose name matches the release (i.e. |
| <filename>&DISTRO_NAME_NO_CAP;</filename>). |
| The local branch tracks the upstream branch of the |
| same name. |
| Creating your own branch based on the released |
| branch ensures you are using the latest files for |
| that release. |
| </para></listitem> |
| <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 the OpenEmbedded |
| 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> |
| <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. |
| Before using BitBake to start the build, you can |
| look at this file and be sure your general |
| configurations are how you want them: |
| <itemizedlist> |
| <listitem><para> |
| To help conserve disk space during builds, |
| you can add the following statement to your |
| project's configuration file, which for this |
| example is |
| <filename>poky/build/conf/local.conf</filename>. |
| Adding this statement deletes the work |
| directory used for building a recipe once the |
| recipe is built. |
| <literallayout class='monospaced'> |
| INHERIT += "rm_work" |
| </literallayout> |
| </para></listitem> |
| <listitem><para> |
| By default, the target machine for the build is |
| <filename>qemux86</filename>, |
| which produces an image that can be used in |
| the QEMU emulator and is targeted at an |
| <trademark class='registered'>Intel</trademark> |
| 32-bit based architecture. |
| Further on in this example, this default is |
| easily changed through the |
| <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> |
| variable so that you can quickly |
| build an image for a different machine. |
| </para></listitem> |
| <listitem><para> |
| Another consideration before you build is the |
| package manager used when creating the image. |
| The default <filename>local.conf</filename> |
| file selects the RPM package manager. |
| You can control this configuration by using the |
| <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></ulink></filename> |
| variable.</para> |
| <para>Selection of the package manager is separate |
| from whether package management is used at runtime |
| in the target image.</para> |
| <para>For additional package manager selection |
| information, see the |
| "<ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-package'><filename>package.bbclass</filename></ulink>" |
| section in the Yocto Project Reference Manual. |
| </para></listitem> |
| </itemizedlist> |
| </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: |
| <note> |
| Depending on the number of processors and cores, the |
| amount of RAM, the speed of your Internet connection |
| and other factors, the build process could take |
| several hours the first time you run it. |
| Subsequent builds run much faster since parts of the |
| build are cached. |
| </note> |
| <literallayout class='monospaced'> |
| $ bitbake core-image-sato |
| </literallayout> |
| <note> |
| <para> |
| If you experience a build error due to resources |
| temporarily being unavailable and it appears you |
| should not be having this issue, it might be due |
| to the combination of a 4.3+ Linux kernel and |
| <filename>systemd</filename> version 228+ |
| (i.e. see this |
| <ulink url='http://unix.stackexchange.com/questions/253903/creating-threads-fails-with-resource-temporarily-unavailable-with-4-3-kernel'>link</ulink> |
| for information). |
| </para> |
| |
| <para> |
| To work around this issue, you can try either |
| of the following: |
| <itemizedlist> |
| <listitem><para> |
| Try the build again. |
| </para></listitem> |
| <listitem><para> |
| Modify the "DefaultTasksMax" |
| <filename>systemd</filename> parameter |
| by uncommenting it and setting it to |
| "infinity". |
| You can find this parameter in the |
| <filename>system.conf</filename> file |
| located in |
| <filename>/etc/systemd</filename> |
| on most systems. |
| </para></listitem> |
| </itemizedlist> |
| </para> |
| </note> |
| For information on using the |
| <filename>bitbake</filename> command, see the |
| "<ulink url='&YOCTO_DOCS_REF_URL;#usingpoky-components-bitbake'>BitBake</ulink>" |
| section in the Yocto Project Reference Manual, or see the |
| "<ulink url='&YOCTO_DOCS_BB_URL;#bitbake-user-manual-command'>BitBake Command</ulink>" |
| section in the BitBake User Manual. |
| For information on other targets, see the |
| "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>" |
| chapter in the Yocto Project Reference Manual. |
| </para></listitem> |
| <listitem><para> |
| <emphasis>Simulate Your Image Using QEMU:</emphasis> |
| Once this particular image is built, you can start QEMU |
| and run the image: |
| <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='building-an-image-for-hardware'> |
| <title>Building an Image for Hardware</title> |
| |
| <para id='qs-minnowboard-example'> |
| The following steps show how easy it is to set up to build an |
| image for a new machine. |
| These steps build an image for the MinnowBoard Turbot, which is |
| supported by the Yocto Project and the |
| <filename>meta-intel</filename> <filename>intel-corei7-64</filename> |
| and <filename>intel-core2-32</filename> Board Support Packages |
| (BSPs). |
| <note> |
| The MinnowBoard Turbot ships with 64-bit firmware. |
| If you want to use the board in 32-bit mode, you must |
| download the |
| <ulink url='http://firmware.intel.com/projects/minnowboard-max'>32-bit firmware</ulink>. |
| </note> |
| </para> |
| |
| <para> |
| <orderedlist> |
| <listitem><para> |
| <emphasis>Create a Local Copy of the |
| <filename>meta-intel</filename> Repository:</emphasis> |
| Building an image for the MinnowBoard Turbot requires |
| the |
| <filename>meta-intel</filename> layer. |
| Use the <filename>git clone</filename> command to create |
| a local copy of the repository inside your |
| <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>, |
| which is <filename>poky</filename> in this example: |
| <literallayout class='monospaced'> |
| $ cd $HOME/poky |
| $ git clone git://git.yoctoproject.org/meta-intel |
| Cloning into 'meta-intel'... |
| remote: Counting objects: 14039, done. |
| remote: Compressing objects: 100% (4471/4471), done. |
| remote: Total 14039 (delta 8130), reused 13837 (delta 7947) |
| Receiving objects: 100% (14039/14039), 4.27 MiB | 3.98 MiB/s, done. |
| Resolving deltas: 100% (8130/8130), done. |
| Checking connectivity... done. |
| </literallayout> |
| By default when you clone a Git repository, the |
| "master" branch is checked out. |
| Before you build your image that uses the |
| <filename>meta-intel</filename> layer, you must be |
| sure that both repositories |
| (<filename>meta-intel</filename> and |
| <filename>poky</filename>) are using the same releases. |
| Because you used the <filename>&DISTRO_REL_TAG;</filename> |
| tag when you checked out the <filename>poky</filename> |
| repository by tag, you should use a |
| <filename>meta-intel</filename> |
| tag that corresponds with the release you used for |
| <filename>poky</filename>. |
| Consequently, you need to checkout out the |
| "<filename>&METAINTELVERSION;-&DISTRO_NAME_NO_CAP;-&YOCTO_DOC_VERSION;</filename>" |
| branch after cloning <filename>meta-intel</filename>: |
| <literallayout class='monospaced'> |
| $ cd $HOME/poky/meta-intel |
| $ git checkout tags/&METAINTELVERSION;-&DISTRO_NAME_NO_CAP;-&YOCTO_DOC_VERSION; -b meta-intel-&DISTRO_NAME_NO_CAP;-&YOCTO_DOC_VERSION; |
| Switched to a new branch 'meta-intel-&DISTRO_NAME_NO_CAP;-&YOCTO_DOC_VERSION;' |
| </literallayout> |
| The previous Git <filename>checkout</filename> command |
| creates a local branch named |
| <filename>meta-intel-&DISTRO_NAME_NO_CAP;-&YOCTO_DOC_VERSION;</filename>. |
| You have the option to name your local branch whatever |
| you want by providing any name you like for |
| "meta-intel-&DISTRO_NAME_NO_CAP;-&YOCTO_DOC_VERSION;" |
| in the above example. |
| </para></listitem> |
| <listitem><para> |
| <emphasis>Configure the Build:</emphasis> |
| To configure the build, you edit the |
| <filename>bblayers.conf</filename> and |
| <filename>local.conf</filename> files, both of which are |
| located in the <filename>build/conf</filename> directory. |
| </para> |
| |
| <para>Here is a quick way to make the edits. |
| The first command uses the |
| <filename>bitbake-layers add-layer</filename> command |
| to add the <filename>meta-intel</filename> |
| layer, which contains the <filename>intel-core*</filename> |
| BSPs to the build. |
| The second command selects the BSP by setting the |
| <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> |
| variable. |
| <literallayout class='monospaced'> |
| $ cd $HOME/poky/build |
| $ bitbake-layers add-layer "$HOME/poky/meta-intel" |
| $ echo 'MACHINE = "intel-corei7-64"' >> conf/local.conf |
| </literallayout> |
| <note><title>Notes</title> |
| <para> |
| If you want a 64-bit build, use the following: |
| <literallayout class='monospaced'> |
| $ echo 'MACHINE = "intel-corei7-64"' >> conf/local.conf |
| </literallayout> |
| </para> |
| |
| <para> |
| If you want 32-bit images, use the following: |
| <literallayout class='monospaced'> |
| $ echo 'MACHINE = "intel-core2-32"' >> conf/local.conf |
| </literallayout> |
| </para> |
| </note> |
| </para></listitem> |
| <listitem><para> |
| <emphasis>Build an Image for MinnowBoard |
| Turbot:</emphasis> |
| The type of image you build depends on your goals. |
| For example, the previous build created a |
| <filename>core-image-sato</filename> image, which is an |
| image with Sato support. |
| It is possible to build many image types for the |
| MinnowBoard Turbot. |
| Some possibilities are <filename>core-image-base</filename>, |
| which is a console-only image. |
| Another choice could be a |
| <filename>core-image-full-cmdline</filename>, which is |
| another console-only image but has more full-features |
| Linux system functionality installed. |
| For types of images you can build using the Yocto |
| Project, see the |
| "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>" |
| chapter in the Yocto Project Reference Manual.</para> |
| <para>Because configuration changes are minimal to set up |
| for this second build, the OpenEmbedded build system can |
| re-use files from previous builds as much as possible. |
| Re-using files means this second build will be much faster |
| than an initial build. |
| For this example, the <filename>core-image-base</filename> |
| image is built: |
| <literallayout class='monospaced'> |
| $ bitbake core-image-base |
| </literallayout> |
| <note> |
| <para> |
| If you experience a build error due to resources |
| temporarily being unavailable and it appears you |
| should not be having this issue, it might be due |
| to the combination of a 4.3+ Linux kernel and |
| <filename>systemd</filename> version 228+ |
| (i.e. see this |
| <ulink url='http://unix.stackexchange.com/questions/253903/creating-threads-fails-with-resource-temporarily-unavailable-with-4-3-kernel'>link</ulink> |
| for information). |
| </para> |
| |
| <para> |
| To work around this issue, you can try either |
| of the following: |
| <itemizedlist> |
| <listitem><para> |
| Try the build again. |
| </para></listitem> |
| <listitem><para> |
| Modify the "DefaultTasksMax" |
| <filename>systemd</filename> parameter |
| by uncommenting it and setting it to |
| "infinity". |
| You can find this parameter in the |
| <filename>system.conf</filename> file |
| located in |
| <filename>/etc/systemd</filename> |
| on most systems. |
| </para></listitem> |
| </itemizedlist> |
| </para> |
| </note> |
| Once the build completes, the resulting console-only image |
| is located in the Build Directory here: |
| <literallayout class='monospaced'> |
| tmp/deploy/images/intel-corei7-64/core-image-base-intel-corei7-64.wic |
| </literallayout> |
| </para></listitem> |
| <listitem><para> |
| <emphasis>Write the Image:</emphasis> |
| You can write the image just built to a bootable media |
| (e.g. a USB key, SATA drive, SD card, etc.) using the |
| <filename>dd</filename> utility: |
| <literallayout class='monospaced'> |
| $ sudo dd if=tmp/deploy/images/intel-corei7-64/core-image-base-intel-corei7-64.wic of=TARGET_DEVICE |
| </literallayout> |
| In the previous command, the |
| <filename>TARGET_DEVICE</filename> is the device node in |
| the host machine (e.g. <filename>/dev/sdc</filename>, which |
| is most likely a USB stick, or |
| <filename>/dev/mmcblk0</filename>, which is most likely an |
| SD card). |
| </para></listitem> |
| <listitem><para> |
| <emphasis>Boot the Hardware:</emphasis> |
| With the boot device provisioned, you can insert the |
| media into the MinnowBoard Turbot and boot the hardware. |
| The board should automatically detect the media and boot to |
| the bootloader and subsequently the operating system. |
| </para> |
| |
| <para>If the board does not boot automatically, you can |
| boot it manually from the EFI shell as follows: |
| <literallayout class='monospaced'> |
| Shell> connect -r |
| Shell> map -r |
| Shell> fs0: |
| Shell> bootx64 |
| </literallayout> |
| <note> |
| For a 32-bit image use the following: |
| <literallayout class='monospaced'> |
| Shell> bootia32 |
| </literallayout> |
| </note> |
| </para></listitem> |
| </orderedlist> |
| </para> |
| </section> |
| </section> |
| |
| <section id='qs-next-steps'> |
| <title>Next Steps</title> |
| |
| <para> |
| If you completed all the steps in the previous section then |
| congratulations! |
| What now? |
| </para> |
| |
| <para> |
| Depending on what you primary interests are with the Yocto Project, |
| you could consider any of the following: |
| <itemizedlist> |
| <listitem><para> |
| <emphasis>Visit the Yocto Project Web Site:</emphasis> |
| The official |
| <ulink url='&YOCTO_HOME_URL;'>Yocto Project</ulink> |
| web site contains information on the entire project. |
| Visiting this site is a good way to familiarize yourself |
| with the overall project. |
| </para></listitem> |
| <listitem><para> |
| <emphasis>Look Through the |
| <ulink url='&YOCTO_DOCS_DEV_URL;#dev-manual-intro'>Yocto Project Development Tasks Manual</ulink>:</emphasis> |
| This manual contains procedural information grouped to |
| help you get set up, work with layers, customize images, |
| write new recipes, work with libraries, and use QEMU. |
| The information is task-based and spans the breadth of the |
| Yocto Project. |
| </para></listitem> |
| <listitem><para> |
| <emphasis>Look Through the |
| <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink> |
| manual:</emphasis> |
| This manual describes how to use both the |
| <ulink url='&YOCTO_DOCS_SDK_URL;#sdk-using-the-standard-sdk'>standard SDK</ulink> |
| and the |
| <ulink url='&YOCTO_DOCS_SDK_URL;#sdk-extensible'>extensible SDK</ulink>, |
| which are used primarily for application development. |
| This manual also provides example workflows |
| that use the popular <trademark class='trade'>Eclipse</trademark> |
| development environment and that use <filename>devtool</filename>. |
| See the |
| "<ulink url='&YOCTO_DOCS_SDK_URL;#workflow-using-eclipse'>Workflow using Eclipse™</ulink>" |
| and |
| "<ulink url='&YOCTO_DOCS_SDK_URL;#using-devtool-in-your-sdk-workflow'>Using <filename>devtool</filename> in your SDK Workflow</ulink>" |
| sections for more information. |
| </para></listitem> |
| <listitem><para> |
| <emphasis>Learn About Kernel Development:</emphasis> |
| If you want to see how to work with the kernel and |
| understand Yocto Linux kernels, see the |
| <ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#kernel-dev-intro'>Yocto Project Linux Kernel Development Manual</ulink>. |
| This manual provides information on how to patch the |
| kernel, modify kernel recipes, and configure the kernel. |
| </para></listitem> |
| <listitem><para> |
| <emphasis>Learn About Board Support Packages (BSPs):</emphasis> |
| If you want to learn about BSPs, see the |
| <ulink url='&YOCTO_DOCS_BSP_URL;#bsp'>Yocto Project Board Support Packages (BSP) Developer's Guide</ulink>. |
| This manual also provides an example BSP creation workflow. |
| See the |
| <ulink url='&YOCTO_DOCS_BSP_URL;#developing-a-board-support-package-bsp'>"Developing a Board Support Package (BSP)</ulink>" |
| section. |
| </para></listitem> |
| <listitem><para> |
| <emphasis>Learn About Toaster:</emphasis> |
| Toaster is a web interface to the Yocto Project's |
| OpenEmbedded build system. |
| If you are interested in using this type of interface to |
| create images, see the |
| <ulink url='&YOCTO_DOCS_TOAST_URL;#toaster-manual-intro'>Toaster User Manual</ulink>. |
| </para></listitem> |
| <listitem><para> |
| <emphasis>Have Available the |
| <ulink url='&YOCTO_DOCS_REF_URL;#ref-manual-intro'>Yocto Project Reference Manual:</ulink></emphasis> |
| Unlike the rest of the Yocto Project manual set, this manual |
| is comprised of material suited for reference rather than |
| procedures. |
| You can get |
| <ulink url='&YOCTO_DOCS_REF_URL;#usingpoky'>build details</ulink>, |
| a |
| <ulink url='&YOCTO_DOCS_REF_URL;#development-concepts'>closer look</ulink> |
| at how the pieces of the Yocto Project development |
| environment work together, information on various |
| <ulink url='&YOCTO_DOCS_REF_URL;#technical-details'>technical details</ulink>, |
| guidance on |
| <ulink url='&YOCTO_DOCS_REF_URL;#migration'>migrating to a newer Yocto Project release</ulink>, |
| reference material on the |
| <ulink url='&YOCTO_DOCS_REF_URL;#ref-structure'>directory structure</ulink>, |
| <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes'>classes</ulink>, |
| and |
| <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks'>tasks</ulink>. |
| The Yocto Project Reference Manual also contains a fairly |
| comprehensive |
| <ulink url='&YOCTO_DOCS_REF_URL;#ref-variables-glossary'>glossary of variables</ulink> |
| used within the Yocto Project. |
| </para></listitem> |
| </itemizedlist> |
| </para> |
| </section> |
| </article> |
| <!-- |
| vim: expandtab tw=80 ts=4 |
| --> |