Yocto Project Reference Manual

Table of Contents

• 1 System Requirements
  • 1.1 Minimum Free Disk Space
  • 1.2 Minimum System RAM
  • 1.3 Supported Linux Distributions
  • 1.4 Required Packages for the Build Host
    • 1.4.1 Ubuntu and Debian
    • 1.4.2 Fedora Packages
    • 1.4.3 openSUSE Packages
    • 1.4.4 AlmaLinux Packages
  • 1.5 Required Git, tar, Python, make and gcc Versions
    • 1.5.1 Installing a Pre-Built buildtools Tarball with install-buildtools script
    • 1.5.2 Downloading a Pre-Built buildtools Tarball
    • 1.5.3 Building Your Own buildtools Tarball
• 2 Yocto Project Supported Architectures And Features
  • 2.1 Primary Supported
  • 2.2 Secondary Supported
  • 2.3 Untested
• 3 Yocto Project Terms
• 4 Yocto Project Releases and the Stable Release Process
  • 4.1 Major and Minor Release Cadence
  • 4.2 Major Release Codenames
  • 4.3 Stable Release Process
  • 4.4 Long Term Support Releases
  • 4.5 Testing and Quality Assurance
• 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/cache/
    • 5.2.3 build/conf/local.conf
    • 5.2.4 build/conf/bblayers.conf
    • 5.2.5 build/conf/bblock.conf
    • 5.2.6 build/downloads/
    • 5.2.7 build/sstate-cache/
    • 5.2.8 build/tmp/
      • 5.2.8.1 build/tmp/buildstats/
      • 5.2.8.2 build/tmp/cache/
      • 5.2.8.3 build/tmp/deploy/
        • 5.2.8.3.1 build/tmp/deploy/deb/
        • 5.2.8.3.2 build/tmp/deploy/rpm/
        • 5.2.8.3.3 build/tmp/deploy/ipk/
        • 5.2.8.3.4 build/tmp/deploy/licenses/
        • 5.2.8.3.5 build/tmp/deploy/images/
        • 5.2.8.3.6 build/tmp/deploy/sdk/
      • 5.2.8.4 build/tmp/hosttools/
      • 5.2.8.5 build/tmp/pkgdata/
      • 5.2.8.6 build/tmp/sstate-control/
      • 5.2.8.7 build/tmp/sysroots-components/
      • 5.2.8.8 build/tmp/sysroots/
      • 5.2.8.9 build/tmp/stamps/
      • 5.2.8.10 build/tmp/log/
      • 5.2.8.11 build/tmp/work/
        • 5.2.8.11.1 build/tmp/work/tunearch/recipename/version/
      • 5.2.8.12 build/tmp/work-shared/
  • 5.3 The Metadata — meta/
    • 5.3.1 meta/classes*/
    • 5.3.2 meta/conf/
      • 5.3.2.1 meta/conf/machine/
      • 5.3.2.2 meta/conf/distro/
      • 5.3.2.3 meta/conf/machine-sdk/
    • 5.3.3 meta/files/
    • 5.3.4 meta/lib/
    • 5.3.5 meta/recipes-bsp/
    • 5.3.6 meta/recipes-connectivity/
    • 5.3.7 meta/recipes-core/
    • 5.3.8 meta/recipes-devtools/
    • 5.3.9 meta/recipes-extended/
    • 5.3.10 meta/recipes-gnome/
    • 5.3.11 meta/recipes-graphics/
    • 5.3.12 meta/recipes-kernel/
    • 5.3.13 meta/recipes-multimedia/
    • 5.3.14 meta/recipes-rt/
    • 5.3.15 meta/recipes-sato/
    • 5.3.16 meta/recipes-support/
    • 5.3.17 meta/site/
    • 5.3.18 meta/recipes.txt
