Yocto Project Reference Manual

Scott Rifenbark

Scotty's Documentation Services, INC

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.6 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.3 May 2017
Released with the Yocto Project 2.3 Release.
Revision 2.4 October 2017
Released with the Yocto Project 2.4 Release.
Revision 2.5 May 2018
Released with the Yocto Project 2.5 Release.
Revision 2.6 TBD
Released with the Yocto Project 2.6 Release.

Table of Contents

1. System Requirements
1.1. Supported Linux Distributions
1.2. Required Packages for the Host Development System
1.2.1. Ubuntu and Debian
1.2.2. Fedora Packages
1.2.3. openSUSE Packages
1.2.4. CentOS Packages
1.3. Required Git, tar, and Python Versions
1.3.1. Downloading a Pre-Built buildtools Tarball
1.3.2. Building Your Own buildtools Tarball
2. Yocto Project Terms
3. Yocto Project Releases and the Stable Release Process
3.1. Major and Minor Release Cadence
3.2. Major Release Codenames
3.3. Stable Release Process
3.4. Testing and Quality Assurance
4. Migrating to a Newer Yocto Project Release
4.1. General Migration Considerations
4.2. Moving to the Yocto Project 1.3 Release
4.2.1. Local Configuration
4.2.2. Recipes
4.2.3. Linux Kernel Naming
4.3. Moving to the Yocto Project 1.4 Release
4.3.1. BitBake
4.3.2. Build Behavior
4.3.3. Proxies and Fetching Source
4.3.4. Custom Interfaces File (netbase change)
4.3.5. Remote Debugging
4.3.6. Variables
4.3.7. Target Package Management with RPM
4.3.8. Recipes Moved
4.3.9. Removals and Renames
4.4. Moving to the Yocto Project 1.5 Release
4.4.1. Host Dependency Changes
4.4.2. atom-pc Board Support Package (BSP)
4.4.3. BitBake
4.4.4. QA Warnings
4.4.5. Directory Layout Changes
4.4.6. Shortened Git SRCREV Values
4.4.7. IMAGE_FEATURES
4.4.8. /run
4.4.9. Removal of Package Manager Database Within Image Recipes
4.4.10. Images Now Rebuild Only on Changes Instead of Every Time
4.4.11. Task Recipes
4.4.12. BusyBox
4.4.13. Automated Image Testing
4.4.14. Build History
4.4.15. udev
4.4.16. Removed and Renamed Recipes
4.4.17. Other Changes
4.5. Moving to the Yocto Project 1.6 Release
4.5.1. archiver Class
4.5.2. Packaging Changes
4.5.3. BitBake
4.5.4. Changes to Variables
4.5.5. Package Test (ptest)
4.5.6. Build Changes
4.5.7. qemu-native
4.5.8. core-image-basic
4.5.9. Licensing
4.5.10. CFLAGS Options
4.5.11. Custom Image Output Types
4.5.12. Tasks
4.5.13. update-alternative Provider
4.5.14. virtclass Overrides
4.5.15. Removed and Renamed Recipes
4.5.16. Removed Classes
4.5.17. Reference Board Support Packages (BSPs)
4.6. Moving to the Yocto Project 1.7 Release
4.6.1. Changes to Setting QEMU PACKAGECONFIG Options in local.conf
4.6.2. Minimum Git version
4.6.3. Autotools Class Changes
4.6.4. Binary Configuration Scripts Disabled
4.6.5. eglibc 2.19 Replaced with glibc 2.20
4.6.6. Kernel Module Autoloading
4.6.7. QA Check Changes
4.6.8. Removed Recipes
4.6.9. Miscellaneous Changes
4.7. Moving to the Yocto Project 1.8 Release
4.7.1. Removed Recipes
4.7.2. BlueZ 4.x / 5.x Selection
4.7.3. Kernel Build Changes
4.7.4. SSL 3.0 is Now Disabled in OpenSSL
4.7.5. Default Sysroot Poisoning
4.7.6. Rebuild Improvements
4.7.7. QA Check and Validation Changes
4.7.8. Miscellaneous Changes
4.8. Moving to the Yocto Project 2.0 Release
4.8.1. GCC 5
4.8.2. Gstreamer 0.10 Removed
4.8.3. Removed Recipes
4.8.4. BitBake datastore improvements
4.8.5. Shell Message Function Changes
4.8.6. Extra Development/Debug Package Cleanup
4.8.7. Recipe Maintenance Tracking Data Moved to OE-Core
4.8.8. Automatic Stale Sysroot File Cleanup
4.8.9. linux-yocto Kernel Metadata Repository Now Split from Source
4.8.10. Additional QA checks
4.8.11. Miscellaneous Changes
4.9. Moving to the Yocto Project 2.1 Release
4.9.1. Variable Expansion in Python Functions
4.9.2. Overrides Must Now be Lower-Case
4.9.3. Expand Parameter to getVar() and getVarFlag() is Now Mandatory
4.9.4. Makefile Environment Changes
4.9.5. libexecdir Reverted to ${prefix}/libexec
4.9.6. ac_cv_sizeof_off_t is No Longer Cached in Site Files
4.9.7. Image Generation is Now Split Out from Filesystem Generation
4.9.8. Removed Recipes
4.9.9. Class Changes
4.9.10. Build System User Interface Changes
4.9.11. ADT Removed
4.9.12. Poky Reference Distribution Changes
4.9.13. Packaging Changes
4.9.14. Tuning File Changes
4.9.15. Supporting GObject Introspection
4.9.16. Miscellaneous Changes
4.10. Moving to the Yocto Project 2.2 Release
4.10.1. Minimum Kernel Version
4.10.2. Staging Directories in Sysroot Has Been Simplified
4.10.3. Removal of Old Images and Other Files in tmp/deploy Now Enabled
4.10.4. Python Changes
4.10.5. uClibc Replaced by musl
4.10.6. ${B} No Longer Default Working Directory for Tasks
4.10.7. runqemu Ported to Python
4.10.8. Default Linker Hash Style Changed
4.10.9. KERNEL_IMAGE_BASE_NAME no Longer Uses KERNEL_IMAGETYPE
4.10.10. BitBake Changes
4.10.11. Swabber has Been Removed
4.10.12. Removed Recipes
4.10.13. Removed Classes
4.10.14. Minor Packaging Changes
4.10.15. Miscellaneous Changes
4.11. Moving to the Yocto Project 2.3 Release
4.11.1. Recipe-specific Sysroots
4.11.2. PATH Variable
4.11.3. Changes to Scripts
4.11.4. Changes to Functions
4.11.5. BitBake Changes
4.11.6. Absolute Symbolic Links
4.11.7. GPLv2 Versions of GPLv3 Recipes Moved
4.11.8. Package Management Changes
4.11.9. Removed Recipes
4.11.10. Wic Changes
4.11.11. QA Changes
4.11.12. Miscellaneous Changes
4.12. Moving to the Yocto Project 2.4 Release
4.12.1. Memory Resident Mode
4.12.2. Packaging Changes
4.12.3. Removed Recipes
4.12.4. Kernel Device Tree Move
4.12.5. Package QA Changes
4.12.6. README File Changes
4.12.7. Miscellaneous Changes
4.13. Moving to the Yocto Project 2.5 Release
4.13.1. Packaging Changes
4.13.2. Removed Recipes
4.13.3. Scripts and Tools Changes
4.13.4. BitBake Changes
4.13.5. Python and Python 3 Changes
4.13.6. Miscellaneous Changes
5. Source Directory Structure
5.1. Top-Level Core Components
5.1.1. bitbake/
5.1.2. build/
5.1.3. documentation/
5.1.4. meta/
5.1.5. meta-poky/
5.1.6. meta-yocto-bsp/
5.1.7. meta-selftest/
5.1.8. meta-skeleton/
5.1.9. scripts/
5.1.10. oe-init-build-env
5.1.11. LICENSE, README, and README.hardware
5.2. The Build Directory - build/
5.2.1. build/buildhistory
5.2.2. build/conf/local.conf
5.2.3. build/conf/bblayers.conf
5.2.4. build/conf/sanity_info
5.2.5. build/downloads/
5.2.6. build/sstate-cache/
5.2.7. build/tmp/
5.2.8. build/tmp/buildstats/
5.2.9. build/tmp/cache/
5.2.10. build/tmp/deploy/
5.2.11. build/tmp/deploy/deb/
5.2.12. build/tmp/deploy/rpm/
5.2.13. build/tmp/deploy/ipk/
5.2.14. build/tmp/deploy/licenses/
5.2.15. build/tmp/deploy/images/
5.2.16. build/tmp/deploy/sdk/
5.2.17. build/tmp/sstate-control/
5.2.18. build/tmp/sysroots-components/
5.2.19. build/tmp/sysroots/
5.2.20. build/tmp/stamps/
5.2.21. build/tmp/log/
5.2.22. build/tmp/work/
5.2.23. build/tmp/work/tunearch/recipename/version/
5.2.24. build/tmp/work-shared/
5.3. The Metadata - meta/
5.3.1. meta/classes/
5.3.2. meta/conf/
5.3.3. meta/conf/machine/
5.3.4. meta/conf/distro/
5.3.5. meta/conf/machine-sdk/
5.3.6. meta/files/
5.3.7. meta/lib/
5.3.8. meta/recipes-bsp/
5.3.9. meta/recipes-connectivity/
5.3.10. meta/recipes-core/
5.3.11. meta/recipes-devtools/
5.3.12. meta/recipes-extended/
5.3.13. meta/recipes-gnome/
5.3.14. meta/recipes-graphics/
5.3.15. meta/recipes-kernel/
5.3.16. meta/recipes-lsb4/
5.3.17. meta/recipes-multimedia/
5.3.18. meta/recipes-rt/
5.3.19. meta/recipes-sato/
5.3.20. meta/recipes-support/
5.3.21. meta/site/
5.3.22. meta/recipes.txt
6. Classes
6.1. allarch.bbclass
6.2. archiver.bbclass
6.3. autotools*.bbclass
6.4. base.bbclass
6.5. bash-completion.bbclass
6.6. bin_package.bbclass
6.7. binconfig.bbclass
6.8. binconfig-disabled.bbclass
6.9. blacklist.bbclass
6.10. bluetooth.bbclass
6.11. bugzilla.bbclass
6.12. buildhistory.bbclass
6.13. buildstats.bbclass
6.14. buildstats-summary.bbclass
6.15. ccache.bbclass
6.16. chrpath.bbclass
6.17. clutter.bbclass
6.18. cmake.bbclass
6.19. cml1.bbclass
6.20. compress_doc.bbclass
6.21. copyleft_compliance.bbclass
6.22. copyleft_filter.bbclass
6.23. core-image.bbclass
6.24. cpan*.bbclass
6.25. cross.bbclass
6.26. cross-canadian.bbclass
6.27. crosssdk.bbclass
6.28. debian.bbclass
6.29. deploy.bbclass
6.30. devshell.bbclass
6.31. distro_features_check.bbclass
6.32. distrodata.bbclass
6.33. distutils*.bbclass
6.34. distutils3*.bbclass
6.35. externalsrc.bbclass
6.36. extrausers.bbclass
6.37. fontcache.bbclass
6.38. fs-uuid.bbclass
6.39. gconf.bbclass
6.40. gettext.bbclass
6.41. gnome.bbclass
6.42. gnomebase.bbclass
6.43. gobject-introspection.bbclass
6.44. grub-efi.bbclass
6.45. gsettings.bbclass
6.46. gtk-doc.bbclass
6.47. gtk-icon-cache.bbclass
6.48. gtk-immodules-cache.bbclass
6.49. gzipnative.bbclass
6.50. icecc.bbclass
6.51. image.bbclass
6.52. image-buildinfo.bbclass
6.53. image_types.bbclass
6.54. image-live.bbclass
6.55. image-mklibs.bbclass
6.56. image-prelink.bbclass
6.57. insane.bbclass
6.58. insserv.bbclass
6.59. kernel.bbclass
6.60. kernel-arch.bbclass
6.61. kernel-devicetree.bbclass
6.62. kernel-fitimage.bbclass
6.63. kernel-grub.bbclass
6.64. kernel-module-split.bbclass
6.65. kernel-uboot.bbclass
6.66. kernel-uimage.bbclass
6.67. kernel-yocto.bbclass
6.68. kernelsrc.bbclass
6.69. lib_package.bbclass
6.70. libc*.bbclass
6.71. license.bbclass
6.72. linux-kernel-base.bbclass
6.73. linuxloader.bbclass
6.74. logging.bbclass
6.75. meta.bbclass
6.76. metadata_scm.bbclass
6.77. migrate_localcount.bbclass
6.78. mime.bbclass
6.79. mirrors.bbclass
6.80. module.bbclass
6.81. module-base.bbclass
6.82. multilib*.bbclass
6.83. native.bbclass
6.84. nativesdk.bbclass
6.85. nopackages.bbclass
6.86. npm.bbclass
6.87. oelint.bbclass
6.88. own-mirrors.bbclass
6.89. package.bbclass
6.90. package_deb.bbclass
6.91. package_ipk.bbclass
6.92. package_rpm.bbclass
6.93. package_tar.bbclass
6.94. packagedata.bbclass
6.95. packagegroup.bbclass
6.96. patch.bbclass
6.97. perlnative.bbclass
6.98. pixbufcache.bbclass
6.99. pkgconfig.bbclass
6.100. populate_sdk.bbclass
6.101. populate_sdk_*.bbclass
6.102. prexport.bbclass
6.103. primport.bbclass
6.104. prserv.bbclass
6.105. ptest.bbclass
6.106. ptest-gnome.bbclass
6.107. python-dir.bbclass
6.108. python3native.bbclass
6.109. pythonnative.bbclass
6.110. qemu.bbclass
6.111. recipe_sanity.bbclass
6.112. relocatable.bbclass
6.113. remove-libtool.bbclass
6.114. report-error.bbclass
6.115. rm_work.bbclass
6.116. rootfs*.bbclass
6.117. sanity.bbclass
6.118. scons.bbclass
6.119. sdl.bbclass
6.120. setuptools.bbclass
6.121. setuptools3.bbclass
6.122. sign_rpm.bbclass
6.123. sip.bbclass
6.124. siteconfig.bbclass
6.125. siteinfo.bbclass
6.126. spdx.bbclass
6.127. sstate.bbclass
6.128. staging.bbclass
6.129. syslinux.bbclass
6.130. systemd.bbclass
6.131. systemd-boot.bbclass
6.132. terminal.bbclass
6.133. testimage*.bbclass
6.134. testsdk.bbclass
6.135. texinfo.bbclass
6.136. tinderclient.bbclass
6.137. toaster.bbclass
6.138. toolchain-scripts.bbclass
6.139. typecheck.bbclass
6.140. uboot-config.bbclass
6.141. uninative.bbclass
6.142. update-alternatives.bbclass
6.143. update-rc.d.bbclass
6.144. useradd*.bbclass
6.145. utility-tasks.bbclass
6.146. utils.bbclass
6.147. vala.bbclass
6.148. waf.bbclass
7. Tasks
7.1. Normal Recipe Build Tasks
7.1.1. do_build
7.1.2. do_compile
7.1.3. do_compile_ptest_base
7.1.4. do_configure
7.1.5. do_configure_ptest_base
7.1.6. do_deploy
7.1.7. do_distrodata
7.1.8. do_fetch
7.1.9. do_image
7.1.10. do_image_complete
7.1.11. do_install
7.1.12. do_install_ptest_base
7.1.13. do_package
7.1.14. do_package_qa
7.1.15. do_package_write_deb
7.1.16. do_package_write_ipk
7.1.17. do_package_write_rpm
7.1.18. do_package_write_tar
7.1.19. do_packagedata
7.1.20. do_patch
7.1.21. do_populate_lic
7.1.22. do_populate_sdk
7.1.23. do_populate_sysroot
7.1.24. do_prepare_recipe_sysroot
7.1.25. do_rm_work
7.1.26. do_unpack
7.2. Manually Called Tasks
7.2.1. do_checkpkg
7.2.2. do_checkuri
7.2.3. do_clean
7.2.4. do_cleanall
7.2.5. do_cleansstate
7.2.6. do_devpyshell
7.2.7. do_devshell
7.2.8. do_listtasks
7.2.9. do_package_index
7.3. Image-Related Tasks
7.3.1. do_bootimg
7.3.2. do_bundle_initramfs
7.3.3. do_rootfs
7.3.4. do_testimage
7.3.5. do_testimage_auto
7.4. Kernel-Related Tasks
7.4.1. do_compile_kernelmodules
7.4.2. do_diffconfig
7.4.3. do_kernel_checkout
7.4.4. do_kernel_configcheck
7.4.5. do_kernel_configme
7.4.6. do_kernel_menuconfig
7.4.7. do_kernel_metadata
7.4.8. do_menuconfig
7.4.9. do_savedefconfig
7.4.10. do_shared_workdir
7.4.11. do_sizecheck
7.4.12. do_strip
7.4.13. do_validate_branches
7.5. Miscellaneous Tasks
7.5.1. do_spdx
8. devtool Quick Reference
8.1. Getting Help
8.2. The Workspace Layer Structure
8.3. Adding a New Recipe to the Workspace Layer
8.4. Extracting the Source for an Existing Recipe
8.5. Synchronizing a Recipe's Extracted Source Tree
8.6. Modifying an Existing Recipe
8.7. Edit an Existing Recipe
8.8. Updating a Recipe
8.9. Upgrading a Recipe
8.10. Resetting a Recipe
8.11. Building Your Recipe
8.12. Building Your Image
8.13. Deploying Your Software on the Target Machine
8.14. Removing Your Software from the Target Machine
8.15. Creating the Workspace Layer in an Alternative Location
8.16. Get the Status of the Recipes in Your Workspace
8.17. Search for Available Target Recipes
9. OpenEmbedded Kickstart (.wks) Reference
9.1. Introduction
9.2. Command: part or partition
9.3. Command: bootloader
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. Contributions and Additional Information
16.1. Introduction
16.2. Contributions
16.3. Yocto Project Bugzilla
16.4. Mailing lists
16.5. Internet Relay Chat (IRC)
16.6. Links and Related Documentation