| <!DOCTYPE chapter 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; ] > |
| |
| <chapter id='ref-manual-intro'> |
| <title>Introduction</title> |
| |
| <section id='ref-welcome'> |
| <title>Welcome</title> |
| |
| <para> |
| Welcome to the Yocto Project Reference Manual. |
| This manual provides reference information for the current release |
| of the Yocto Project. |
| This manual is best used after you have an understanding |
| of the basics of the Yocto Project. |
| The manual is neither meant to be read as a starting point to the |
| Yocto Project nor read from start to finish. |
| Use this manual to find concepts, variable definitions, class |
| descriptions, and so forth as needed during the course of using |
| the Yocto Project. |
| </para> |
| |
| <para> |
| For introductory information on the Yocto Project, see the |
| <ulink url='&YOCTO_HOME_URL;'>Yocto Project Website</ulink> and the |
| "<link linkend='yp-intro'>Introducing the Yocto Project Development Environment</link>" |
| section. |
| </para> |
| |
| <para> |
| If you want to use the Yocto Project to test run building an image |
| without having to understand concepts, work through the |
| <ulink url='&YOCTO_DOCS_QS_URL;'>Yocto Project Quick Start</ulink>. |
| You can find "how-to" information in the |
| <ulink url='&YOCTO_DOCS_DEV_URL;'>Yocto Project Development Tasks Manual</ulink>. |
| <note><title>Tip</title> |
| For more information about the Yocto Project Documentation set, |
| see the |
| "<link linkend='resources-links-and-related-documentation'>Links and Related Documentation</link>" |
| section. |
| </note> |
| </para> |
| </section> |
| |
| <section id='yp-intro'> |
| <title>Introducing the Yocto Project Development Environment</title> |
| |
| <para> |
| The Yocto Project is an open-source collaboration project whose |
| focus is for developers of embedded Linux systems. |
| Among other things, the Yocto Project uses an |
| <link linkend='build-system-term'>OpenEmbedded build system</link>. |
| The build system, which is based on the OpenEmbedded (OE) project and |
| uses the |
| <link linkend='bitbake-term'>BitBake</link> tool, constructs complete |
| Linux images for architectures based on ARM, MIPS, PowerPC, x86 and |
| x86-64. |
| <note> |
| Historically, the OpenEmbedded build system, which is the |
| combination of BitBake and OE components, formed a reference |
| build host that was known as |
| "<link linkend='poky'>Poky</link>" (<emphasis>Pah</emphasis>-kee). |
| The term "Poky", as used throughout the Yocto Project Documentation |
| set, can have different meanings. |
| </note> |
| The Yocto Project provides various ancillary tools for the embedded |
| developer and also features the Sato reference User Interface, which |
| is optimized for stylus-driven, low-resolution screens. |
| </para> |
| |
| <mediaobject> |
| <imageobject> |
| <imagedata fileref="figures/YP-flow-diagram.png" |
| format="PNG" align='center' width="8in"/> |
| </imageobject> |
| </mediaobject> |
| |
| <para> |
| Here are some highlights for the Yocto Project: |
| </para> |
| |
| <itemizedlist> |
| <listitem><para> |
| Provides a recent Linux kernel along with a set of system |
| commands and libraries suitable for the embedded |
| environment. |
| </para></listitem> |
| <listitem><para> |
| Makes available system components such as X11, GTK+, Qt, |
| Clutter, and SDL (among others) so you can create a rich user |
| experience on devices that have display hardware. |
| For devices that do not have a display or where you wish to |
| use alternative UI frameworks, these components need not be |
| installed. |
| </para></listitem> |
| <listitem><para> |
| Creates a focused and stable core compatible with the |
| OpenEmbedded project with which you can easily and reliably |
| build and develop. |
| </para></listitem> |
| <listitem><para> |
| Fully supports a wide range of hardware and device emulation |
| through the Quick EMUlator (QEMU). |
| </para></listitem> |
| <listitem><para> |
| Provides a layer mechanism that allows you to easily extend |
| the system, make customizations, and keep them organized. |
| </para></listitem> |
| </itemizedlist> |
| |
| <para> |
| You can use the Yocto Project to generate images for many kinds |
| of devices. |
| As mentioned earlier, the Yocto Project supports creation of |
| reference images that you can boot within and emulate using QEMU. |
| The standard example machines target QEMU full-system |
| emulation for 32-bit and 64-bit variants of x86, ARM, MIPS, and |
| PowerPC architectures. |
| Beyond emulation, you can use the layer mechanism to extend |
| support to just about any platform that Linux can run on and that |
| a toolchain can target. |
| </para> |
| |
| <para> |
| Another Yocto Project feature is the Sato reference User |
| Interface. |
| This optional UI that is based on GTK+ is intended for devices with |
| restricted screen sizes and is included as part of the |
| OpenEmbedded Core layer so that developers can test parts of the |
| software stack. |
| </para> |
| |
| <para> |
| While the Yocto Project does not provide a strict testing framework, |
| it does provide or generate for you artifacts that let you perform |
| target-level and emulated testing and debugging. |
| Additionally, if you are an |
| <trademark class='trade'>Eclipse</trademark> IDE user, you can |
| install an Eclipse Yocto Plug-in to allow you to develop within that |
| familiar environment. |
| </para> |
| |
| <para> |
| By default, using the Yocto Project to build an image creates a Poky |
| distribution. |
| However, you can create your own distribution by providing key |
| <link link='metadata'>Metadata</link>. |
| A good example is Angstrom, which has had a distribution |
| based on the Yocto Project since its inception. |
| Other examples include commercial distributions like |
| <ulink url='https://www.yoctoproject.org/organization/wind-river-systems'>Wind River Linux</ulink>, |
| <ulink url='https://www.yoctoproject.org/organization/mentor-graphics'>Mentor Embedded Linux</ulink>, |
| <ulink url='https://www.yoctoproject.org/organization/enea-ab'>ENEA Linux</ulink> |
| and <ulink url='https://www.yoctoproject.org/ecosystem/member-organizations'>others</ulink>. |
| See the "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-your-own-distribution'>Creating Your Own Distribution</ulink>" |
| section in the Yocto Project Development Tasks Manual for more |
| information. |
| </para> |
| </section> |
| |
| <section id='intro-requirements'> |
| <title>System Requirements</title> |
| <para> |
| For general Yocto Project system requirements, see the |
| "<ulink url='&YOCTO_DOCS_QS_URL;#yp-resources'>Setting Up to Use the Yocto Project</ulink>" section |
| in the Yocto Project Quick Start. |
| The remainder of this section provides details on system requirements |
| not covered in the Yocto Project Quick Start. |
| </para> |
| |
| <section id='detailed-supported-distros'> |
| <title>Supported Linux Distributions</title> |
| |
| <para> |
| Currently, the Yocto Project is supported on the following |
| distributions: |
| <note> |
| <para> |
| Yocto Project releases are tested against the stable Linux |
| distributions in the following list. |
| The Yocto Project should work on other distributions but |
| validation is not performed against them. |
| </para> |
| |
| <para> |
| In particular, the Yocto Project does not support |
| and currently has no plans to support |
| rolling-releases or development distributions due to their |
| constantly changing nature. |
| We welcome patches and bug reports, but keep in mind that |
| our priority is on the supported platforms listed below. |
| </para> |
| |
| <para> |
| If you encounter problems, please go to |
| <ulink url='&YOCTO_BUGZILLA_URL;'>Yocto Project Bugzilla</ulink> |
| and submit a bug. |
| We are interested in hearing about your experience. |
| </para> |
| </note> |
| <itemizedlist> |
| <!-- |
| <listitem><para>Ubuntu 10.04</para></listitem> |
| <listitem><para>Ubuntu 11.10</para></listitem> |
| <listitem><para>Ubuntu 12.04 (LTS)</para></listitem> |
| <listitem><para>Ubuntu 13.10</para></listitem> |
| <listitem><para>Ubuntu 14.04 (LTS)</para></listitem> --> |
| <listitem><para>Ubuntu 14.10</para></listitem> |
| <listitem><para>Ubuntu 15.04</para></listitem> |
| <listitem><para>Ubuntu 15.10</para></listitem> |
| <listitem><para>Ubuntu 16.04 (LTS)</para></listitem> |
| <!-- <listitem><para>Fedora 16 (Verne)</para></listitem> |
| <listitem><para>Fedora 17 (Spherical)</para></listitem> |
| <listitem><para>Fedora release 19 (Schrödinger's Cat)</para></listitem> |
| <listitem><para>Fedora release 20 (Heisenbug)</para></listitem> --> |
| <listitem><para>Fedora release 22</para></listitem> |
| <listitem><para>Fedora release 23</para></listitem> |
| <listitem><para>Fedora release 24</para></listitem> |
| <!-- <listitem><para>CentOS release 5.6 (Final)</para></listitem> |
| <listitem><para>CentOS release 5.7 (Final)</para></listitem> |
| <listitem><para>CentOS release 5.8 (Final)</para></listitem> |
| <listitem><para>CentOS release 6.3 (Final)</para></listitem> |
| <listitem><para>CentOS release 6.x</para></listitem> --> |
| <listitem><para>CentOS release 7.x</para></listitem> |
| <!-- <listitem><para>Debian GNU/Linux 6.0 (Squeeze)</para></listitem> |
| <listitem><para>Debian GNU/Linux 7.x (Wheezy)</para></listitem> --> |
| <listitem><para>Debian GNU/Linux 8.x (Jessie)</para></listitem> |
| <listitem><para>Debian GNU/Linux 9.x (Stretch)</para></listitem> |
| <!-- <listitem><para>Debian GNU/Linux 7.1 (Wheezy)</para></listitem> |
| <listitem><para>Debian GNU/Linux 7.2 (Wheezy)</para></listitem> |
| <listitem><para>Debian GNU/Linux 7.3 (Wheezy)</para></listitem> |
| <listitem><para>Debian GNU/Linux 7.4 (Wheezy)</para></listitem> |
| <listitem><para>Debian GNU/Linux 7.5 (Wheezy)</para></listitem> |
| <listitem><para>Debian GNU/Linux 7.6 (Wheezy)</para></listitem> --> |
| <!-- <listitem><para>openSUSE 11.4</para></listitem> |
| <listitem><para>openSUSE 12.1</para></listitem> |
| <listitem><para>openSUSE 12.2</para></listitem> |
| <listitem><para>openSUSE 12.3</para></listitem> |
| <listitem><para>openSUSE 13.1</para></listitem> --> |
| <listitem><para>openSUSE 13.2</para></listitem> |
| <listitem><para>openSUSE 42.1</para></listitem> |
| </itemizedlist> |
| </para> |
| |
| <note> |
| While the Yocto Project Team attempts to ensure all Yocto Project |
| releases are one hundred percent compatible with each officially |
| supported Linux distribution, instances might exist where you |
| encounter a problem while using the Yocto Project on a specific |
| distribution. |
| </note> |
| </section> |
| |
| <section id='required-packages-for-the-host-development-system'> |
| <title>Required Packages for the Host Development System</title> |
| |
| <para> |
| The list of packages you need on the host development system can |
| be large when covering all build scenarios using the Yocto Project. |
| This section provides required packages according to |
| Linux distribution and function. |
| </para> |
| |
| <section id='ubuntu-packages'> |
| <title>Ubuntu and Debian</title> |
| |
| <para> |
| The following list shows the required packages by function |
| given a supported Ubuntu or Debian Linux distribution: |
| <note> |
| If your build system has the |
| <filename>oss4-dev</filename> package installed, you |
| might experience QEMU build failures due to the package |
| installing its own custom |
| <filename>/usr/include/linux/soundcard.h</filename> on |
| the Debian system. |
| If you run into this situation, either of the following |
| solutions exist: |
| <literallayout class='monospaced'> |
| $ sudo apt-get build-dep qemu |
| $ sudo apt-get remove oss4-dev |
| </literallayout> |
| </note> |
| <itemizedlist> |
| <listitem><para><emphasis>Essentials:</emphasis> |
| Packages needed to build an image on a headless |
| system: |
| <literallayout class='monospaced'> |
| $ sudo apt-get install &UBUNTU_HOST_PACKAGES_ESSENTIAL; |
| </literallayout></para></listitem> |
| <listitem><para><emphasis>Graphical and Eclipse Plug-In Extras:</emphasis> |
| Packages recommended if the host system has graphics |
| support or if you are going to use the Eclipse |
| IDE: |
| <literallayout class='monospaced'> |
| $ sudo apt-get install libsdl1.2-dev xterm |
| </literallayout></para></listitem> |
| <listitem><para><emphasis>Documentation:</emphasis> |
| Packages needed if you are going to build out the |
| Yocto Project documentation manuals: |
| <literallayout class='monospaced'> |
| $ sudo apt-get install make xsltproc docbook-utils fop dblatex xmlto |
| </literallayout></para></listitem> |
| <listitem><para><emphasis>OpenEmbedded Self-Test (<filename>oe-selftest</filename>):</emphasis> |
| Packages needed if you are going to run |
| <filename>oe-selftest</filename>: |
| <literallayout class='monospaced'> |
| $ sudo apt-get install python-git |
| </literallayout> |
| </para></listitem> |
| </itemizedlist> |
| </para> |
| </section> |
| |
| <section id='fedora-packages'> |
| <title>Fedora Packages</title> |
| |
| <para> |
| The following list shows the required packages by function |
| given a supported Fedora Linux distribution: |
| <itemizedlist> |
| <listitem><para><emphasis>Essentials:</emphasis> |
| Packages needed to build an image for a headless |
| system: |
| <literallayout class='monospaced'> |
| $ sudo dnf install &FEDORA_HOST_PACKAGES_ESSENTIAL; |
| </literallayout></para></listitem> |
| <listitem><para><emphasis>Graphical and Eclipse Plug-In Extras:</emphasis> |
| Packages recommended if the host system has graphics |
| support or if you are going to use the Eclipse |
| IDE: |
| <literallayout class='monospaced'> |
| $ sudo dnf install SDL-devel xterm |
| </literallayout></para></listitem> |
| <listitem><para><emphasis>Documentation:</emphasis> |
| Packages needed if you are going to build out the |
| Yocto Project documentation manuals: |
| <literallayout class='monospaced'> |
| $ sudo dnf install make docbook-style-dsssl docbook-style-xsl \ |
| docbook-dtds docbook-utils fop libxslt dblatex xmlto |
| </literallayout></para></listitem> |
| <listitem><para><emphasis>OpenEmbedded Self-Test (<filename>oe-selftest</filename>):</emphasis> |
| Packages needed if you are going to run |
| <filename>oe-selftest</filename>: |
| <literallayout class='monospaced'> |
| $ sudo dnf install python3-GitPython |
| </literallayout> |
| </para></listitem> |
| </itemizedlist> |
| </para> |
| </section> |
| |
| <section id='opensuse-packages'> |
| <title>openSUSE Packages</title> |
| |
| <para> |
| The following list shows the required packages by function |
| given a supported openSUSE Linux distribution: |
| <itemizedlist> |
| <listitem><para><emphasis>Essentials:</emphasis> |
| Packages needed to build an image for a headless |
| system: |
| <literallayout class='monospaced'> |
| $ sudo zypper install &OPENSUSE_HOST_PACKAGES_ESSENTIAL; |
| </literallayout></para></listitem> |
| <listitem><para><emphasis>Graphical and Eclipse Plug-In Extras:</emphasis> |
| Packages recommended if the host system has graphics |
| support or if you are going to use the Eclipse |
| IDE: |
| <literallayout class='monospaced'> |
| $ sudo zypper install libSDL-devel xterm |
| </literallayout></para></listitem> |
| <listitem><para><emphasis>Documentation:</emphasis> |
| Packages needed if you are going to build out the |
| Yocto Project documentation manuals: |
| <literallayout class='monospaced'> |
| $ sudo zypper install make dblatex xmlto |
| </literallayout></para></listitem> |
| <listitem><para><emphasis>OpenEmbedded Self-Test (<filename>oe-selftest</filename>):</emphasis> |
| Packages needed if you are going to run |
| <filename>oe-selftest</filename>: |
| <literallayout class='monospaced'> |
| $ sudo zypper install python-GitPython |
| </literallayout></para></listitem> |
| </itemizedlist> |
| </para> |
| </section> |
| |
| <section id='centos-packages'> |
| <title>CentOS Packages</title> |
| |
| <para> |
| The following list shows the required packages by function |
| given a supported CentOS Linux distribution: |
| <itemizedlist> |
| <listitem><para><emphasis>Essentials:</emphasis> |
| Packages needed to build an image for a headless |
| system: |
| <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> |
| <listitem><para><emphasis>Graphical and Eclipse Plug-In Extras:</emphasis> |
| Packages recommended if the host system has graphics |
| support or if you are going to use the Eclipse |
| IDE: |
| <literallayout class='monospaced'> |
| $ sudo yum install SDL-devel xterm |
| </literallayout></para></listitem> |
| <listitem><para><emphasis>Documentation:</emphasis> |
| Packages needed if you are going to build out the |
| Yocto Project documentation manuals: |
| <literallayout class='monospaced'> |
| $ sudo yum install make docbook-style-dsssl docbook-style-xsl \ |
| docbook-dtds docbook-utils fop libxslt dblatex xmlto |
| </literallayout></para></listitem> |
| <listitem><para><emphasis>OpenEmbedded Self-Test (<filename>oe-selftest</filename>):</emphasis> |
| Packages needed if you are going to run |
| <filename>oe-selftest</filename>: |
| <literallayout class='monospaced'> |
| $ sudo yum install GitPython |
| </literallayout> |
| </para></listitem> |
| </itemizedlist> |
| </para> |
| </section> |
| </section> |
| |
| <section id='required-git-tar-and-python-versions'> |
| <title>Required Git, tar, and Python Versions</title> |
| |
| <para> |
| In order to use the build system, your host development system |
| must meet the following version requirements 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> |
| </para> |
| |
| <para> |
| If your host development system does not meet all these requirements, |
| you can resolve this by installing a <filename>buildtools</filename> |
| tarball that contains these tools. |
| You can get the tarball one of two ways: download a pre-built |
| tarball or use BitBake to build the tarball. |
| </para> |
| |
| <section id='downloading-a-pre-built-buildtools-tarball'> |
| <title>Downloading a Pre-Built <filename>buildtools</filename> Tarball</title> |
| |
| <para> |
| Downloading and running a pre-built buildtools installer is |
| the easiest of the two methods by which you can get these tools: |
| <orderedlist> |
| <listitem><para> |
| Locate and download the <filename>*.sh</filename> at |
| <ulink url='&YOCTO_DL_URL;/releases/yocto/yocto-&DISTRO;/buildtools/'></ulink>. |
| </para></listitem> |
| <listitem><para> |
| Execute the installation script. |
| Here is an example: |
| <literallayout class='monospaced'> |
| $ sh poky-glibc-x86_64-buildtools-tarball-x86_64-buildtools-nativesdk-standalone-&DISTRO;.sh |
| </literallayout> |
| During execution, a prompt appears that allows you to |
| choose the installation directory. |
| For example, you could choose the following: |
| <literallayout class='monospaced'> |
| /home/<replaceable>your-username</replaceable>/buildtools |
| </literallayout> |
| </para></listitem> |
| <listitem><para> |
| Source the tools environment setup script by using a |
| command like the following: |
| <literallayout class='monospaced'> |
| $ source /home/<replaceable>your_username</replaceable>/buildtools/environment-setup-i586-poky-linux |
| </literallayout> |
| Of course, you need to supply your installation directory and be |
| sure to use the right file (i.e. i585 or x86-64). |
| </para> |
| <para> |
| After you have sourced the setup script, |
| the tools are added to <filename>PATH</filename> |
| and any other environment variables required to run the |
| tools are initialized. |
| The results are working versions versions of Git, tar, |
| Python and <filename>chrpath</filename>. |
| </para></listitem> |
| </orderedlist> |
| </para> |
| </section> |
| |
| <section id='building-your-own-buildtools-tarball'> |
| <title>Building Your Own <filename>buildtools</filename> Tarball</title> |
| |
| <para> |
| Building and running your own buildtools installer applies |
| only when you have a build host that can already run BitBake. |
| In this case, you use that machine to build the |
| <filename>.sh</filename> file and then |
| take steps to transfer and run it on a |
| machine that does not meet the minimal Git, tar, and Python |
| requirements. |
| </para> |
| |
| <para> |
| Here are the steps to take to build and run your own |
| buildtools installer: |
| <orderedlist> |
| <listitem><para> |
| On the machine that is able to run BitBake, |
| be sure you have set up your build environment with |
| the setup script |
| (<link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>). |
| </para></listitem> |
| <listitem><para> |
| Run the BitBake command to build the tarball: |
| <literallayout class='monospaced'> |
| $ bitbake buildtools-tarball |
| </literallayout> |
| <note> |
| The |
| <link linkend='var-SDKMACHINE'><filename>SDKMACHINE</filename></link> |
| variable in your <filename>local.conf</filename> file |
| determines whether you build tools for a 32-bit |
| or 64-bit system. |
| </note> |
| Once the build completes, you can find the |
| <filename>.sh</filename> file that installs |
| the tools in the <filename>tmp/deploy/sdk</filename> |
| subdirectory of the |
| <link linkend='build-directory'>Build Directory</link>. |
| The installer file has the string "buildtools" |
| in the name. |
| </para></listitem> |
| <listitem><para> |
| Transfer the <filename>.sh</filename> file from the |
| build host to the machine that does not meet the |
| Git, tar, or Python requirements. |
| </para></listitem> |
| <listitem><para> |
| On the machine that does not meet the requirements, |
| run the <filename>.sh</filename> file |
| to install the tools. |
| Here is an example: |
| <literallayout class='monospaced'> |
| $ sh poky-glibc-x86_64-buildtools-tarball-x86_64-buildtools-nativesdk-standalone-&DISTRO;.sh |
| </literallayout> |
| During execution, a prompt appears that allows you to |
| choose the installation directory. |
| For example, you could choose the following: |
| <literallayout class='monospaced'> |
| /home/<replaceable>your_username</replaceable>/buildtools |
| </literallayout> |
| </para></listitem> |
| <listitem><para> |
| Source the tools environment setup script by using a |
| command like the following: |
| <literallayout class='monospaced'> |
| $ source /home/<replaceable>your_username</replaceable>/buildtools/environment-setup-i586-poky-linux |
| </literallayout> |
| Of course, you need to supply your installation directory and be |
| sure to use the right file (i.e. i585 or x86-64). |
| </para> |
| <para> |
| After you have sourced the setup script, |
| the tools are added to <filename>PATH</filename> |
| and any other environment variables required to run the |
| tools are initialized. |
| The results are working versions versions of Git, tar, |
| Python and <filename>chrpath</filename>. |
| </para></listitem> |
| </orderedlist> |
| </para> |
| </section> |
| </section> |
| </section> |
| |
| <section id='intro-getit'> |
| <title>Obtaining the Yocto Project</title> |
| <para> |
| The Yocto Project development team makes the Yocto Project available through a number |
| of methods: |
| <itemizedlist> |
| <listitem><para><emphasis>Source Repositories:</emphasis> |
| Working from a copy of the upstream |
| <filename>poky</filename> repository is the |
| preferred method for obtaining and using a Yocto Project |
| release. |
| You can view the Yocto Project Source Repositories at |
| <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>. |
| In particular, you can find the |
| <filename>poky</filename> repository at |
| <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/poky/'></ulink>. |
| </para></listitem> |
| <listitem><para><emphasis>Releases:</emphasis> Stable, tested |
| releases are available as tarballs through |
| <ulink url='&YOCTO_DL_URL;/releases/yocto/'/>.</para></listitem> |
| <listitem><para><emphasis>Nightly Builds:</emphasis> These |
| tarball releases are available at |
| <ulink url='&YOCTO_AB_NIGHTLY_URL;'/>. |
| These builds include Yocto Project releases, SDK installation |
| scripts, and experimental builds. |
| </para></listitem> |
| <listitem><para><emphasis>Yocto Project Website:</emphasis> You can |
| find tarball releases of the Yocto Project and supported BSPs |
| at the |
| <ulink url='&YOCTO_HOME_URL;'>Yocto Project website</ulink>. |
| Along with these downloads, you can find lots of other |
| information at this site. |
| </para></listitem> |
| </itemizedlist> |
| </para> |
| </section> |
| |
| <section id='intro-getit-dev'> |
| <title>Development Checkouts</title> |
| <para> |
| Development using the Yocto Project requires a local |
| <link linkend='source-directory'>Source Directory</link>. |
| You can set up the Source Directory by cloning a copy of the upstream |
| <link linkend='poky'>poky</link> Git repository. |
| For information on how to do this, 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 id='yocto-project-terms'> |
| <title>Yocto Project Terms</title> |
| |
| <para> |
| Following is a list of terms and definitions users new to the Yocto |
| Project development environment might find helpful. |
| While some of these terms are universal, the list includes them |
| just in case: |
| <itemizedlist> |
| <listitem><para> |
| <emphasis>Append Files:</emphasis> |
| Files that append build information to a recipe file. |
| Append files are known as BitBake append files and |
| <filename>.bbappend</filename> files. |
| The OpenEmbedded build system expects every append file to have |
| a corresponding recipe (<filename>.bb</filename>) file. |
| Furthermore, the append file and corresponding recipe file |
| must use the same root filename. |
| The filenames can differ only in the file type suffix used |
| (e.g. |
| <filename>formfactor_0.0.bb</filename> and |
| <filename>formfactor_0.0.bbappend</filename>).</para> |
| |
| <para>Information in append files extends or overrides the |
| information in the similarly-named recipe file. |
| For an example of an append file in use, see the |
| "<ulink url='&YOCTO_DOCS_DEV_URL;#using-bbappend-files'>Using .bbappend Files in Your Layer</ulink>" |
| section in the Yocto Project Development Tasks Manual. |
| <note> |
| Append files can also use wildcard patterns in their |
| version numbers so they can be applied to more than one |
| version of the underlying recipe file. |
| </note> |
| </para></listitem> |
| <listitem><para id='bitbake-term'> |
| <emphasis>BitBake:</emphasis> |
| The task executor and scheduler used by the OpenEmbedded build |
| system to build images. |
| For more information on BitBake, see the |
| <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>. |
| </para></listitem> |
| <listitem><para id='board-support-package-bsp-term'> |
| <emphasis>Board Support Package (BSP):</emphasis> |
| A group of drivers, definitions, and other components that |
| provide support for a specific hardware configuration. |
| For more information on BSPs, see the |
| <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink>. |
| </para></listitem> |
| <listitem> |
| <para id='build-directory'> |
| <emphasis>Build Directory:</emphasis> |
| This term refers to the area used by the OpenEmbedded build |
| system for builds. |
| The area is created when you <filename>source</filename> the |
| setup environment script that is found in the Source Directory |
| (i.e. <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>). |
| The |
| <link linkend='var-TOPDIR'><filename>TOPDIR</filename></link> |
| variable points to the Build Directory.</para> |
| |
| <para>You have a lot of flexibility when creating the Build |
| Directory. |
| Following are some examples that show how to create the |
| directory. |
| The examples assume your |
| <link linkend='source-directory'>Source Directory</link> is |
| named <filename>poky</filename>: |
| <itemizedlist> |
| <listitem><para>Create the Build Directory inside your |
| Source Directory and let the name of the Build |
| Directory default to <filename>build</filename>: |
| <literallayout class='monospaced'> |
| $ cd $HOME/poky |
| $ source &OE_INIT_FILE; |
| </literallayout> |
| </para></listitem> |
| <listitem><para>Create the Build Directory inside your |
| home directory and specifically name it |
| <filename>test-builds</filename>: |
| <literallayout class='monospaced'> |
| $ cd $HOME |
| $ source poky/&OE_INIT_FILE; test-builds |
| </literallayout> |
| </para></listitem> |
| <listitem><para> |
| Provide a directory path and specifically name the |
| Build Directory. |
| Any intermediate folders in the pathname must exist. |
| This next example creates a Build Directory named |
| <filename>YP-&POKYVERSION;</filename> |
| in your home directory within the existing |
| directory <filename>mybuilds</filename>: |
| <literallayout class='monospaced'> |
| $cd $HOME |
| $ source $HOME/poky/&OE_INIT_FILE; $HOME/mybuilds/YP-&POKYVERSION; |
| </literallayout> |
| </para></listitem> |
| </itemizedlist> |
| <note> |
| By default, the Build Directory contains |
| <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>, |
| which is a temporary directory the build system uses for |
| its work. |
| <filename>TMPDIR</filename> cannot be under NFS. |
| Thus, by default, the Build Directory cannot be under NFS. |
| However, if you need the Build Directory to be under NFS, |
| you can set this up by setting <filename>TMPDIR</filename> |
| in your <filename>local.conf</filename> file |
| to use a local drive. |
| Doing so effectively separates <filename>TMPDIR</filename> |
| from <filename>TOPDIR</filename>, which is the Build |
| Directory. |
| </note> |
| </para></listitem> |
| <listitem><para id='hardware-build-system-term'> |
| <emphasis>Build System:</emphasis> |
| The system used to build images in a Yocto Project |
| Development environment. |
| The build system is sometimes referred to as the |
| development host. |
| </para></listitem> |
| <listitem><para> |
| <emphasis>Classes:</emphasis> |
| Files that provide for logic encapsulation and inheritance so |
| that commonly used patterns can be defined once and then |
| easily used in multiple recipes. |
| For reference information on the Yocto Project classes, see the |
| "<link linkend='ref-classes'>Classes</link>" chapter. |
| Class files end with the <filename>.bbclass</filename> |
| filename extension. |
| </para></listitem> |
| <listitem><para> |
| <emphasis>Configuration File:</emphasis> |
| Configuration information in various <filename>.conf</filename> |
| files provides global definitions of variables. |
| The <filename>conf/local.conf</filename> configuration file in |
| the |
| <link linkend='build-directory'>Build Directory</link> |
| contains user-defined variables that affect every build. |
| The <filename>meta-poky/conf/distro/poky.conf</filename> |
| configuration file defines Yocto "distro" configuration |
| variables used only when building with this policy. |
| Machine configuration files, which |
| are located throughout the |
| <link linkend='source-directory'>Source Directory</link>, define |
| variables for specific hardware and are only used when building |
| for that target (e.g. the |
| <filename>machine/beaglebone.conf</filename> configuration |
| file defines variables for the Texas Instruments ARM Cortex-A8 |
| development board). |
| Configuration files end with a <filename>.conf</filename> |
| filename extension. |
| </para></listitem> |
| <listitem><para id='cross-development-toolchain'> |
| <emphasis>Cross-Development Toolchain:</emphasis> |
| In general, a cross-development toolchain is a collection of |
| software development tools and utilities that run on one |
| architecture and allow you to develop software for a |
| different, or targeted, architecture. |
| These toolchains contain cross-compilers, linkers, and |
| debuggers that are specific to the target architecture.</para> |
| |
| <para>The Yocto Project supports two different cross-development |
| toolchains: |
| <itemizedlist> |
| <listitem><para> |
| A toolchain only used by and within |
| BitBake when building an image for a target |
| architecture. |
| </para></listitem> |
| <listitem><para>A relocatable toolchain used outside of |
| BitBake by developers when developing applications |
| that will run on a targeted device. |
| </para></listitem> |
| </itemizedlist></para> |
| |
| <para>Creation of these toolchains is simple and automated. |
| For information on toolchain concepts as they apply to the |
| Yocto Project, see the |
| "<link linkend='cross-development-toolchain-generation'>Cross-Development Toolchain Generation</link>" |
| section. |
| You can also find more information on using the |
| relocatable toolchain in the |
| <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink> |
| manual. |
| </para></listitem> |
| <listitem><para> |
| <emphasis>Image:</emphasis> |
| An image is an artifact of the BitBake build process given |
| a collection of recipes and related Metadata. |
| Images are the binary output that run on specific hardware or |
| QEMU and are used for specific use-cases. |
| For a list of the supported image types that the Yocto Project |
| provides, see the |
| "<link linkend='ref-images'>Images</link>" |
| chapter. |
| </para></listitem> |
| <listitem><para> |
| <emphasis>Layer:</emphasis> |
| A collection of recipes representing the core, |
| a BSP, or an application stack. |
| For a discussion specifically on BSP Layers, see the |
| "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>" |
| section in the Yocto Project Board Support Packages (BSP) |
| Developer's Guide. |
| </para></listitem> |
| <listitem><para id='metadata'> |
| <emphasis>Metadata:</emphasis> |
| The files that BitBake parses when building an image. |
| In general, Metadata includes recipes, classes, and |
| configuration files. |
| In the context of the kernel ("kernel Metadata"), the |
| term refers to the kernel config fragments and features |
| contained in the |
| <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/yocto-kernel-cache'><filename>yocto-kernel-cache</filename></ulink> |
| Git repository. |
| </para></listitem> |
| <listitem><para id='oe-core'> |
| <emphasis>OE-Core:</emphasis> |
| A core set of Metadata originating with OpenEmbedded (OE) |
| that is shared between OE and the Yocto Project. |
| This Metadata is found in the <filename>meta</filename> |
| directory of the |
| <link linkend='source-directory'>Source Directory</link>. |
| </para></listitem> |
| <listitem><para id='build-system-term'> |
| <emphasis>OpenEmbedded Build System:</emphasis> |
| The build system specific to the Yocto Project. |
| The OpenEmbedded build system is based on another project known |
| as "Poky", which uses |
| <link linkend='bitbake-term'>BitBake</link> as the task |
| executor. |
| Throughout the Yocto Project documentation set, the |
| OpenEmbedded build system is sometimes referred to simply |
| as "the build system". |
| If other build systems, such as a host or target build system |
| are referenced, the documentation clearly states the |
| difference. |
| <note> |
| For some historical information about Poky, see the |
| <link linkend='poky'>Poky</link> term. |
| </note> |
| </para></listitem> |
| <listitem><para> |
| <emphasis>Package:</emphasis> |
| In the context of the Yocto Project, this term refers to a |
| recipe's packaged output produced by BitBake (i.e. a |
| "baked recipe"). |
| A package is generally the compiled binaries produced from the |
| recipe's sources. |
| You "bake" something by running it through BitBake.</para> |
| |
| <para>It is worth noting that the term "package" can, |
| in general, have subtle meanings. |
| For example, the packages referred to in the |
| "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Build Host Packages</ulink>" |
| section in the Yocto Project Quick Start are compiled binaries |
| that, when installed, add functionality to your Linux |
| distribution.</para> |
| |
| <para>Another point worth noting is that historically within |
| the Yocto Project, recipes were referred to as packages - thus, |
| the existence of several BitBake variables that are seemingly |
| mis-named, |
| (e.g. <link linkend='var-PR'><filename>PR</filename></link>, |
| <link linkend='var-PV'><filename>PV</filename></link>, and |
| <link linkend='var-PE'><filename>PE</filename></link>). |
| </para></listitem> |
| <listitem><para> |
| <emphasis>Package Groups:</emphasis> |
| Arbitrary groups of software Recipes. |
| You use package groups to hold recipes that, when built, |
| usually accomplish a single task. |
| For example, a package group could contain the recipes for a |
| company’s proprietary or value-add software. |
| Or, the package group could contain the recipes that enable |
| graphics. |
| A package group is really just another recipe. |
| Because package group files are recipes, they end with the |
| <filename>.bb</filename> filename extension. |
| </para></listitem> |
| <listitem><para id='poky'> |
| <emphasis>Poky:</emphasis> |
| The term "poky", which is pronounced |
| <emphasis>Pah</emphasis>-kee, can mean several things: |
| <itemizedlist> |
| <listitem><para> |
| In its most general sense, poky is an open-source |
| project that was initially developed by OpenedHand. |
| OpenedHand developed poky off of the existing |
| OpenEmbedded build system to create a commercially |
| supportable build system for embedded Linux. |
| After Intel Corporation acquired OpenedHand, the |
| poky project became the basis for the Yocto Project's |
| build system. |
| </para></listitem> |
| <listitem><para> |
| Within the Yocto Project |
| <ulink url='&YOCTO_GIT_URL;'>Source Repositories</ulink>, |
| "poky" exists as a separate Git |
| repository from which you can clone to yield a local |
| Git repository that is a copy on your host system. |
| Thus, "poky" can refer to the upstream or |
| local copy of the files used for development within |
| the Yocto Project. |
| </para></listitem> |
| <listitem><para> |
| Finally, "poky" can refer to the default |
| <link linkend='var-DISTRO'><filename>DISTRO</filename></link> |
| (i.e. distribution) created when you use the Yocto |
| Project in conjunction with the |
| <filename>poky</filename> repository to build an image. |
| </para></listitem> |
| </itemizedlist> |
| </para></listitem> |
| <listitem><para> |
| <emphasis>Recipe:</emphasis> |
| A set of instructions for building packages. |
| A recipe describes where you get source code, which patches |
| to apply, how to configure the source, how to compile it and so on. |
| Recipes also describe dependencies for libraries or for other |
| recipes. |
| Recipes represent the logical unit of execution, the software |
| to build, the images to build, and use the |
| <filename>.bb</filename> file extension. |
| </para></listitem> |
| <listitem><para id='reference-kit-term'> |
| <emphasis>Reference Kit:</emphasis> |
| A working example of a system, which includes a |
| <link linkend='board-support-package-bsp-term'>BSP</link> |
| as well as a |
| <link linkend='hardware-build-system-term'>build system</link> |
| and other components, that can work on specific hardware. |
| </para></listitem> |
| <listitem> |
| <para id='source-directory'> |
| <emphasis>Source Directory:</emphasis> |
| This term refers to the directory structure created as a result |
| of creating a local copy of the <filename>poky</filename> Git |
| repository <filename>git://git.yoctoproject.org/poky</filename> |
| or expanding a released <filename>poky</filename> tarball. |
| <note> |
| Creating a local copy of the <filename>poky</filename> |
| Git repository is the recommended method for setting up |
| your Source Directory. |
| </note> |
| Sometimes you might hear the term "poky directory" used to refer |
| to this directory structure. |
| <note> |
| The OpenEmbedded build system does not support file or |
| directory names that contain spaces. |
| Be sure that the Source Directory you use does not contain |
| these types of names. |
| </note></para> |
| |
| <para>The Source Directory contains BitBake, Documentation, |
| Metadata and other files that all support the Yocto Project. |
| Consequently, you must have the Source Directory in place on |
| your development system in order to do any development using |
| the Yocto Project.</para> |
| |
| <para>When you create a local copy of the Git repository, you |
| can name the repository anything you like. |
| Throughout much of the documentation, "poky" |
| is used as the name of the top-level folder of the local copy of |
| the poky Git repository. |
| So, for example, cloning the <filename>poky</filename> Git |
| repository results in a local Git repository whose top-level |
| folder is also named "poky".</para> |
| |
| <para>While it is not recommended that you use tarball expansion |
| to set up the Source Directory, if you do, the top-level |
| directory name of the Source Directory is derived from the |
| Yocto Project release tarball. |
| For example, downloading and unpacking |
| <filename>&YOCTO_POKY_TARBALL;</filename> results in a |
| Source Directory whose root folder is named |
| <filename>&YOCTO_POKY;</filename>.</para> |
| |
| <para>It is important to understand the differences between the |
| Source Directory created by unpacking a released tarball as |
| compared to cloning |
| <filename>git://git.yoctoproject.org/poky</filename>. |
| When you unpack a tarball, you have an exact copy of the files |
| based on the time of release - a fixed release point. |
| Any changes you make to your local files in the Source Directory |
| are on top of the release and will remain local only. |
| On the other hand, when you clone the <filename>poky</filename> |
| Git repository, you have an active development repository with |
| access to the upstream repository's branches and tags. |
| In this case, any local changes you make to the local |
| Source Directory can be later applied to active development |
| branches of the upstream <filename>poky</filename> Git |
| repository.</para> |
| |
| <para>For more information on concepts related to Git |
| repositories, branches, and tags, see the |
| "<link linkend='repositories-tags-and-branches'>Repositories, Tags, and Branches</link>" |
| section. |
| </para></listitem> |
| <listitem><para><emphasis>Task:</emphasis> |
| A unit of execution for BitBake (e.g. |
| <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>, |
| <link linkend='ref-tasks-fetch'><filename>do_fetch</filename></link>, |
| <link linkend='ref-tasks-patch'><filename>do_patch</filename></link>, |
| and so forth). |
| </para></listitem> |
| <listitem><para id='toaster-term'><emphasis>Toaster:</emphasis> |
| A web interface to the Yocto Project's |
| <link linkend='build-system-term'>OpenEmbedded Build System</link>. |
| The interface enables you to configure and run your builds. |
| Information about builds is collected and stored in a database. |
| For information on Toaster, see the |
| <ulink url='&YOCTO_DOCS_TOAST_URL;'>Yocto Project Toaster Manual</ulink>. |
| </para></listitem> |
| <listitem><para> |
| <emphasis>Upstream:</emphasis> |
| A reference to source code or repositories |
| that are not local to the development system but located in a |
| master area that is controlled by the maintainer of the source |
| code. |
| For example, in order for a developer to work on a particular |
| piece of code, they need to first get a copy of it from an |
| "upstream" source. |
| </para></listitem> |
| </itemizedlist> |
| </para> |
| </section> |
| |
| </chapter> |
| <!-- |
| vim: expandtab tw=80 ts=4 |
| --> |