Yocto Project Reference Manual

Table of Contents

• 1 System Requirements
  • 1.1 Supported Linux Distributions
  • 1.2 Required Packages for the Build Host
    • 1.2.1 Ubuntu and Debian
    • 1.2.2 Fedora Packages
    • 1.2.3 openSUSE Packages
    • 1.2.4 AlmaLinux-8 Packages
  • 1.3 Required Git, tar, Python, make and gcc Versions
    • 1.3.1 Installing a Pre-Built buildtools Tarball with install-buildtools script
    • 1.3.2 Downloading a Pre-Built buildtools Tarball
    • 1.3.3 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 Source Directory Structure
  • 4.1 Top-Level Core Components
    • 4.1.1 bitbake/
    • 4.1.2 build/
    • 4.1.3 documentation/
    • 4.1.4 meta/
    • 4.1.5 meta-poky/
    • 4.1.6 meta-yocto-bsp/
    • 4.1.7 meta-selftest/
    • 4.1.8 meta-skeleton/
    • 4.1.9 scripts/
    • 4.1.10 oe-init-build-env
    • 4.1.11 LICENSE, README, and README.hardware
  • 4.2 The Build Directory — build/
    • 4.2.1 build/buildhistory/
    • 4.2.2 build/cache/
    • 4.2.3 build/conf/local.conf
    • 4.2.4 build/conf/bblayers.conf
    • 4.2.5 build/downloads/
    • 4.2.6 build/sstate-cache/
    • 4.2.7 build/tmp/
      • 4.2.7.1 build/tmp/buildstats/
      • 4.2.7.2 build/tmp/cache/
      • 4.2.7.3 build/tmp/deploy/
        • 4.2.7.3.1 build/tmp/deploy/deb/
        • 4.2.7.3.2 build/tmp/deploy/rpm/
        • 4.2.7.3.3 build/tmp/deploy/ipk/
        • 4.2.7.3.4 build/tmp/deploy/licenses/
        • 4.2.7.3.5 build/tmp/deploy/images/
        • 4.2.7.3.6 build/tmp/deploy/sdk/
      • 4.2.7.4 build/tmp/sstate-control/
      • 4.2.7.5 build/tmp/sysroots-components/
      • 4.2.7.6 build/tmp/sysroots/
      • 4.2.7.7 build/tmp/stamps/
      • 4.2.7.8 build/tmp/log/
      • 4.2.7.9 build/tmp/work/
        • 4.2.7.9.1 build/tmp/work/tunearch/recipename/version/
      • 4.2.7.10 build/tmp/work-shared/
  • 4.3 The Metadata — meta/
    • 4.3.1 meta/classes*/
    • 4.3.2 meta/conf/
      • 4.3.2.1 meta/conf/machine/
      • 4.3.2.2 meta/conf/distro/
      • 4.3.2.3 meta/conf/machine-sdk/
    • 4.3.3 meta/files/
    • 4.3.4 meta/lib/
    • 4.3.5 meta/recipes-bsp/
    • 4.3.6 meta/recipes-connectivity/
    • 4.3.7 meta/recipes-core/
    • 4.3.8 meta/recipes-devtools/
    • 4.3.9 meta/recipes-extended/
    • 4.3.10 meta/recipes-gnome/
    • 4.3.11 meta/recipes-graphics/
    • 4.3.12 meta/recipes-kernel/
    • 4.3.13 meta/recipes-multimedia/
    • 4.3.14 meta/recipes-rt/
    • 4.3.15 meta/recipes-sato/
    • 4.3.16 meta/recipes-support/
    • 4.3.17 meta/site/
    • 4.3.18 meta/recipes.txt
