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.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 Sometime in 2016
Released with the Yocto Project 2.2 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. Checking for Missing Build-Time Dependencies
2.3.4. Dependency Graphs
2.3.5. General BitBake Problems
2.3.6. Development Host System Issues
2.3.7. Building with No Dependencies
2.3.8. Variables
2.3.9. Recipe Logging Mechanisms
2.3.10. 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. 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. 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. 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
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. gummiboot.bbclass
7.50. gzipnative.bbclass
7.51. icecc.bbclass
7.52. image.bbclass
7.53. image-buildinfo.bbclass
7.54. image_types.bbclass
7.55. image_types_uboot.bbclass
7.56. image-live.bbclass
7.57. image-mklibs.bbclass
7.58. image-prelink.bbclass
7.59. image-swab.bbclass
7.60. image-vm.bbclass
7.61. image-vmdk.bbclass
7.62. insane.bbclass
7.63. insserv.bbclass
7.64. kernel.bbclass
7.65. kernel-arch.bbclass
7.66. kernel-fitimage.bbclass
7.67. kernel-grub.bbclass
7.68. kernel-module-split.bbclass
7.69. kernel-uboot.bbclass
7.70. kernel-uimage.bbclass
7.71. kernel-yocto.bbclass
7.72. kernelsrc.bbclass
7.73. lib_package.bbclass
7.74. libc*.bbclass
7.75. license.bbclass
7.76. linux-kernel-base.bbclass
7.77. linuxloader.bbclass
7.78. logging.bbclass
7.79. meta.bbclass
7.80. metadata_scm.bbclass
7.81. migrate_localcount.bbclass
7.82. mime.bbclass
7.83. mirrors.bbclass
7.84. module.bbclass
7.85. module-base.bbclass
7.86. multilib*.bbclass
7.87. native.bbclass
7.88. nativesdk.bbclass
7.89. nopackages.bbclass
7.90. npm.bbclass
7.91. oelint.bbclass
7.92. own-mirrors.bbclass
7.93. package.bbclass
7.94. package_deb.bbclass
7.95. package_ipk.bbclass
7.96. package_rpm.bbclass
7.97. package_tar.bbclass
7.98. packagedata.bbclass
7.99. packagegroup.bbclass
7.100. patch.bbclass
7.101. perlnative.bbclass
7.102. pixbufcache.bbclass
7.103. pkgconfig.bbclass
7.104. populate_sdk.bbclass
7.105. populate_sdk_*.bbclass
7.106. prexport.bbclass
7.107. primport.bbclass
7.108. prserv.bbclass
7.109. ptest.bbclass
7.110. ptest-gnome.bbclass
7.111. python-dir.bbclass
7.112. python3native.bbclass
7.113. pythonnative.bbclass
7.114. qemu.bbclass
7.115. recipe_sanity.bbclass
7.116. relocatable.bbclass
7.117. remove-libtool.bbclass
7.118. report-error.bbclass
7.119. rm_work.bbclass
7.120. rootfs*.bbclass
7.121. sanity.bbclass
7.122. scons.bbclass
7.123. sdl.bbclass
7.124. setuptools.bbclass
7.125. setuptools3.bbclass
7.126. sign_rpm.bbclass
7.127. sip.bbclass
7.128. siteconfig.bbclass
7.129. siteinfo.bbclass
7.130. spdx.bbclass
7.131. sstate.bbclass
7.132. staging.bbclass
7.133. syslinux.bbclass
7.134. systemd.bbclass
7.135. terminal.bbclass
7.136. testimage*.bbclass
7.137. testsdk.bbclass
7.138. texinfo.bbclass
7.139. tinderclient.bbclass
7.140. toaster.bbclass
7.141. toolchain-scripts.bbclass
7.142. typecheck.bbclass
7.143. uboot-config.bbclass
7.144. uninative.bbclass
7.145. update-alternatives.bbclass
7.146. update-rc.d.bbclass
7.147. useradd*.bbclass
7.148. utility-tasks.bbclass
7.149. utils.bbclass
7.150. vala.bbclass
7.151. waf.bbclass
8. Tasks
8.1. Normal Recipe Build Tasks
8.1.1. do_build
8.1.2. do_checkpkg
8.1.3. do_compile
8.1.4. do_compile_ptest_base
8.1.5. do_configure
8.1.6. do_configure_ptest_base
8.1.7. do_deploy
8.1.8. do_distrodata
8.1.9. do_fetch
8.1.10. do_image
8.1.11. do_image_complete
8.1.12. do_install
8.1.13. do_install_ptest_base
8.1.14. do_package
8.1.15. do_package_qa
8.1.16. do_package_write_deb
8.1.17. do_package_write_ipk
8.1.18. do_package_write_rpm
8.1.19. do_package_write_tar
8.1.20. do_packagedata
8.1.21. do_patch
8.1.22. do_populate_lic
8.1.23. do_populate_sdk
8.1.24. do_populate_sysroot
8.1.25. do_rm_work
8.1.26. do_rm_work_all
8.1.27. do_unpack
8.2. Manually Called Tasks
8.2.1. do_checkuri
8.2.2. do_checkuriall
8.2.3. do_clean
8.2.4. do_cleanall
8.2.5. do_cleansstate
8.2.6. do_devshell
8.2.7. do_fetchall
8.2.8. do_listtasks
8.2.9. 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. QA Error and Warning Messages
9.1. Introduction
9.2. Errors and Warnings
9.3. Configuring and Disabling QA Checks
10. Images
11. Features
11.1. Machine Features
11.2. Distro Features
11.3. Image Features
11.4. Feature Backfilling
12. Variables Glossary
Glossary
13. Variable Context
13.1. Configuration
13.1.1. Distribution (Distro)
13.1.2. Machine
13.1.3. Local
13.2. Recipes
13.2.1. Required
13.2.2. Dependencies
13.2.3. Paths
13.2.4. Extra Build Information
14. FAQ
15. Contributing to the Yocto Project
15.1. Introduction
15.2. Tracking Bugs
15.3. Mailing lists
15.4. Internet Relay Chat (IRC)
15.5. Links
15.6. Contributions