Information that lets you get set up to develop using the Yocto Project.

Information to help developers that are new to the open source environment and to the distributed revision control system Git, which the Yocto Project uses.

An understanding of common end-to-end development models.

Development case overviews for both system development and user-space applications.

An overview and understanding of the emulation environment used with the Yocto Project (QEMU).

An understanding of basic kernel architecture and concepts.

Many references to other sources of related information.

Step-by-step instructions if those instructions exist in other Yocto Project documentation. For example, The Application Development Toolkit (ADT) User’s Guide contains detailed instruction on how to obtain and configure the Eclipse™ Yocto Plug-in.

Reference material. This type of material resides in an appropriate reference manual. For example, system variables are documented in the Yocto Project Reference Manual.

Detailed public information that is not specific to the Yocto Project. For example, exhaustive information on how to use Git is covered better through the Internet than in this manual.

The Yocto Project Website: The home page for the Yocto Project provides lots of information on the project as well as links to software and documentation.

The Yocto Project Quick Start: This short document lets you get started with the Yocto Project quickly and start building an image.

The Yocto Project Reference Manual: This manual is a reference guide to the Yocto Project build component known as "Poky." The manual also contains a reference chapter on Board Support Package (BSP) layout.

The Yocto Project Application Development Toolkit (ADT) User's Guide: This guide provides information that lets you get going with the ADT to develop projects using the Yocto Project.

The Yocto Project Board Support Package (BSP) Developer's Guide: This guide defines the structure for BSP components. Having a commonly understood structure encourages standardization.

The Yocto Project Kernel Architecture and Use Manual: This manual describes the architecture of the Yocto Project kernel and provides some work flow examples.

Yocto Eclipse Plug-in: A step-by-step instructional video that demonstrates how an application developer uses Yocto Plug-in features within the Eclipse IDE.

FAQ: A list of commonly asked questions and their answers.

Release Notes: Features, updates and known issues for the current release of the Yocto Project.

Bugzilla: The bug tracking application the Yocto Project uses. If you find problems with the Yocto Project, you should report them using this application.

Yocto Project Mailing Lists: To subscribe to the Yocto Project mailing lists, click on the following URLs and follow the instructions:

Internet Relay Chat (IRC): Two IRC channels on freenode are available for Yocto Project and Poky discussions: #yocto and #poky.

OpenedHand: The company where the Yocto Project build system Poky was first developed. OpenedHand has since been acquired by Intel Corporation.

Intel Corporation: The company who acquired OpenedHand in 2008 and continues development on the Yocto Project.

OpenEmbedded: The upstream, generic, embedded distribution the Yocto Project build system (Poky) derives from and to which it contributes.

BitBake: The tool used to process Yocto Project metadata.

BitBake User Manual: A comprehensive guide to the BitBake tool.

Pimlico: A suite of lightweight Personal Information Management (PIM) applications designed primarily for handheld and mobile devices.

QEMU: An open-source machine emulator and virtualizer.

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, or Ubuntu as these releases are frequently tested against the Yocto Project and officially supported. You should also have about 100 gigabytes of free disk space for building images.

Packages: The Yocto Project requires certain packages exist on your development system (e.g. Python 2.6 or 2.7). See "The Packages" section in the Yocto Project Quick start 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. You can get set up with local Yocto Project files one of two ways depending on whether you are going to be contributing back into the Yocto Project source repository or not.

Linux Yocto Kernel: If you are going to be making modifications to a supported Linux Yocto kernel, you need to establish local copies of the source. This setup involves creating a bare clone of the Linux Yocto kernel and then cloning that 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 Yocto Project files' Git repository.

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

In the following example, the bare clone is named linux-yocto-3.0.git, while the copy is named linux-yocto-3.0:

     $ git clone --bare git://git.yoctoproject.org/linux-yocto-3.0 linux-yocto-3.0.git
     Initialized empty Git repository in /home/scottrif/linux-yocto-3.0.git/
     remote: Counting objects: 2123870, done.
     remote: Compressing objects: 100% (341338/341338), done.
     remote: Total 2123870 (delta 1778780), reused 2107534 (delta 1762583)
     Receiving objects: 100% (2123870/2123870), 445.72 MiB | 2.06 MiB/s, done.
     Resolving deltas: 100% (1778780/1778780), done.                

