Yocto Project Reference Manual

Richard Purdie

Linux Foundation

Permission is granted to copy, distribute and/or modify this document under the terms of the Creative Commons Attribution-Share Alike 2.0 UK: England & Wales as published by Creative Commons.

Note

Due to production processes, there could be differences between the Yocto Project documentation bundled in the release tarball and the Yocto Project Reference Manual on the Yocto Project website. For the latest version of this manual, see the manual on the website.
Revision History
Revision 4.0+git 24 November 2010
Released with the Yocto Project 0.9 Release
Revision 1.0 6 April 2011
Released with the Yocto Project 1.0 Release.
Revision 1.0.1 23 May 2011
Released with the Yocto Project 1.0.1 Release.
Revision 1.1 6 October 2011
Released with the Yocto Project 1.1 Release.
Revision 1.2 April 2012
Released with the Yocto Project 1.2 Release.
Revision 1.3 October 2012
Released with the Yocto Project 1.3 Release.
Revision 1.4 April 2013
Released with the Yocto Project 1.4 Release.
Revision 1.5 October 2013
Released with the Yocto Project 1.5 Release.

Table of Contents

1. Introduction
1.1. Introduction
1.2. Documentation Overview
1.3. System Requirements
1.3.1. Supported Linux Distributions
1.3.2. Required Packages for the Host Development System
1.3.3. Required Git, tar, and Python Versions
1.4. Obtaining the Yocto Project
1.5. Development Checkouts
2. Using the Yocto Project
2.1. Running a Build
2.1.1. Build Overview
2.1.2. Building an Image Using GPL Components
2.2. Installing and Using the Result
2.3. Debugging Build Failures
2.3.1. Task Failures
2.3.2. Running Specific Tasks
2.3.3. Dependency Graphs
2.3.4. General BitBake Problems
2.3.5. Development Host System Issues
2.3.6. Building with No Dependencies
2.3.7. Variables
2.3.8. Recipe Logging Mechanisms
2.3.9. Other Tips
2.4. Maintaining Build Output Quality
2.4.1. Enabling and Disabling Build History
2.4.2. Understanding What the Build History Contains
3. A Closer Look at the Yocto Project Development Environment
3.1. User Configuration
3.2. Metadata, Machine Configuration, and Policy Configuration
3.2.1. Distro Layer
3.2.2. BSP Layer
3.2.3. Software Layer
3.3. Sources
3.3.1. Upstream Project Releases
3.3.2. Local Projects
3.3.3. Source Control Managers (Optional)
3.3.4. Source Mirror(s)
3.4. Package Feeds
3.5. BitBake
3.5.1. Source Fetching
3.5.2. Patching
3.5.3. Configuration and Compilation
3.5.4. Package Splitting
3.5.5. Image Generation
3.5.6. SDK Generation
3.6. Images
3.7. Application Development SDK
4. Technical Details
4.1. Yocto Project Components
4.1.1. BitBake
4.1.2. Metadata (Recipes)
4.1.3. Classes
4.1.4. Configuration
4.2. Cross-Development Toolchain Generation
4.3. Shared State Cache
4.3.1. Overall Architecture
4.3.2. Checksums (Signatures)
4.3.3. Shared State
4.3.4. Tips and Tricks
4.4. x32
4.4.1. Support
4.4.2. Stabilizing and Completing x32
4.4.3. Using x32 Right Now
4.5. Wayland
4.5.1. Support
4.5.2. Enabling Wayland in an Image
4.5.3. Running Weston
4.6. Licenses
4.6.1. Tracking License Changes
4.6.2. Enabling Commercially Licensed Recipes
5. Migrating to a Newer Yocto Project Release
5.1. Moving to the Yocto Project 1.3 Release
5.1.1. Local Configuration
5.1.2. Recipes
5.1.3. Linux Kernel Naming
5.2. Moving to the Yocto Project 1.4 Release
5.2.1. BitBake
5.2.2. Build Behavior
5.2.3. Proxies and Fetching Source
5.2.4. Custom Interfaces File (netbase change)
5.2.5. Remote Debugging
5.2.6. Variables
5.2.7. Target Package Management with RPM
5.2.8. Recipes Moved
5.2.9. Removals and Renames
5.3. Moving to the Yocto Project 1.5 Release
5.3.1. Host Dependency Changes
5.3.2. atom-pc Board Support Package (BSP)
5.3.3. BitBake
5.3.4. QA Warnings
5.3.5. Directory Layout Changes
5.3.6. Shortened Git SRCREV Values
5.3.7. IMAGE_FEATURES
5.3.8. /run
5.3.9. Removal of Package Manager Database Within Image Recipes
5.3.10. Images Now Rebuild Only on Changes Instead of Every Time
5.3.11. Task Recipes
5.3.12. BusyBox
5.3.13. Automated Image Testing
5.3.14. Build History
5.3.15. udev
5.3.16. Removed and Renamed Recipes
5.3.17. Other Changes
6. Source Directory Structure
6.1. Top-Level Core Components
6.1.1. bitbake/
6.1.2. build/
6.1.3. documentation
6.1.4. meta/
6.1.5. meta-yocto/
6.1.6. meta-yocto-bsp/
6.1.7. meta-hob/
6.1.8. meta-skeleton/
6.1.9. scripts/
6.1.10. oe-init-build-env
6.1.11. oe-init-build-env-memres
6.1.12. LICENSE, README, and README.hardware
6.2. The Build Directory - build/
6.2.1. build/pseudodone
6.2.2. build/conf/local.conf
6.2.3. build/conf/bblayers.conf
6.2.4. build/conf/sanity_info
6.2.5. build/downloads/
6.2.6. build/sstate-cache/
6.2.7. build/tmp/
6.2.8. build/tmp/buildstats/
6.2.9. build/tmp/cache/
6.2.10. build/tmp/deploy/
6.2.11. build/tmp/deploy/deb/
6.2.12. build/tmp/deploy/rpm/
6.2.13. build/tmp/deploy/licenses/
6.2.14. build/tmp/deploy/images/
6.2.15. build/tmp/deploy/ipk/
6.2.16. build/tmp/sysroots/
6.2.17. build/tmp/stamps/
6.2.18. build/tmp/log/
6.2.19. build/tmp/pkgdata/
6.2.20. build/tmp/work/
6.3. The Metadata - meta/
6.3.1. meta/classes/
6.3.2. meta/conf/
6.3.3. meta/conf/machine/
6.3.4. meta/conf/distro/
6.3.5. meta/files/
6.3.6. meta/lib/
6.3.7. meta/recipes-bsp/
6.3.8. meta/recipes-connectivity/
6.3.9. meta/recipes-core/
6.3.10. meta/recipes-devtools/
6.3.11. meta/recipes-extended/
6.3.12. meta/recipes-gnome/
6.3.13. meta/recipes-graphics/
6.3.14. meta/recipes-kernel/
6.3.15. meta/recipes-lsb4/
6.3.16. meta/recipes-multimedia/
6.3.17. meta/recipes-qt/
6.3.18. meta/recipes-rt/
6.3.19. meta/recipes-sato/
6.3.20. meta/recipes-support/
6.3.21. meta/site/
6.3.22. meta/recipes.txt
7. BitBake
7.1. Parsing
7.2. Preferences and Providers
7.3. Dependencies
7.4. The Task List
7.5. Running a Task
7.6. BitBake Command Line
7.7. Fetchers
8. Classes
8.1. The base Class - base.bbclass
8.2. Autotooled Packages - autotools.bbclass
8.3. Alternatives - update-alternatives.bbclass
8.4. Initscripts - update-rc.d.bbclass
8.5. binconfig.bbclass
8.6. Debian Renaming - debian.bbclass
8.7. Pkg-config - pkgconfig.bbclass
8.8. Archiving Sources - archive*.bbclass
8.9. Perl Modules - cpan.bbclass
8.10. Python Extensions - distutils.bbclass
8.11. Developer Shell - devshell.bbclass
8.12. Package Groups - packagegroup.bbclass
8.13. Packaging - package*.bbclass
8.14. Building Kernels - kernel.bbclass
8.15. Creating Images - image.bbclass and rootfs*.bbclass
8.16. Host System Sanity Checks - sanity.bbclass
8.17. insane.bbclass
8.18. Removing Work Files During the Build - rm_work.bbclass
8.19. Autotools Configuration Data Cache - siteinfo.bbclass
8.20. Adding Users - useradd.bbclass
8.21. externalsrc.bbclass
8.22. testimage.bbclass
8.23. Other Classes
9. Images
10. Reference: Features
10.1. Distro
10.2. Machine
10.3. Images
10.4. Feature Backfilling
11. Variables Glossary
Glossary
12. Variable Context
12.1. Configuration
12.1.1. Distribution (Distro)
12.1.2. Machine
12.1.3. Local
12.2. Recipes
12.2.1. Required
12.2.2. Dependencies
12.2.3. Paths
12.2.4. Extra Build Information
13. FAQ
14. Contributing to the Yocto Project
14.1. Introduction
14.2. Tracking Bugs
14.3. Mailing lists
14.4. Internet Relay Chat (IRC)
14.5. Links
14.6. Contributions