poky: subtree update:c67f57c09e..c6bc20857c
Adrian Freihofer (2):
oe-publish-sdk: fix layers init via ssh
oe-publish-sdk: add --keep-orig option
Alexander Kanavin (68):
meta-selftest: correct the virgl test for 5.8 kernels
bison: upgrade 3.6.4 -> 3.7.1
util-linux: upgrade 2.35.2 -> 2.36
python3-numpy: upgrade 1.19.0 -> 1.19.1
python3-setuptools: upgrade 49.3.1 -> 49.6.0
rsync: upgrade 3.2.2 -> 3.2.3
util-linux: merge .inc into .bb
acpica: upgrade 20200528 -> 20200717
asciidoc: upgrade 9.0.1 -> 9.0.2
cryptodev: upgrade 1.10 -> 1.11
diffoscope: upgrade 153 -> 156
epiphany: upgrade 3.36.3 -> 3.36.4
font-alias: upgrade 1.0.3 -> 1.0.4
gtk+3: upgrade 3.24.21 -> 3.24.22
libcheck: upgrade 0.15.0 -> 0.15.2
libinput: upgrade 1.16.0 -> 1.16.1
libpipeline: upgrade 1.5.2 -> 1.5.3
libx11: upgrade 1.6.9 -> 1.6.11
linux-firmware: upgrade 20200619 -> 20200721
man-pages: upgrade 5.07 -> 5.08
mc: upgrade 4.8.24 -> 4.8.25
mesa: upgrade 20.1.4 -> 20.1.5
piglit: upgrade to latest revision
re2c: upgrade 2.0 -> 2.0.2
sysstat: upgrade 12.2.2 -> 12.4.0
vala: upgrade 0.48.7 -> 0.48.9
bootchart2: update 0.14.8 -> 0.14.9
harfbuzz: convert to meson, enable gobject introspection
pango: update 1.44.7 -> 1.46.0
boost: update 1.73.0 -> 1.74.0
xev: update 1.2.3 -> 1.2.4
wpebackend-fdo: update 1.6.1 -> 1.7.1
gpgme: update 1.13.1 -> 1.14.0
libpsl: update 0.21.0 -> 0.21.1.
gettext: update 0.20.2 -> 0.21
cmake: update 3.17.3 -> 3.18.1
linux-firmware: update 20200721 -> 20200817
meson: update 0.55.0 -> 0.55.1
systemd-boot: bump version to 246.2
json-glib: inherit upstream-version-is-even
packagegroup-core-device-devel: remove
oeqa/x32lib: rework to use readelf from the host
oeqa/multilib: rework to use readelf from the host
oeqa/multilib: un-skip the connman test
poky.conf: do not install packagegroup-core-device-devel into qemu images
glib-2.0: update 2.64.4 -> 2.64.5
cmake: upgrade 3.18.1 -> 3.18.2
libxcrypt: upgrade 4.4.16 -> 4.4.17
debianutils: upgrade 4.11 -> 4.11.1
enchant2: upgrade 2.2.8 -> 2.2.9
harfbuzz: upgrade 2.7.1 -> 2.7.2
libmpc: upgrade 1.1.0 -> 1.2.0
librepo: upgrade 1.12.0 -> 1.12.1
libuv: upgrade 1.38.1 -> 1.39.0
msmtp: upgrade 1.8.11 -> 1.8.12
ninja: upgrade 1.10.0 -> 1.10.1
p11-kit: upgrade 0.23.20 -> 0.23.21
pango: upgrade 1.46.0 -> 1.46.1
re2c: upgrade 2.0.2 -> 2.0.3
resolvconf: upgrade 1.82 -> 1.83
stress-ng: upgrade 0.11.18 -> 0.11.19
gnu-config: update to latest revision
nasm: update 2.15.03 -> 2.15.05
libva-utils: fix upstream version check
gnupg: update 2.2.21 -> 2.2.22
libx11: update 1.6.11 -> 1.6.12
mesa: update 20.1.5 -> 20.1.6
xserver-xorg: update 1.20.8 -> 1.20.9
Andrey Zhizhikin (1):
insane: check for missing update-alternatives inherit
Anibal Limon (1):
recipes-kernel: linux-firmware add qcom-venus-{5.2,5.4} packages
Aníbal Limón (1):
recipes-graphics/xorg-xserver: Add patch to fix segfault when probe
Armin Kuster (2):
bind: update to 9.11.22 ESV
core-image-sato: qemumips use 512 mem
Bruce Ashfield (30):
linux-yocto/5.4: update to v5.4.59
linux-yocto/5.8: update to v5.8.2
yocto-bsp: update to v5.4.56
yocto-bsp: update to v5.4.58
qemu: bump default reference kernel to v5.8
linux-yocto/5.8: fix perf and virtio_scsi warnings
linux-yocto-rt/5.8: fix lttng-modules build
linux-yocto/5.8: selftests/bpf: Prevent runqslower from racing on building bpftool
linux-yocto/5.8: disable CONFIG_NFS_DISABLE_UDP_SUPPORT
poky: set preferred version for linux-yocto to be v5.8
poky-tiny: set preferred version to 5.8
poky: add preferred version for linux-yocto-rt
linux-yocto/5.8: update to v5.8.3
linux-yocto/5.4: update to v5.4.60
kernel: config cleanups for 5.8+
linux-yocto/5.4: update to v5.4.61
linux-yocto/5.8: update to v5.8.4
linux-yocto/5.8: disable IKHEADERS in default builds
kernel-yocto: allow promotion of configuration warnings to errors
kernel-yocto: checksum all modifications to available kernel fragments directories
lttng-modules/devupstream: bump to latest 2.12 commits
linux-yocto-dev: bump to v5.9+
linux-yocto/5.8: update to v5.8.5
kernel-devsrc: account for HOSTCC and HOSTCXX
linux-yocto/config: netfilter: Enable nat for ipv4 and ipv6
linux-yocto/5.8: update to v5.8.8
linux-yocto/5.4: update to v5.4.64
linux-yocto/config: configuration warning cleanup
linux-yocto/5.8: update to v5.8.9
linux-yocto/5.4: update to v5.4.65
Changhyeok Bae (2):
iw: upgrade 5.4 -> 5.8
iputils: upgrade s20190709 -> s20200821
Chris Laplante (12):
bitbake: compat.py: remove file since it no longer actually implements anything
bitbake: COW: formatting
bitbake: COW: migrate test suite into tests/cow
cve-update-db-native: add progress handler
cve-check/cve-update-db-native: use lockfile to fix usage under multiconfig
cve-update-db-native: use context manager for cve_f
cve-check: avoid FileNotFoundError if no do_cve_check task has run
bitbake: utils: process_profilelog: use context manager
bitbake: utils: fix UnboundLocalError when _print_exception raises
cve-update-db-native: be less magical about checking whether the cve-check class is enabled
cve-update-db-native: move -journal checking into do_fetch
cve-update-db-native: remove unused variable
Christophe GUIBOUT (1):
initramfs-framework: support kernel cmdline with double quotes
Denys Dmytriyenko (2):
weston: upgrade 8.0.0 -> 9.0.0
cryptodev: bump 1 commit past 1.11 to fix 5.9-rc1+
Diego Sueiro (2):
license_image.bbclass: Create symlink to the image license manifest dir
license_image.bbclass: Fix symlink to the image license manifest dir creation
Douglas Royds (1):
tcmode-default: Drop gcc-cross-initial, gcc-crosssdk-initial references
Frazer Clews (1):
bitbake: lib: fix most undefined code picked up by pylint
Geoff Parker (1):
systemd-serialgetty: Replace sed quoting using ' with " to allow var expansion
Jacob Kroon (1):
gcc10: Don't default back to -fcommon
Jean-Francois Dagenais (1):
bitbake: siggen: clean_basepath: remove recipe full path when virtual:xyz present
Jens Rehsack (1):
lttng-modules: backport patches from 2.12.x to fix 5.4.64+ and 5.8.9+ builds
Joe Slater (1):
pseudo: fix renaming to self
Jon Mason (4):
cortex-m0plus.inc: change file permissions
tune-cortexa55.inc: clean-up ARMv8.2a uses
tune-cortexa57-cortexa53.inc: add CRC and set march
tune-cortexa*: Cleanups
Joshua Watt (8):
wic: Add 512 Byte alignment to --offset
oeqa: runtime_tests: Extra GPG debugging
oeqa: sdk: Capture stderr output
oeqa: reproducible: Fix test not producing diffs
diffoscope: upgrade 156 -> 158
bitbake: bitbake: Add parsing torture test
bitbake: cooker: Block SIGINT in worker processes
sphinx: dev-manual: Clarify that virtual providers do not apply to runtime dependencies
Kai Kang (1):
dhcpcd: 9.1.4 -> 9.2.0
Kevin Hao (1):
meta-yocto-bsp: Bump to the v5.8 kernel
Khairul Rohaizzat Jamaluddin (1):
wic/bootimg-efi: IMAGE_EFI_BOOT_FILES variable added to separate bootimg-efi and bootimg-partition
Khem Raj (24):
gcc-cross-canadian: Install gcc/g++ wrappers for musl
uninative: Upgrade to 2.9
packagegroup-core-tools-profile: Disable lttng-modules for riscv64
lttng-modules: Disable on riscv64
kexec-tools: Fix build with -fno-common on ppc
lttng-tools: Do not build for riscv64
util-linux: Allow update alternatives for additional apps
lttng-tools: lttng-ust works on riscv64
json-glib: Backport a build fix with clang
rpcbind: Use update-alternatives for rpcinfo
go: Upgrade to 1.15 major release
weston-init: Redefine weston service and add socket activation option
musl: Upgrade to latest master
libucontext: Recognise riscv32 architecture
linuxloader.bbclass: Define riscv32 ldso for musl
populate_sdk_ext: Do not assume local.conf will always exist
weston: plane_add_prop() calls break musl atomic modesetting
weston-init: Enable RDP screen share
weston-init: Do not use fbdev backend
weston-init: Select drm/fbdev backends for qemu machines
oeqa/weston: Fix tests to run with systemd
core-image-weston: Bump qemu memory to 512M
go: Update to 1.15.2 minor release
bind: Inherit update-alternatives
Mark Hatle (6):
package_tar.bbclass: Sync to the other package_* classes
kernel.bbclass: Remove do_install[prefunc] no longer needed
buildhistory.bbclass: Rework to use read_subpackage_metadata
kernel.bbclass: Move away from calling package_get_auto_pr
package.bbclass: hash equivalency and pr service
bitbake: process.py: Handle SystemExit exception to eliminate backtrace
Mark Morton (1):
sphinx: test-manual code block, link, and format update
Martin Jansa (7):
devtool: expand SRC_URI when guessing recipe update mode
image-artifact-names: introduce new bbclass and move some variables into it
kernel.bbclass: use bash variables like imageType, base_name without {}
kernel.bbclass: eliminate (initramfs_)symlink_name variables
kernel.bbclass: use camelCase notation for bash variables in do_deploy
*-initramfs: don't use .rootfs IMAGE_NAME_SUFFIX
bitbake.conf: use ${TCMODE}-${TCLIBC} directory for CACHE
Matt Madison (1):
image.bbclass: fix REPRODUCIBLE_TIMESTAMP_ROOTFS reference
Michael Gloff (2):
sysvinit rc: Use PSPLASH_FIFO_DIR for progress fifo
sysvinit: Remove ${B} assignment
Michael Tretter (1):
devtool: deploy-target: Fix size calculation for hard links
Ming Liu (2):
systemd: split systemd specific udev rules into its own package
libubootenv: inherit uboot-config
Mingli Yu (3):
qemu: always define unknown_lock_type
qemu: override DEBUG_BUILD
bison: remove the parallel build patch
Naveen Saini (1):
lib/oe/recipeutils.py: add support for BBFILES_DYNAMIC
Nicolas Dechesne (73):
linux-libc-headers: kernel headers are installed in STAGING_KERNEL_BUILDDIR
bitbake: sphinx: add initial build infrastructure
bitbake: sphinx: initial sphinx support
bitbake: sphinx: bitbake-user-manual: use builtin sphinx glossary
bitbake: sphinx: switch to readthedocs theme
bitbake: sphinx: override theme CSS
bitbake: sphinx: fixup for links
bitbake: sphinx: fix links inside notes
bitbake: sphinx: fixes all remaining warnings
bitbake: sphinx: Makefile.sphinx: add clean and publish targets
bitbake: sphinx: tweak html output a bit
bitbake: sphinx: add SPDX headers
bitbake: sphinx: index: move the boilerplate at the end of the page
bitbake: sphinx: conf: enable extlinks extension
bitbake: sphinx: add releases page
bitbake: sphinx: bitbake-user-manual: insert additional blank line after title
bitbake: sphinx: last manual round of fixes/improvements
bitbake: sphinx: update style for important, caution and warnings
bitbake: sphinx: remove leading '/'
bitbake: sphinx: theme_override: properly set font for verbatim text
bitbake: bitbake-user-manual: fix bad links
sphinx: add initial build infrastructure
sphinx: initial sphinx support
sphinx: ref-variables: use builtin sphinx glossary
sphinx: overview-manual: add figures
sphinx: switch to readthedocs theme
sphinx: Add SPDX license headers
sphinx: add CSS theme override
sphinx: bsp-guide: add figures
sphinx: add Yocto project logo
sphinx: conf: update copyright
sphinx: conf: add substitutions/global variables
sphinx: add boilerplate file
sphinx: add boilerplate to manuals
sphinx: ref-manual: add revision history table
sphinx: add a general index
sphinx: conf.py: enable sphinx.ext.autosectionlabel
sphinx: ref-manual: use builtin glossary for the Terms section
sphinx: fix internal links
sphinx: ref-manual: fix typo
sphinx: fix custom term links
sphinx: manual updates for some links
sphinx: dev-manual add figures
sphinx: kernel-dev: add figures
sphinx: profile-manual: add figures
sphinx: fix up bold text for informalexample container
sphinx: ref-manual: add figures
sphinx: sdk-manual: add figures
sphinx: test-manual: add figures
sphinx: toaster-manual: add figures
sphinx: add links for Yocto project website
sphinx: fix links when the link text should be displayed
sphinx: add links to terms in the BitBake glossary
sphinx: add links to section in the Bitbake manual
sphinx: setup extlink for docs.yoctoproject.org
sphinx: enable intersphinx extension
sphinx: insert blank below between title and toc
sphinx: fix up terms related to kernel-fitimage
sphinx: conf: a few rendering tweaks
sphinx: makefile: add publish target
sphinx: conf: include CSS/JS files, the proper way
sphinx: convert 'what I wish I'd known'
sphinx: convert 'transitioning to a custom environment'
sphinx: ref-manual: fix heading for oe-init-build-env
sphinx: brief-yoctoprojectqs: fix up all remaining rendering issues
sphinx: Makefile.sphinx improvements
sphinx: convert bsp-guide
sphinx: remove leading '/'
sphinx: update style for important, caution and warnings
sphinx: profile-manual: convert profile-manual
sphinx: theme_override: properly set font for verbatim text
sphinx: theme_override: add tying-it-together admonition
sphinx: conf: exclude adt-manual/*.rst
Oleksandr Kravchuk (1):
ell: update to 0.33
Ovidiu Panait (1):
libxml2: Fix CVE-2020-24977
Peter A. Bigot (2):
bluez5: fix builds that require ell support
timezone: include leap second data in tzdata-core
Peter Bergin (1):
systemd: avoid failing if no udev rules provided
Pierre-Jean Texier (2):
libubootenv: upgrade 0.3 -> 0.3.1
diffoscope: upgrade 158 -> 160
Quentin Schulz (16):
sphinx: brief-yoctoprojectqs: remove redundant welcome
sphinx: brief-yoctoprojectqs: fix ambiguous note for cyclone5 example
sphinx: brief-yoctoprojectqs: add missing boilerplate
sphinx: overview-manual: add link to AUH how-to section
sphinx: overview-manual: fix bitbake basic explanation
sphinx: brief-yoctoprojectqs: add note on branch consistency between layers
sphinx: what-i-wish-id-known: update "don't be fooled by doc search results"
sphinx: overview-manual: remove highlight in bold section
sphinx: replace special quotes with single and double quotes
sphinx: fix incorrect indentations
sphinx: brief-yoctoprojectqs: put other distros note after Ubuntu-specific packages
sphinx: fix a few typos or missing/too many words
sphinx: "highlight" some variables, tasks or files
sphinx: fix or add missing links and remove mention of Eclipse workflow
ref-manual: examples: hello-autotools: upgrade to 2.10
ref-manual: examples: libxpm: add relative path to .inc
Rahul Kumar (1):
systemd-serialgetty: Fix sed expression quoting
Rasmus Villemoes (1):
kernel.bbclass: run do_symlink_kernsrc before do_patch
Richard Purdie (74):
nativesdk-sdk-provides-dummy: Add /bin/sh
bitbake: fetch2/wget: Remove buffering parameter
bitbake: cooker: Ensure parse_quit thread is closed down
bitbake: cooker: Explictly shut down the sync thread
bitbake: fetch2: Drop cups.org from wget status checks
bitbake: build/msg: Cleanup verbose option handling
bitbake: cooker/cookerdata/main: Improve loglevel handling
bitbake: cookerdata: Ensure UI options are updated to the server
bitbake: cooker/cookerdata: Ensure UI event log is updated from commandline
bitbake: cooker: Defer configuration init to after UI connection
bitbake: server/process: Move the socket code to server process only
bitbake: main/server/process: Drop configuration object passing
bitbake: cooker: Ensure BB_ORIGENV is updated by changes to configuration.env
bitbake: server/process: Log extra threads at exit
bitbake: server/process: Add bitbake-server and exec() a new server process
bitbake: runqueue: Don't use sys.argv
bitbake: cooker: Ensure cooker's enviroment is updated on updateConfig
connman-gnome/matchbox-desktop: Remove file:// globbing
selftest/recipetool: Drop globbing SRC_URI test, no longer supported
local.conf.sample: Document memory resident bitbake
bitbake: fetch2: Drop globbing supprt in file:// SRC_URIs
bitbake: server/process: Use sys.executable for bitbake-server
bitbake: process: Avoid bb.utils.timeout
bitbake: utils: Drop broken timeout function
bitbake: server/process: Fix typo in code causing tracebacks
oeqa/selftest: Apply patch to fix cpio build with -fno-common
runqemu: Show an error for conflicting graphics options
lttng: Move platform logic to dedicated inc file
patchelf: upgrade 0.11 -> 0.12
build-appliance/packagegroup-core-base-utils: Replace dhcp-client/dhcp-server with dhcpcd/kea
selftest/prservice: Improve test failure message
iputils: Adapt ${PN}-tftpd package dependency to PACKAGECONFIG
bitbake: process/knotty: Improve early exception handling
bitbake: cooker/cookerdata: Use BBHandledException, not sys.exit()
bitbake: cookerdata: Fix exception raise statements
bitbake: process: Avoid printing binary strings for leftover processes
bitbake: server/process: Ensure logging is flushed
bitbake: server/process: Don't show tracebacks if the lockfile is removed
bitbake: cooker: Ensure parser replacement calls parser final_cleanup
bitbake: cooker: Assign a name to the sync thread to aid debugging
bitbake: server/process: Ensure we don't keep looping if some other server is started
bitbake: server/process: Prefix the log data with pid/time information
bitbake: server/process: Note when commands complete in logs
bitbake: cooker: Ensure parser is cleaned up
runqemu: Add a hook to allow it to renice
bitbake: cooker: Avoid parser deadlocks
bitbake: cooker: Ensure parser worker signal handlers are default
selftest/signing: Ensure build path relocation is safe
oeqa/concurrencytest: Improve builddir path manipulations
bitbake: cooker/command: Fix disconnection handling
bitbake: tinfoil: Ensure sockets don't leak even when exceptions occur
bitbake: tests/fetch: Move away from problematic freedesktop.org urls
bitbake: sphinx: Enhance the sphinx experience/nagivation with:
bitbake: sphinx: theme_override: Use bold for emphasis text
Revert "qemu: always define unknown_lock_type"
Revert "core-image-sato: qemumips use 512 mem"
sphinx: Organize top level docs
sphinx: releases.rst: Add index/links to docs for previous releases
sphinx: boilerplate.rst: Drop versions notes as we have better navigation now
sphinx: boilerplate.rst: Sphinx puts the copyright elsewhere
sphinx: history: Move revision history to its own section
sphinx: manuals: Move boilerplate after toctree
sphinx: Add support for multiple docs version
sphinx: index.rst: Fix links
sphinx: ref-system-requirements: Improve formatting of the notes sections, merging them
sphinx: ref-manual links fixes and many other cleanups to import
sphinx: dev-manual: Various URL, code block and other fixes to imported data
sphinx: sdk-manual: Various URL, code block and other fixes to imported data
sphinx: kernel-dev: Various URL, code block and other fixes to imported data
sphinx: theme_override: Use bold for emphasis text
sphinx: ref-tasks: Add populate_sdk_ext task definition
sphinx: ref-manual/migration: Split each release into its own file
sphinx: overview-manual: Various URL, code block and other fixes to imported data
build-appliance-image: Update to master head revision
Robert Yang (3):
bitbake: cooker.py: Save prioritized BBFILES to BBFILES_PRIORITIZED
bitbake: utils.py: get_file_layer(): Exit the loop when file is matched
bitbake: utils.py: get_file_layer(): Improve performance
Ross Burton (25):
package.bbclass: explode the RPROVIDES so we don't think the versions are provides
elfutils: silence a new QA warning
insane: improve gnu-hash-style warning
gdk-pixbuf: add tests PACKAGECONFIG
debianutils: change SRC_URI to use snapshot.debian.org
insane: only load real files as ELF
autoconf: consolidate SRC_URI
autoconf: consolidate DEPENDS
kea: no need to depend on kea-native
kea: don't use PACKAGECONFIG inappropriately
kea: bump to 1.7.10
help2man: rewrite recipe
local.conf.sample.extended: remove help2man reference
curl: add vendors to CVE_PRODUCT to exclude false positives
harfbuzz: update patch status
harfbuzz: fix a build race around hb-version.h
cmake: whitelist CVE-2016-10642
ncurses: remove config.cache
qemu: fix CVE-2020-14364
cve-update-db-native: remove unused import
cve-update-db-native: add more logging when fetching
cve-update-db-native: use fetch task
alsa-plugins: improve .la removal
sato-screenshot: improve .la removal
buildhistory-diff: use BUILDDIR to know where buildhistory is
Saul Wold (1):
gnupg: uprev 2.2.22 -> 2.2.23
Stacy Gaikovaia (2):
bison: uprev from 3.7.1 to 3.7.2
valgrind: fix memcheck vgtests remove fullpath-after flags
Steve Sakoman (1):
xinput-calibrator: change SRC_URI to branch with libinput support
Sumit Garg (1):
insane: fix gnu-hash-style check
TeohJayShen (1):
oeqa/runtime: add test for matchbox-terminal
Tim Orling (1):
sphinx: toaster-manual: fix vars, links, code blocks
Vijai Kumar K (2):
image_types_wic: Add ASSUME_PROVIDED to WICVARS
wic: misc: Add /bin to the list of searchpaths
Yanfei Xu (1):
kernel-yocto: only replace leading -I in include paths
Yi Zhao (1):
glib-networking: add ptest
Zhixiong Chi (1):
gnutls: CVE-2020-24659
akuster (8):
log4cplus: move meta-oe pkg to core
kea: Move from meta-networking
maintainers.inc: Add me as kea & log4plus maintainer.
dhcpcd: Move from meta-network as OE-Core needs a client
maintainers.inc: Add me as dhcpcd maintainer
dhcp: remove from core
bind: Add 9.16.x
bind: 9.11 remove
hongxu (1):
sysstat: fix installed-vs-shipped QA Issue in systemd
zangrc (4):
libcap:upgrade 2.42 -> 2.43
libcap-ng:upgrade 0.7.10 -> 0.7.11
libgpg-error:upgrade 1.38 -> 1.39
at-spi2-core:upgrade 2.36.0 -> 2.36.1
Signed-off-by: Andrew Geissler <geissonator@yahoo.com>
Change-Id: I5542f5eea751a2641342e945725fd687cd74bebe
diff --git a/poky/documentation/overview-manual/overview-manual-yp-intro.rst b/poky/documentation/overview-manual/overview-manual-yp-intro.rst
new file mode 100644
index 0000000..265fbda
--- /dev/null
+++ b/poky/documentation/overview-manual/overview-manual-yp-intro.rst
@@ -0,0 +1,941 @@
+.. SPDX-License-Identifier: CC-BY-2.0-UK
+
+*****************************
+Introducing the Yocto Project
+*****************************
+
+What is the Yocto Project?
+==========================
+
+The Yocto Project is an open source collaboration project that helps
+developers create custom Linux-based systems that are designed for
+embedded products regardless of the product's hardware architecture.
+Yocto Project provides a flexible toolset and a development environment
+that allows embedded device developers across the world to collaborate
+through shared technologies, software stacks, configurations, and best
+practices used to create these tailored Linux images.
+
+Thousands of developers worldwide have discovered that Yocto Project
+provides advantages in both systems and applications development,
+archival and management benefits, and customizations used for speed,
+footprint, and memory utilization. The project is a standard when it
+comes to delivering embedded software stacks. The project allows
+software customizations and build interchange for multiple hardware
+platforms as well as software stacks that can be maintained and scaled.
+
+.. image:: figures/key-dev-elements.png
+ :align: center
+
+For further introductory information on the Yocto Project, you might be
+interested in this
+`article <https://www.embedded.com/electronics-blogs/say-what-/4458600/Why-the-Yocto-Project-for-my-IoT-Project->`__
+by Drew Moseley and in this short introductory
+`video <https://www.youtube.com/watch?v=utZpKM7i5Z4>`__.
+
+The remainder of this section overviews advantages and challenges tied
+to the Yocto Project.
+
+.. _gs-features:
+
+Features
+--------
+
+The following list describes features and advantages of the Yocto
+Project:
+
+- *Widely Adopted Across the Industry:* Semiconductor, operating
+ system, software, and service vendors exist whose products and
+ services adopt and support the Yocto Project. For a look at the Yocto
+ Project community and the companies involved with the Yocto Project,
+ see the "COMMUNITY" and "ECOSYSTEM" tabs on the
+ :yocto_home:`Yocto Project <>` home page.
+
+- *Architecture Agnostic:* Yocto Project supports Intel, ARM, MIPS,
+ AMD, PPC and other architectures. Most ODMs, OSVs, and chip vendors
+ create and supply BSPs that support their hardware. If you have
+ custom silicon, you can create a BSP that supports that architecture.
+
+ Aside from lots of architecture support, the Yocto Project fully
+ supports a wide range of device emulation through the Quick EMUlator
+ (QEMU).
+
+- *Images and Code Transfer Easily:* Yocto Project output can easily
+ move between architectures without moving to new development
+ environments. Additionally, if you have used the Yocto Project to
+ create an image or application and you find yourself not able to
+ support it, commercial Linux vendors such as Wind River, Mentor
+ Graphics, Timesys, and ENEA could take it and provide ongoing
+ support. These vendors have offerings that are built using the Yocto
+ Project.
+
+- *Flexibility:* Corporations use the Yocto Project many different
+ ways. One example is to create an internal Linux distribution as a
+ code base the corporation can use across multiple product groups.
+ Through customization and layering, a project group can leverage the
+ base Linux distribution to create a distribution that works for their
+ product needs.
+
+- *Ideal for Constrained Embedded and IoT devices:* Unlike a full Linux
+ distribution, you can use the Yocto Project to create exactly what
+ you need for embedded devices. You only add the feature support or
+ packages that you absolutely need for the device. For devices that
+ have display hardware, you can use available system components such
+ as X11, GTK+, Qt, Clutter, and SDL (among others) to create a rich
+ user experience. For devices that do not have a display or where you
+ want to use alternative UI frameworks, you can choose to not install
+ these components.
+
+- *Comprehensive Toolchain Capabilities:* Toolchains for supported
+ architectures satisfy most use cases. However, if your hardware
+ supports features that are not part of a standard toolchain, you can
+ easily customize that toolchain through specification of
+ platform-specific tuning parameters. And, should you need to use a
+ third-party toolchain, mechanisms built into the Yocto Project allow
+ for that.
+
+- *Mechanism Rules Over Policy:* Focusing on mechanism rather than
+ policy ensures that you are free to set policies based on the needs
+ of your design instead of adopting decisions enforced by some system
+ software provider.
+
+- *Uses a Layer Model:* The Yocto Project `layer
+ infrastructure <#the-yocto-project-layer-model>`__ groups related
+ functionality into separate bundles. You can incrementally add these
+ grouped functionalities to your project as needed. Using layers to
+ isolate and group functionality reduces project complexity and
+ redundancy, allows you to easily extend the system, make
+ customizations, and keep functionality organized.
+
+- *Supports Partial Builds:* You can build and rebuild individual
+ packages as needed. Yocto Project accomplishes this through its
+ `shared-state cache <#shared-state-cache>`__ (sstate) scheme. Being
+ able to build and debug components individually eases project
+ development.
+
+- *Releases According to a Strict Schedule:* Major releases occur on a
+ :doc:`six-month cycle <../ref-manual/ref-release-process>`
+ predictably in October and April. The most recent two releases
+ support point releases to address common vulnerabilities and
+ exposures. This predictability is crucial for projects based on the
+ Yocto Project and allows development teams to plan activities.
+
+- *Rich Ecosystem of Individuals and Organizations:* For open source
+ projects, the value of community is very important. Support forums,
+ expertise, and active developers who continue to push the Yocto
+ Project forward are readily available.
+
+- *Binary Reproducibility:* The Yocto Project allows you to be very
+ specific about dependencies and achieves very high percentages of
+ binary reproducibility (e.g. 99.8% for ``core-image-minimal``). When
+ distributions are not specific about which packages are pulled in and
+ in what order to support dependencies, other build systems can
+ arbitrarily include packages.
+
+- *License Manifest:* The Yocto Project provides a :ref:`license
+ manifest <dev-manual/dev-manual-common-tasks:maintaining open source license compliance during your product's lifecycle>`
+ for review by people who need to track the use of open source
+ licenses (e.g. legal teams).
+
+.. _gs-challenges:
+
+Challenges
+----------
+
+The following list presents challenges you might encounter when
+developing using the Yocto Project:
+
+- *Steep Learning Curve:* The Yocto Project has a steep learning curve
+ and has many different ways to accomplish similar tasks. It can be
+ difficult to choose how to proceed when varying methods exist by
+ which to accomplish a given task.
+
+- *Understanding What Changes You Need to Make For Your Design Requires
+ Some Research:* Beyond the simple tutorial stage, understanding what
+ changes need to be made for your particular design can require a
+ significant amount of research and investigation. For information
+ that helps you transition from trying out the Yocto Project to using
+ it for your project, see the ":ref:`what-i-wish-id-known:what i wish i'd known about yocto project`" and
+ ":ref:`transitioning-to-a-custom-environment:transitioning to a custom environment for systems development`"
+ documents on the Yocto Project website.
+
+- *Project Workflow Could Be Confusing:* The `Yocto Project
+ workflow <#overview-development-environment>`__ could be confusing if
+ you are used to traditional desktop and server software development.
+ In a desktop development environment, mechanisms exist to easily pull
+ and install new packages, which are typically pre-compiled binaries
+ from servers accessible over the Internet. Using the Yocto Project,
+ you must modify your configuration and rebuild to add additional
+ packages.
+
+- *Working in a Cross-Build Environment Can Feel Unfamiliar:* When
+ developing code to run on a target, compilation, execution, and
+ testing done on the actual target can be faster than running a
+ BitBake build on a development host and then deploying binaries to
+ the target for test. While the Yocto Project does support development
+ tools on the target, the additional step of integrating your changes
+ back into the Yocto Project build environment would be required.
+ Yocto Project supports an intermediate approach that involves making
+ changes on the development system within the BitBake environment and
+ then deploying only the updated packages to the target.
+
+ The Yocto Project :term:`OpenEmbedded Build System`
+ produces packages
+ in standard formats (i.e. RPM, DEB, IPK, and TAR). You can deploy
+ these packages into the running system on the target by using
+ utilities on the target such as ``rpm`` or ``ipk``.
+
+- *Initial Build Times Can be Significant:* Long initial build times
+ are unfortunately unavoidable due to the large number of packages
+ initially built from scratch for a fully functioning Linux system.
+ Once that initial build is completed, however, the shared-state
+ (sstate) cache mechanism Yocto Project uses keeps the system from
+ rebuilding packages that have not been "touched" since the last
+ build. The sstate mechanism significantly reduces times for
+ successive builds.
+
+The Yocto Project Layer Model
+=============================
+
+The Yocto Project's "Layer Model" is a development model for embedded
+and IoT Linux creation that distinguishes the Yocto Project from other
+simple build systems. The Layer Model simultaneously supports
+collaboration and customization. Layers are repositories that contain
+related sets of instructions that tell the :term:`OpenEmbedded Build System`
+what to do. You can
+collaborate, share, and reuse layers.
+
+Layers can contain changes to previous instructions or settings at any
+time. This powerful override capability is what allows you to customize
+previously supplied collaborative or community layers to suit your
+product requirements.
+
+You use different layers to logically separate information in your
+build. As an example, you could have BSP, GUI, distro configuration,
+middleware, or application layers. Putting your entire build into one
+layer limits and complicates future customization and reuse. Isolating
+information into layers, on the other hand, helps simplify future
+customizations and reuse. You might find it tempting to keep everything
+in one layer when working on a single project. However, the more modular
+your Metadata, the easier it is to cope with future changes.
+
+.. note::
+
+ - Use Board Support Package (BSP) layers from silicon vendors when
+ possible.
+
+ - Familiarize yourself with the `Yocto Project curated layer
+ index <https://caffelli-staging.yoctoproject.org/software-overview/layers/>`__
+ or the `OpenEmbedded layer
+ index <http://layers.openembedded.org/layerindex/branch/master/layers/>`__.
+ The latter contains more layers but they are less universally
+ validated.
+
+ - Layers support the inclusion of technologies, hardware components,
+ and software components. The :ref:`Yocto Project
+ Compatible <dev-manual/dev-manual-common-tasks:making sure your layer is compatible with yocto project>`
+ designation provides a minimum level of standardization that
+ contributes to a strong ecosystem. "YP Compatible" is applied to
+ appropriate products and software components such as BSPs, other
+ OE-compatible layers, and related open-source projects, allowing
+ the producer to use Yocto Project badges and branding assets.
+
+To illustrate how layers are used to keep things modular, consider
+machine customizations. These types of customizations typically reside
+in a special layer, rather than a general layer, called a BSP Layer.
+Furthermore, the machine customizations should be isolated from recipes
+and Metadata that support a new GUI environment, for example. This
+situation gives you a couple of layers: one for the machine
+configurations, and one for the GUI environment. It is important to
+understand, however, that the BSP layer can still make machine-specific
+additions to recipes within the GUI environment layer without polluting
+the GUI layer itself with those machine-specific changes. You can
+accomplish this through a recipe that is a BitBake append
+(``.bbappend``) file, which is described later in this section.
+
+.. note::
+
+ For general information on BSP layer structure, see the
+ :doc:`../bsp-guide/bsp-guide`
+ .
+
+The :term:`Source Directory`
+contains both general layers and BSP layers right out of the box. You
+can easily identify layers that ship with a Yocto Project release in the
+Source Directory by their names. Layers typically have names that begin
+with the string ``meta-``.
+
+.. note::
+
+ It is not a requirement that a layer name begin with the prefix
+ meta-
+ , but it is a commonly accepted standard in the Yocto Project
+ community.
+
+For example, if you were to examine the `tree
+view <https://git.yoctoproject.org/cgit/cgit.cgi/poky/tree/>`__ of the
+``poky`` repository, you will see several layers: ``meta``,
+``meta-skeleton``, ``meta-selftest``, ``meta-poky``, and
+``meta-yocto-bsp``. Each of these repositories represents a distinct
+layer.
+
+For procedures on how to create layers, see the
+":ref:`dev-manual/dev-manual-common-tasks:understanding and creating layers`"
+section in the Yocto Project Development Tasks Manual.
+
+Components and Tools
+====================
+
+The Yocto Project employs a collection of components and tools used by
+the project itself, by project developers, and by those using the Yocto
+Project. These components and tools are open source projects and
+metadata that are separate from the reference distribution
+(:term:`Poky`) and the
+:term:`OpenEmbedded Build System`. Most of the
+components and tools are downloaded separately.
+
+This section provides brief overviews of the components and tools
+associated with the Yocto Project.
+
+.. _gs-development-tools:
+
+Development Tools
+-----------------
+
+The following list consists of tools that help you develop images and
+applications using the Yocto Project:
+
+- *CROPS:* `CROPS <https://github.com/crops/poky-container/>`__ is an
+ open source, cross-platform development framework that leverages
+ `Docker Containers <https://www.docker.com/>`__. CROPS provides an
+ easily managed, extensible environment that allows you to build
+ binaries for a variety of architectures on Windows, Linux and Mac OS
+ X hosts.
+
+- *devtool:* This command-line tool is available as part of the
+ extensible SDK (eSDK) and is its cornerstone. You can use ``devtool``
+ to help build, test, and package software within the eSDK. You can
+ use the tool to optionally integrate what you build into an image
+ built by the OpenEmbedded build system.
+
+ The ``devtool`` command employs a number of sub-commands that allow
+ you to add, modify, and upgrade recipes. As with the OpenEmbedded
+ build system, "recipes" represent software packages within
+ ``devtool``. When you use ``devtool add``, a recipe is automatically
+ created. When you use ``devtool modify``, the specified existing
+ recipe is used in order to determine where to get the source code and
+ how to patch it. In both cases, an environment is set up so that when
+ you build the recipe a source tree that is under your control is used
+ in order to allow you to make changes to the source as desired. By
+ default, both new recipes and the source go into a "workspace"
+ directory under the eSDK. The ``devtool upgrade`` command updates an
+ existing recipe so that you can build it for an updated set of source
+ files.
+
+ You can read about the ``devtool`` workflow in the Yocto Project
+ Application Development and Extensible Software Development Kit
+ (eSDK) Manual in the
+ ":ref:`sdk-manual/sdk-extensible:using \`\`devtool\`\` in your sdk workflow`"
+ section.
+
+- *Extensible Software Development Kit (eSDK):* The eSDK provides a
+ cross-development toolchain and libraries tailored to the contents of
+ a specific image. The eSDK makes it easy to add new applications and
+ libraries to an image, modify the source for an existing component,
+ test changes on the target hardware, and integrate into the rest of
+ the OpenEmbedded build system. The eSDK gives you a toolchain
+ experience supplemented with the powerful set of ``devtool`` commands
+ tailored for the Yocto Project environment.
+
+ For information on the eSDK, see the :doc:`../sdk-manual/sdk-manual` Manual.
+
+- *Toaster:* Toaster is a web interface to the Yocto Project
+ OpenEmbedded build system. Toaster allows you to configure, run, and
+ view information about builds. For information on Toaster, see the
+ :doc:`../toaster-manual/toaster-manual`.
+
+.. _gs-production-tools:
+
+Production Tools
+----------------
+
+The following list consists of tools that help production related
+activities using the Yocto Project:
+
+- *Auto Upgrade Helper:* This utility when used in conjunction with the
+ :term:`OpenEmbedded Build System`
+ (BitBake and
+ OE-Core) automatically generates upgrades for recipes that are based
+ on new versions of the recipes published upstream. See
+ :ref:`dev-manual/dev-manual-common-tasks:using the auto upgrade helper (auh)`
+ for how to set it up.
+
+- *Recipe Reporting System:* The Recipe Reporting System tracks recipe
+ versions available for Yocto Project. The main purpose of the system
+ is to help you manage the recipes you maintain and to offer a dynamic
+ overview of the project. The Recipe Reporting System is built on top
+ of the `OpenEmbedded Layer
+ Index <http://layers.openembedded.org/layerindex/layers/>`__, which
+ is a website that indexes OpenEmbedded-Core layers.
+
+- *Patchwork:* `Patchwork <http://jk.ozlabs.org/projects/patchwork/>`__
+ is a fork of a project originally started by
+ `OzLabs <http://ozlabs.org/>`__. The project is a web-based tracking
+ system designed to streamline the process of bringing contributions
+ into a project. The Yocto Project uses Patchwork as an organizational
+ tool to handle patches, which number in the thousands for every
+ release.
+
+- *AutoBuilder:* AutoBuilder is a project that automates build tests
+ and quality assurance (QA). By using the public AutoBuilder, anyone
+ can determine the status of the current "master" branch of Poky.
+
+ .. note::
+
+ AutoBuilder is based on buildbot.
+
+ A goal of the Yocto Project is to lead the open source industry with
+ a project that automates testing and QA procedures. In doing so, the
+ project encourages a development community that publishes QA and test
+ plans, publicly demonstrates QA and test plans, and encourages
+ development of tools that automate and test and QA procedures for the
+ benefit of the development community.
+
+ You can learn more about the AutoBuilder used by the Yocto Project
+ Autobuilder :doc:`here <../test-manual/test-manual-understand-autobuilder>`.
+
+- *Cross-Prelink:* Prelinking is the process of pre-computing the load
+ addresses and link tables generated by the dynamic linker as compared
+ to doing this at runtime. Doing this ahead of time results in
+ performance improvements when the application is launched and reduced
+ memory usage for libraries shared by many applications.
+
+ Historically, cross-prelink is a variant of prelink, which was
+ conceived by `Jakub
+ Jelínek <http://people.redhat.com/jakub/prelink.pdf>`__ a number of
+ years ago. Both prelink and cross-prelink are maintained in the same
+ repository albeit on separate branches. By providing an emulated
+ runtime dynamic linker (i.e. ``glibc``-derived ``ld.so`` emulation),
+ the cross-prelink project extends the prelink software's ability to
+ prelink a sysroot environment. Additionally, the cross-prelink
+ software enables the ability to work in sysroot style environments.
+
+ The dynamic linker determines standard load address calculations
+ based on a variety of factors such as mapping addresses, library
+ usage, and library function conflicts. The prelink tool uses this
+ information, from the dynamic linker, to determine unique load
+ addresses for executable and linkable format (ELF) binaries that are
+ shared libraries and dynamically linked. The prelink tool modifies
+ these ELF binaries with the pre-computed information. The result is
+ faster loading and often lower memory consumption because more of the
+ library code can be re-used from shared Copy-On-Write (COW) pages.
+
+ The original upstream prelink project only supports running prelink
+ on the end target device due to the reliance on the target device's
+ dynamic linker. This restriction causes issues when developing a
+ cross-compiled system. The cross-prelink adds a synthesized dynamic
+ loader that runs on the host, thus permitting cross-prelinking
+ without ever having to run on a read-write target filesystem.
+
+- *Pseudo:* Pseudo is the Yocto Project implementation of
+ `fakeroot <http://man.he.net/man1/fakeroot>`__, which is used to run
+ commands in an environment that seemingly has root privileges.
+
+ During a build, it can be necessary to perform operations that
+ require system administrator privileges. For example, file ownership
+ or permissions might need definition. Pseudo is a tool that you can
+ either use directly or through the environment variable
+ ``LD_PRELOAD``. Either method allows these operations to succeed as
+ if system administrator privileges exist even when they do not.
+
+ You can read more about Pseudo in the "`Fakeroot and
+ Pseudo <#fakeroot-and-pseudo>`__" section.
+
+.. _gs-openembedded-build-system:
+
+Open-Embedded Build System Components
+-------------------------------------
+
+The following list consists of components associated with the
+:term:`OpenEmbedded Build System`:
+
+- *BitBake:* BitBake is a core component of the Yocto Project and is
+ used by the OpenEmbedded build system to build images. While BitBake
+ is key to the build system, BitBake is maintained separately from the
+ Yocto Project.
+
+ BitBake is a generic task execution engine that allows shell and
+ Python tasks to be run efficiently and in parallel while working
+ within complex inter-task dependency constraints. In short, BitBake
+ is a build engine that works through recipes written in a specific
+ format in order to perform sets of tasks.
+
+ You can learn more about BitBake in the :doc:`BitBake User
+ Manual <bitbake:index>`.
+
+- *OpenEmbedded-Core:* OpenEmbedded-Core (OE-Core) is a common layer of
+ metadata (i.e. recipes, classes, and associated files) used by
+ OpenEmbedded-derived systems, which includes the Yocto Project. The
+ Yocto Project and the OpenEmbedded Project both maintain the
+ OpenEmbedded-Core. You can find the OE-Core metadata in the Yocto
+ Project :yocto_git:`Source Repositories </cgit/cgit.cgi/poky/tree/meta>`.
+
+ Historically, the Yocto Project integrated the OE-Core metadata
+ throughout the Yocto Project source repository reference system
+ (Poky). After Yocto Project Version 1.0, the Yocto Project and
+ OpenEmbedded agreed to work together and share a common core set of
+ metadata (OE-Core), which contained much of the functionality
+ previously found in Poky. This collaboration achieved a long-standing
+ OpenEmbedded objective for having a more tightly controlled and
+ quality-assured core. The results also fit well with the Yocto
+ Project objective of achieving a smaller number of fully featured
+ tools as compared to many different ones.
+
+ Sharing a core set of metadata results in Poky as an integration
+ layer on top of OE-Core. You can see that in this
+ `figure <#yp-key-dev-elements>`__. The Yocto Project combines various
+ components such as BitBake, OE-Core, script "glue", and documentation
+ for its build system.
+
+.. _gs-reference-distribution-poky:
+
+Reference Distribution (Poky)
+-----------------------------
+
+Poky is the Yocto Project reference distribution. It contains the
+:term:`OpenEmbedded Build System`
+(BitBake and OE-Core) as well as a set of metadata to get you started
+building your own distribution. See the
+`figure <#what-is-the-yocto-project>`__ in "What is the Yocto Project?"
+section for an illustration that shows Poky and its relationship with
+other parts of the Yocto Project.
+
+To use the Yocto Project tools and components, you can download
+(``clone``) Poky and use it to bootstrap your own distribution.
+
+.. note::
+
+ Poky does not contain binary files. It is a working example of how to
+ build your own custom Linux distribution from source.
+
+You can read more about Poky in the "`Reference Embedded Distribution
+(Poky) <#reference-embedded-distribution>`__" section.
+
+.. _gs-packages-for-finished-targets:
+
+Packages for Finished Targets
+-----------------------------
+
+The following lists components associated with packages for finished
+targets:
+
+- *Matchbox:* Matchbox is an Open Source, base environment for the X
+ Window System running on non-desktop, embedded platforms such as
+ handhelds, set-top boxes, kiosks, and anything else for which screen
+ space, input mechanisms, or system resources are limited.
+
+ Matchbox consists of a number of interchangeable and optional
+ applications that you can tailor to a specific, non-desktop platform
+ to enhance usability in constrained environments.
+
+ You can find the Matchbox source in the Yocto Project
+ :yocto_git:`Source Repositories <>`.
+
+- *Opkg:* Open PacKaGe management (opkg) is a lightweight package
+ management system based on the itsy package (ipkg) management system.
+ Opkg is written in C and resembles Advanced Package Tool (APT) and
+ Debian Package (dpkg) in operation.
+
+ Opkg is intended for use on embedded Linux devices and is used in
+ this capacity in the
+ `OpenEmbedded <http://www.openembedded.org/wiki/Main_Page>`__ and
+ `OpenWrt <https://openwrt.org/>`__ projects, as well as the Yocto
+ Project.
+
+ .. note::
+
+ As best it can, opkg maintains backwards compatibility with ipkg
+ and conforms to a subset of Debian's policy manual regarding
+ control files.
+
+ You can find the opkg source in the Yocto Project
+ :yocto_git:`Source Repositories <>`.
+
+.. _gs-archived-components:
+
+Archived Components
+-------------------
+
+The Build Appliance is a virtual machine image that enables you to build
+and boot a custom embedded Linux image with the Yocto Project using a
+non-Linux development system.
+
+Historically, the Build Appliance was the second of three methods by
+which you could use the Yocto Project on a system that was not native to
+Linux.
+
+1. *Hob:* Hob, which is now deprecated and is no longer available since
+ the 2.1 release of the Yocto Project provided a rudimentary,
+ GUI-based interface to the Yocto Project. Toaster has fully replaced
+ Hob.
+
+2. *Build Appliance:* Post Hob, the Build Appliance became available. It
+ was never recommended that you use the Build Appliance as a
+ day-to-day production development environment with the Yocto Project.
+ Build Appliance was useful as a way to try out development in the
+ Yocto Project environment.
+
+3. *CROPS:* The final and best solution available now for developing
+ using the Yocto Project on a system not native to Linux is with
+ `CROPS <#gs-crops-overview>`__.
+
+.. _gs-development-methods:
+
+Development Methods
+===================
+
+The Yocto Project development environment usually involves a
+:term:`Build Host` and target
+hardware. You use the Build Host to build images and develop
+applications, while you use the target hardware to test deployed
+software.
+
+This section provides an introduction to the choices or development
+methods you have when setting up your Build Host. Depending on the your
+particular workflow preference and the type of operating system your
+Build Host runs, several choices exist that allow you to use the Yocto
+Project.
+
+.. note::
+
+ For additional detail about the Yocto Project development
+ environment, see the ":doc:`overview-manual-development-environment`"
+ chapter.
+
+- *Native Linux Host:* By far the best option for a Build Host. A
+ system running Linux as its native operating system allows you to
+ develop software by directly using the
+ :term:`BitBake` tool. You can
+ accomplish all aspects of development from a familiar shell of a
+ supported Linux distribution.
+
+ For information on how to set up a Build Host on a system running
+ Linux as its native operating system, see the
+ ":ref:`dev-manual/dev-manual-start:setting up a native linux host`"
+ section in the Yocto Project Development Tasks Manual.
+
+- *CROss PlatformS (CROPS):* Typically, you use
+ `CROPS <https://github.com/crops/poky-container/>`__, which leverages
+ `Docker Containers <https://www.docker.com/>`__, to set up a Build
+ Host that is not running Linux (e.g. Microsoft Windows or macOS).
+
+ .. note::
+
+ You can, however, use CROPS on a Linux-based system.
+
+ CROPS is an open source, cross-platform development framework that
+ provides an easily managed, extensible environment for building
+ binaries targeted for a variety of architectures on Windows, macOS,
+ or Linux hosts. Once the Build Host is set up using CROPS, you can
+ prepare a shell environment to mimic that of a shell being used on a
+ system natively running Linux.
+
+ For information on how to set up a Build Host with CROPS, see the
+ ":ref:`dev-manual/dev-manual-start:setting up to use cross platforms (crops)`"
+ section in the Yocto Project Development Tasks Manual.
+
+- *Windows Subsystem For Linux (WSLv2):* You may use Windows Subsystem
+ For Linux v2 to set up a build host using Windows 10.
+
+ .. note::
+
+ The Yocto Project is not compatible with WSLv1, it is compatible
+ but not officially supported nor validated with WSLv2, if you
+ still decide to use WSL please upgrade to WSLv2.
+
+ The Windows Subsystem For Linux allows Windows 10 to run a real Linux
+ kernel inside of a lightweight utility virtual machine (VM) using
+ virtualization technology.
+
+ For information on how to set up a Build Host with WSLv2, see the
+ ":ref:`dev-manual/dev-manual-start:setting up to use windows subsystem for linux (wslv2)`"
+ section in the Yocto Project Development Tasks Manual.
+
+- *Toaster:* Regardless of what your Build Host is running, you can use
+ Toaster to develop software using the Yocto Project. Toaster is a web
+ interface to the Yocto Project's :term:`OpenEmbedded Build System`.
+ The interface
+ enables you to configure and run your builds. Information about
+ builds is collected and stored in a database. You can use Toaster to
+ configure and start builds on multiple remote build servers.
+
+ For information about and how to use Toaster, see the
+ :doc:`../toaster-manual/toaster-manual`.
+
+.. _reference-embedded-distribution:
+
+Reference Embedded Distribution (Poky)
+======================================
+
+"Poky", which is pronounced *Pock*-ee, is the name of the Yocto
+Project's reference distribution or Reference OS Kit. Poky contains the
+:term:`OpenEmbedded Build System`
+(:term:`BitBake` and
+:term:`OpenEmbedded-Core (OE-Core)`) as well as a set
+of :term:`Metadata` to get you started
+building your own distro. In other words, Poky is a base specification
+of the functionality needed for a typical embedded system as well as the
+components from the Yocto Project that allow you to build a distribution
+into a usable binary image.
+
+Poky is a combined repository of BitBake, OpenEmbedded-Core (which is
+found in ``meta``), ``meta-poky``, ``meta-yocto-bsp``, and documentation
+provided all together and known to work well together. You can view
+these items that make up the Poky repository in the
+:yocto_git:`Source Repositories </cgit/cgit.cgi/poky/tree/>`.
+
+.. note::
+
+ If you are interested in all the contents of the
+ poky
+ Git repository, see the ":ref:`ref-manual/ref-structure:top-level core components`"
+ section in the Yocto Project Reference Manual.
+
+The following figure illustrates what generally comprises Poky:
+
+.. image:: figures/poky-reference-distribution.png
+ :align: center
+
+- BitBake is a task executor and scheduler that is the heart of the
+ OpenEmbedded build system.
+
+- ``meta-poky``, which is Poky-specific metadata.
+
+- ``meta-yocto-bsp``, which are Yocto Project-specific Board Support
+ Packages (BSPs).
+
+- OpenEmbedded-Core (OE-Core) metadata, which includes shared
+ configurations, global variable definitions, shared classes,
+ packaging, and recipes. Classes define the encapsulation and
+ inheritance of build logic. Recipes are the logical units of software
+ and images to be built.
+
+- Documentation, which contains the Yocto Project source files used to
+ make the set of user manuals.
+
+.. note::
+
+ While Poky is a "complete" distribution specification and is tested
+ and put through QA, you cannot use it as a product "out of the box"
+ in its current form.
+
+To use the Yocto Project tools, you can use Git to clone (download) the
+Poky repository then use your local copy of the reference distribution
+to bootstrap your own distribution.
+
+.. note::
+
+ Poky does not contain binary files. It is a working example of how to
+ build your own custom Linux distribution from source.
+
+Poky has a regular, well established, six-month release cycle under its
+own version. Major releases occur at the same time major releases (point
+releases) occur for the Yocto Project, which are typically in the Spring
+and Fall. For more information on the Yocto Project release schedule and
+cadence, see the ":doc:`../ref-manual/ref-release-process`" chapter in the
+Yocto Project Reference Manual.
+
+Much has been said about Poky being a "default configuration". A default
+configuration provides a starting image footprint. You can use Poky out
+of the box to create an image ranging from a shell-accessible minimal
+image all the way up to a Linux Standard Base-compliant image that uses
+a GNOME Mobile and Embedded (GMAE) based reference user interface called
+Sato.
+
+One of the most powerful properties of Poky is that every aspect of a
+build is controlled by the metadata. You can use metadata to augment
+these base image types by adding metadata
+`layers <#the-yocto-project-layer-model>`__ that extend functionality.
+These layers can provide, for example, an additional software stack for
+an image type, add a board support package (BSP) for additional
+hardware, or even create a new image type.
+
+Metadata is loosely grouped into configuration files or package recipes.
+A recipe is a collection of non-executable metadata used by BitBake to
+set variables or define additional build-time tasks. A recipe contains
+fields such as the recipe description, the recipe version, the license
+of the package and the upstream source repository. A recipe might also
+indicate that the build process uses autotools, make, distutils or any
+other build process, in which case the basic functionality can be
+defined by the classes it inherits from the OE-Core layer's class
+definitions in ``./meta/classes``. Within a recipe you can also define
+additional tasks as well as task prerequisites. Recipe syntax through
+BitBake also supports both ``_prepend`` and ``_append`` operators as a
+method of extending task functionality. These operators inject code into
+the beginning or end of a task. For information on these BitBake
+operators, see the
+":ref:`bitbake:bitbake-user-manual/bitbake-user-manual-metadata:appending and prepending (override style syntax)`"
+section in the BitBake User's Manual.
+
+.. _openembedded-build-system-workflow:
+
+The OpenEmbedded Build System Workflow
+======================================
+
+The :term:`OpenEmbedded Build System` uses a "workflow" to
+accomplish image and SDK generation. The following figure overviews that
+workflow:
+
+.. image:: figures/YP-flow-diagram.png
+ :align: center
+
+Following is a brief summary of the "workflow":
+
+1. Developers specify architecture, policies, patches and configuration
+ details.
+
+2. The build system fetches and downloads the source code from the
+ specified location. The build system supports standard methods such
+ as tarballs or source code repositories systems such as Git.
+
+3. Once source code is downloaded, the build system extracts the sources
+ into a local work area where patches are applied and common steps for
+ configuring and compiling the software are run.
+
+4. The build system then installs the software into a temporary staging
+ area where the binary package format you select (DEB, RPM, or IPK) is
+ used to roll up the software.
+
+5. Different QA and sanity checks run throughout entire build process.
+
+6. After the binaries are created, the build system generates a binary
+ package feed that is used to create the final root file image.
+
+7. The build system generates the file system image and a customized
+ Extensible SDK (eSDK) for application development in parallel.
+
+For a very detailed look at this workflow, see the "`OpenEmbedded Build
+System Concepts <#openembedded-build-system-build-concepts>`__" section.
+
+Some Basic Terms
+================
+
+It helps to understand some basic fundamental terms when learning the
+Yocto Project. Although a list of terms exists in the ":doc:`Yocto Project
+Terms <../ref-manual/ref-terms>`" section of the Yocto Project
+Reference Manual, this section provides the definitions of some terms
+helpful for getting started:
+
+- *Configuration Files:* Files that hold global definitions of
+ variables, user-defined variables, and hardware configuration
+ information. These files tell the :term:`OpenEmbedded Build System`
+ what to build and
+ what to put into the image to support a particular platform.
+
+- *Extensible Software Development Kit (eSDK):* A custom SDK for
+ application developers. This eSDK allows developers to incorporate
+ their library and programming changes back into the image to make
+ their code available to other application developers. For information
+ on the eSDK, see the :doc:`../sdk-manual/sdk-manual` manual.
+
+- *Layer:* A collection of related recipes. Layers allow you to
+ consolidate related metadata to customize your build. Layers also
+ isolate information used when building for multiple architectures.
+ Layers are hierarchical in their ability to override previous
+ specifications. You can include any number of available layers from
+ the Yocto Project and customize the build by adding your layers after
+ them. You can search the Layer Index for layers used within Yocto
+ Project.
+
+ For more detailed information on layers, see the
+ ":ref:`dev-manual/dev-manual-common-tasks:understanding and creating layers`"
+ section in the Yocto Project Development Tasks Manual. For a
+ discussion specifically on BSP Layers, see the
+ ":ref:`bsp-guide/bsp:bsp layers`" section in the Yocto
+ Project Board Support Packages (BSP) Developer's Guide.
+
+- *Metadata:* A key element of the Yocto Project is the Metadata that
+ is used to construct a Linux distribution and is contained in the
+ files that the OpenEmbedded build system parses when building an
+ image. In general, Metadata includes recipes, configuration files,
+ and other information that refers to the build instructions
+ themselves, as well as the data used to control what things get built
+ and the effects of the build. Metadata also includes commands and
+ data used to indicate what versions of software are used, from where
+ they are obtained, and changes or additions to the software itself
+ (patches or auxiliary files) that are used to fix bugs or customize
+ the software for use in a particular situation. OpenEmbedded-Core is
+ an important set of validated metadata.
+
+- *OpenEmbedded Build System:* The terms "BitBake" and "build system"
+ are sometimes used for the OpenEmbedded Build System.
+
+ BitBake is a task scheduler and execution engine that parses
+ instructions (i.e. recipes) and configuration data. After a parsing
+ phase, BitBake creates a dependency tree to order the compilation,
+ schedules the compilation of the included code, and finally executes
+ the building of the specified custom Linux image (distribution).
+ BitBake is similar to the ``make`` tool.
+
+ During a build process, the build system tracks dependencies and
+ performs a native or cross-compilation of the package. As a first
+ step in a cross-build setup, the framework attempts to create a
+ cross-compiler toolchain (i.e. Extensible SDK) suited for the target
+ platform.
+
+- *OpenEmbedded-Core (OE-Core):* OE-Core is metadata comprised of
+ foundation recipes, classes, and associated files that are meant to
+ be common among many different OpenEmbedded-derived systems,
+ including the Yocto Project. OE-Core is a curated subset of an
+ original repository developed by the OpenEmbedded community that has
+ been pared down into a smaller, core set of continuously validated
+ recipes. The result is a tightly controlled and quality-assured core
+ set of recipes.
+
+ You can see the Metadata in the ``meta`` directory of the Yocto
+ Project `Source
+ Repositories <http://git.yoctoproject.org/cgit/cgit.cgi>`__.
+
+- *Packages:* In the context of the Yocto Project, this term refers to
+ a recipe's packaged output produced by BitBake (i.e. a "baked
+ recipe"). A package is generally the compiled binaries produced from
+ the recipe's sources. You "bake" something by running it through
+ BitBake.
+
+ It is worth noting that the term "package" can, in general, have
+ subtle meanings. For example, the packages referred to in the
+ ":ref:`ref-manual/ref-system-requirements:required packages for the build host`"
+ section in the Yocto Project Reference Manual are compiled binaries
+ that, when installed, add functionality to your Linux distribution.
+
+ Another point worth noting is that historically within the Yocto
+ Project, recipes were referred to as packages - thus, the existence
+ of several BitBake variables that are seemingly mis-named, (e.g.
+ :term:`PR`,
+ :term:`PV`, and
+ :term:`PE`).
+
+- *Poky:* Poky is a reference embedded distribution and a reference
+ test configuration. Poky provides the following:
+
+ - A base-level functional distro used to illustrate how to customize
+ a distribution.
+
+ - A means by which to test the Yocto Project components (i.e. Poky
+ is used to validate the Yocto Project).
+
+ - A vehicle through which you can download the Yocto Project.
+
+ Poky is not a product level distro. Rather, it is a good starting
+ point for customization.
+
+ .. note::
+
+ Poky is an integration layer on top of OE-Core.
+
+- *Recipe:* The most common form of metadata. A recipe contains a list
+ of settings and tasks (i.e. instructions) for building packages that
+ are then used to build the binary image. A recipe describes where you
+ get source code and which patches to apply. Recipes describe
+ dependencies for libraries or for other recipes as well as
+ configuration and compilation options. Related recipes are
+ consolidated into a layer.