1.. SPDX-License-Identifier: CC-BY-SA-2.0-UK 2 3***************************** 4Introducing the Yocto Project 5***************************** 6 7What is the Yocto Project? 8========================== 9 10The Yocto Project is an open source collaboration project that helps 11developers create custom Linux-based systems that are designed for 12embedded products regardless of the product's hardware architecture. 13Yocto Project provides a flexible toolset and a development environment 14that allows embedded device developers across the world to collaborate 15through shared technologies, software stacks, configurations, and best 16practices used to create these tailored Linux images. 17 18Thousands of developers worldwide have discovered that Yocto Project 19provides advantages in both systems and applications development, 20archival and management benefits, and customizations used for speed, 21footprint, and memory utilization. The project is a standard when it 22comes to delivering embedded software stacks. The project allows 23software customizations and build interchange for multiple hardware 24platforms as well as software stacks that can be maintained and scaled. 25 26.. image:: figures/key-dev-elements.png 27 :width: 100% 28 29For further introductory information on the Yocto Project, you might be 30interested in this 31`article <https://www.embedded.com/electronics-blogs/say-what-/4458600/Why-the-Yocto-Project-for-my-IoT-Project->`__ 32by Drew Moseley and in this short introductory 33`video <https://www.youtube.com/watch?v=utZpKM7i5Z4>`__. 34 35The remainder of this section overviews advantages and challenges tied 36to the Yocto Project. 37 38Features 39-------- 40 41Here are features and advantages of the Yocto Project: 42 43- *Widely Adopted Across the Industry:* Many semiconductor, operating 44 system, software, and service vendors adopt and support the Yocto 45 Project in their products and services. For a look at the Yocto 46 Project community and the companies involved with the Yocto Project, 47 see the "COMMUNITY" and "ECOSYSTEM" tabs on the 48 :yocto_home:`Yocto Project <>` home page. 49 50- *Architecture Agnostic:* Yocto Project supports Intel, ARM, MIPS, 51 AMD, PPC and other architectures. Most ODMs, OSVs, and chip vendors 52 create and supply BSPs that support their hardware. If you have 53 custom silicon, you can create a BSP that supports that architecture. 54 55 Aside from broad architecture support, the Yocto Project fully 56 supports a wide range of devices emulated by the Quick EMUlator 57 (QEMU). 58 59- *Images and Code Transfer Easily:* Yocto Project output can easily 60 move between architectures without moving to new development 61 environments. Additionally, if you have used the Yocto Project to 62 create an image or application and you find yourself not able to 63 support it, commercial Linux vendors such as Wind River, Mentor 64 Graphics, Timesys, and ENEA could take it and provide ongoing 65 support. These vendors have offerings that are built using the Yocto 66 Project. 67 68- *Flexibility:* Corporations use the Yocto Project many different 69 ways. One example is to create an internal Linux distribution as a 70 code base the corporation can use across multiple product groups. 71 Through customization and layering, a project group can leverage the 72 base Linux distribution to create a distribution that works for their 73 product needs. 74 75- *Ideal for Constrained Embedded and IoT devices:* Unlike a full Linux 76 distribution, you can use the Yocto Project to create exactly what 77 you need for embedded devices. You only add the feature support or 78 packages that you absolutely need for the device. For devices that 79 have display hardware, you can use available system components such 80 as X11, Wayland, GTK+, Qt, Clutter, and SDL (among others) to create 81 a rich user experience. For devices that do not have a display or 82 where you want to use alternative UI frameworks, you can choose to 83 not build these components. 84 85- *Comprehensive Toolchain Capabilities:* Toolchains for supported 86 architectures satisfy most use cases. However, if your hardware 87 supports features that are not part of a standard toolchain, you can 88 easily customize that toolchain through specification of 89 platform-specific tuning parameters. And, should you need to use a 90 third-party toolchain, mechanisms built into the Yocto Project allow 91 for that. 92 93- *Mechanism Rules Over Policy:* Focusing on mechanism rather than 94 policy ensures that you are free to set policies based on the needs 95 of your design instead of adopting decisions enforced by some system 96 software provider. 97 98- *Uses a Layer Model:* The Yocto Project :ref:`layer 99 infrastructure <overview-manual/yp-intro:the yocto project layer model>` 100 groups related functionality into separate bundles. You can incrementally 101 add these grouped functionalities to your project as needed. Using layers to 102 isolate and group functionality reduces project complexity and 103 redundancy, allows you to easily extend the system, make 104 customizations, and keep functionality organized. 105 106- *Supports Partial Builds:* You can build and rebuild individual 107 packages as needed. Yocto Project accomplishes this through its 108 :ref:`overview-manual/concepts:shared state cache` (sstate) scheme. 109 Being able to build and debug components individually eases project 110 development. 111 112- *Releases According to a Strict Schedule:* Major releases occur on a 113 :doc:`six-month cycle </ref-manual/release-process>` 114 predictably in October and April. The most recent two releases 115 support point releases to address common vulnerabilities and 116 exposures. This predictability is crucial for projects based on the 117 Yocto Project and allows development teams to plan activities. 118 119- *Rich Ecosystem of Individuals and Organizations:* For open source 120 projects, the value of community is very important. Support forums, 121 expertise, and active developers who continue to push the Yocto 122 Project forward are readily available. 123 124- *Binary Reproducibility:* The Yocto Project allows you to be very 125 specific about dependencies and achieves very high percentages of 126 binary reproducibility (e.g. 99.8% for ``core-image-minimal``). When 127 distributions are not specific about which packages are pulled in and 128 in what order to support dependencies, other build systems can 129 arbitrarily include packages. 130 131- *License Manifest:* The Yocto Project provides a :ref:`license 132 manifest <dev-manual/licenses:maintaining open source license compliance during your product's lifecycle>` 133 for review by people who need to track the use of open source 134 licenses (e.g. legal teams). 135 136Challenges 137---------- 138 139Here are challenges you might encounter when developing using the Yocto Project: 140 141- *Steep Learning Curve:* The Yocto Project has a steep learning curve 142 and has many different ways to accomplish similar tasks. It can be 143 difficult to choose between such ways. 144 145- *Understanding What Changes You Need to Make For Your Design Requires 146 Some Research:* Beyond the simple tutorial stage, understanding what 147 changes need to be made for your particular design can require a 148 significant amount of research and investigation. For information 149 that helps you transition from trying out the Yocto Project to using 150 it for your project, see the ":ref:`what-i-wish-id-known:what i wish i'd known about yocto project`" and 151 ":ref:`transitioning-to-a-custom-environment:transitioning to a custom environment for systems development`" 152 documents on the Yocto Project website. 153 154- *Project Workflow Could Be Confusing:* The :ref:`Yocto Project 155 workflow <overview-manual/development-environment:the yocto project development environment>` 156 could be confusing if you are used to traditional desktop and server 157 software development. 158 In a desktop development environment, there are mechanisms to easily pull 159 and install new packages, which are typically pre-compiled binaries 160 from servers accessible over the Internet. Using the Yocto Project, 161 you must modify your configuration and rebuild to add additional 162 packages. 163 164- *Working in a Cross-Build Environment Can Feel Unfamiliar:* When 165 developing code to run on a target, compilation, execution, and 166 testing done on the actual target can be faster than running a 167 BitBake build on a development host and then deploying binaries to 168 the target for test. While the Yocto Project does support development 169 tools on the target, the additional step of integrating your changes 170 back into the Yocto Project build environment would be required. 171 Yocto Project supports an intermediate approach that involves making 172 changes on the development system within the BitBake environment and 173 then deploying only the updated packages to the target. 174 175 The Yocto Project :term:`OpenEmbedded Build System` 176 produces packages 177 in standard formats (i.e. RPM, DEB, IPK, and TAR). You can deploy 178 these packages into the running system on the target by using 179 utilities on the target such as ``rpm`` or ``ipk``. 180 181- *Initial Build Times Can be Significant:* Long initial build times 182 are unfortunately unavoidable due to the large number of packages 183 initially built from scratch for a fully functioning Linux system. 184 Once that initial build is completed, however, the shared-state 185 (sstate) cache mechanism Yocto Project uses keeps the system from 186 rebuilding packages that have not been "touched" since the last 187 build. The sstate mechanism significantly reduces times for 188 successive builds. 189 190The Yocto Project Layer Model 191============================= 192 193The Yocto Project's "Layer Model" is a development model for embedded 194and IoT Linux creation that distinguishes the Yocto Project from other 195simple build systems. The Layer Model simultaneously supports 196collaboration and customization. Layers are repositories that contain 197related sets of instructions that tell the :term:`OpenEmbedded Build System` 198what to do. You can 199collaborate, share, and reuse layers. 200 201Layers can contain changes to previous instructions or settings at any 202time. This powerful override capability is what allows you to customize 203previously supplied collaborative or community layers to suit your 204product requirements. 205 206You use different layers to logically separate information in your 207build. As an example, you could have BSP, GUI, distro configuration, 208middleware, or application layers. Putting your entire build into one 209layer limits and complicates future customization and reuse. Isolating 210information into layers, on the other hand, helps simplify future 211customizations and reuse. You might find it tempting to keep everything 212in one layer when working on a single project. However, the more modular 213your Metadata, the easier it is to cope with future changes. 214 215.. note:: 216 217 - Use Board Support Package (BSP) layers from silicon vendors when 218 possible. 219 220 - Familiarize yourself with the 221 :yocto_home:`Yocto Project Compatible Layers </software-overview/layers/>` 222 or the :oe_layerindex:`OpenEmbedded Layer Index <>`. 223 The latter contains more layers but they are less universally 224 validated. 225 226 - Layers support the inclusion of technologies, hardware components, 227 and software components. The :ref:`Yocto Project 228 Compatible <dev-manual/layers:making sure your layer is compatible with yocto project>` 229 designation provides a minimum level of standardization that 230 contributes to a strong ecosystem. "YP Compatible" is applied to 231 appropriate products and software components such as BSPs, other 232 OE-compatible layers, and related open-source projects, allowing 233 the producer to use Yocto Project badges and branding assets. 234 235To illustrate how layers are used to keep things modular, consider 236machine customizations. These types of customizations typically reside 237in a special layer, rather than a general layer, called a BSP Layer. 238Furthermore, the machine customizations should be isolated from recipes 239and Metadata that support a new GUI environment, for example. This 240situation gives you a couple of layers: one for the machine 241configurations, and one for the GUI environment. It is important to 242understand, however, that the BSP layer can still make machine-specific 243additions to recipes within the GUI environment layer without polluting 244the GUI layer itself with those machine-specific changes. You can 245accomplish this through a recipe that is a BitBake append 246(``.bbappend``) file, which is described later in this section. 247 248.. note:: 249 250 For general information on BSP layer structure, see the 251 :doc:`/bsp-guide/index`. 252 253The :term:`Source Directory` 254contains both general layers and BSP layers right out of the box. You 255can easily identify layers that ship with a Yocto Project release in the 256Source Directory by their names. Layers typically have names that begin 257with the string ``meta-``. 258 259.. note:: 260 261 It is not a requirement that a layer name begin with the prefix 262 ``meta-``, but it is a commonly accepted standard in the Yocto Project 263 community. 264 265For example, if you were to examine the :yocto_git:`tree view </poky/tree/>` 266of the ``poky`` repository, you will see several layers: ``meta``, 267``meta-skeleton``, ``meta-selftest``, ``meta-poky``, and 268``meta-yocto-bsp``. Each of these repositories represents a distinct 269layer. 270 271For procedures on how to create layers, see the 272":ref:`dev-manual/layers:understanding and creating layers`" 273section in the Yocto Project Development Tasks Manual. 274 275Components and Tools 276==================== 277 278The Yocto Project employs a collection of components and tools used by 279the project itself, by project developers, and by those using the Yocto 280Project. These components and tools are open source projects and 281metadata that are separate from the reference distribution 282(:term:`Poky`) and the :term:`OpenEmbedded Build System`. Most of the 283components and tools are downloaded separately. 284 285This section provides brief overviews of the components and tools 286associated with the Yocto Project. 287 288Development Tools 289----------------- 290 291Here are tools that help you develop images and applications using 292the Yocto Project: 293 294- *CROPS:* `CROPS <https://github.com/crops/poky-container/>`__ is an 295 open source, cross-platform development framework that leverages 296 `Docker Containers <https://www.docker.com/>`__. CROPS provides an 297 easily managed, extensible environment that allows you to build 298 binaries for a variety of architectures on Windows, Linux and Mac OS 299 X hosts. 300 301- *devtool:* This command-line tool is available as part of the 302 extensible SDK (eSDK) and is its cornerstone. You can use ``devtool`` 303 to help build, test, and package software within the eSDK. You can 304 use the tool to optionally integrate what you build into an image 305 built by the OpenEmbedded build system. 306 307 The ``devtool`` command employs a number of sub-commands that allow 308 you to add, modify, and upgrade recipes. As with the OpenEmbedded 309 build system, "recipes" represent software packages within 310 ``devtool``. When you use ``devtool add``, a recipe is automatically 311 created. When you use ``devtool modify``, the specified existing 312 recipe is used in order to determine where to get the source code and 313 how to patch it. In both cases, an environment is set up so that when 314 you build the recipe a source tree that is under your control is used 315 in order to allow you to make changes to the source as desired. By 316 default, both new recipes and the source go into a "workspace" 317 directory under the eSDK. The ``devtool upgrade`` command updates an 318 existing recipe so that you can build it for an updated set of source 319 files. 320 321 You can read about the ``devtool`` workflow in the Yocto Project 322 Application Development and Extensible Software Development Kit 323 (eSDK) Manual in the 324 ":ref:`sdk-manual/extensible:using \`\`devtool\`\` in your sdk workflow`" 325 section. 326 327- *Extensible Software Development Kit (eSDK):* The eSDK provides a 328 cross-development toolchain and libraries tailored to the contents of 329 a specific image. The eSDK makes it easy to add new applications and 330 libraries to an image, modify the source for an existing component, 331 test changes on the target hardware, and integrate into the rest of 332 the OpenEmbedded build system. The eSDK gives you a toolchain 333 experience supplemented with the powerful set of ``devtool`` commands 334 tailored for the Yocto Project environment. 335 336 For information on the eSDK, see the :doc:`/sdk-manual/index` Manual. 337 338- *Toaster:* Toaster is a web interface to the Yocto Project 339 OpenEmbedded build system. Toaster allows you to configure, run, and 340 view information about builds. For information on Toaster, see the 341 :doc:`/toaster-manual/index`. 342 343- *VSCode IDE Extension:* The `Yocto Project BitBake 344 <https://marketplace.visualstudio.com/items?itemName=yocto-project.yocto-bitbake>`__ 345 extension for Visual Studio Code provides a rich set of features for working 346 with BitBake recipes. The extension provides syntax highlighting, 347 hover tips, and completion for BitBake files as well as embedded Python and 348 Bash languages. Additional views and commands allow you to efficiently 349 browse, build and edit recipes. It also provides SDK integration for 350 cross-compiling and debugging through ``devtool``. 351 352 Learn more about the VSCode Extension on the `extension's frontpage 353 <https://marketplace.visualstudio.com/items?itemName=yocto-project.yocto-bitbake>`__. 354 355Production Tools 356---------------- 357 358Here are tools that help with production related activities using the 359Yocto Project: 360 361- *Auto Upgrade Helper:* This utility when used in conjunction with the 362 :term:`OpenEmbedded Build System` 363 (BitBake and 364 OE-Core) automatically generates upgrades for recipes that are based 365 on new versions of the recipes published upstream. See 366 :ref:`dev-manual/upgrading-recipes:using the auto upgrade helper (auh)` 367 for how to set it up. 368 369- *Recipe Reporting System:* The Recipe Reporting System tracks recipe 370 versions available for Yocto Project. The main purpose of the system 371 is to help you manage the recipes you maintain and to offer a dynamic 372 overview of the project. The Recipe Reporting System is built on top 373 of the :oe_layerindex:`OpenEmbedded Layer Index <>`, which 374 is a website that indexes OpenEmbedded-Core layers. 375 376- *Patchwork:* `Patchwork <https://patchwork.yoctoproject.org/>`__ 377 is a fork of a project originally started by 378 `OzLabs <https://ozlabs.org/>`__. The project is a web-based tracking 379 system designed to streamline the process of bringing contributions 380 into a project. The Yocto Project uses Patchwork as an organizational 381 tool to handle patches, which number in the thousands for every 382 release. 383 384- *AutoBuilder:* AutoBuilder is a project that automates build tests 385 and quality assurance (QA). By using the public AutoBuilder, anyone 386 can determine the status of the current development branch of Poky. 387 388 .. note:: 389 390 AutoBuilder is based on buildbot. 391 392 A goal of the Yocto Project is to lead the open source industry with 393 a project that automates testing and QA procedures. In doing so, the 394 project encourages a development community that publishes QA and test 395 plans, publicly demonstrates QA and test plans, and encourages 396 development of tools that automate and test and QA procedures for the 397 benefit of the development community. 398 399 You can learn more about the AutoBuilder used by the Yocto Project 400 Autobuilder :doc:`here </test-manual/understand-autobuilder>`. 401 402- *Pseudo:* Pseudo is the Yocto Project implementation of 403 `fakeroot <http://man.he.net/man1/fakeroot>`__, which is used to run 404 commands in an environment that seemingly has root privileges. 405 406 During a build, it can be necessary to perform operations that 407 require system administrator privileges. For example, file ownership 408 or permissions might need to be defined. Pseudo is a tool that you 409 can either use directly or through the environment variable 410 ``LD_PRELOAD``. Either method allows these operations to succeed 411 even without system administrator privileges. 412 413 Thanks to Pseudo, the Yocto Project never needs root privileges to 414 build images for your target system. 415 416 You can read more about Pseudo in the 417 ":ref:`overview-manual/concepts:fakeroot and pseudo`" section. 418 419Open-Embedded Build System Components 420------------------------------------- 421 422Here are components associated with the :term:`OpenEmbedded Build System`: 423 424- *BitBake:* BitBake is a core component of the Yocto Project and is 425 used by the OpenEmbedded build system to build images. While BitBake 426 is key to the build system, BitBake is maintained separately from the 427 Yocto Project. 428 429 BitBake is a generic task execution engine that allows shell and 430 Python tasks to be run efficiently and in parallel while working 431 within complex inter-task dependency constraints. In short, BitBake 432 is a build engine that works through recipes written in a specific 433 format in order to perform sets of tasks. 434 435 You can learn more about BitBake in the :doc:`BitBake User 436 Manual <bitbake:index>`. 437 438- *OpenEmbedded-Core:* OpenEmbedded-Core (OE-Core) is a common layer of 439 metadata (i.e. recipes, classes, and associated files) used by 440 OpenEmbedded-derived systems, which includes the Yocto Project. The 441 Yocto Project and the OpenEmbedded Project both maintain the 442 OpenEmbedded-Core. You can find the OE-Core metadata in the Yocto 443 Project :yocto_git:`Source Repositories </poky/tree/meta>`. 444 445 Historically, the Yocto Project integrated the OE-Core metadata 446 throughout the Yocto Project source repository reference system 447 (Poky). After Yocto Project Version 1.0, the Yocto Project and 448 OpenEmbedded agreed to work together and share a common core set of 449 metadata (OE-Core), which contained much of the functionality 450 previously found in Poky. This collaboration achieved a long-standing 451 OpenEmbedded objective for having a more tightly controlled and 452 quality-assured core. The results also fit well with the Yocto 453 Project objective of achieving a smaller number of fully featured 454 tools as compared to many different ones. 455 456 Sharing a core set of metadata results in Poky as an integration 457 layer on top of OE-Core. You can see that in this 458 :ref:`figure <overview-manual/yp-intro:what is the yocto project?>`. 459 The Yocto Project combines various components such as BitBake, OE-Core, 460 script "glue", and documentation for its build system. 461 462Reference Distribution (Poky) 463----------------------------- 464 465Poky is the Yocto Project reference distribution. It contains the 466:term:`OpenEmbedded Build System` 467(BitBake and OE-Core) as well as a set of metadata to get you started 468building your own distribution. See the figure in 469":ref:`overview-manual/yp-intro:what is the yocto project?`" 470section for an illustration that shows Poky and its relationship with 471other parts of the Yocto Project. 472 473To use the Yocto Project tools and components, you can download 474(``clone``) Poky and use it to bootstrap your own distribution. 475 476.. note:: 477 478 Poky does not contain binary files. It is a working example of how to 479 build your own custom Linux distribution from source. 480 481You can read more about Poky in the 482":ref:`overview-manual/yp-intro:reference embedded distribution (poky)`" 483section. 484 485Packages for Finished Targets 486----------------------------- 487 488Here are components associated with packages for finished targets: 489 490- *Matchbox:* Matchbox is an Open Source, base environment for the X 491 Window System running on non-desktop, embedded platforms such as 492 handhelds, set-top boxes, kiosks, and anything else for which screen 493 space, input mechanisms, or system resources are limited. 494 495 Matchbox consists of a number of interchangeable and optional 496 applications that you can tailor to a specific, non-desktop platform 497 to enhance usability in constrained environments. 498 499 You can find the Matchbox source in the Yocto Project 500 :yocto_git:`Source Repositories <>`. 501 502- *Opkg:* Open PacKaGe management (opkg) is a lightweight package 503 management system based on the itsy package (ipkg) management system. 504 Opkg is written in C and resembles Advanced Package Tool (APT) and 505 Debian Package (dpkg) in operation. 506 507 Opkg is intended for use on embedded Linux devices and is used in 508 this capacity in the :oe_home:`OpenEmbedded <>` and 509 `OpenWrt <https://openwrt.org/>`__ projects, as well as the Yocto 510 Project. 511 512 .. note:: 513 514 As best it can, opkg maintains backwards compatibility with ipkg 515 and conforms to a subset of Debian's policy manual regarding 516 control files. 517 518 You can find the opkg source in the Yocto Project 519 :yocto_git:`Source Repositories <>`. 520 521Archived Components 522------------------- 523 524The Build Appliance is a virtual machine image that enables you to build 525and boot a custom embedded Linux image with the Yocto Project using a 526non-Linux development system. 527 528Historically, the Build Appliance was the second of three methods by 529which you could use the Yocto Project on a system that was not native to 530Linux. 531 532#. *Hob:* Hob, which is now deprecated and is no longer available since 533 the 2.1 release of the Yocto Project provided a rudimentary, 534 GUI-based interface to the Yocto Project. Toaster has fully replaced 535 Hob. 536 537#. *Build Appliance:* Post Hob, the Build Appliance became available. It 538 was never recommended that you use the Build Appliance as a 539 day-to-day production development environment with the Yocto Project. 540 Build Appliance was useful as a way to try out development in the 541 Yocto Project environment. 542 543#. *CROPS:* The final and best solution available now for developing 544 using the Yocto Project on a system not native to Linux is with 545 :ref:`CROPS <overview-manual/yp-intro:development tools>`. 546 547Development Methods 548=================== 549 550The Yocto Project development environment usually involves a 551:term:`Build Host` and target 552hardware. You use the Build Host to build images and develop 553applications, while you use the target hardware to execute deployed 554software. 555 556This section provides an introduction to the choices or development 557methods you have when setting up your Build Host. Depending on your 558particular workflow preference and the type of operating system your 559Build Host runs, you have several choices. 560 561.. note:: 562 563 For additional detail about the Yocto Project development 564 environment, see the ":doc:`/overview-manual/development-environment`" 565 chapter. 566 567- *Native Linux Host:* By far the best option for a Build Host. A 568 system running Linux as its native operating system allows you to 569 develop software by directly using the 570 :term:`BitBake` tool. You can 571 accomplish all aspects of development from a regular shell in a 572 supported Linux distribution. 573 574 For information on how to set up a Build Host on a system running 575 Linux as its native operating system, see the 576 ":ref:`dev-manual/start:setting up a native linux host`" 577 section in the Yocto Project Development Tasks Manual. 578 579- *CROss PlatformS (CROPS):* Typically, you use 580 `CROPS <https://github.com/crops/poky-container/>`__, which leverages 581 `Docker Containers <https://www.docker.com/>`__, to set up a Build 582 Host that is not running Linux (e.g. Microsoft Windows or macOS). 583 584 .. note:: 585 586 You can, however, use CROPS on a Linux-based system. 587 588 CROPS is an open source, cross-platform development framework that 589 provides an easily managed, extensible environment for building 590 binaries targeted for a variety of architectures on Windows, macOS, 591 or Linux hosts. Once the Build Host is set up using CROPS, you can 592 prepare a shell environment to mimic that of a shell being used on a 593 system natively running Linux. 594 595 For information on how to set up a Build Host with CROPS, see the 596 ":ref:`dev-manual/start:setting up to use cross platforms (crops)`" 597 section in the Yocto Project Development Tasks Manual. 598 599- *Windows Subsystem For Linux (WSL 2):* You may use Windows Subsystem 600 For Linux version 2 to set up a Build Host using Windows 10 or later, 601 or Windows Server 2019 or later. 602 603 The Windows Subsystem For Linux allows Windows to run a real Linux 604 kernel inside of a lightweight virtual machine (VM). 605 606 For information on how to set up a Build Host with WSL 2, see the 607 ":ref:`dev-manual/start:setting up to use windows subsystem for linux (wsl 2)`" 608 section in the Yocto Project Development Tasks Manual. 609 610- *Toaster:* Regardless of what your Build Host is running, you can use 611 Toaster to develop software using the Yocto Project. Toaster is a web 612 interface to the Yocto Project's :term:`OpenEmbedded Build System`. 613 The interface allows you to configure and run your builds. Information 614 about builds is collected and stored in a database. You can use Toaster 615 to configure and start builds on multiple remote build servers. 616 617 For information about and how to use Toaster, see the 618 :doc:`/toaster-manual/index`. 619 620- *Using the VSCode Extension:* You can use the `Yocto Project BitBake 621 <https://marketplace.visualstudio.com/items?itemName=yocto-project.yocto-bitbake>`__ 622 extension for Visual Studio Code to start your BitBake builds through a 623 graphical user interface. 624 625 Learn more about the VSCode Extension on the `extension's marketplace page 626 <https://marketplace.visualstudio.com/items?itemName=yocto-project.yocto-bitbake>`__ 627 628Reference Embedded Distribution (Poky) 629====================================== 630 631"Poky", which is pronounced *Pock*-ee, is the name of the Yocto 632Project's reference distribution or Reference OS Kit. Poky contains the 633:term:`OpenEmbedded Build System` (:term:`BitBake` and 634:term:`OpenEmbedded-Core (OE-Core)`) as well as a set of 635:term:`Metadata` to get you started building your own distro. In other 636words, Poky is a base specification of the functionality needed for a 637typical embedded system as well as the components from the Yocto Project 638that allow you to build a distribution into a usable binary image. 639 640Poky is a combined repository of BitBake, OpenEmbedded-Core (which is 641found in ``meta``), ``meta-poky``, ``meta-yocto-bsp``, and documentation 642provided all together and known to work well together. You can view 643these items that make up the Poky repository in the 644:yocto_git:`Source Repositories </poky/tree/>`. 645 646.. note:: 647 648 If you are interested in all the contents of the 649 poky 650 Git repository, see the ":ref:`ref-manual/structure:top-level core components`" 651 section in the Yocto Project Reference Manual. 652 653The following figure illustrates what generally comprises Poky: 654 655.. image:: figures/poky-reference-distribution.png 656 :width: 100% 657 658- BitBake is a task executor and scheduler that is the heart of the 659 OpenEmbedded build system. 660 661- ``meta-poky``, which is Poky-specific metadata. 662 663- ``meta-yocto-bsp``, which are Yocto Project-specific Board Support 664 Packages (BSPs). 665 666- OpenEmbedded-Core (OE-Core) metadata, which includes shared 667 configurations, global variable definitions, shared classes, 668 packaging, and recipes. Classes define the encapsulation and 669 inheritance of build logic. Recipes are the logical units of software 670 and images to be built. 671 672- Documentation, which contains the Yocto Project source files used to 673 make the set of user manuals. 674 675.. note:: 676 677 While Poky is a "complete" distribution specification and is tested 678 and put through QA, you cannot use it as a product "out of the box" 679 in its current form. 680 681To use the Yocto Project tools, you can use Git to clone (download) the 682Poky repository then use your local copy of the reference distribution 683to bootstrap your own distribution. 684 685.. note:: 686 687 Poky does not contain binary files. It is a working example of how to 688 build your own custom Linux distribution from source. 689 690Poky has a regular, well established, six-month release cycle under its 691own version. Major releases occur at the same time major releases (point 692releases) occur for the Yocto Project, which are typically in the Spring 693and Fall. For more information on the Yocto Project release schedule and 694cadence, see the ":doc:`/ref-manual/release-process`" chapter in the 695Yocto Project Reference Manual. 696 697Much has been said about Poky being a "default configuration". A default 698configuration provides a starting image footprint. You can use Poky out 699of the box to create an image ranging from a shell-accessible minimal 700image all the way up to a Linux Standard Base-compliant image that uses 701a GNOME Mobile and Embedded (GMAE) based reference user interface called 702Sato. 703 704One of the most powerful properties of Poky is that every aspect of a 705build is controlled by the metadata. You can use metadata to augment 706these base image types by adding metadata :ref:`layers 707<overview-manual/yp-intro:the yocto project layer model>` that extend 708functionality. 709These layers can provide, for example, an additional software stack for 710an image type, add a board support package (BSP) for additional 711hardware, or even create a new image type. 712 713Metadata is loosely grouped into configuration files or package recipes. 714A recipe is a collection of non-executable metadata used by BitBake to 715set variables or define additional build-time tasks. A recipe contains 716fields such as the recipe description, the recipe version, the license 717of the package and the upstream source repository. A recipe might also 718indicate that the build process uses autotools, make, distutils or any 719other build process, in which case the basic functionality can be 720defined by the classes it inherits from the OE-Core layer's class 721definitions in ``./meta/classes``. Within a recipe you can also define 722additional tasks as well as task prerequisites. Recipe syntax through 723BitBake also supports both ``:prepend`` and ``:append`` operators as a 724method of extending task functionality. These operators inject code into 725the beginning or end of a task. For information on these BitBake 726operators, see the 727":ref:`bitbake-user-manual/bitbake-user-manual-metadata:appending and prepending (override style syntax)`" 728section in the BitBake User's Manual. 729 730The OpenEmbedded Build System Workflow 731====================================== 732 733The :term:`OpenEmbedded Build System` uses a "workflow" to 734accomplish image and SDK generation. The following figure overviews that 735workflow: 736 737.. image:: figures/YP-flow-diagram.png 738 :width: 100% 739 740Here is a brief summary of the "workflow": 741 742#. Developers specify architecture, policies, patches and configuration 743 details. 744 745#. The build system fetches and downloads the source code from the 746 specified location. The build system supports standard methods such 747 as tarballs or source code repositories systems such as Git. 748 749#. Once source code is downloaded, the build system extracts the sources 750 into a local work area where patches are applied and common steps for 751 configuring and compiling the software are run. 752 753#. The build system then installs the software into a temporary staging 754 area where the binary package format you select (DEB, RPM, or IPK) is 755 used to roll up the software. 756 757#. Different QA and sanity checks run throughout entire build process. 758 759#. After the binaries are created, the build system generates a binary 760 package feed that is used to create the final root file image. 761 762#. The build system generates the file system image and a customized 763 Extensible SDK (eSDK) for application development in parallel. 764 765For a very detailed look at this workflow, see the 766":ref:`overview-manual/concepts:openembedded build system concepts`" section. 767 768Some Basic Terms 769================ 770 771It helps to understand some basic fundamental terms when learning the 772Yocto Project. Although there is a list of terms in the ":doc:`Yocto Project 773Terms </ref-manual/terms>`" section of the Yocto Project 774Reference Manual, this section provides the definitions of some terms 775helpful for getting started: 776 777- *Configuration Files:* Files that hold global definitions of 778 variables, user-defined variables, and hardware configuration 779 information. These files tell the :term:`OpenEmbedded Build System` 780 what to build and 781 what to put into the image to support a particular platform. 782 783- *Extensible Software Development Kit (eSDK):* A custom SDK for 784 application developers. This eSDK allows developers to incorporate 785 their library and programming changes back into the image to make 786 their code available to other application developers. For information 787 on the eSDK, see the :doc:`/sdk-manual/index` manual. 788 789- *Layer:* A collection of related recipes. Layers allow you to 790 consolidate related metadata to customize your build. Layers also 791 isolate information used when building for multiple architectures. 792 Layers are hierarchical in their ability to override previous 793 specifications. You can include any number of available layers from 794 the Yocto Project and customize the build by adding your own layers 795 after them. You can search the Layer Index for layers used within 796 Yocto Project. 797 798 For more detailed information on layers, see the 799 ":ref:`dev-manual/layers:understanding and creating layers`" 800 section in the Yocto Project Development Tasks Manual. For a 801 discussion specifically on BSP Layers, see the 802 ":ref:`bsp-guide/bsp:bsp layers`" section in the Yocto 803 Project Board Support Packages (BSP) Developer's Guide. 804 805- *Metadata:* A key element of the Yocto Project is the Metadata that 806 is used to construct a Linux distribution and is contained in the 807 files that the OpenEmbedded build system parses when building an 808 image. In general, Metadata includes recipes, configuration files, 809 and other information that refers to the build instructions 810 themselves, as well as the data used to control what things get built 811 and the effects of the build. Metadata also includes commands and 812 data used to indicate what versions of software are used, from where 813 they are obtained, and changes or additions to the software itself 814 (patches or auxiliary files) that are used to fix bugs or customize 815 the software for use in a particular situation. OpenEmbedded-Core is 816 an important set of validated metadata. 817 818- *OpenEmbedded Build System:* The terms "BitBake" and "build system" 819 are sometimes used for the OpenEmbedded Build System. 820 821 BitBake is a task scheduler and execution engine that parses 822 instructions (i.e. recipes) and configuration data. After a parsing 823 phase, BitBake creates a dependency tree to order the compilation, 824 schedules the compilation of the included code, and finally executes 825 the building of the specified custom Linux image (distribution). 826 BitBake is similar to the ``make`` tool. 827 828 During a build process, the build system tracks dependencies and 829 performs a native or cross-compilation of each package. As a first 830 step in a cross-build setup, the framework attempts to create a 831 cross-compiler toolchain (i.e. Extensible SDK) suited for the target 832 platform. 833 834- *OpenEmbedded-Core (OE-Core):* OE-Core is metadata comprised of 835 foundation recipes, classes, and associated files that are meant to 836 be common among many different OpenEmbedded-derived systems, 837 including the Yocto Project. OE-Core is a curated subset of an 838 original repository developed by the OpenEmbedded community that has 839 been pared down into a smaller, core set of continuously validated 840 recipes. The result is a tightly controlled and quality-assured core 841 set of recipes. 842 843 You can see the Metadata in the ``meta`` directory of the Yocto 844 Project :yocto_git:`Source Repositories <>`. 845 846- *Packages:* In the context of the Yocto Project, this term refers to 847 a recipe's packaged output produced by BitBake (i.e. a "baked 848 recipe"). A package is generally the compiled binaries produced from 849 the recipe's sources. You "bake" something by running it through 850 BitBake. 851 852 It is worth noting that the term "package" can, in general, have 853 subtle meanings. For example, the packages referred to in the 854 ":ref:`ref-manual/system-requirements:required packages for the build host`" 855 section in the Yocto Project Reference Manual are compiled binaries 856 that, when installed, add functionality to your host Linux 857 distribution. 858 859 Another point worth noting is that historically within the Yocto 860 Project, recipes were referred to as packages --- thus, the existence 861 of several BitBake variables that are seemingly mis-named, (e.g. 862 :term:`PR`, 863 :term:`PV`, and 864 :term:`PE`). 865 866- *Poky:* Poky is a reference embedded distribution and a reference 867 test configuration. Poky provides the following: 868 869 - A base-level functional distro used to illustrate how to customize 870 a distribution. 871 872 - A means by which to test the Yocto Project components (i.e. Poky 873 is used to validate the Yocto Project). 874 875 - A vehicle through which you can download the Yocto Project. 876 877 Poky is not a product level distro. Rather, it is a good starting 878 point for customization. 879 880 .. note:: 881 882 Poky is an integration layer on top of OE-Core. 883 884- *Recipe:* The most common form of metadata. A recipe contains a list 885 of settings and tasks (i.e. instructions) for building packages that 886 are then used to build the binary image. A recipe describes where you 887 get source code and which patches to apply. Recipes describe 888 dependencies for libraries or for other recipes as well as 889 configuration and compilation options. Related recipes are 890 consolidated into a layer. 891
