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

For the latest version of this manual associated with this Yocto Project release, see the Yocto Project Reference Manual from the Yocto Project 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.
Revision 1.5.1 January 2014
Released with the Yocto Project 1.5.1 Release.
Revision 1.6 April 2014
Released with the Yocto Project 1.6 Release.
Revision 1.6.1 July 2014
Released with the Yocto Project 1.6.1 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. 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
5.4. Moving to the Yocto Project 1.6 Release
5.4.1. archiver Class
5.4.2. Packaging Changes
5.4.3. BitBake
5.4.4. Changes to Variables
5.4.5. Directory Layout Changes
5.4.6. Package Test (ptest)
5.4.7. Build Changes
5.4.8. qemu-native
5.4.9. core-image-basic
5.4.10. Licensing
5.4.11. CFLAGS Options
5.4.12. Custom Image Output Types
5.4.13. Tasks
5.4.14. update-alternative Provider
5.4.15. virtclass Overrides
5.4.16. Removed and Renamed Recipes
5.4.17. Removed Classes
5.4.18. Reference Board Support Packages (BSPs)
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-selftest/
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/buildhistory
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/ipk/
6.2.14. build/tmp/deploy/licenses/
6.2.15. build/tmp/deploy/images/
6.2.16. build/tmp/deploy/sdk/
6.2.17. build/tmp/sstate-control/
6.2.18. build/tmp/sysroots/
6.2.19. build/tmp/stamps/
6.2.20. build/tmp/log/
6.2.21. build/tmp/work/
6.2.22. build/tmp/work-shared/
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/conf/machine-sdk/
6.3.6. meta/files/
6.3.7. meta/lib/
6.3.8. meta/recipes-bsp/
6.3.9. meta/recipes-connectivity/
6.3.10. meta/recipes-core/
6.3.11. meta/recipes-devtools/
6.3.12. meta/recipes-extended/
6.3.13. meta/recipes-gnome/
6.3.14. meta/recipes-graphics/
6.3.15. meta/recipes-kernel/
6.3.16. meta/recipes-lsb4/
6.3.17. meta/recipes-multimedia/
6.3.18. meta/recipes-qt/
6.3.19. meta/recipes-rt/
6.3.20. meta/recipes-sato/
6.3.21. meta/recipes-support/
6.3.22. meta/site/
6.3.23. meta/recipes.txt
7. Classes
7.1. allarch.bbclass
7.2. archiver.bbclass
7.3. autotools.bbclass
7.4. autotools-brokensep.bbclass
7.5. base.bbclass
7.6. bin_package.bbclass
7.7. binconfig.bbclass
7.8. blacklist.bbclass
7.9. boot-directdisk.bbclass
7.10. bootimg.bbclass
7.11. bugzilla.bbclass
7.12. buildhistory.bbclass
7.13. buildstats.bbclass
7.14. ccache.bbclass
7.15. chrpath.bbclass
7.16. clutter.bbclass
7.17. cmake.bbclass
7.18. cml1.bbclass
7.19. copyleft_compliance.bbclass
7.20. core-image.bbclass
7.21. cpan.bbclass
7.22. cross.bbclass
7.23. cross-canadian.bbclass
7.24. crosssdk.bbclass
7.25. debian.bbclass
7.26. deploy.bbclass
7.27. devshell.bbclass
7.28. distro_features_check.bbclass
7.29. distrodata.bbclass
7.30. distutils.bbclass
7.31. distutils3.bbclass
7.32. externalsrc.bbclass
7.33. extrausers.bbclass
7.34. fontcache.bbclass
7.35. gconf.bbclass
7.36. gettext.bbclass
7.37. gnome.bbclass
7.38. gnomebase.bbclass
7.39. grub-efi.bbclass
7.40. gsettings.bbclass
7.41. gtk-doc.bbclass
7.42. gtk-icon-cache.bbclass
7.43. gtk-immodules-cache.bbclass
7.44. gzipnative.bbclass
7.45. icecc.bbclass
7.46. image.bbclass
7.47. image_types.bbclass
7.48. image_types_uboot.bbclass
7.49. image-live.bbclass
7.50. image-mklibs.bbclass
7.51. image-prelink.bbclass
7.52. image-swab.bbclass
7.53. image-vmdk.bbclass
7.54. insane.bbclass
7.55. insserv.bbclass
7.56. kernel.bbclass
7.57. kernel-arch.bbclass
7.58. kernel-module-split.bbclass
7.59. kernel-yocto.bbclass
7.60. lib_package.bbclass
7.61. license.bbclass
7.62. linux-kernel-base.bbclass
7.63. logging.bbclass
7.64. meta.bbclass
7.65. metadata_scm.bbclass
7.66. mime.bbclass
7.67. mirrors.bbclass
7.68. module.bbclass
7.69. module-base.bbclass
7.70. multilib*.bbclass
7.71. native.bbclass
7.72. nativesdk.bbclass
7.73. oelint.bbclass
7.74. own-mirrors.bbclass
7.75. package.bbclass
7.76. package_deb.bbclass
7.77. package_ipk.bbclass
7.78. package_rpm.bbclass
7.79. package_tar.bbclass
7.80. packagedata.bbclass
7.81. packagegroup.bbclass
7.82. packageinfo.bbclass
7.83. patch.bbclass
7.84. perlnative.bbclass
7.85. pixbufcache.bbclass
7.86. pkgconfig.bbclass
7.87. populate_sdk.bbclass
7.88. populate_sdk_*.bbclass
7.89. prexport.bbclass
7.90. primport.bbclass
7.91. prserv.bbclass
7.92. ptest.bbclass
7.93. python-dir.bbclass
7.94. pythonnative.bbclass
7.95. qemu.bbclass
7.96. qmake*.bbclass
7.97. qt4*.bbclass
7.98. relocatable.bbclass
7.99. report-error.bbclass
7.100. rm_work.bbclass
7.101. rootfs*.bbclass
7.102. sanity.bbclass
7.103. scons.bbclass
7.104. sdl.bbclass
7.105. setuptools.bbclass
7.106. setuptools3.bbclass
7.107. sip.bbclass
7.108. siteconfig.bbclass
7.109. siteinfo.bbclass
7.110. spdx.bbclass
7.111. sstate.bbclass
7.112. staging.bbclass
7.113. syslinux.bbclass
7.114. systemd.bbclass
7.115. terminal.bbclass
7.116. testimage.bbclass
7.117. tinderclient.bbclass
7.118. toaster.bbclass
7.119. toolchain-scripts.bbclass
7.120. typecheck.bbclass
7.121. uboot-config.bbclass
7.122. update-alternatives.bbclass
7.123. update-rc.d.bbclass
7.124. useradd.bbclass
7.125. useradd-staticids.bbclass
7.126. utility-tasks.bbclass
7.127. utils.bbclass
7.128. vala.bbclass
7.129. waf.bbclass
8. Images
9. Features
9.1. Machine Features
9.2. Distro Features
9.3. Image Features
9.4. Feature Backfilling
10. Variables Glossary
Glossary
11. Variable Context
11.1. Configuration
11.1.1. Distribution (Distro)
11.1.2. Machine
11.1.3. Local
11.2. Recipes
11.2.1. Required
11.2.2. Dependencies
11.2.3. Paths
11.2.4. Extra Build Information
12. FAQ
13. Contributing to the Yocto Project
13.1. Introduction
13.2. Tracking Bugs
13.3. Mailing lists
13.4. Internet Relay Chat (IRC)
13.5. Links
13.6. Contributions