# Getting Started with the Yocto Project

This chapter introduces the Yocto Project and gives you an idea of what you need to get started. You can find enough information to set up your development host and build or use images for hardware supported by the Yocto Project by reading the Yocto Project Quick Start.

The remainder of this chapter summarizes what is in the Yocto Project Quick Start and provides some higher-level concepts you might want to consider.

## Introducing the Yocto Project

The Yocto Project is an open-source collaboration project focused on embedded Linux development. The project currently provides a build system that is referred to as the OpenEmbedded build system in the Yocto Project documentation. 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.

You can use the OpenEmbedded build system, which uses BitBake, to develop complete Linux images and associated user-space applications for architectures based on ARM, MIPS, PowerPC, x86 and x86-64.

By default, using the Yocto Project creates a Poky distribution. However, you can create your own distribution by providing key Metadata. See the "Creating Your Own Distribution" section for more information.
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 Eclipse IDE user, you can install an Eclipse Yocto Plug-in to allow you to develop within that familiar environment.

## Getting Set Up

Here is what you need to use the Yocto Project:

- Host System: You should have a reasonably current Linux-based host system. You will have the best results with a recent release of Fedora, openSUSE, Debian, Ubuntu, or CentOS as these releases are frequently tested against the Yocto Project and officially supported. For a list of the distributions under validation and their status, see the "Supported Linux Distributions" section in the Yocto Project Reference Manual and the wiki page at Distribution Support.

  You should also have about 50 Gbytes of free disk space for building images.

- Packages: The OpenEmbedded build system requires that certain packages exist on your development system (e.g. Python 2.7). See "The Packages" section in the Yocto Project Quick Start and the "Required Packages for the Host Development System" section in the Yocto Project Reference Manual for the exact package requirements and the installation commands to install them for the supported distributions.

- Yocto Project Release: You need a release of the Yocto Project locally installed on your development system. The documentation refers to this set of locally installed files as the Source Directory. You create your Source Directory by using Git to clone a local copy of the upstream `poky` repository, or by downloading and unpacking a tarball of an official Yocto Project release. The preferred method is to create a clone of the repository.

  Working from a copy of the upstream repository allows you to contribute back into the Yocto Project or simply work with the latest software on a development branch. Because Git maintains and creates an upstream repository with a complete history of changes and you are working with a local clone of that repository, you have access to all the Yocto Project development branches and tag names used in the upstream repository.

  You can view the Yocto Project Source Repositories at

  The following transcript shows how to clone the `poky` Git repository into the current working directory. The command creates the local repository in a directory named `poky`. For information on Git used within the Yocto Project, see the "Git" section.

           $ git clone git://git.yoctoproject.org/poky
           Cloning into 'poky'...
           remote: Counting objects: 226790, done.
           remote: Compressing objects: 100% (57465/57465), done.
           remote: Total 226790 (delta 165212), reused 225887 (delta 164327)
           Receiving objects: 100% (226790/226790), 100.98 MiB | 263 KiB/s, done.
           Resolving deltas: 100% (165212/165212), done.

  For another example of how to set up your own local Git repositories, see this wiki page, which describes how to create local Git repositories for both `poky` and `meta-intel`.