• 5 Classes
  • 5.1 allarch.bbclass
  • 5.2 archiver.bbclass
  • 5.3 autotools*.bbclass
  • 5.4 base.bbclass
  • 5.5 bash-completion.bbclass
  • 5.6 bin_package.bbclass
  • 5.7 binconfig.bbclass
  • 5.8 binconfig-disabled.bbclass
  • 5.9 buildhistory.bbclass
  • 5.10 buildstats.bbclass
  • 5.11 buildstats-summary.bbclass
  • 5.12 ccache.bbclass
  • 5.13 chrpath.bbclass
  • 5.14 cmake.bbclass
  • 5.15 cml1.bbclass
  • 5.16 compress_doc.bbclass
  • 5.17 copyleft_compliance.bbclass
  • 5.18 copyleft_filter.bbclass
  • 5.19 core-image.bbclass
  • 5.20 cpan*.bbclass
  • 5.21 create-spdx.bbclass
  • 5.22 cross.bbclass
  • 5.23 cross-canadian.bbclass
  • 5.24 crosssdk.bbclass
  • 5.25 cve-check.bbclass
  • 5.26 debian.bbclass
  • 5.27 deploy.bbclass
  • 5.28 devshell.bbclass
  • 5.29 devupstream.bbclass
  • 5.30 externalsrc.bbclass
  • 5.31 extrausers.bbclass
  • 5.32 features_check.bbclass
  • 5.33 fontcache.bbclass
  • 5.34 fs-uuid.bbclass
  • 5.35 gconf.bbclass
  • 5.36 gettext.bbclass
  • 5.37 github-releases
  • 5.38 gnomebase.bbclass
  • 5.39 gobject-introspection.bbclass
  • 5.40 grub-efi.bbclass
  • 5.41 gsettings.bbclass
  • 5.42 gtk-doc.bbclass
  • 5.43 gtk-icon-cache.bbclass
  • 5.44 gtk-immodules-cache.bbclass
  • 5.45 gzipnative.bbclass
  • 5.46 icecc.bbclass
  • 5.47 image.bbclass
  • 5.48 image-buildinfo.bbclass
  • 5.49 image_types.bbclass
  • 5.50 image-live.bbclass
  • 5.51 insane.bbclass
  • 5.52 insserv.bbclass
  • 5.53 kernel.bbclass
  • 5.54 kernel-arch.bbclass
  • 5.55 kernel-devicetree.bbclass
  • 5.56 kernel-fitimage.bbclass
  • 5.57 kernel-grub.bbclass
  • 5.58 kernel-module-split.bbclass
  • 5.59 kernel-uboot.bbclass
  • 5.60 kernel-uimage.bbclass
  • 5.61 kernel-yocto.bbclass
  • 5.62 kernelsrc.bbclass
  • 5.63 lib_package.bbclass
  • 5.64 libc*.bbclass
  • 5.65 license.bbclass
  • 5.66 linux-kernel-base.bbclass
  • 5.67 linuxloader.bbclass
  • 5.68 logging.bbclass
  • 5.69 metadata_scm.bbclass
  • 5.70 migrate_localcount.bbclass
  • 5.71 mime.bbclass
  • 5.72 mirrors.bbclass
  • 5.73 module.bbclass
  • 5.74 module-base.bbclass
  • 5.75 multilib*.bbclass
  • 5.76 native.bbclass
  • 5.77 nativesdk.bbclass
  • 5.78 nopackages.bbclass
  • 5.79 npm.bbclass
  • 5.80 oelint.bbclass
  • 5.81 overlayfs.bbclass
  • 5.82 overlayfs-etc.bbclass
  • 5.83 own-mirrors.bbclass
  • 5.84 package.bbclass
  • 5.85 package_deb.bbclass
  • 5.86 package_ipk.bbclass
  • 5.87 package_rpm.bbclass
  • 5.88 package_tar.bbclass
  • 5.89 packagedata.bbclass
  • 5.90 packagegroup.bbclass
  • 5.91 patch.bbclass
  • 5.92 perlnative.bbclass
  • 5.93 pypi.bbclass
  • 5.94 python_flit_core.bbclass
  • 5.95 python_pep517.bbclass
  • 5.96 python_poetry_core.bbclass
  • 5.97 pixbufcache.bbclass
  • 5.98 pkgconfig.bbclass
  • 5.99 populate_sdk.bbclass
  • 5.100 populate_sdk_*.bbclass
  • 5.101 prexport.bbclass
  • 5.102 primport.bbclass
  • 5.103 prserv.bbclass
  • 5.104 ptest.bbclass
  • 5.105 ptest-gnome.bbclass
  • 5.106 python3-dir.bbclass
  • 5.107 python3native.bbclass
  • 5.108 python3targetconfig.bbclass
  • 5.109 qemu.bbclass
  • 5.110 recipe_sanity.bbclass
  • 5.111 relocatable.bbclass
  • 5.112 remove-libtool.bbclass
  • 5.113 report-error.bbclass
  • 5.114 rm_work.bbclass
  • 5.115 rootfs*.bbclass
  • 5.116 sanity.bbclass
  • 5.117 scons.bbclass
  • 5.118 sdl.bbclass
  • 5.119 python_setuptools_build_meta.bbclass
  • 5.120 setuptools3.bbclass
  • 5.121 setuptools3_legacy.bbclass
  • 5.122 setuptools3-base.bbclass
  • 5.123 sign_rpm.bbclass
  • 5.124 sip.bbclass
  • 5.125 siteconfig.bbclass
  • 5.126 siteinfo.bbclass
  • 5.127 sstate.bbclass
  • 5.128 staging.bbclass
  • 5.129 syslinux.bbclass
  • 5.130 systemd.bbclass
  • 5.131 systemd-boot.bbclass
  • 5.132 terminal.bbclass
  • 5.133 testimage.bbclass
  • 5.134 testsdk.bbclass
  • 5.135 texinfo.bbclass
  • 5.136 toaster.bbclass
  • 5.137 toolchain-scripts.bbclass
  • 5.138 typecheck.bbclass
  • 5.139 uboot-config.bbclass
  • 5.140 uninative.bbclass
  • 5.141 update-alternatives.bbclass
  • 5.142 update-rc.d.bbclass
  • 5.143 useradd*.bbclass
  • 5.144 utility-tasks.bbclass
  • 5.145 utils.bbclass
  • 5.146 vala.bbclass
  • 5.147 waf.bbclass