Now create a clone of the bare clone just created:

     $ git clone linux-yocto-3.0.git linux-yocto-3.0
     Initialized empty Git repository in /home/scottrif/linux-yocto-3.0/.git/
     Checking out files: 100% (36898/36898), done.                

The poky-extras Git Repository: The poky-extras Git repository contains metadata needed to build the kernel image. In particular, it contains the kernel .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 source files from upstream each time you make changes to the kernel.

It is good practice to create this Git repository inside the Yocto Project files Git repository. Following is an example that creates the poky-extras Git repository inside the Yocto Project files Git repository, which is named poky in this case:

     $ cd ~/poky
     $ git clone git://git.yoctoproject.org/poky-extras poky-extras
     Initialized empty Git repository in /home/scottrif/poky/poky-extras/.git/
     remote: Counting objects: 543, done.
     remote: Compressing objects: 100% (483/483), done.
     remote: Total 543 (delta 144), reused 307 (delta 39)
     Receiving objects: 100% (543/543), 520.55 KiB, done.
     Resolving deltas: 100% (144/144), done.                

Supported Board Support Packages (BSPs): Similar considerations exist for BSPs. You can get set up for BSP development one of two ways: tarball extraction or with a local Git repository. Regardless of the method you use, 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-n450
                

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 in the Yocto Application Development Toolkit (ADT) User’s Guide for more information.

Source Repositories: This area contains IDE Plugins, Matchbox, Poky, Poky Support, Tools, Yocto Linux Kernel, and Yocto Metadata Layers. You can create Git repositories for each of these areas.

Index of /releases: This area contains an index of downloads such as the Eclipse™ Yocto Plug-in, miscellaneous support, Poky, pseudo, cross-development toolchains, and all released versions of Yocto Project in the form of images or tarballs. Downloading and extracting these files does not produce a Git repository but rather a snapshot of a particular release or image.

Yocto Project Download Page This page on the Yocto Project website allows you to download any Yocto Project release or Board Support Package (BSP) in tarball form. The tarballs are similar to those found in the Index of /releases: area.

Append Files: Files that append build information to a recipe file. Information in append files overrides the information in the similarly-named recipe file. Append files use the .bbappend filename suffix.

BitBake: The task executor and scheduler used by the Yocto Project to build images. For more information on BitBake, see the BitBake documentation.

Classes: Files that provide for logic encapsulation and inheritance allowing commonly used patterns to be defined once and easily used in multiple recipes. Class files end with the .bbclass filename extension.

Configuration File: Configuration information in various .conf files provides global definitions of variables. The conf/local.conf configuration file in the Yocto Project build directory contains user-defined variables that affect each build. The meta-yocto/conf/distro/poky.conf configuration file defines Yocto ‘distro’ configuration variables used only when building with this policy. Machine configuration files, which are located throughout the Yocto Project file structure, define variables for specific hardware and are only used when building for that target (e.g. the machine/beagleboard.conf configuration file defines variables for the Texas Instruments ARM Cortex-A8 development board). Configuration files end with a .conf filename extension.

Cross-Development Toolchain: A collection of software development tools and utilities that allow you to develop software for targeted architectures. This toolchain contains cross-compilers, linkers, and debuggers that are specific to an architecture. You can use the Yocto Project to build cross-development toolchains in tarball form that when unpacked contain the development tools you need to cross-compile and test your software. The Yocto Project ships with images that contain toolchains for supported architectures as well. Sometimes this toolchain is referred to as the meta-toolchain.

Image: An image is the result produced when BitBake processes a given collection of recipes and related metadata. Images are the binary output that runs on specific hardware and for specific use cases. For a list of the supported image types that the Yocto Project provides, see the "Reference: Images" appendix in The Yocto Project Reference Manual.

Layer: A collection of recipes representing the core, a BSP, or an application stack.

Metadata: The files that BitBake parses when building an image. Metadata includes recipes, classes, and configuration files.