- Yocto Project Kernel: If you are going to be making modifications to a supported Yocto Project kernel, you need to establish local copies of the source. You can find Git repositories of supported Yocto Project kernels organized under "Yocto Linux Kernel" in the Yocto Project Source Repositories at .

  This setup can involve creating a bare clone of the Yocto Project kernel and then copying that cloned repository. You can create the bare clone and the copy of the bare clone anywhere you like. For simplicity, it is recommended that you create these structures outside of the Source Directory, which is usually named `poky`.

  As an example, the following transcript shows how to create the bare clone of the `linux-yocto-3.19` kernel and then create a copy of that clone.

  When you have a local Yocto Project kernel Git repository, you can reference that repository rather than the upstream Git repository as part of the `clone` command. Doing so can speed up the process.

  In the following example, the bare clone is named `linux-yocto-3.19.git`, while the copy is named `my-linux-yocto-3.19-work`:

           $ git clone --bare git://git.yoctoproject.org/linux-yocto-3.19 linux-yocto-3.19.git
           Cloning into bare repository 'linux-yocto-3.19.git'...
           remote: Counting objects: 3983256, done.
           remote: Compressing objects: 100% (605006/605006), done.
           remote: Total 3983256 (delta 3352832), reused 3974503 (delta 3344079)
           Receiving objects: 100% (3983256/3983256), 843.66 MiB | 1.07 MiB/s, done.
           Resolving deltas: 100% (3352832/3352832), done.
           Checking connectivity... done.

  Now create a clone of the bare clone just created:

           $ git clone linux-yocto-3.19.git my-linux-yocto-3.19-work
           Cloning into 'my-linux-yocto-3.19-work'...
           done.
           Checking out files: 100% (48440/48440), done.

- The `meta-yocto-kernel-extras` Git Repository: The `meta-yocto-kernel-extras` Git repository contains Metadata needed only if you are modifying and building the kernel image. In particular, it contains the kernel BitBake append (`.bbappend`) files that you edit to point to your locally modified kernel source files and to build the kernel image. Pointing to these local files is much more efficient than requiring a download of the kernel's source files from upstream each time you make changes to the kernel.

  You can find the `meta-yocto-kernel-extras` Git Repository in the "Yocto Metadata Layers" area of the Yocto Project Source Repositories at . It is good practice to create this Git repository inside the Source Directory.

  Following is an example that creates the `meta-yocto-kernel-extras` Git repository inside the Source Directory, which is named `poky` in this case:

           $ cd ~/poky
           $ git clone git://git.yoctoproject.org/meta-yocto-kernel-extras meta-yocto-kernel-extras
           Cloning into 'meta-yocto-kernel-extras'...
           remote: Counting objects: 727, done.
           remote: Compressing objects: 100% (452/452), done.
           remote: Total 727 (delta 260), reused 719 (delta 252)
           Receiving objects: 100% (727/727), 536.36 KiB | 240 KiB/s, done.
           Resolving deltas: 100% (260/260), done.

- Supported Board Support Packages (BSPs): The Yocto Project supports many BSPs, which are maintained in their own layers or in layers designed to contain several BSPs. To get an idea of machine support through BSP layers, you can look at the index of machines for the release.

  The Yocto Project uses the following BSP layer naming scheme:

           meta-bsp_name

  where bsp_name is the recognized BSP name. Here are some examples:

           meta-crownbay
           meta-emenlow
           meta-raspberrypi

  See the "BSP Layers" section in the Yocto Project Board Support Package (BSP) Developer's Guide for more information on BSP Layers.

  A useful Git repository released with the Yocto Project is `meta-intel`, which is a parent layer that contains many supported BSP Layers. You can locate the `meta-intel` Git repository in the "Yocto Metadata Layers" area of the Yocto Project Source Repositories at .

  Using Git to create a local clone of the upstream repository can be helpful if you are working with BSPs. Typically, you set up the `meta-intel` Git repository inside the Source Directory. For example, the following transcript shows the steps to clone `meta-intel`.

  Be sure to work in the `meta-intel` branch that matches your Source Directory (i.e. `poky`) branch. For example, if you have checked out the "master" branch of `poky` and you are going to use `meta-intel`, be sure to checkout the "master" branch of `meta-intel`.

           $ cd ~/poky
           $ git clone git://git.yoctoproject.org/meta-intel.git
           Cloning into 'meta-intel'...
           remote: Counting objects: 8844, done.
           remote: Compressing objects: 100% (2864/2864), done.
           remote: Total 8844 (delta 4931), reused 8780 (delta 4867)
           Receiving objects: 100% (8844/8844), 2.48 MiB | 264 KiB/s, done.
           Resolving deltas: 100% (4931/4931), done.

  The same wiki page referenced earlier covers how to set up the `meta-intel` Git repository.