• 6 Tasks
  • 6.1 Normal Recipe Build Tasks
    • 6.1.1 do_build
    • 6.1.2 do_compile
    • 6.1.3 do_compile_ptest_base
    • 6.1.4 do_configure
    • 6.1.5 do_configure_ptest_base
    • 6.1.6 do_deploy
    • 6.1.7 do_fetch
    • 6.1.8 do_image
    • 6.1.9 do_image_complete
    • 6.1.10 do_install
    • 6.1.11 do_install_ptest_base
    • 6.1.12 do_package
    • 6.1.13 do_package_qa
    • 6.1.14 do_package_write_deb
    • 6.1.15 do_package_write_ipk
    • 6.1.16 do_package_write_rpm
    • 6.1.17 do_package_write_tar
    • 6.1.18 do_packagedata
    • 6.1.19 do_patch
    • 6.1.20 do_populate_lic
    • 6.1.21 do_populate_sdk
    • 6.1.22 do_populate_sdk_ext
    • 6.1.23 do_populate_sysroot
    • 6.1.24 do_prepare_recipe_sysroot
    • 6.1.25 do_rm_work
    • 6.1.26 do_unpack
  • 6.2 Manually Called Tasks
    • 6.2.1 do_checkuri
    • 6.2.2 do_clean
    • 6.2.3 do_cleanall
    • 6.2.4 do_cleansstate
    • 6.2.5 do_pydevshell
    • 6.2.6 do_devshell
    • 6.2.7 do_listtasks
    • 6.2.8 do_package_index
  • 6.3 Image-Related Tasks
    • 6.3.1 do_bootimg
    • 6.3.2 do_bundle_initramfs
    • 6.3.3 do_rootfs
    • 6.3.4 do_testimage
    • 6.3.5 do_testimage_auto
  • 6.4 Kernel-Related Tasks
    • 6.4.1 do_compile_kernelmodules
    • 6.4.2 do_diffconfig
    • 6.4.3 do_kernel_checkout
    • 6.4.4 do_kernel_configcheck
    • 6.4.5 do_kernel_configme
    • 6.4.6 do_kernel_menuconfig
    • 6.4.7 do_kernel_metadata
    • 6.4.8 do_menuconfig
    • 6.4.9 do_savedefconfig
    • 6.4.10 do_shared_workdir
    • 6.4.11 do_sizecheck
    • 6.4.12 do_strip
    • 6.4.13 do_validate_branches
