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

  • This version of the Yocto Project Reference Manual is for the 2.2.4 release of the Yocto Project. To be sure you have the latest version of the manual for this release, go to the Yocto Project documentation page and select the manual from that site. Manuals from the site are more up-to-date than manuals derived from the Yocto Project released TAR files.

  • If you located this manual through a web search, the version of the manual might not be the one you want (e.g. the search might have returned a manual much older than the Yocto Project version with which you are working). You can see all Yocto Project major releases by visiting the Releases page. If you need a version of this manual for a different Yocto Project release, visit the Yocto Project documentation page and select the manual set by using the "ACTIVE RELEASES DOCUMENTATION" or "DOCUMENTS ARCHIVE" pull-down menus.

  • To report any inaccuracies or problems with this manual, send an email to the Yocto Project discussion group at yocto@yoctoproject.com or log into the freenode #yocto channel.

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.2.1 January 2017
Released with the Yocto Project 2.2.1 Release.
Revision 2.2.2 June 2017
Released with the Yocto Project 2.2.2 Release.
Revision 2.2.3 December 2017
Released with the Yocto Project 2.2.3 Release.
Revision 2.2.4 April 2018
Released with the Yocto Project 2.2.4 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. Migrating to a Newer Yocto Project Release
5.1. General Migration Considerations
5.2. Moving to the Yocto Project 1.3 Release
5.2.1. Local Configuration
5.2.2. Recipes
5.2.3. Linux Kernel Naming
5.3. Moving to the Yocto Project 1.4 Release
5.3.1. BitBake
5.3.2. Build Behavior
5.3.3. Proxies and Fetching Source
5.3.4. Custom Interfaces File (netbase change)
5.3.5. Remote Debugging
5.3.6. Variables
5.3.7. Target Package Management with RPM
5.3.8. Recipes Moved
5.3.9. Removals and Renames
5.4. Moving to the Yocto Project 1.5 Release
5.4.1. Host Dependency Changes
5.4.2. atom-pc Board Support Package (BSP)
5.4.3. BitBake
5.4.4. QA Warnings
5.4.5. Directory Layout Changes
5.4.6. Shortened Git SRCREV Values
5.4.7. IMAGE_FEATURES
5.4.8. /run
5.4.9. Removal of Package Manager Database Within Image Recipes
5.4.10. Images Now Rebuild Only on Changes Instead of Every Time
5.4.11. Task Recipes
5.4.12. BusyBox
5.4.13. Automated Image Testing
5.4.14. Build History
5.4.15. udev
5.4.16. Removed and Renamed Recipes
5.4.17. Other Changes
5.5. Moving to the Yocto Project 1.6 Release
5.5.1. archiver Class
5.5.2. Packaging Changes
5.5.3. BitBake
5.5.4. Changes to Variables
5.5.5. Package Test (ptest)
5.5.6. Build Changes
5.5.7. qemu-native
5.5.8. core-image-basic
5.5.9. Licensing
5.5.10. CFLAGS Options
5.5.11. Custom Image Output Types
5.5.12. Tasks
5.5.13. update-alternative Provider
5.5.14. virtclass Overrides
5.5.15. Removed and Renamed Recipes
5.5.16. Removed Classes
5.5.17. Reference Board Support Packages (BSPs)
5.6. Moving to the Yocto Project 1.7 Release
5.6.1. Changes to Setting QEMU PACKAGECONFIG Options in local.conf
5.6.2. Minimum Git version
5.6.3. Autotools Class Changes
5.6.4. Binary Configuration Scripts Disabled
5.6.5. eglibc 2.19 Replaced with glibc 2.20
5.6.6. Kernel Module Autoloading
5.6.7. QA Check Changes
5.6.8. Removed Recipes
5.6.9. Miscellaneous Changes
5.7. Moving to the Yocto Project 1.8 Release
5.7.1. Removed Recipes
5.7.2. BlueZ 4.x / 5.x Selection
5.7.3. Kernel Build Changes
5.7.4. SSL 3.0 is Now Disabled in OpenSSL
5.7.5. Default Sysroot Poisoning
5.7.6. Rebuild Improvements
5.7.7. QA Check and Validation Changes
5.7.8. Miscellaneous Changes
5.8. Moving to the Yocto Project 2.0 Release
5.8.1. GCC 5
5.8.2. Gstreamer 0.10 Removed
5.8.3. Removed Recipes
5.8.4. BitBake datastore improvements
5.8.5. Shell Message Function Changes
5.8.6. Extra Development/Debug Package Cleanup
5.8.7. Recipe Maintenance Tracking Data Moved to OE-Core
5.8.8. Automatic Stale Sysroot File Cleanup
5.8.9. linux-yocto Kernel Metadata Repository Now Split from Source
5.8.10. Additional QA checks
5.8.11. Miscellaneous Changes
5.9. Moving to the Yocto Project 2.1 Release
5.9.1. Variable Expansion in Python Functions
5.9.2. Overrides Must Now be Lower-Case
5.9.3. Expand Parameter to getVar() and getVarFlag() is Now Mandatory
5.9.4. Makefile Environment Changes
5.9.5. libexecdir Reverted to ${prefix}/libexec
5.9.6. ac_cv_sizeof_off_t is No Longer Cached in Site Files
5.9.7. Image Generation is Now Split Out from Filesystem Generation
5.9.8. Removed Recipes
5.9.9. Class Changes
5.9.10. Build System User Interface Changes
5.9.11. ADT Removed
5.9.12. Poky Reference Distribution Changes
5.9.13. Packaging Changes
5.9.14. Tuning File Changes
5.9.15. Supporting GObject Introspection
5.9.16. Miscellaneous Changes
5.10. Moving to the Yocto Project 2.2 Release
5.10.1. Minimum Kernel Version
5.10.2. Staging Directories in Sysroot Has Been Simplified
5.10.3. Removal of Old Images and Other Files in tmp/deploy Now Enabled
5.10.4. Python Changes
5.10.5. uClibc Replaced by musl
5.10.6. ${B} No Longer Default Working Directory for Tasks
5.10.7. runqemu Ported to Python
5.10.8. Default Linker Hash Style Changed
5.10.9. KERNEL_IMAGE_BASE_NAME no Longer Uses KERNEL_IMAGETYPE
5.10.10. BitBake Changes
5.10.11. Swabber has Been Removed
5.10.12. Removed Recipes
5.10.13. Removed Classes
5.10.14. Minor Packaging Changes
5.10.15. Miscellaneous 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-poky/
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-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. Classes
7.1. allarch.bbclass
7.2. archiver.bbclass
7.3. autotools*.bbclass
7.4. base.bbclass
7.5. bash-completion.bbclass
7.6. bin_package.bbclass
7.7. binconfig.bbclass
7.8. binconfig-disabled.bbclass
7.9. blacklist.bbclass
7.10. bluetooth.bbclass
7.11. bugzilla.bbclass
7.12. buildhistory.bbclass
7.13. buildstats.bbclass
7.14. buildstats-summary.bbclass
7.15. ccache.bbclass
7.16. chrpath.bbclass
7.17. clutter.bbclass
7.18. cmake.bbclass
7.19. cml1.bbclass
7.20. compress_doc.bbclass
7.21. copyleft_compliance.bbclass
7.22. copyleft_filter.bbclass
7.23. core-image.bbclass
7.24. cpan*.bbclass
7.25. cross.bbclass
7.26. cross-canadian.bbclass
7.27. crosssdk.bbclass
7.28. debian.bbclass
7.29. deploy.bbclass
7.30. devshell.bbclass
7.31. distro_features_check.bbclass
7.32. distrodata.bbclass
7.33. distutils*.bbclass
7.34. distutils3*.bbclass
7.35. externalsrc.bbclass
7.36. extrausers.bbclass
7.37. fontcache.bbclass
7.38. fs-uuid.bbclass
7.39. gconf.bbclass
7.40. gettext.bbclass
7.41. gnome.bbclass
7.42. gnomebase.bbclass
7.43. gobject-introspection.bbclass
7.44. grub-efi.bbclass
7.45. gsettings.bbclass
7.46. gtk-doc.bbclass
7.47. gtk-icon-cache.bbclass
7.48. gtk-immodules-cache.bbclass
7.49. gzipnative.bbclass
7.50. icecc.bbclass
7.51. image.bbclass
7.52. image-buildinfo.bbclass
7.53. image_types.bbclass
7.54. image_types_uboot.bbclass
7.55. image-live.bbclass
7.56. image-mklibs.bbclass
7.57. image-prelink.bbclass
7.58. image-vm.bbclass
7.59. image-vmdk.bbclass
7.60. insane.bbclass
7.61. insserv.bbclass
7.62. kernel.bbclass
7.63. kernel-arch.bbclass
7.64. kernel-fitimage.bbclass
7.65. kernel-grub.bbclass
7.66. kernel-module-split.bbclass
7.67. kernel-uboot.bbclass
7.68. kernel-uimage.bbclass
7.69. kernel-yocto.bbclass
7.70. kernelsrc.bbclass
7.71. lib_package.bbclass
7.72. libc*.bbclass
7.73. license.bbclass
7.74. linux-kernel-base.bbclass
7.75. linuxloader.bbclass
7.76. logging.bbclass
7.77. meta.bbclass
7.78. metadata_scm.bbclass
7.79. migrate_localcount.bbclass
7.80. mime.bbclass
7.81. mirrors.bbclass
7.82. module.bbclass
7.83. module-base.bbclass
7.84. multilib*.bbclass
7.85. native.bbclass
7.86. nativesdk.bbclass
7.87. nopackages.bbclass
7.88. npm.bbclass
7.89. oelint.bbclass
7.90. own-mirrors.bbclass
7.91. package.bbclass
7.92. package_deb.bbclass
7.93. package_ipk.bbclass
7.94. package_rpm.bbclass
7.95. package_tar.bbclass
7.96. packagedata.bbclass
7.97. packagegroup.bbclass
7.98. patch.bbclass
7.99. perlnative.bbclass
7.100. pixbufcache.bbclass
7.101. pkgconfig.bbclass
7.102. populate_sdk.bbclass
7.103. populate_sdk_*.bbclass
7.104. prexport.bbclass
7.105. primport.bbclass
7.106. prserv.bbclass
7.107. ptest.bbclass
7.108. ptest-gnome.bbclass
7.109. python-dir.bbclass
7.110. python3native.bbclass
7.111. pythonnative.bbclass
7.112. qemu.bbclass
7.113. recipe_sanity.bbclass
7.114. relocatable.bbclass
7.115. remove-libtool.bbclass
7.116. report-error.bbclass
7.117. rm_work.bbclass
7.118. rootfs*.bbclass
7.119. sanity.bbclass
7.120. scons.bbclass
7.121. sdl.bbclass
7.122. setuptools.bbclass
7.123. setuptools3.bbclass
7.124. sign_rpm.bbclass
7.125. sip.bbclass
7.126. siteconfig.bbclass
7.127. siteinfo.bbclass
7.128. spdx.bbclass
7.129. sstate.bbclass
7.130. staging.bbclass
7.131. syslinux.bbclass
7.132. systemd.bbclass
7.133. systemd-boot.bbclass
7.134. terminal.bbclass
7.135. testimage*.bbclass
7.136. testsdk.bbclass
7.137. texinfo.bbclass
7.138. tinderclient.bbclass
7.139. toaster.bbclass
7.140. toolchain-scripts.bbclass
7.141. typecheck.bbclass
7.142. uboot-config.bbclass
7.143. uninative.bbclass
7.144. update-alternatives.bbclass
7.145. update-rc.d.bbclass
7.146. useradd*.bbclass
7.147. utility-tasks.bbclass
7.148. utils.bbclass
7.149. vala.bbclass
7.150. waf.bbclass
8. Tasks
8.1. Normal Recipe Build Tasks
8.1.1. do_build
8.1.2. do_compile
8.1.3. do_compile_ptest_base
8.1.4. do_configure
8.1.5. do_configure_ptest_base
8.1.6. do_deploy
8.1.7. do_distrodata
8.1.8. do_fetch
8.1.9. do_image
8.1.10. do_image_complete
8.1.11. do_install
8.1.12. do_install_ptest_base
8.1.13. do_package
8.1.14. do_package_qa
8.1.15. do_package_write_deb
8.1.16. do_package_write_ipk
8.1.17. do_package_write_rpm
8.1.18. do_package_write_tar
8.1.19. do_packagedata
8.1.20. do_patch
8.1.21. do_populate_lic
8.1.22. do_populate_sdk
8.1.23. do_populate_sysroot
8.1.24. do_rm_work
8.1.25. do_rm_work_all
8.1.26. do_unpack
8.2. Manually Called Tasks
8.2.1. do_checkpkg
8.2.2. do_checkuri
8.2.3. do_checkuriall
8.2.4. do_clean
8.2.5. do_cleanall
8.2.6. do_cleansstate
8.2.7. do_devpyshell
8.2.8. do_devshell
8.2.9. do_fetchall
8.2.10. do_listtasks
8.2.11. do_package_index
8.3. Image-Related Tasks
8.3.1. do_bootimg
8.3.2. do_bundle_initramfs
8.3.3. do_rootfs
8.3.4. do_testimage
8.3.5. do_testimage_auto
8.3.6. do_vmdkimg
8.4. Kernel-Related Tasks
8.4.1. do_compile_kernelmodules
8.4.2. do_diffconfig
8.4.3. do_kernel_checkout
8.4.4. do_kernel_configcheck
8.4.5. do_kernel_configme
8.4.6. do_kernel_link_vmlinux
8.4.7. do_kernel_metadata
8.4.8. do_menuconfig
8.4.9. do_savedefconfig
8.4.10. do_shared_workdir
8.4.11. do_sizecheck
8.4.12. do_strip
8.4.13. do_uboot_mkimage
8.4.14. do_validate_branches
8.5. Miscellaneous Tasks
8.5.1. do_spdx
9. devtool Quick Reference
9.1. Getting Help
9.2. The Workspace Layer Structure
9.3. Adding a New Recipe to the Workspace Layer
9.4. Extracting the Source for an Existing Recipe
9.5. Synchronizing a Recipe's Extracted Source Tree
9.6. Modifying an Existing Recipe
9.7. Edit an Existing Recipe
9.8. Updating a Recipe
9.9. Upgrading a Recipe
9.10. Resetting a Recipe
9.11. Building Your Recipe
9.12. Building Your Image
9.13. Deploying Your Software on the Target Machine
9.14. Removing Your Software from the Target Machine
9.15. Creating the Workspace Layer in an Alternative Location
9.16. Get the Status of the Recipes in Your Workspace
9.17. Search for Available Target Recipes
10. QA Error and Warning Messages
10.1. Introduction
10.2. Errors and Warnings
10.3. Configuring and Disabling QA Checks
11. Images
12. Features
12.1. Machine Features
12.2. Distro Features
12.3. Image Features
12.4. Feature Backfilling
13. Variables Glossary
Glossary
14. Variable Context
14.1. Configuration
14.1.1. Distribution (Distro)
14.1.2. Machine
14.1.3. Local
14.2. Recipes
14.2.1. Required
14.2.2. Dependencies
14.2.3. Paths
14.2.4. Extra Build Information
15. FAQ
16. Contributing to the Yocto Project
16.1. Introduction
16.2. Tracking Bugs
16.3. Mailing lists
16.4. Internet Relay Chat (IRC)
16.5. Links
16.6. Contributions