• 6 Classes
  • 6.1 allarch
  • 6.2 archiver
  • 6.3 autotools*
  • 6.4 barebox
  • 6.5 base
  • 6.6 bash-completion
  • 6.7 bin_package
  • 6.8 binconfig
  • 6.9 binconfig-disabled
  • 6.10 buildhistory
  • 6.11 buildstats
  • 6.12 buildstats-summary
  • 6.13 cargo
  • 6.14 cargo_c
  • 6.15 cargo_common
  • 6.16 cargo-update-recipe-crates
  • 6.17 ccache
  • 6.18 chrpath
  • 6.19 cmake
  • 6.20 cmake-qemu
  • 6.21 cml1
  • 6.22 compress_doc
  • 6.23 copyleft_compliance
  • 6.24 copyleft_filter
  • 6.25 core-image
  • 6.26 cpan*
  • 6.27 create-spdx
  • 6.28 cross
  • 6.29 cross-canadian
  • 6.30 crosssdk
  • 6.31 cve-check
  • 6.32 cython
  • 6.33 debian
  • 6.34 deploy
  • 6.35 devicetree
  • 6.36 devshell
  • 6.37 devupstream
  • 6.38 externalsrc
  • 6.39 extrausers
  • 6.40 features_check
  • 6.41 fontcache
  • 6.42 fs-uuid
  • 6.43 gconf
  • 6.44 gettext
  • 6.45 github-releases
  • 6.46 gnomebase
  • 6.47 go
  • 6.48 go-mod
  • 6.49 go-vendor
  • 6.50 gobject-introspection
  • 6.51 grub-efi
  • 6.52 gsettings
  • 6.53 gtk-doc
  • 6.54 gtk-icon-cache
  • 6.55 gtk-immodules-cache
  • 6.56 gzipnative
  • 6.57 icecc
  • 6.58 image
  • 6.59 image-buildinfo
  • 6.60 image_types
  • 6.61 image-live
  • 6.62 insane
  • 6.63 kernel
  • 6.64 kernel-arch
  • 6.65 kernel-devicetree
  • 6.66 kernel-fitimage
  • 6.67 kernel-grub
  • 6.68 kernel-module-split
  • 6.69 kernel-uboot
  • 6.70 kernel-uimage
  • 6.71 kernel-yocto
  • 6.72 kernelsrc
  • 6.73 lib_package
  • 6.74 libc*
  • 6.75 license
  • 6.76 linux-kernel-base
  • 6.77 linuxloader
  • 6.78 logging
  • 6.79 meson
  • 6.80 metadata_scm
  • 6.81 mime
  • 6.82 mime-xdg
  • 6.83 mirrors
  • 6.84 module
  • 6.85 module-base
  • 6.86 multilib*
  • 6.87 native
  • 6.88 nativesdk
  • 6.89 nopackages
  • 6.90 nospdx
  • 6.91 npm
  • 6.92 oelint
  • 6.93 overlayfs
  • 6.94 overlayfs-etc
  • 6.95 own-mirrors
  • 6.96 package
  • 6.97 package_deb
  • 6.98 package_ipk
  • 6.99 package_rpm
  • 6.100 packagedata
  • 6.101 packagegroup
  • 6.102 patch
  • 6.103 perlnative
  • 6.104 pypi
  • 6.105 python_flit_core
  • 6.106 python_maturin
  • 6.107 python_mesonpy
  • 6.108 python_pep517
  • 6.109 python_poetry_core
  • 6.110 python_pyo3
  • 6.111 python-setuptools3_rust
  • 6.112 pixbufcache
  • 6.113 pkgconfig
  • 6.114 populate_sdk
  • 6.115 populate_sdk_*
  • 6.116 prexport
  • 6.117 primport
  • 6.118 prserv
  • 6.119 ptest
  • 6.120 ptest-cargo
  • 6.121 ptest-gnome
  • 6.122 ptest-python-pytest
  • 6.123 python3-dir
  • 6.124 python3native
  • 6.125 python3targetconfig
  • 6.126 qemu
  • 6.127 recipe_sanity
  • 6.128 relocatable
  • 6.129 remove-libtool
  • 6.130 report-error
  • 6.131 retain
  • 6.132 rm_work
  • 6.133 rootfs*
  • 6.134 rust
  • 6.135 rust-common
  • 6.136 sanity
  • 6.137 scons
  • 6.138 sdl
  • 6.139 python_setuptools_build_meta
  • 6.140 setuptools3
  • 6.141 setuptools3_legacy
  • 6.142 setuptools3-base
  • 6.143 sign_rpm
  • 6.144 siteinfo
  • 6.145 sstate
  • 6.146 staging
  • 6.147 syslinux
  • 6.148 systemd
  • 6.149 systemd-boot
  • 6.150 terminal
  • 6.151 testimage
  • 6.152 testsdk
  • 6.153 texinfo
  • 6.154 toaster
  • 6.155 toolchain-scripts
  • 6.156 typecheck
  • 6.157 uboot-config
  • 6.158 uboot-sign
  • 6.159 uki
  • 6.160 uninative
  • 6.161 update-alternatives
  • 6.162 update-rc.d
  • 6.163 useradd*
  • 6.164 utility-tasks
  • 6.165 utils
  • 6.166 vala
  • 6.167 vex
  • 6.168 waf
  • 6.169 yocto-check-layer