• 7 devtool Quick Reference
  • 7.1 Getting Help
  • 7.2 The Workspace Layer Structure
  • 7.3 Adding a New Recipe to the Workspace Layer
  • 7.4 Extracting the Source for an Existing Recipe
  • 7.5 Synchronizing a Recipe’s Extracted Source Tree
  • 7.6 Modifying an Existing Recipe
  • 7.7 Edit an Existing Recipe
  • 7.8 Updating a Recipe
  • 7.9 Checking on the Upgrade Status of a Recipe
  • 7.10 Upgrading a Recipe
  • 7.11 Resetting a Recipe
  • 7.12 Building Your Recipe
  • 7.13 Building Your Image
  • 7.14 Deploying Your Software on the Target Machine
  • 7.15 Removing Your Software from the Target Machine
  • 7.16 Creating the Workspace Layer in an Alternative Location
  • 7.17 Get the Status of the Recipes in Your Workspace
  • 7.18 Search for Available Target Recipes
• 8 OpenEmbedded Kickstart (.wks) Reference
  • 8.1 Introduction
  • 8.2 Command: part or partition
  • 8.3 Command: bootloader
• 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
• 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
  • 14.1 General questions
    • 14.1.1 How does Poky differ from OpenEmbedded?
    • 14.1.2 How can you claim Poky / OpenEmbedded-Core is stable?
    • 14.1.3 Are there any products built using the OpenEmbedded build system?
  • 14.2 Building environment
    • 14.2.1 Missing dependencies on the development system?
    • 14.2.2 How does OpenEmbedded fetch source code? Will it work through a firewall or proxy server?
  • 14.3 Using the OpenEmbedded Build system
    • 14.3.1 How do I use an external toolchain?
    • 14.3.2 Why do I get chmod permission issues?
    • 14.3.3 I see many 404 errors trying to download sources. Is anything wrong?
    • 14.3.4 Why do I get random build failures?
    • 14.3.5 Why does the build fail with iconv.h problems?
    • 14.3.6 Why don’t other recipes find the files provided by my *-native recipe?
    • 14.3.7 Can I get rid of build output so I can start over?
  • 14.4 Customizing generated images
    • 14.4.1 What does the OpenEmbedded build system produce as output?
    • 14.4.2 How do I make the Yocto Project support my board?
    • 14.4.3 How do I make the Yocto Project support my package?
    • 14.4.4 What do I need to ship for license compliance?
    • 14.4.5 Do I have to make a full reflash after recompiling one package?
    • 14.4.6 How to prevent my package from being marked as machine specific?
    • 14.4.7 What’s the difference between target and target-native?
    • 14.4.8 Why do ${bindir} and ${libdir} have strange values for -native recipes?
    • 14.4.9 How do I create images with more free space?
    • 14.4.10 Why aren’t spaces in path names supported?
    • 14.4.11 I’m adding a binary in a recipe. Why is it different in the image?
  • 14.5 Issues on the running system
    • 14.5.1 How do I disable the cursor on my touchscreen device?
    • 14.5.2 How to always bring up connected network interfaces?
• 15 Contributions and Additional Information
  • 15.1 Introduction
  • 15.2 Contributions
  • 15.3 Yocto Project Bugzilla
  • 15.4 Mailing lists
  • 15.5 Internet Relay Chat (IRC)
  • 15.6 Links and Related Documentation

---

The Yocto Project ®

<docs@lists.yoctoproject.org>

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.

To report any inaccuracies or problems with this (or any other Yocto Project) manual, or to send additions or changes, please send email/patches to the Yocto Project documentation mailing list at docs@lists.yoctoproject.org or log into the Libera Chat #yocto channel.