OE-Core: A core set of metadata originating with OpenEmbedded (OE) that is shared between OE and the Yocto Project. This metadata is found in the meta directory of the Yocto Project files.

Package: The packaged output from a baked recipe. A package is generally the compiled binaries produced from the recipe's sources. You ‘bake’ something by running it through BitBake.

Poky: The build tool that the Yocto Project uses to create images.

Recipe: A set of instructions for building packages. A recipe describes where you get source code and which patches to apply. Recipes describe dependencies for libraries or for other recipes, and they also contain configuration and compilation options. Recipes contain the logical unit of execution, the software/images to build, and use the .bb file extension.

Tasks: Arbitrary groups of software Recipes. You simply use Tasks to hold recipes that, when built, usually accomplish a single task. For example, a task could contain the recipes for a company’s proprietary or value-add software. Or, the task could contain the recipes that enable graphics. A task is really just another recipe. Because task files are recipes, they end with the .bb filename extension.

Upstream: 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.

Yocto Project Files: This term refers to the directory structure created as a result of downloading and unpacking a Yocto Project release tarball or setting up a Git repository by cloning git://git.yoctoproject.org/poky. Sometimes the term "the Yocto Project Files structure" is used as well.

The Yocto Project files contain BitBake, Documentation, metadata and other files that all support the development environment. Consequently, you must have the Yocto Project files in place on your development system in order to do any development using the Yocto Project.

The name of the top-level directory of the Yocto Project file structure is derived from the Yocto Project release tarball. For example, downloading and unpacking poky-edison-6.0.tar.bz2 results in a Yocto Project file structure whose Yocto Project source directory is named poky-edison-6.0. If you create a Git repository, then you can name the repository anything you like.

You can find instruction on how to set up the Yocto Project files on your host development system by reading the "Getting Setup" section.

Yocto Project Build Directory: This term refers to the area used by the Yocto Project for builds. The area is created when you source the Yocto Project setup environment script that is found in the Yocto Project files area. (e.g. oe-init-build-env). You can create the Yocto Project build directory anywhere you want on your development system. Here is an example that creates the directory in mybuilds and names the Yocto Project build directory YP-6.0:

 
     $ source poky-edison-6.0/oe-init-build-env $HOME/mybuilds/YP-6.0
            

If you don't specifically name the directory, BitBake creates it in the current directory and uses the name build. Also, if you supply an existing directory, then BitBake uses that directory as the Yocto Project build directory and populates the build hierarchy beneath it.

Open source license history

Free software license history

git init: Initializes an empty Git repository. You cannot use Git commands unless you have a .git repository.

git clone: Creates a clone of a repository. During collaboration, this command allows you to create a local repository that is on equal footing with a fellow developer’s repository.

git add: Adds updated file contents to the index that Git uses to track changes. You must add all files that have changed before you can commit them.

git commit: Creates a “commit” that documents the changes you made. Commits are used for historical purposes, for determining if a maintainer of a project will allow the change, and for ultimately pushing the change from your local Git repository into the project’s upstream (or master) repository.

git status: Reports any modified files that possibly need to be added and committed.

git checkout <branch-name>: Changes your working branch. This command is analogous to “cd”.

git checkout –b <working-branch>: Creates a working branch on your local machine where you can isolate work. It is a good idea to use local branches when adding specific features or changes. This way if you don’t like what you have done you can easily get rid of the work.

git branch: Reports existing branches and tells you which branch in which you are currently working.

git branch -D <branch-name>: Deletes an existing branch. You need to be in a branch other than the one you are deleting in order to delete <branch-name>.

git pull: Retrieves information from an upstream Git repository and places it in your local Git repository. You use this command to make sure you are synchronized with the repository from which you are basing changes (.e.g. the master repository).

git push: Sends all your local changes you have committed to an upstream Git repository (e.g. a contribution repository). The maintainer of the project draws from these repositories when adding your changes to the project’s master repository.

git merge: Combines or adds changes from one local branch of your repository with another branch. When you create a local Git repository, the default branch is named “master”. A typical workflow is to create a temporary branch for isolated work, make and commit your changes, switch to your local master branch, merge the changes from the temporary branch into the local master branch, and then delete the temporary branch.

