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 343Production Tools 344---------------- 345 346Here are tools that help with production related activities using the 347Yocto Project: 348 349- *Auto Upgrade Helper:* This utility when used in conjunction with the 350 :term:`OpenEmbedded Build System` 351 (BitBake and 352 OE-Core) automatically generates upgrades for recipes that are based 353 on new versions of the recipes published upstream. See 354 :ref:`dev-manual/upgrading-recipes:using the auto upgrade helper (auh)` 355 for how to set it up. 356 357- *Recipe Reporting System:* The Recipe Reporting System tracks recipe 358 versions available for Yocto Project. The main purpose of the system 359 is to help you manage the recipes you maintain and to offer a dynamic 360 overview of the project. The Recipe Reporting System is built on top 361 of the :oe_layerindex:`OpenEmbedded Layer Index <>`, which 362 is a website that indexes OpenEmbedded-Core layers. 363 364- *Patchwork:* `Patchwork <http://jk.ozlabs.org/projects/patchwork/>`__ 365 is a fork of a project originally started by 366 `OzLabs <https://ozlabs.org/>`__. The project is a web-based tracking 367 system designed to streamline the process of bringing contributions 368 into a project. The Yocto Project uses Patchwork as an organizational 369 tool to handle patches, which number in the thousands for every 370 release. 371 372- *AutoBuilder:* AutoBuilder is a project that automates build tests 373 and quality assurance (QA). By using the public AutoBuilder, anyone 374 can determine the status of the current development branch of Poky. 375 376 .. note:: 377 378 AutoBuilder is based on buildbot. 379 380 A goal of the Yocto Project is to lead the open source industry with 381 a project that automates testing and QA procedures. In doing so, the 382 project encourages a development community that publishes QA and test 383 plans, publicly demonstrates QA and test plans, and encourages 384 development of tools that automate and test and QA procedures for the 385 benefit of the development community. 386 387 You can learn more about the AutoBuilder used by the Yocto Project 388 Autobuilder :doc:`here </test-manual/understand-autobuilder>`. 389 390- *Pseudo:* Pseudo is the Yocto Project implementation of 391 `fakeroot <http://man.he.net/man1/fakeroot>`__, which is used to run 392 commands in an environment that seemingly has root privileges. 393 394 During a build, it can be necessary to perform operations that 395 require system administrator privileges. For example, file ownership 396 or permissions might need to be defined. Pseudo is a tool that you 397 can either use directly or through the environment variable 398 ``LD_PRELOAD``. Either method allows these operations to succeed 399 even without system administrator privileges. 400 401 Thanks to Pseudo, the Yocto Project never needs root privileges to 402 build images for your target system. 403 404 You can read more about Pseudo in the 405 ":ref:`overview-manual/concepts:fakeroot and pseudo`" section. 406 407Open-Embedded Build System Components 408------------------------------------- 409 410Here are components associated with the :term:`OpenEmbedded Build System`: 411 412- *BitBake:* BitBake is a core component of the Yocto Project and is 413 used by the OpenEmbedded build system to build images. While BitBake 414 is key to the build system, BitBake is maintained separately from the 415 Yocto Project. 416 417 BitBake is a generic task execution engine that allows shell and 418 Python tasks to be run efficiently and in parallel while working 419 within complex inter-task dependency constraints. In short, BitBake 420 is a build engine that works through recipes written in a specific 421 format in order to perform sets of tasks. 422 423 You can learn more about BitBake in the :doc:`BitBake User 424 Manual <bitbake:index>`. 425 426- *OpenEmbedded-Core:* OpenEmbedded-Core (OE-Core) is a common layer of 427 metadata (i.e. recipes, classes, and associated files) used by 428 OpenEmbedded-derived systems, which includes the Yocto Project. The 429 Yocto Project and the OpenEmbedded Project both maintain the 430 OpenEmbedded-Core. You can find the OE-Core metadata in the Yocto 431 Project :yocto_git:`Source Repositories </poky/tree/meta>`. 432 433 Historically, the Yocto Project integrated the OE-Core metadata 434 throughout the Yocto Project source repository reference system 435 (Poky). After Yocto Project Version 1.0, the Yocto Project and 436 OpenEmbedded agreed to work together and share a common core set of 437 metadata (OE-Core), which contained much of the functionality 438 previously found in Poky. This collaboration achieved a long-standing 439 OpenEmbedded objective for having a more tightly controlled and 440 quality-assured core. The results also fit well with the Yocto 441 Project objective of achieving a smaller number of fully featured 442 tools as compared to many different ones. 443 444 Sharing a core set of metadata results in Poky as an integration 445 layer on top of OE-Core. You can see that in this 446 :ref:`figure <overview-manual/yp-intro:what is the yocto project?>`. 447 The Yocto Project combines various components such as BitBake, OE-Core, 448 script "glue", and documentation for its build system. 449 450Reference Distribution (Poky) 451----------------------------- 452 453Poky is the Yocto Project reference distribution. It contains the 454:term:`OpenEmbedded Build System` 455(BitBake and OE-Core) as well as a set of metadata to get you started 456building your own distribution. See the figure in 457":ref:`overview-manual/yp-intro:what is the yocto project?`" 458section for an illustration that shows Poky and its relationship with 459other parts of the Yocto Project. 460 461To use the Yocto Project tools and components, you can download 462(``clone``) Poky and use it to bootstrap your own distribution. 463 464.. note:: 465 466 Poky does not contain binary files. It is a working example of how to 467 build your own custom Linux distribution from source. 468 469You can read more about Poky in the 470":ref:`overview-manual/yp-intro:reference embedded distribution (poky)`" 471section. 472 473Packages for Finished Targets 474----------------------------- 475 476Here are components associated with packages for finished targets: 477 478- *Matchbox:* Matchbox is an Open Source, base environment for the X 479 Window System running on non-desktop, embedded platforms such as 480 handhelds, set-top boxes, kiosks, and anything else for which screen 481 space, input mechanisms, or system resources are limited. 482 483 Matchbox consists of a number of interchangeable and optional 484 applications that you can tailor to a specific, non-desktop platform 485 to enhance usability in constrained environments. 486 487 You can find the Matchbox source in the Yocto Project 488 :yocto_git:`Source Repositories <>`. 489 490- *Opkg:* Open PacKaGe management (opkg) is a lightweight package 491 management system based on the itsy package (ipkg) management system. 492 Opkg is written in C and resembles Advanced Package Tool (APT) and 493 Debian Package (dpkg) in operation. 494 495 Opkg is intended for use on embedded Linux devices and is used in 496 this capacity in the :oe_home:`OpenEmbedded <>` and 497 `OpenWrt <https://openwrt.org/>`__ projects, as well as the Yocto 498 Project. 499 500 .. note:: 501 502 As best it can, opkg maintains backwards compatibility with ipkg 503 and conforms to a subset of Debian's policy manual regarding 504 control files. 505 506 You can find the opkg source in the Yocto Project 507 :yocto_git:`Source Repositories <>`. 508 509Archived Components 510------------------- 511 512The Build Appliance is a virtual machine image that enables you to build 513and boot a custom embedded Linux image with the Yocto Project using a 514non-Linux development system. 515 516Historically, the Build Appliance was the second of three methods by 517which you could use the Yocto Project on a system that was not native to 518Linux. 519 520#. *Hob:* Hob, which is now deprecated and is no longer available since 521 the 2.1 release of the Yocto Project provided a rudimentary, 522 GUI-based interface to the Yocto Project. Toaster has fully replaced 523 Hob. 524 525#. *Build Appliance:* Post Hob, the Build Appliance became available. It 526 was never recommended that you use the Build Appliance as a 527 day-to-day production development environment with the Yocto Project. 528 Build Appliance was useful as a way to try out development in the 529 Yocto Project environment. 530 531#. *CROPS:* The final and best solution available now for developing 532 using the Yocto Project on a system not native to Linux is with 533 :ref:`CROPS <overview-manual/yp-intro:development tools>`. 534 535Development Methods 536=================== 537 538The Yocto Project development environment usually involves a 539:term:`Build Host` and target 540hardware. You use the Build Host to build images and develop 541applications, while you use the target hardware to execute deployed 542software. 543 544This section provides an introduction to the choices or development 545methods you have when setting up your Build Host. Depending on your 546particular workflow preference and the type of operating system your 547Build Host runs, you have several choices. 548 549.. note:: 550 551 For additional detail about the Yocto Project development 552 environment, see the ":doc:`/overview-manual/development-environment`" 553 chapter. 554 555- *Native Linux Host:* By far the best option for a Build Host. A 556 system running Linux as its native operating system allows you to 557 develop software by directly using the 558 :term:`BitBake` tool. You can 559 accomplish all aspects of development from a regular shell in a 560 supported Linux distribution. 561 562 For information on how to set up a Build Host on a system running 563 Linux as its native operating system, see the 564 ":ref:`dev-manual/start:setting up a native linux host`" 565 section in the Yocto Project Development Tasks Manual. 566 567- *CROss PlatformS (CROPS):* Typically, you use 568 `CROPS <https://github.com/crops/poky-container/>`__, which leverages 569 `Docker Containers <https://www.docker.com/>`__, to set up a Build 570 Host that is not running Linux (e.g. Microsoft Windows or macOS). 571 572 .. note:: 573 574 You can, however, use CROPS on a Linux-based system. 575 576 CROPS is an open source, cross-platform development framework that 577 provides an easily managed, extensible environment for building 578 binaries targeted for a variety of architectures on Windows, macOS, 579 or Linux hosts. Once the Build Host is set up using CROPS, you can 580 prepare a shell environment to mimic that of a shell being used on a 581 system natively running Linux. 582 583 For information on how to set up a Build Host with CROPS, see the 584 ":ref:`dev-manual/start:setting up to use cross platforms (crops)`" 585 section in the Yocto Project Development Tasks Manual. 586 587- *Windows Subsystem For Linux (WSL 2):* You may use Windows Subsystem 588 For Linux version 2 to set up a Build Host using Windows 10 or later, 589 or Windows Server 2019 or later. 590 591 The Windows Subsystem For Linux allows Windows to run a real Linux 592 kernel inside of a lightweight virtual machine (VM). 593 594 For information on how to set up a Build Host with WSL 2, see the 595 ":ref:`dev-manual/start:setting up to use windows subsystem for linux (wsl 2)`" 596 section in the Yocto Project Development Tasks Manual. 597 598- *Toaster:* Regardless of what your Build Host is running, you can use 599 Toaster to develop software using the Yocto Project. Toaster is a web 600 interface to the Yocto Project's :term:`OpenEmbedded Build System`. 601 The interface allows you to configure and run your builds. Information 602 about builds is collected and stored in a database. You can use Toaster 603 to configure and start builds on multiple remote build servers. 604 605 For information about and how to use Toaster, see the 606 :doc:`/toaster-manual/index`. 607 608Reference Embedded Distribution (Poky) 609====================================== 610 611"Poky", which is pronounced *Pock*-ee, is the name of the Yocto 612Project's reference distribution or Reference OS Kit. Poky contains the 613:term:`OpenEmbedded Build System` (:term:`BitBake` and 614:term:`OpenEmbedded-Core (OE-Core)`) as well as a set of 615:term:`Metadata` to get you started building your own distro. In other 616words, Poky is a base specification of the functionality needed for a 617typical embedded system as well as the components from the Yocto Project 618that allow you to build a distribution into a usable binary image. 619 620Poky is a combined repository of BitBake, OpenEmbedded-Core (which is 621found in ``meta``), ``meta-poky``, ``meta-yocto-bsp``, and documentation 622provided all together and known to work well together. You can view 623these items that make up the Poky repository in the 624:yocto_git:`Source Repositories </poky/tree/>`. 625 626.. note:: 627 628 If you are interested in all the contents of the 629 poky 630 Git repository, see the ":ref:`ref-manual/structure:top-level core components`" 631 section in the Yocto Project Reference Manual. 632 633The following figure illustrates what generally comprises Poky: 634 635.. image:: figures/poky-reference-distribution.png 636 :width: 100% 637 638- BitBake is a task executor and scheduler that is the heart of the 639 OpenEmbedded build system. 640 641- ``meta-poky``, which is Poky-specific metadata. 642 643- ``meta-yocto-bsp``, which are Yocto Project-specific Board Support 644 Packages (BSPs). 645 646- OpenEmbedded-Core (OE-Core) metadata, which includes shared 647 configurations, global variable definitions, shared classes, 648 packaging, and recipes. Classes define the encapsulation and 649 inheritance of build logic. Recipes are the logical units of software 650 and images to be built. 651 652- Documentation, which contains the Yocto Project source files used to 653 make the set of user manuals. 654 655.. note:: 656 657 While Poky is a "complete" distribution specification and is tested 658 and put through QA, you cannot use it as a product "out of the box" 659 in its current form. 660 661To use the Yocto Project tools, you can use Git to clone (download) the 662Poky repository then use your local copy of the reference distribution 663to bootstrap your own distribution. 664 665.. note:: 666 667 Poky does not contain binary files. It is a working example of how to 668 build your own custom Linux distribution from source. 669 670Poky has a regular, well established, six-month release cycle under its 671own version. Major releases occur at the same time major releases (point 672releases) occur for the Yocto Project, which are typically in the Spring 673and Fall. For more information on the Yocto Project release schedule and 674cadence, see the ":doc:`/ref-manual/release-process`" chapter in the 675Yocto Project Reference Manual. 676 677Much has been said about Poky being a "default configuration". A default 678configuration provides a starting image footprint. You can use Poky out 679of the box to create an image ranging from a shell-accessible minimal 680image all the way up to a Linux Standard Base-compliant image that uses 681a GNOME Mobile and Embedded (GMAE) based reference user interface called 682Sato. 683 684One of the most powerful properties of Poky is that every aspect of a 685build is controlled by the metadata. You can use metadata to augment 686these base image types by adding metadata :ref:`layers 687<overview-manual/yp-intro:the yocto project layer model>` that extend 688functionality. 689These layers can provide, for example, an additional software stack for 690an image type, add a board support package (BSP) for additional 691hardware, or even create a new image type. 692 693Metadata is loosely grouped into configuration files or package recipes. 694A recipe is a collection of non-executable metadata used by BitBake to 695set variables or define additional build-time tasks. A recipe contains 696fields such as the recipe description, the recipe version, the license 697of the package and the upstream source repository. A recipe might also 698indicate that the build process uses autotools, make, distutils or any 699other build process, in which case the basic functionality can be 700defined by the classes it inherits from the OE-Core layer's class 701definitions in ``./meta/classes``. Within a recipe you can also define 702additional tasks as well as task prerequisites. Recipe syntax through 703BitBake also supports both ``:prepend`` and ``:append`` operators as a 704method of extending task functionality. These operators inject code into 705the beginning or end of a task. For information on these BitBake 706operators, see the 707":ref:`bitbake:bitbake-user-manual/bitbake-user-manual-metadata:appending and prepending (override style syntax)`" 708section in the BitBake User's Manual. 709 710The OpenEmbedded Build System Workflow 711====================================== 712 713The :term:`OpenEmbedded Build System` uses a "workflow" to 714accomplish image and SDK generation. The following figure overviews that 715workflow: 716 717.. image:: figures/YP-flow-diagram.png 718 :width: 100% 719 720Following is a brief summary of the "workflow": 721 722#. Developers specify architecture, policies, patches and configuration 723 details. 724 725#. The build system fetches and downloads the source code from the 726 specified location. The build system supports standard methods such 727 as tarballs or source code repositories systems such as Git. 728 729#. Once source code is downloaded, the build system extracts the sources 730 into a local work area where patches are applied and common steps for 731 configuring and compiling the software are run. 732 733#. The build system then installs the software into a temporary staging 734 area where the binary package format you select (DEB, RPM, or IPK) is 735 used to roll up the software. 736 737#. Different QA and sanity checks run throughout entire build process. 738 739#. After the binaries are created, the build system generates a binary 740 package feed that is used to create the final root file image. 741 742#. The build system generates the file system image and a customized 743 Extensible SDK (eSDK) for application development in parallel. 744 745For a very detailed look at this workflow, see the 746":ref:`overview-manual/concepts:openembedded build system concepts`" section. 747 748Some Basic Terms 749================ 750 751It helps to understand some basic fundamental terms when learning the 752Yocto Project. Although there is a list of terms in the ":doc:`Yocto Project 753Terms </ref-manual/terms>`" section of the Yocto Project 754Reference Manual, this section provides the definitions of some terms 755helpful for getting started: 756 757- *Configuration Files:* Files that hold global definitions of 758 variables, user-defined variables, and hardware configuration 759 information. These files tell the :term:`OpenEmbedded Build System` 760 what to build and 761 what to put into the image to support a particular platform. 762 763- *Extensible Software Development Kit (eSDK):* A custom SDK for 764 application developers. This eSDK allows developers to incorporate 765 their library and programming changes back into the image to make 766 their code available to other application developers. For information 767 on the eSDK, see the :doc:`/sdk-manual/index` manual. 768 769- *Layer:* A collection of related recipes. Layers allow you to 770 consolidate related metadata to customize your build. Layers also 771 isolate information used when building for multiple architectures. 772 Layers are hierarchical in their ability to override previous 773 specifications. You can include any number of available layers from 774 the Yocto Project and customize the build by adding your own layers 775 after them. You can search the Layer Index for layers used within 776 Yocto Project. 777 778 For more detailed information on layers, see the 779 ":ref:`dev-manual/layers:understanding and creating layers`" 780 section in the Yocto Project Development Tasks Manual. For a 781 discussion specifically on BSP Layers, see the 782 ":ref:`bsp-guide/bsp:bsp layers`" section in the Yocto 783 Project Board Support Packages (BSP) Developer's Guide. 784 785- *Metadata:* A key element of the Yocto Project is the Metadata that 786 is used to construct a Linux distribution and is contained in the 787 files that the OpenEmbedded build system parses when building an 788 image. In general, Metadata includes recipes, configuration files, 789 and other information that refers to the build instructions 790 themselves, as well as the data used to control what things get built 791 and the effects of the build. Metadata also includes commands and 792 data used to indicate what versions of software are used, from where 793 they are obtained, and changes or additions to the software itself 794 (patches or auxiliary files) that are used to fix bugs or customize 795 the software for use in a particular situation. OpenEmbedded-Core is 796 an important set of validated metadata. 797 798- *OpenEmbedded Build System:* The terms "BitBake" and "build system" 799 are sometimes used for the OpenEmbedded Build System. 800 801 BitBake is a task scheduler and execution engine that parses 802 instructions (i.e. recipes) and configuration data. After a parsing 803 phase, BitBake creates a dependency tree to order the compilation, 804 schedules the compilation of the included code, and finally executes 805 the building of the specified custom Linux image (distribution). 806 BitBake is similar to the ``make`` tool. 807 808 During a build process, the build system tracks dependencies and 809 performs a native or cross-compilation of each package. As a first 810 step in a cross-build setup, the framework attempts to create a 811 cross-compiler toolchain (i.e. Extensible SDK) suited for the target 812 platform. 813 814- *OpenEmbedded-Core (OE-Core):* OE-Core is metadata comprised of 815 foundation recipes, classes, and associated files that are meant to 816 be common among many different OpenEmbedded-derived systems, 817 including the Yocto Project. OE-Core is a curated subset of an 818 original repository developed by the OpenEmbedded community that has 819 been pared down into a smaller, core set of continuously validated 820 recipes. The result is a tightly controlled and quality-assured core 821 set of recipes. 822 823 You can see the Metadata in the ``meta`` directory of the Yocto 824 Project :yocto_git:`Source Repositories <>`. 825 826- *Packages:* In the context of the Yocto Project, this term refers to 827 a recipe's packaged output produced by BitBake (i.e. a "baked 828 recipe"). A package is generally the compiled binaries produced from 829 the recipe's sources. You "bake" something by running it through 830 BitBake. 831 832 It is worth noting that the term "package" can, in general, have 833 subtle meanings. For example, the packages referred to in the 834 ":ref:`ref-manual/system-requirements:required packages for the build host`" 835 section in the Yocto Project Reference Manual are compiled binaries 836 that, when installed, add functionality to your host Linux 837 distribution. 838 839 Another point worth noting is that historically within the Yocto 840 Project, recipes were referred to as packages --- thus, the existence 841 of several BitBake variables that are seemingly mis-named, (e.g. 842 :term:`PR`, 843 :term:`PV`, and 844 :term:`PE`). 845 846- *Poky:* Poky is a reference embedded distribution and a reference 847 test configuration. Poky provides the following: 848 849 - A base-level functional distro used to illustrate how to customize 850 a distribution. 851 852 - A means by which to test the Yocto Project components (i.e. Poky 853 is used to validate the Yocto Project). 854 855 - A vehicle through which you can download the Yocto Project. 856 857 Poky is not a product level distro. Rather, it is a good starting 858 point for customization. 859 860 .. note:: 861 862 Poky is an integration layer on top of OE-Core. 863 864- *Recipe:* The most common form of metadata. A recipe contains a list 865 of settings and tasks (i.e. instructions) for building packages that 866 are then used to build the binary image. A recipe describes where you 867 get source code and which patches to apply. Recipes describe 868 dependencies for libraries or for other recipes as well as 869 configuration and compilation options. Related recipes are 870 consolidated into a layer. 871