• 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_fetch
    • 7.1.8 do_image
    • 7.1.9 do_image_complete
    • 7.1.10 do_install
    • 7.1.11 do_install_ptest_base
    • 7.1.12 do_package
    • 7.1.13 do_package_qa
    • 7.1.14 do_package_write_deb
    • 7.1.15 do_package_write_ipk
    • 7.1.16 do_package_write_rpm
    • 7.1.17 do_packagedata
    • 7.1.18 do_patch
    • 7.1.19 do_populate_lic
    • 7.1.20 do_populate_sdk
    • 7.1.21 do_populate_sdk_ext
    • 7.1.22 do_populate_sysroot
    • 7.1.23 do_prepare_recipe_sysroot
    • 7.1.24 do_rm_work
    • 7.1.25 do_unpack
  • 7.2 Manually Called Tasks
    • 7.2.1 do_checkuri
    • 7.2.2 do_clean
    • 7.2.3 do_cleanall
    • 7.2.4 do_cleansstate
    • 7.2.5 do_pydevshell
    • 7.2.6 do_devshell
    • 7.2.7 do_listtasks
    • 7.2.8 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
• 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 Checking on the Upgrade Status of a Recipe
  • 8.10 Upgrading a Recipe
  • 8.11 Resetting a Recipe
  • 8.12 Finish Working on a Recipe
  • 8.13 Building Your Recipe
  • 8.14 Building Your Image
  • 8.15 Deploying Your Software on the Target Machine
  • 8.16 Removing Your Software from the Target Machine
  • 8.17 Creating the Workspace Layer in an Alternative Location
  • 8.18 Get the Status of the Recipes in Your Workspace
  • 8.19 Search for Available Target Recipes
  • 8.20 Get Information on Recipe Configuration Scripts
  • 8.21 Generate an IDE Configuration for a Recipe
• 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
• 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
  • 15.1 General questions
    • 15.1.1 How does Poky differ from OpenEmbedded?
    • 15.1.2 How can you claim Poky / OpenEmbedded-Core is stable?
    • 15.1.3 Are there any products built using the OpenEmbedded build system?
    • 15.1.4 Why isn’t systemd the default init system for OpenEmbedded-Core/Yocto Project or in Poky?
  • 15.2 Building environment
    • 15.2.1 Missing dependencies on the development system?
    • 15.2.2 How does OpenEmbedded fetch source code? Will it work through a firewall or proxy server?
  • 15.3 Using the OpenEmbedded Build system
    • 15.3.1 How do I use an external toolchain?
    • 15.3.2 Why do I get chmod permission issues?
    • 15.3.3 I see many 404 errors trying to download sources. Is anything wrong?
    • 15.3.4 Why do I get random build failures?
    • 15.3.5 Why does the build fail with iconv.h problems?
    • 15.3.6 Why don’t other recipes find the files provided by my *-native recipe?
    • 15.3.7 Can I get rid of build output so I can start over?
    • 15.3.8 Why isn’t there a way to append bbclass files like bbappend for recipes?
  • 15.4 Customizing generated images
    • 15.4.1 What does the OpenEmbedded build system produce as output?
    • 15.4.2 How do I make the Yocto Project support my board?
    • 15.4.3 How do I make the Yocto Project support my package?
    • 15.4.4 What do I need to ship for license compliance?
    • 15.4.5 Do I have to make a full reflash after recompiling one package?
    • 15.4.6 How to prevent my package from being marked as machine specific?
    • 15.4.7 What’s the difference between target and target-native?
    • 15.4.8 Why do ${bindir} and ${libdir} have strange values for -native recipes?
    • 15.4.9 How do I create images with more free space?
    • 15.4.10 Why aren’t spaces in path names supported?
    • 15.4.11 I’m adding a binary in a recipe. Why is it different in the image?
  • 15.5 Issues on the running system
    • 15.5.1 How do I disable the cursor on my touchscreen device?
    • 15.5.2 How to always bring up connected network interfaces?
• 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

---

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.