- Eclipse Yocto Plug-in: If you are developing applications using the Eclipse Integrated Development Environment (IDE), you will need this plug-in. See the "Setting up the Eclipse IDE" section for more information.

## Building Images

The build process creates an entire Linux distribution, including the toolchain, from source. For more information on this topic, see the "Building an Image" section in the Yocto Project Quick Start.

The build process is as follows:

1. Make sure you have set up the Source Directory described in the previous section.

2. Initialize the build environment by sourcing a build environment script (i.e. `&OE_INIT_FILE;` or `oe-init-build-env-memres`).

3. Optionally ensure the `conf/local.conf` configuration file, which is found in the Build Directory, is set up how you want it. This file defines many aspects of the build environment including the target machine architecture through the `MACHINE` variable, the packaging format used during the build (`PACKAGE_CLASSES`), and a centralized tarball download directory through the `DL_DIR` variable.

4. Build the image using the `bitbake` command. If you want information on BitBake, see the BitBake User Manual.

5. Run the image either on the actual hardware or using the QEMU emulator.

## Using Pre-Built Binaries and QEMU

Another option you have to get started is to use pre-built binaries. The Yocto Project provides many types of binaries with each release. See the "Images" chapter in the Yocto Project Reference Manual for descriptions of the types of binaries that ship with a Yocto Project release.

Using a pre-built binary is ideal for developing software applications to run on your target hardware. To do this, you need to be able to access the appropriate cross-toolchain tarball for the architecture on which you are developing. If you are using an SDK type image, the image ships with the complete toolchain native to the architecture. If you are not using an SDK type image, you need to separately download and install the stand-alone Yocto Project cross-toolchain tarball.

Regardless of the type of image you are using, you need to download the pre-built kernel that you will boot in the QEMU emulator and then download and extract the target root filesystem for your target machine’s architecture. You can get architecture-specific binaries and file systems from machines. You can get installation scripts for stand-alone toolchains from toolchains. Once you have all your files, you set up the environment to emulate the hardware by sourcing an environment setup script. Finally, you start the QEMU emulator. You can find details on all these steps in the "Using Pre-Built Binaries and QEMU" section of the Yocto Project Quick Start. You can learn more about using QEMU with the Yocto Project in the "Using the Quick EMUlator (QEMU)" section.

Using QEMU to emulate your hardware can result in speed issues depending on the target and host architecture mix. For example, using the `qemux86` image in the emulator on an Intel-based 32-bit (x86) host machine is fast because the target and host architectures match. On the other hand, using the `qemuarm` image on the same Intel-based host can be slower. But, you still achieve faithful emulation of ARM-specific issues.

To speed things up, the QEMU images support using `distcc` to call a cross-compiler outside the emulated system. If you used `runqemu` to start QEMU, and the `distccd` application is present on the host system, any BitBake cross-compiling toolchain available from the build system is automatically used from within QEMU simply by calling `distcc`. You can accomplish this by defining the cross-compiler variable (e.g. `export CC="distcc"`). Alternatively, if you are using a suitable SDK image or the appropriate stand-alone toolchain is present, the toolchain is also automatically used.

Several mechanisms exist that let you connect to the system running on the QEMU emulator:

- QEMU provides a framebuffer interface that makes standard consoles available.

- Generally, headless embedded devices have a serial port. If so, you can configure the operating system of the running image to use that port to run a console. The connection uses standard IP networking.

- SSH servers exist in some QEMU images. The `core-image-sato` QEMU image has a Dropbear secure shell (SSH) server that runs with the root password disabled. The `core-image-full-cmdline` and `core-image-lsb` QEMU images have OpenSSH instead of Dropbear. Including these SSH servers allow you to use standard `ssh` and `scp` commands. The `core-image-minimal` QEMU image, however, contains no SSH server.

- You can use a provided, user-space NFS server to boot the QEMU session using a local copy of the root filesystem on the host. In order to make this connection, you must extract a root filesystem tarball by using the `runqemu-extract-sdk` command. After running the command, you must then point the `runqemu` script to the extracted directory instead of a root filesystem image file.