git cherry-pick: Choose and apply specific commits from one branch into another branch. There are times when you might not be able to merge all the changes in one branch with another but need to pick out certain ones.

gitk: Provides a GUI view of the branches and changes in your local Git repository. This command is a good way to graphically see where things have diverged in your local repository.

git log: Reports a history of your changes to the repository.

git diff: Displays line-by-line differences between your local working files and the same files in the upstream Git repository that your branch currently tracks.

Make Small Changes: It is best to keep the changes you commit small as compared to bundling many disparate changes into a single commit. This practice not only keeps things manageable but also allows the maintainer to more easily include or refuse changes.

It is also good practice to leave the repository in a state that allows you to still successfully build your project. In other words, do not commit half of a feature, then add the other half in a separate, later commit. Each commit should take you from one buildable project state to another buildable state.

Use Branches Liberally: It is very easy to create, use, and delete local branches in your working Git repository. You can name these branches anything you like. It is helpful to give them names associated with the particular feature or change on which you are working. Once you are done with a feature or change, simply discard the branch.

Merge Changes: The git merge command allows you to take the changes from one branch and fold them into another branch. This process is especially helpful when more than a single developer might be working on different parts of the same feature. Merging changes also automatically identifies any collisions or “conflicts” that might happen as a result of the same lines of code being altered by two different developers.

Manage Branches: Because branches are easy to use, you should use a system where branches indicate varying levels of code readiness. For example, you can have a “work” branch to develop in, a “test” branch where the code or change is tested, a “stage” branch where changes are ready to be committed, and so forth. As your project develops, you can merge code across the branches to reflect ever-increasing stable states of the development.

Use Push and Pull: The push-pull workflow is based on the concept of developers “pushing” local commits to a remote repository, which is usually a contribution repository. This workflow is also based on developers “pulling” known states of the project down into their local development repositories. The workflow easily allows you to pull changes submitted by other developers from the upstream repository into your work area ensuring that you have the most recent software on which to develop. The Yocto Project has two scripts named create-pull-request and send-pull-request that ship with the release to facilitate this workflow. You can find these scripts in the local Yocto Project files Git repository in the scripts directory.

Patch Workflow: This workflow allows you to notify the maintainer through an email that you have a change (or patch) you would like considered for the "master" branch of the Git repository. To send this type of change you format the patch and then send the email using the Git commands git format-patch and git send-email. You can find information on how to submit later in this chapter.

The Yocto Project follows a bug-naming convention: [YOCTO #<number>], where <number> is the assigned defect ID used in Bugzilla. So, for example, a valid way to refer to a defect when creating a commit comment would be [YOCTO #1011]. This convention becomes important if you are submitting patches against the Yocto Project code itself. See the following section for more information.

Defects for Yocto Project fall into one of four classifications: Yocto Projects, Infrastructure, Poky, and Yocto Metadata Layers.

For defects against the Yocto Project build system Poky, send your patch to the http://lists.yoctoproject.org/listinfo/poky mailing list. This mailing list corresponds to issues that are not specific to the Yocto Project but are part of the OE-core. For example, a defect against anything in the meta layer or the BitBake Manual could be sent to this mailing list.

For defects against Yocto-specific layers, tools, and Yocto Project documentation use the http://lists.yoctoproject.org/listinfo/yocto mailing list. This mailing list corresponds to Yocto-specific areas such as meta-yocto, meta-intel, linux-yocto, and documentation.

Provide a single-line, short summary of the change. This summary is typically viewable by source control systems. Thus, providing something short and descriptive that gives the reader a summary of the change is useful when viewing a list of many commits.

For the body of the commit message, provide detailed information that describes what you changed, why you made the change, and the approach you used. Provide as much detail as you can in the body of the commit message.

If the change addresses a specific bug or issue that is associated with a bug-tracking ID, prefix your detailed description with the bug or issue ID. For example, the Yocto Project tracks bugs using a bug-naming convention. Any commits that address a bug must start with the bug ID in the description as follows:

     YOCTO #<bug-id>:  <Detailed description of commit>