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.

Manual Notes

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.7 October 2014
Released with the Yocto Project 1.7 Release.
Revision 1.8 April 2015
Released with the Yocto Project 1.8 Release.
Revision 2.0 October 2015
Released with the Yocto Project 2.0 Release.
Revision 2.1 April 2016
Released with the Yocto Project 2.1 Release.
Revision 2.2 October 2016
Released with the Yocto Project 2.2 Release.
Revision 2.3 May 2017
Released with the Yocto Project 2.3 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 Tools and Techniques
2.3.1. Viewing Logs from Failed Tasks
2.3.2. Viewing Variable Values
2.3.3. Viewing Package Information with oe-pkgdata-util
2.3.4. Viewing Dependencies Between Recipes and Tasks
2.3.5. Viewing Task Variable Dependencies
2.3.6. Running Specific Tasks
2.3.7. Checking for Missing Build-Time Dependencies
2.3.8. General BitBake Problems
2.3.9. Development Host System Issues
2.3.10. Building with No Dependencies
2.3.11. Recipe Logging Mechanisms
2.3.12. 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
2.5. Speeding Up the Build
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.5.7. Stamp Files and the Rerunning of Tasks
3.5.8. Setscene Tasks and Shared State
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. Automatically Added Runtime Dependencies
4.5. Fakeroot and Pseudo
4.6. x32
4.6.1. Support
4.6.2. Completing x32
4.6.3. Using x32 Right Now
4.7. Wayland
4.7.1. Support
4.7.2. Enabling Wayland in an Image
4.7.3. Running Weston
4.8. Licenses
4.8.1. Tracking License Changes
4.8.2. Enabling Commercially Licensed Recipes
5. Yocto Project Releases and the Stable Release Process
5.1. Major and Minor Release Cadence
5.2. Major Release Codenames
5.3. Stable Release Process
5.4. Testing and Quality Assurance
6. Migrating to a Newer Yocto Project Release
6.1. General Migration Considerations
6.2. Moving to the Yocto Project 1.3 Release
6.2.1. Local Configuration
6.2.2. Recipes
6.2.3. Linux Kernel Naming
6.3. Moving to the Yocto Project 1.4 Release
6.3.1. BitBake
6.3.2. Build Behavior
6.3.3. Proxies and Fetching Source
6.3.4. Custom Interfaces File (netbase change)
6.3.5. Remote Debugging
6.3.6. Variables
6.3.7. Target Package Management with RPM
6.3.8. Recipes Moved
6.3.9. Removals and Renames
6.4. Moving to the Yocto Project 1.5 Release
6.4.1. Host Dependency Changes
6.4.2. atom-pc Board Support Package (BSP)
6.4.3. BitBake
6.4.4. QA Warnings
6.4.5. Directory Layout Changes
6.4.6. Shortened Git SRCREV Values
6.4.7. IMAGE_FEATURES
6.4.8. /run
6.4.9. Removal of Package Manager Database Within Image Recipes
6.4.10. Images Now Rebuild Only on Changes Instead of Every Time
6.4.11. Task Recipes
6.4.12. BusyBox
6.4.13. Automated Image Testing
6.4.14. Build History
6.4.15. udev
6.4.16. Removed and Renamed Recipes
6.4.17. Other Changes
6.5. Moving to the Yocto Project 1.6 Release
6.5.1. archiver Class
6.5.2. Packaging Changes
6.5.3. BitBake
6.5.4. Changes to Variables
6.5.5. Package Test (ptest)
6.5.6. Build Changes
6.5.7. qemu-native
6.5.8. core-image-basic
6.5.9. Licensing
6.5.10. CFLAGS Options
6.5.11. Custom Image Output Types
6.5.12. Tasks
6.5.13. update-alternative Provider
6.5.14. virtclass Overrides
6.5.15. Removed and Renamed Recipes
6.5.16. Removed Classes
6.5.17. Reference Board Support Packages (BSPs)
6.6. Moving to the Yocto Project 1.7 Release
6.6.1. Changes to Setting QEMU PACKAGECONFIG Options in local.conf
6.6.2. Minimum Git version
6.6.3. Autotools Class Changes
6.6.4. Binary Configuration Scripts Disabled
6.6.5. eglibc 2.19 Replaced with glibc 2.20
6.6.6. Kernel Module Autoloading
6.6.7. QA Check Changes
6.6.8. Removed Recipes
6.6.9. Miscellaneous Changes
6.7. Moving to the Yocto Project 1.8 Release
6.7.1. Removed Recipes
6.7.2. BlueZ 4.x / 5.x Selection
6.7.3. Kernel Build Changes
6.7.4. SSL 3.0 is Now Disabled in OpenSSL
6.7.5. Default Sysroot Poisoning
6.7.6. Rebuild Improvements
6.7.7. QA Check and Validation Changes
6.7.8. Miscellaneous Changes
6.8. Moving to the Yocto Project 2.0 Release
6.8.1. GCC 5
6.8.2. Gstreamer 0.10 Removed
6.8.3. Removed Recipes
6.8.4. BitBake datastore improvements
6.8.5. Shell Message Function Changes
6.8.6. Extra Development/Debug Package Cleanup
6.8.7. Recipe Maintenance Tracking Data Moved to OE-Core
6.8.8. Automatic Stale Sysroot File Cleanup
6.8.9. linux-yocto Kernel Metadata Repository Now Split from Source
6.8.10. Additional QA checks
6.8.11. Miscellaneous Changes
6.9. Moving to the Yocto Project 2.1 Release
6.9.1. Variable Expansion in Python Functions
6.9.2. Overrides Must Now be Lower-Case
6.9.3. Expand Parameter to getVar() and getVarFlag() is Now Mandatory
6.9.4. Makefile Environment Changes
6.9.5. libexecdir Reverted to ${prefix}/libexec
6.9.6. ac_cv_sizeof_off_t is No Longer Cached in Site Files
6.9.7. Image Generation is Now Split Out from Filesystem Generation
6.9.8. Removed Recipes
6.9.9. Class Changes
6.9.10. Build System User Interface Changes
6.9.11. ADT Removed
6.9.12. Poky Reference Distribution Changes
6.9.13. Packaging Changes
6.9.14. Tuning File Changes
6.9.15. Supporting GObject Introspection
6.9.16. Miscellaneous Changes
6.10. Moving to the Yocto Project 2.2 Release
6.10.1. Minimum Kernel Version
6.10.2. Staging Directories in Sysroot Has Been Simplified
6.10.3. Removal of Old Images and Other Files in tmp/deploy Now Enabled
6.10.4. Python Changes
6.10.5. uClibc Replaced by musl
6.10.6. ${B} No Longer Default Working Directory for Tasks
6.10.7. runqemu Ported to Python
6.10.8. Default Linker Hash Style Changed
6.10.9. KERNEL_IMAGE_BASE_NAME no Longer Uses KERNEL_IMAGETYPE
6.10.10. BitBake Changes
6.10.11. Swabber has Been Removed
6.10.12. Removed Recipes
6.10.13. Removed Classes
6.10.14. Minor Packaging Changes
6.10.15. Miscellaneous Changes
6.11. Moving to the Yocto Project 2.3 Release
6.11.1. Sysroots
6.11.2. PATH Variable
6.11.3. Changes to Functions
6.11.4. Dependency Tree Information
6.11.5. BitBake Changes
6.11.6. Absolute Symbolic Links
6.11.7. GPLv2 Versions of GPLv3 Recipes Moved
6.11.8. Package Management Changes
7. Source Directory Structure
7.1. Top-Level Core Components
7.1.1. bitbake/
7.1.2. build/
7.1.3. documentation/
7.1.4. meta/
7.1.5. meta-poky/
7.1.6. meta-yocto-bsp/
7.1.7. meta-selftest/
7.1.8. meta-skeleton/
7.1.9. scripts/
7.1.10. oe-init-build-env
7.1.11. oe-init-build-env-memres
7.1.12. LICENSE, README, and README.hardware
7.2. The Build Directory - build/
7.2.1. build/buildhistory
7.2.2. build/conf/local.conf
7.2.3. build/conf/bblayers.conf
7.2.4. build/conf/sanity_info
7.2.5. build/downloads/
7.2.6. build/sstate-cache/
7.2.7. build/tmp/
7.2.8. build/tmp/buildstats/
7.2.9. build/tmp/cache/
7.2.10. build/tmp/deploy/
7.2.11. build/tmp/deploy/deb/
7.2.12. build/tmp/deploy/rpm/
7.2.13. build/tmp/deploy/ipk/
7.2.14. build/tmp/deploy/licenses/
7.2.15. build/tmp/deploy/images/
7.2.16. build/tmp/deploy/sdk/
7.2.17. build/tmp/sstate-control/
7.2.18. build/tmp/sysroots/
7.2.19. build/tmp/stamps/
7.2.20. build/tmp/log/
7.2.21. build/tmp/work/
7.2.22. build/tmp/work/tunearch/recipename/version/
7.2.23. build/tmp/work-shared/
7.3. The Metadata - meta/
7.3.1. meta/classes/
7.3.2. meta/conf/
7.3.3. meta/conf/machine/
7.3.4. meta/conf/distro/
7.3.5. meta/conf/machine-sdk/
7.3.6. meta/files/
7.3.7. meta/lib/
7.3.8. meta/recipes-bsp/
7.3.9. meta/recipes-connectivity/
7.3.10. meta/recipes-core/
7.3.11. meta/recipes-devtools/
7.3.12. meta/recipes-extended/
7.3.13. meta/recipes-gnome/
7.3.14. meta/recipes-graphics/
7.3.15. meta/recipes-kernel/
7.3.16. meta/recipes-lsb4/
7.3.17. meta/recipes-multimedia/
7.3.18. meta/recipes-rt/
7.3.19. meta/recipes-sato/
7.3.20. meta/recipes-support/
7.3.21. meta/site/
7.3.22. meta/recipes.txt
8. Classes
8.1. allarch.bbclass
8.2. archiver.bbclass
8.3. autotools*.bbclass
8.4. base.bbclass
8.5. bash-completion.bbclass
8.6. bin_package.bbclass
8.7. binconfig.bbclass
8.8. binconfig-disabled.bbclass
8.9. blacklist.bbclass
8.10. bluetooth.bbclass
8.11. bugzilla.bbclass
8.12. buildhistory.bbclass
8.13. buildstats.bbclass
8.14. buildstats-summary.bbclass
8.15. ccache.bbclass
8.16. chrpath.bbclass
8.17. clutter.bbclass
8.18. cmake.bbclass
8.19. cml1.bbclass
8.20. compress_doc.bbclass
8.21. copyleft_compliance.bbclass
8.22. copyleft_filter.bbclass
8.23. core-image.bbclass
8.24. cpan*.bbclass
8.25. cross.bbclass
8.26. cross-canadian.bbclass
8.27. crosssdk.bbclass
8.28. debian.bbclass
8.29. deploy.bbclass
8.30. devshell.bbclass
8.31. distro_features_check.bbclass
8.32. distrodata.bbclass
8.33. distutils*.bbclass
8.34. distutils3*.bbclass
8.35. externalsrc.bbclass
8.36. extrausers.bbclass
8.37. fontcache.bbclass
8.38. fs-uuid.bbclass
8.39. gconf.bbclass
8.40. gettext.bbclass
8.41. gnome.bbclass
8.42. gnomebase.bbclass
8.43. gobject-introspection.bbclass
8.44. grub-efi.bbclass
8.45. gsettings.bbclass
8.46. gtk-doc.bbclass
8.47. gtk-icon-cache.bbclass
8.48. gtk-immodules-cache.bbclass
8.49. gzipnative.bbclass
8.50. icecc.bbclass
8.51. image.bbclass
8.52. image-buildinfo.bbclass
8.53. image_types.bbclass
8.54. image_types_uboot.bbclass
8.55. image-live.bbclass
8.56. image-mklibs.bbclass
8.57. image-prelink.bbclass
8.58. image-vm.bbclass
8.59. image-vmdk.bbclass
8.60. insane.bbclass
8.61. insserv.bbclass
8.62. kernel.bbclass
8.63. kernel-arch.bbclass
8.64. kernel-fitimage.bbclass
8.65. kernel-grub.bbclass
8.66. kernel-module-split.bbclass
8.67. kernel-uboot.bbclass
8.68. kernel-uimage.bbclass
8.69. kernel-yocto.bbclass
8.70. kernelsrc.bbclass
8.71. lib_package.bbclass
8.72. libc*.bbclass
8.73. license.bbclass
8.74. linux-kernel-base.bbclass
8.75. linuxloader.bbclass
8.76. logging.bbclass
8.77. meta.bbclass
8.78. metadata_scm.bbclass
8.79. migrate_localcount.bbclass
8.80. mime.bbclass
8.81. mirrors.bbclass
8.82. module.bbclass
8.83. module-base.bbclass
8.84. multilib*.bbclass
8.85. native.bbclass
8.86. nativesdk.bbclass
8.87. nopackages.bbclass
8.88. npm.bbclass
8.89. oelint.bbclass
8.90. own-mirrors.bbclass
8.91. package.bbclass
8.92. package_deb.bbclass
8.93. package_ipk.bbclass
8.94. package_rpm.bbclass
8.95. package_tar.bbclass
8.96. packagedata.bbclass
8.97. packagegroup.bbclass
8.98. patch.bbclass
8.99. perlnative.bbclass
8.100. pixbufcache.bbclass
8.101. pkgconfig.bbclass
8.102. populate_sdk.bbclass
8.103. populate_sdk_*.bbclass
8.104. prexport.bbclass
8.105. primport.bbclass
8.106. prserv.bbclass
8.107. ptest.bbclass
8.108. ptest-gnome.bbclass
8.109. python-dir.bbclass
8.110. python3native.bbclass
8.111. pythonnative.bbclass
8.112. qemu.bbclass
8.113. recipe_sanity.bbclass
8.114. relocatable.bbclass
8.115. remove-libtool.bbclass
8.116. report-error.bbclass
8.117. rm_work.bbclass
8.118. rootfs*.bbclass
8.119. sanity.bbclass
8.120. scons.bbclass
8.121. sdl.bbclass
8.122. setuptools.bbclass
8.123. setuptools3.bbclass
8.124. sign_rpm.bbclass
8.125. sip.bbclass
8.126. siteconfig.bbclass
8.127. siteinfo.bbclass
8.128. spdx.bbclass
8.129. sstate.bbclass
8.130. staging.bbclass
8.131. syslinux.bbclass
8.132. systemd.bbclass
8.133. systemd-boot.bbclass
8.134. terminal.bbclass
8.135. testimage*.bbclass
8.136. testsdk.bbclass
8.137. texinfo.bbclass
8.138. tinderclient.bbclass
8.139. toaster.bbclass
8.140. toolchain-scripts.bbclass
8.141. typecheck.bbclass
8.142. uboot-config.bbclass
8.143. uninative.bbclass
8.144. update-alternatives.bbclass
8.145. update-rc.d.bbclass
8.146. useradd*.bbclass
8.147. utility-tasks.bbclass
8.148. utils.bbclass
8.149. vala.bbclass
8.150. waf.bbclass
9. Tasks
9.1. Normal Recipe Build Tasks
9.1.1. do_build
9.1.2. do_compile
9.1.3. do_compile_ptest_base
9.1.4. do_configure
9.1.5. do_configure_ptest_base
9.1.6. do_deploy
9.1.7. do_distrodata
9.1.8. do_fetch
9.1.9. do_image
9.1.10. do_image_complete
9.1.11. do_install
9.1.12. do_install_ptest_base
9.1.13. do_package
9.1.14. do_package_qa
9.1.15. do_package_write_deb
9.1.16. do_package_write_ipk
9.1.17. do_package_write_rpm
9.1.18. do_package_write_tar
9.1.19. do_packagedata
9.1.20. do_patch
9.1.21. do_populate_lic
9.1.22. do_populate_sdk
9.1.23. do_populate_sysroot
9.1.24. do_prepare_recipe_sysroot
9.1.25. do_rm_work
9.1.26. do_rm_work_all
9.1.27. do_unpack
9.2. Manually Called Tasks
9.2.1. do_checkpkg
9.2.2. do_checkuri
9.2.3. do_checkuriall
9.2.4. do_clean
9.2.5. do_cleanall
9.2.6. do_cleansstate
9.2.7. do_devpyshell
9.2.8. do_devshell
9.2.9. do_fetchall
9.2.10. do_listtasks
9.2.11. do_package_index
9.3. Image-Related Tasks
9.3.1. do_bootimg
9.3.2. do_bundle_initramfs
9.3.3. do_rootfs
9.3.4. do_testimage
9.3.5. do_testimage_auto
9.3.6. do_vmdkimg
9.4. Kernel-Related Tasks
9.4.1. do_compile_kernelmodules
9.4.2. do_diffconfig
9.4.3. do_kernel_checkout
9.4.4. do_kernel_configcheck
9.4.5. do_kernel_configme
9.4.6. do_kernel_menuconfig
9.4.7. do_kernel_metadata
9.4.8. do_menuconfig
9.4.9. do_savedefconfig
9.4.10. do_shared_workdir
9.4.11. do_sizecheck
9.4.12. do_strip
9.4.13. do_validate_branches
9.5. Miscellaneous Tasks
9.5.1. do_spdx
10. devtool Quick Reference
10.1. Getting Help
10.2. The Workspace Layer Structure
10.3. Adding a New Recipe to the Workspace Layer
10.4. Extracting the Source for an Existing Recipe
10.5. Synchronizing a Recipe's Extracted Source Tree
10.6. Modifying an Existing Recipe
10.7. Edit an Existing Recipe
10.8. Updating a Recipe
10.9. Upgrading a Recipe
10.10. Resetting a Recipe
10.11. Building Your Recipe
10.12. Building Your Image
10.13. Deploying Your Software on the Target Machine
10.14. Removing Your Software from the Target Machine
10.15. Creating the Workspace Layer in an Alternative Location
10.16. Get the Status of the Recipes in Your Workspace
10.17. Search for Available Target Recipes
11. QA Error and Warning Messages
11.1. Introduction
11.2. Errors and Warnings
11.3. Configuring and Disabling QA Checks
12. Images
13. Features
13.1. Machine Features
13.2. Distro Features
13.3. Image Features
13.4. Feature Backfilling
14. Variables Glossary
Glossary
15. Variable Context
15.1. Configuration
15.1.1. Distribution (Distro)
15.1.2. Machine
15.1.3. Local
15.2. Recipes
15.2.1. Required
15.2.2. Dependencies
15.2.3. Paths
15.2.4. Extra Build Information
16. FAQ
17. Contributing to the Yocto Project
17.1. Introduction
17.2. Tracking Bugs
17.3. Mailing lists
17.4. Internet Relay Chat (IRC)
17.5. Links
17.6. Contributions