blob: a2a1f494bb696f95c6c3f62f80386d18ec520f65 [file] [log] [blame]
Brad Bishop316dfdd2018-06-25 12:45:53 -04001<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
Andrew Geissler475cb722020-07-10 16:00:51 -05004<!--SPDX-License-Identifier: CC-BY-2.0-UK-->
Brad Bishop316dfdd2018-06-25 12:45:53 -04005
6<chapter id='overview-yp'>
7 <title>Introducing the Yocto Project</title>
8
9 <section id='what-is-the-yocto-project'>
10 <title>What is the Yocto Project?</title>
11
12 <para>
13 The Yocto Project is an open source collaboration project
14 that helps developers create custom Linux-based systems that are
15 designed for embedded products regardless of the product's hardware
16 architecture.
17 Yocto Project provides a flexible toolset and a development
18 environment that allows embedded device developers across the
19 world to collaborate through shared technologies, software stacks,
20 configurations, and best practices used to create these tailored
21 Linux images.
22 </para>
23
24 <para>
25 Thousands of developers worldwide have discovered that Yocto
26 Project provides advantages in both systems and applications
27 development, archival and management benefits, and customizations
28 used for speed, footprint, and memory utilization.
29 The project is a standard when it comes to delivering embedded
30 software stacks.
31 The project allows software customizations and build interchange
32 for multiple hardware platforms as well as software stacks that
33 can be maintained and scaled.
34 </para>
35
36 <para id='yp-key-dev-elements'>
37 <imagedata fileref="figures/key-dev-elements.png" format="PNG" align='center' width="8in"/>
38 </para>
39
40 <para>
41 For further introductory information on the Yocto Project, you
42 might be interested in this
43 <ulink url='https://www.embedded.com/electronics-blogs/say-what-/4458600/Why-the-Yocto-Project-for-my-IoT-Project-'>article</ulink>
44 by Drew Moseley and in this short introductory
45 <ulink url='https://www.youtube.com/watch?v=utZpKM7i5Z4'>video</ulink>.
46 </para>
47
48 <para>
49 The remainder of this section overviews advantages and challenges
50 tied to the Yocto Project.
51 </para>
52
53 <section id='gs-features'>
54 <title>Features</title>
55
56 <para>
57 The following list describes features and advantages of the
58 Yocto Project:
59 <itemizedlist>
60 <listitem><para>
61 <emphasis>Widely Adopted Across the Industry:</emphasis>
62 Semiconductor, operating system, software, and
63 service vendors exist whose products and services
64 adopt and support the Yocto Project.
65 For a look at the Yocto Project community and
66 the companies involved with the Yocto
67 Project, see the "COMMUNITY" and "ECOSYSTEM" tabs
68 on the
69 <ulink url='&YOCTO_HOME_URL;'>Yocto Project</ulink>
70 home page.
71 </para></listitem>
72 <listitem><para>
73 <emphasis>Architecture Agnostic:</emphasis>
74 Yocto Project supports Intel, ARM, MIPS, AMD, PPC
75 and other architectures.
76 Most ODMs, OSVs, and chip vendors create and supply
77 BSPs that support their hardware.
78 If you have custom silicon, you can create a BSP
79 that supports that architecture.</para>
80
81 <para>Aside from lots of architecture support, the
82 Yocto Project fully supports a wide range of device
83 emulation through the Quick EMUlator (QEMU).
84 </para></listitem>
85 <listitem><para>
86 <emphasis>Images and Code Transfer Easily:</emphasis>
87 Yocto Project output can easily move between
88 architectures without moving to new development
89 environments.
90 Additionally, if you have used the Yocto Project to
91 create an image or application and you find yourself
92 not able to support it, commercial Linux vendors such
93 as Wind River, Mentor Graphics, Timesys, and ENEA could
94 take it and provide ongoing support.
95 These vendors have offerings that are built using
96 the Yocto Project.
97 </para></listitem>
98 <listitem><para>
99 <emphasis>Flexibility:</emphasis>
100 Corporations use the Yocto Project many different ways.
101 One example is to create an internal Linux distribution
102 as a code base the corporation can use across multiple
103 product groups.
104 Through customization and layering, a project group
105 can leverage the base Linux distribution to create
106 a distribution that works for their product needs.
107 </para></listitem>
108 <listitem><para>
109 <emphasis>Ideal for Constrained Embedded and IoT devices:</emphasis>
110 Unlike a full Linux distribution, you can use the
111 Yocto Project to create exactly what you need for
112 embedded devices.
113 You only add the feature support or packages that you
114 absolutely need for the device.
115 For devices that have display hardware, you can use
116 available system components such as X11, GTK+, Qt,
117 Clutter, and SDL (among others) to create a rich user
118 experience.
119 For devices that do not have a display or where you
120 want to use alternative UI frameworks, you can choose
121 to not install these components.
122 </para></listitem>
123 <listitem><para>
124 <emphasis>Comprehensive Toolchain Capabilities:</emphasis>
125 Toolchains for supported architectures satisfy most
126 use cases.
127 However, if your hardware supports features that are
128 not part of a standard toolchain, you can easily
129 customize that toolchain through specification of
130 platform-specific tuning parameters.
131 And, should you need to use a third-party toolchain,
132 mechanisms built into the Yocto Project allow for that.
133 </para></listitem>
134 <listitem><para>
135 <emphasis>Mechanism Rules Over Policy:</emphasis>
136 Focusing on mechanism rather than policy ensures that
137 you are free to set policies based on the needs of your
138 design instead of adopting decisions enforced by some
139 system software provider.
140 </para></listitem>
141 <listitem><para>
142 <emphasis>Uses a Layer Model:</emphasis>
143 The Yocto Project
144 <link linkend='the-yocto-project-layer-model'>layer infrastructure</link>
145 groups related functionality into separate bundles.
146 You can incrementally add these grouped functionalities
147 to your project as needed.
148 Using layers to isolate and group functionality
149 reduces project complexity and redundancy, allows you
150 to easily extend the system, make customizations,
151 and keep functionality organized.
152 </para></listitem>
153 <listitem><para>
154 <emphasis>Supports Partial Builds:</emphasis>
155 You can build and rebuild individual packages as
156 needed.
157 Yocto Project accomplishes this through its
158 <link linkend='shared-state-cache'>shared-state cache</link>
159 (sstate) scheme.
160 Being able to build and debug components individually
161 eases project development.
162 </para></listitem>
163 <listitem><para>
164 <emphasis>Releases According to a Strict Schedule:</emphasis>
165 Major releases occur on a
166 <ulink url='&YOCTO_DOCS_REF_URL;#ref-release-process'>six-month cycle</ulink>
167 predictably in October and April.
168 The most recent two releases support point releases
169 to address common vulnerabilities and exposures.
170 This predictability is crucial for projects based on
171 the Yocto Project and allows development teams to
172 plan activities.
173 </para></listitem>
174 <listitem><para>
175 <emphasis>Rich Ecosystem of Individuals and Organizations:</emphasis>
176 For open source projects, the value of community is
177 very important.
178 Support forums, expertise, and active developers who
179 continue to push the Yocto Project forward are readily
180 available.
181 </para></listitem>
182 <listitem><para>
183 <emphasis>Binary Reproducibility:</emphasis>
184 The Yocto Project allows you to be very specific about
185 dependencies and achieves very high percentages of
186 binary reproducibility (e.g. 99.8% for
187 <filename>core-image-minimal</filename>).
188 When distributions are not specific about which
189 packages are pulled in and in what order to support
190 dependencies, other build systems can arbitrarily
191 include packages.
192 </para></listitem>
193 <listitem><para>
194 <emphasis>License Manifest:</emphasis>
195 The Yocto Project provides a
196 <ulink url='&YOCTO_DOCS_DEV_URL;#maintaining-open-source-license-compliance-during-your-products-lifecycle'>license manifest</ulink>
197 for review by people who need to track the use of open
198 source licenses (e.g.legal teams).
199 </para></listitem>
200 </itemizedlist>
201 </para>
202 </section>
203
204 <section id='gs-challenges'>
205 <title>Challenges</title>
206
207 <para>
208 The following list presents challenges you might encounter
209 when developing using the Yocto Project:
210 <itemizedlist>
211 <listitem><para>
212 <emphasis>Steep Learning Curve:</emphasis>
213 The Yocto Project has a steep learning curve and has
214 many different ways to accomplish similar tasks.
215 It can be difficult to choose how to proceed when
216 varying methods exist by which to accomplish a given
217 task.
218 </para></listitem>
219 <listitem><para>
220 <emphasis>Understanding What Changes You Need to Make
221 For Your Design Requires Some Research:</emphasis>
222 Beyond the simple tutorial stage, understanding what
223 changes need to be made for your particular design
224 can require a significant amount of research and
225 investigation.
226 For information that helps you transition from
227 trying out the Yocto Project to using it for your
228 project, see the
Andrew Geissler82c905d2020-04-13 13:39:40 -0500229 "<ulink url='&YOCTO_DOCS_URL;/what-i-wish-id-known/'>What I wish I'd Known</ulink>"
Brad Bishop316dfdd2018-06-25 12:45:53 -0400230 and
Andrew Geissler82c905d2020-04-13 13:39:40 -0500231 "<ulink url='&YOCTO_DOCS_URL;/transitioning-to-a-custom-environment/'>Transitioning to a Custom Environment for Systems Development</ulink>"
Brad Bishop316dfdd2018-06-25 12:45:53 -0400232 documents on the Yocto Project website.
233 </para></listitem>
234 <listitem><para>
235 <emphasis>Project Workflow Could Be Confusing:</emphasis>
236 The
237 <link linkend='overview-development-environment'>Yocto Project workflow</link>
238 could be confusing if you are used to traditional
239 desktop and server software development.
240 In a desktop development environment, mechanisms exist
241 to easily pull and install new packages, which are
242 typically pre-compiled binaries from servers accessible
243 over the Internet.
244 Using the Yocto Project, you must modify your
245 configuration and rebuild to add additional packages.
246 </para></listitem>
247 <listitem><para>
248 <emphasis>Working in a Cross-Build Environment Can
249 Feel Unfamiliar:</emphasis>
250 When developing code to run on a target, compilation,
251 execution, and testing done on the actual target
252 can be faster than running a BitBake build on a
253 development host and then deploying binaries to the
254 target for test.
255 While the Yocto Project does support development tools
256 on the target, the additional step of integrating your
257 changes back into the Yocto Project build environment
258 would be required.
259 Yocto Project supports an intermediate approach that
260 involves making changes on the development system
261 within the BitBake environment and then deploying only
262 the updated packages to the target.</para>
263
264 <para>The Yocto Project
265 <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>OpenEmbedded build system</ulink>
266 produces packages in standard formats (i.e. RPM,
267 DEB, IPK, and TAR).
268 You can deploy these packages into the running system
269 on the target by using utilities on the target such
270 as <filename>rpm</filename> or
271 <filename>ipk</filename>.
272 </para></listitem>
273 <listitem><para>
274 <emphasis>Initial Build Times Can be Significant:</emphasis>
275 Long initial build times are unfortunately unavoidable
276 due to the large number of packages initially built
277 from scratch for a fully functioning Linux system.
278 Once that initial build is completed, however, the
279 shared-state (sstate) cache mechanism Yocto Project
280 uses keeps the system from rebuilding packages that
281 have not been "touched" since the last build.
282 The sstate mechanism significantly reduces times
283 for successive builds.
284 </para></listitem>
285 </itemizedlist>
286 </para>
287 </section>
288 </section>
289
290 <section id='the-yocto-project-layer-model'>
291 <title>The Yocto Project Layer Model</title>
292
293 <para>
294 The Yocto Project's "Layer Model" is a development model for
295 embedded and IoT Linux creation that distinguishes the
296 Yocto Project from other simple build systems.
297 The Layer Model simultaneously supports collaboration and
298 customization.
299 Layers are repositories that contain related sets of instructions
300 that tell the
301 <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>OpenEmbedded build system</ulink>
302 what to do.
303 You can collaborate, share, and reuse layers.
304 </para>
305
306 <para>
307 Layers can contain changes to previous instructions or settings
308 at any time.
309 This powerful override capability is what allows you to customize
310 previously supplied collaborative or community layers to suit your
311 product requirements.
312 </para>
313
314 <para>
315 You use different layers to logically separate information in your
316 build.
317 As an example, you could have BSP, GUI, distro configuration,
318 middleware, or application layers.
319 Putting your entire build into one layer limits and complicates
320 future customization and reuse.
321 Isolating information into layers, on the other hand, helps
322 simplify future customizations and reuse.
323 You might find it tempting to keep everything in one layer when
324 working on a single project.
325 However, the more modular your Metadata, the easier
326 it is to cope with future changes.
327 <note><title>Notes</title>
328 <itemizedlist>
329 <listitem><para>
330 Use Board Support Package (BSP) layers from silicon
331 vendors when possible.
332 </para></listitem>
333 <listitem><para>
334 Familiarize yourself with the
335 <ulink url='https://caffelli-staging.yoctoproject.org/software-overview/layers/'>Yocto Project curated layer index</ulink>
336 or the
337 <ulink url='http://layers.openembedded.org/layerindex/branch/master/layers/'>OpenEmbedded layer index</ulink>.
338 The latter contains more layers but they are less
339 universally validated.
340 </para></listitem>
341 <listitem><para>
342 Layers support the inclusion of technologies, hardware
343 components, and software components.
344 The
345 <ulink url='&YOCTO_DOCS_DEV_URL;#making-sure-your-layer-is-compatible-with-yocto-project'>Yocto Project Compatible</ulink>
346 designation provides a minimum level of standardization
347 that contributes to a strong ecosystem.
348 "YP Compatible" is applied to appropriate products and
349 software components such as BSPs, other OE-compatible
350 layers, and related open-source projects, allowing the
351 producer to use Yocto Project badges and branding
352 assets.
353 </para></listitem>
354 </itemizedlist>
355 </note>
356 </para>
357
358 <para>
359 To illustrate how layers are used to keep things modular, consider
360 machine customizations.
361 These types of customizations typically reside in a special layer,
362 rather than a general layer, called a BSP Layer.
363 Furthermore, the machine customizations should be isolated from
364 recipes and Metadata that support a new GUI environment,
365 for example.
366 This situation gives you a couple of layers: one for the machine
367 configurations, and one for the GUI environment.
368 It is important to understand, however, that the BSP layer can
369 still make machine-specific additions to recipes within the GUI
370 environment layer without polluting the GUI layer itself
371 with those machine-specific changes.
372 You can accomplish this through a recipe that is a BitBake append
373 (<filename>.bbappend</filename>) file, which is described later
374 in this section.
375 <note>
376 For general information on BSP layer structure, see the
377 <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Packages (BSP) Developer's Guide</ulink>.
378 </note>
379 </para>
380
381 <para>
382 The
383 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
384 contains both general layers and BSP layers right out of the box.
385 You can easily identify layers that ship with a Yocto Project
386 release in the Source Directory by their names.
387 Layers typically have names that begin with the string
388 <filename>meta-</filename>.
389 <note>
390 It is not a requirement that a layer name begin with the
391 prefix <filename>meta-</filename>, but it is a commonly
392 accepted standard in the Yocto Project community.
393 </note>
394 For example, if you were to examine the
395 <ulink url='https://git.yoctoproject.org/cgit/cgit.cgi/poky/tree/'>tree view</ulink>
396 of the <filename>poky</filename> repository, you will see several
397 layers: <filename>meta</filename>,
398 <filename>meta-skeleton</filename>,
399 <filename>meta-selftest</filename>,
400 <filename>meta-poky</filename>, and
401 <filename>meta-yocto-bsp</filename>.
402 Each of these repositories represents a distinct layer.
403 </para>
404
405 <para>
406 For procedures on how to create layers, see the
407 "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>"
408 section in the Yocto Project Development Tasks Manual.
409 </para>
410 </section>
411
412 <section id='components-and-tools'>
413 <title>Components and Tools</title>
414
415 <para>
416 The Yocto Project employs a collection of components and
417 tools used by the project itself, by project developers,
418 and by those using the Yocto Project.
419 These components and tools are open source projects and
420 metadata that are separate from the reference distribution
421 (<ulink url='&YOCTO_DOCS_REF_URL;#poky'>Poky</ulink>)
422 and the
423 <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>OpenEmbedded build system</ulink>.
424 Most of the components and tools are downloaded separately.
425 </para>
426
427 <para>
428 This section provides brief overviews of the components and
429 tools associated with the Yocto Project.
430 </para>
431
432 <section id='gs-development-tools'>
433 <title>Development Tools</title>
434
435 <para>
436 The following list consists of tools that help you develop
437 images and applications using the Yocto Project:
438 <itemizedlist>
439 <listitem><para id='gs-crops-overview'>
440 <emphasis>CROPS:</emphasis>
Andrew Geissler82c905d2020-04-13 13:39:40 -0500441 <ulink url='https://github.com/crops/poky-container/'>CROPS</ulink>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400442 is an open source, cross-platform development framework
443 that leverages
444 <ulink url='https://www.docker.com/'>Docker Containers</ulink>.
445 CROPS provides an easily managed, extensible environment
446 that allows you to build binaries for a variety of
447 architectures on Windows, Linux and Mac OS X hosts.
448 </para></listitem>
449 <listitem><para>
450 <emphasis><filename>devtool</filename>:</emphasis>
451 This command-line tool is available as part of the
452 extensible SDK (eSDK) and is its cornerstone.
453 You can use <filename>devtool</filename> to help build,
454 test, and package software within the eSDK.
455 You can use the tool to optionally integrate what you
456 build into an image built by the OpenEmbedded build
457 system.</para>
458
459 <para>The <filename>devtool</filename> command employs
460 a number of sub-commands that allow you to add, modify,
461 and upgrade recipes.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500462 As with the OpenEmbedded build system, "recipes"
Brad Bishop316dfdd2018-06-25 12:45:53 -0400463 represent software packages within
464 <filename>devtool</filename>.
465 When you use <filename>devtool add</filename>, a recipe
466 is automatically created.
467 When you use <filename>devtool modify</filename>, the
468 specified existing recipe is used in order to determine
469 where to get the source code and how to patch it.
470 In both cases, an environment is set up so that when
471 you build the recipe a source tree that is under your
472 control is used in order to allow you to make changes
473 to the source as desired.
474 By default, both new recipes and the source go into
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500475 a "workspace" directory under the eSDK.
Brad Bishop316dfdd2018-06-25 12:45:53 -0400476 The <filename>devtool upgrade</filename> command
477 updates an existing recipe so that you can build it
478 for an updated set of source files.</para>
479
480 <para>You can read about the
481 <filename>devtool</filename> workflow in the Yocto
482 Project Application Development and Extensible
483 Software Development Kit (eSDK) Manual in the
484 "<ulink url='&YOCTO_DOCS_SDK_URL;#using-devtool-in-your-sdk-workflow'>Using <filename>devtool</filename> in Your SDK Workflow'</ulink>"
485 section.
486 </para></listitem>
487 <listitem><para>
488 <emphasis>Extensible Software Development Kit (eSDK):</emphasis>
489 The eSDK provides a cross-development toolchain and
490 libraries tailored to the contents of a specific image.
491 The eSDK makes it easy to add new applications and
492 libraries to an image, modify the source for an
493 existing component, test changes on the target
494 hardware, and integrate into the rest of the
495 OpenEmbedded build system.
496 The eSDK gives you a toolchain experience supplemented
497 with the powerful set of <filename>devtool</filename>
498 commands tailored for the Yocto Project environment.
499 </para>
500
501 <para>For information on the eSDK, see the
502 <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink>
503 Manual.
504 </para></listitem>
505 <listitem><para>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400506 <emphasis>Toaster:</emphasis>
507 Toaster is a web interface to the Yocto Project
508 OpenEmbedded build system.
509 Toaster allows you to configure, run, and view
510 information about builds.
511 For information on Toaster, see the
512 <ulink url='&YOCTO_DOCS_TOAST_URL;'>Toaster User Manual</ulink>.
513 </para></listitem>
514 </itemizedlist>
515 </para>
516 </section>
517
518 <section id='gs-production-tools'>
519 <title>Production Tools</title>
520
521 <para>
522 The following list consists of tools that help production
523 related activities using the Yocto Project:
524 <itemizedlist>
525 <listitem><para>
526 <emphasis>Auto Upgrade Helper:</emphasis>
527 This utility when used in conjunction with the
528 <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>OpenEmbedded build system</ulink>
529 (BitBake and OE-Core) automatically generates upgrades
530 for recipes that are based on new versions of the
531 recipes published upstream.
532 </para></listitem>
533 <listitem><para>
534 <emphasis>Recipe Reporting System:</emphasis>
535 The Recipe Reporting System tracks recipe versions
536 available for Yocto Project.
537 The main purpose of the system is to help you
538 manage the recipes you maintain and to offer a dynamic
539 overview of the project.
540 The Recipe Reporting System is built on top of the
541 <ulink url="http://layers.openembedded.org/layerindex/layers/">OpenEmbedded Layer Index</ulink>,
542 which is a website that indexes OpenEmbedded-Core
543 layers.
544 </para></listitem>
545 <listitem><para>
546 <emphasis>Patchwork:</emphasis>
547 <ulink url='http://jk.ozlabs.org/projects/patchwork/'>Patchwork</ulink>
548 is a fork of a project originally started by
549 <ulink url='http://ozlabs.org/'>OzLabs</ulink>.
550 The project is a web-based tracking system designed
551 to streamline the process of bringing contributions
552 into a project.
553 The Yocto Project uses Patchwork as an organizational
554 tool to handle patches, which number in the thousands
555 for every release.
556 </para></listitem>
557 <listitem><para>
558 <emphasis>AutoBuilder:</emphasis>
559 AutoBuilder is a project that automates build tests
560 and quality assurance (QA).
561 By using the public AutoBuilder, anyone can determine
562 the status of the current "master" branch of Poky.
563 <note>
564 AutoBuilder is based on
565 <ulink url='https://buildbot.net/'>buildbot</ulink>.
566 </note></para>
567
568 <para>A goal of the Yocto Project is to lead the
569 open source industry with a project that automates
570 testing and QA procedures.
571 In doing so, the project encourages a development
572 community that publishes QA and test plans, publicly
573 demonstrates QA and test plans, and encourages
574 development of tools that automate and test and QA
575 procedures for the benefit of the development
576 community.</para>
577
578 <para>You can learn more about the AutoBuilder used
579 by the Yocto Project
580 <ulink url='&YOCTO_AB_URL;'>here</ulink>.
581 </para></listitem>
582 <listitem><para>
583 <emphasis>Cross-Prelink:</emphasis>
584 Prelinking is the process of pre-computing the load
585 addresses and link tables generated by the dynamic
586 linker as compared to doing this at runtime.
587 Doing this ahead of time results in performance
588 improvements when the application is launched and
589 reduced memory usage for libraries shared by many
590 applications.</para>
591
592 <para>Historically, cross-prelink is a variant of
593 prelink, which was conceived by
594 <ulink url='http://people.redhat.com/jakub/prelink.pdf'>Jakub Jel&iacute;nek</ulink>
595 a number of years ago.
596 Both prelink and cross-prelink are maintained in the
597 same repository albeit on separate branches.
598 By providing an emulated runtime dynamic linker
599 (i.e. <filename>glibc</filename>-derived
600 <filename>ld.so</filename> emulation), the
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500601 cross-prelink project extends the prelink software's
Brad Bishop316dfdd2018-06-25 12:45:53 -0400602 ability to prelink a sysroot environment.
603 Additionally, the cross-prelink software enables the
604 ability to work in sysroot style environments.</para>
605
606 <para>The dynamic linker determines standard load
607 address calculations based on a variety of factors
608 such as mapping addresses, library usage, and library
609 function conflicts.
610 The prelink tool uses this information, from the
611 dynamic linker, to determine unique load addresses
612 for executable and linkable format (ELF) binaries
613 that are shared libraries and dynamically linked.
614 The prelink tool modifies these ELF binaries with the
615 pre-computed information.
616 The result is faster loading and often lower memory
617 consumption because more of the library code can
618 be re-used from shared Copy-On-Write (COW) pages.
619 </para>
620
621 <para>The original upstream prelink project only
622 supports running prelink on the end target device
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500623 due to the reliance on the target device's dynamic
Brad Bishop316dfdd2018-06-25 12:45:53 -0400624 linker.
625 This restriction causes issues when developing a
626 cross-compiled system.
627 The cross-prelink adds a synthesized dynamic loader
628 that runs on the host, thus permitting cross-prelinking
629 without ever having to run on a read-write target
630 filesystem.
631 </para></listitem>
632 <listitem><para>
633 <emphasis>Pseudo:</emphasis>
634 Pseudo is the Yocto Project implementation of
635 <ulink url='http://man.he.net/man1/fakeroot'>fakeroot</ulink>,
636 which is used to run commands in an environment
637 that seemingly has root privileges.</para>
638
639 <para>During a build, it can be necessary to perform
640 operations that require system administrator
641 privileges.
642 For example, file ownership or permissions might need
643 definition.
644 Pseudo is a tool that you can either use directly or
645 through the environment variable
646 <filename>LD_PRELOAD</filename>.
647 Either method allows these operations to succeed as
648 if system administrator privileges exist even
649 when they do not.</para>
650
651 <para>You can read more about Pseudo in the
652 "<link linkend='fakeroot-and-pseudo'>Fakeroot and Pseudo</link>"
653 section.
654 </para></listitem>
655 </itemizedlist>
656 </para>
657 </section>
658
659 <section id='gs-openembedded-build-system'>
660 <title>Open-Embedded Build System Components</title>
661
662 <para>
663 The following list consists of components associated with the
664 <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>OpenEmbedded build system</ulink>:
665 <itemizedlist>
666 <listitem><para>
667 <emphasis>BitBake:</emphasis>
668 BitBake is a core component of the Yocto Project and is
669 used by the OpenEmbedded build system to build images.
670 While BitBake is key to the build system, BitBake
671 is maintained separately from the Yocto Project.</para>
672
673 <para>BitBake is a generic task execution engine that
674 allows shell and Python tasks to be run efficiently
675 and in parallel while working within complex inter-task
676 dependency constraints.
677 In short, BitBake is a build engine that works
678 through recipes written in a specific format in order
679 to perform sets of tasks.</para>
680
681 <para>You can learn more about BitBake in the
682 <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>.
683 </para></listitem>
684 <listitem><para>
685 <emphasis>OpenEmbedded-Core:</emphasis>
686 OpenEmbedded-Core (OE-Core) is a common layer of
687 metadata (i.e. recipes, classes, and associated files)
688 used by OpenEmbedded-derived systems, which includes
689 the Yocto Project.
690 The Yocto Project and the OpenEmbedded Project both
691 maintain the OpenEmbedded-Core.
692 You can find the OE-Core metadata in the Yocto Project
693 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta'>Source Repositories</ulink>.
694 </para>
695
696 <para>Historically, the Yocto Project integrated the
697 OE-Core metadata throughout the Yocto Project
698 source repository reference system (Poky).
699 After Yocto Project Version 1.0, the Yocto Project
700 and OpenEmbedded agreed to work together and share a
701 common core set of metadata (OE-Core), which contained
702 much of the functionality previously found in Poky.
703 This collaboration achieved a long-standing
704 OpenEmbedded objective for having a more tightly
705 controlled and quality-assured core.
706 The results also fit well with the Yocto Project
707 objective of achieving a smaller number of fully
708 featured tools as compared to many different ones.
709 </para>
710
711 <para>Sharing a core set of metadata results in Poky
712 as an integration layer on top of OE-Core.
713 You can see that in this
714 <link linkend='yp-key-dev-elements'>figure</link>.
715 The Yocto Project combines various components such as
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500716 BitBake, OE-Core, script "glue", and documentation
Brad Bishop316dfdd2018-06-25 12:45:53 -0400717 for its build system.
718 </para></listitem>
719 </itemizedlist>
720 </para>
721 </section>
722
723 <section id='gs-reference-distribution-poky'>
724 <title>Reference Distribution (Poky)</title>
725
726 <para>
727 Poky is the Yocto Project reference distribution.
728 It contains the
729 <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>Open-Embedded build system</ulink>
730 (BitBake and OE-Core) as well as a set of metadata to get you
731 started building your own distribution.
732 See the
733 <link linkend='what-is-the-yocto-project'>figure</link> in
734 "What is the Yocto Project?" section for an illustration
735 that shows Poky and its relationship with other parts of the
736 Yocto Project.</para>
737
738 <para>To use the Yocto Project tools and components, you
739 can download (<filename>clone</filename>) Poky and use it
740 to bootstrap your own distribution.
741 <note>
742 Poky does not contain binary files.
743 It is a working example of how to build your own custom
744 Linux distribution from source.
745 </note>
746 You can read more about Poky in the
747 "<link linkend='reference-embedded-distribution'>Reference Embedded Distribution (Poky)</link>"
748 section.
749 </para>
750 </section>
751
752 <section id='gs-packages-for-finished-targets'>
753 <title>Packages for Finished Targets</title>
754
755 <para>
756 The following lists components associated with packages
757 for finished targets:
758 <itemizedlist>
759 <listitem><para>
760 <emphasis>Matchbox:</emphasis>
761 Matchbox is an Open Source, base environment for the
762 X Window System running on non-desktop, embedded
763 platforms such as handhelds, set-top boxes, kiosks,
764 and anything else for which screen space, input
765 mechanisms, or system resources are limited.</para>
766
767 <para>Matchbox consists of a number of interchangeable
768 and optional applications that you can tailor to a
769 specific, non-desktop platform to enhance usability
770 in constrained environments.</para>
771
772 <para>You can find the Matchbox source in the Yocto
773 Project
774 <ulink url='&YOCTO_GIT_URL;'>Source Repositories</ulink>.
775 </para></listitem>
776 <listitem><para>
777 <emphasis>Opkg</emphasis>
778 Open PacKaGe management (opkg) is a lightweight
779 package management system based on the itsy package
780 (ipkg) management system.
781 Opkg is written in C and resembles Advanced Package
782 Tool (APT) and Debian Package (dpkg) in operation.
783 </para>
784
785 <para>Opkg is intended for use on embedded Linux
786 devices and is used in this capacity in the
787 <ulink url='http://www.openembedded.org/wiki/Main_Page'>OpenEmbedded</ulink>
788 and
789 <ulink url='https://openwrt.org/'>OpenWrt</ulink>
790 projects, as well as the Yocto Project.
791 <note>
792 As best it can, opkg maintains backwards
793 compatibility with ipkg and conforms to a subset
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500794 of Debian's policy manual regarding control files.
Brad Bishop316dfdd2018-06-25 12:45:53 -0400795 </note>
796 </para></listitem>
797 </itemizedlist>
798 </para>
799 </section>
800
801 <section id='gs-archived-components'>
802 <title>Archived Components</title>
803
804 <para>
805 The Build Appliance is a virtual machine image that enables
806 you to build and boot a custom embedded Linux image with
807 the Yocto Project using a non-Linux development system.
808 </para>
809
810 <para>
811 Historically, the Build Appliance was the second of three
812 methods by which you could use the Yocto Project on a system
813 that was not native to Linux.
814 <orderedlist>
815 <listitem><para>
816 <emphasis>Hob:</emphasis>
817 Hob, which is now deprecated and is no longer available
818 since the 2.1 release of the Yocto Project provided
819 a rudimentary, GUI-based interface to the Yocto
820 Project.
821 Toaster has fully replaced Hob.
822 </para></listitem>
823 <listitem><para>
824 <emphasis>Build Appliance:</emphasis>
825 Post Hob, the Build Appliance became available.
826 It was never recommended that you use the Build
827 Appliance as a day-to-day production development
828 environment with the Yocto Project.
829 Build Appliance was useful as a way to try out
830 development in the Yocto Project environment.
831 </para></listitem>
832 <listitem><para>
833 <emphasis>CROPS:</emphasis>
834 The final and best solution available now for
835 developing using the Yocto Project on a system
836 not native to Linux is with
837 <link linkend='gs-crops-overview'>CROPS</link>.
838 </para></listitem>
839 </orderedlist>
840 </para>
841 </section>
842 </section>
843
844 <section id='gs-development-methods'>
845 <title>Development Methods</title>
846
847 <para>
848 The Yocto Project development environment usually involves a
849 <ulink url='&YOCTO_DOCS_REF_URL;#hardware-build-system-term'>Build Host</ulink>
850 and target hardware.
851 You use the Build Host to build images and develop applications,
852 while you use the target hardware to test deployed software.
853 </para>
854
855 <para>
856 This section provides an introduction to the choices or
857 development methods you have when setting up your Build Host.
858 Depending on the your particular workflow preference and the
859 type of operating system your Build Host runs, several choices
860 exist that allow you to use the Yocto Project.
861 <note>
862 For additional detail about the Yocto Project development
863 environment, see the
864 "<link linkend='overview-development-environment'>The Yocto Project Development Environment</link>"
865 chapter.
866 </note>
867 <itemizedlist>
868 <listitem><para>
869 <emphasis>Native Linux Host:</emphasis>
870 By far the best option for a Build Host.
871 A system running Linux as its native operating system
872 allows you to develop software by directly using the
873 <ulink url='&YOCTO_DOCS_REF_URL;#bitbake-term'>BitBake</ulink>
874 tool.
875 You can accomplish all aspects of development from a
876 familiar shell of a supported Linux distribution.</para>
877
878 <para>For information on how to set up a Build Host on
879 a system running Linux as its native operating system,
880 see the
881 "<ulink url='&YOCTO_DOCS_DEV_URL;#setting-up-a-native-linux-host'>Setting Up a Native Linux Host</ulink>"
882 section in the Yocto Project Development Tasks Manual.
883 </para></listitem>
884 <listitem><para>
885 <emphasis>CROss PlatformS (CROPS):</emphasis>
886 Typically, you use
Andrew Geissler82c905d2020-04-13 13:39:40 -0500887 <ulink url='https://github.com/crops/poky-container/'>CROPS</ulink>,
Brad Bishop316dfdd2018-06-25 12:45:53 -0400888 which leverages
889 <ulink url='https://www.docker.com/'>Docker Containers</ulink>,
890 to set up a Build Host that is not running Linux (e.g.
891 <trademark class='registered'>Microsoft</trademark>
892 <trademark class='trademark'>Windows</trademark>
893 or
894 <trademark class='registered'>macOS</trademark>).
895 <note>
896 You can, however, use CROPS on a Linux-based system.
897 </note>
898 CROPS is an open source, cross-platform development
899 framework that provides an easily managed, extensible
900 environment for building binaries targeted for a variety
901 of architectures on Windows, macOS, or Linux hosts.
902 Once the Build Host is set up using CROPS, you can prepare
903 a shell environment to mimic that of a shell being used
904 on a system natively running Linux.</para>
905
906 <para>For information on how to set up a Build Host with
907 CROPS, see the
908 "<ulink url='&YOCTO_DOCS_DEV_URL;#setting-up-to-use-crops'>Setting Up to Use CROss PlatformS (CROPS)</ulink>"
909 section in the Yocto Project Development Tasks Manual.
910 </para></listitem>
911 <listitem><para>
Andrew Geissler82c905d2020-04-13 13:39:40 -0500912 <emphasis>Windows Subsystem For Linux (WSLv2):</emphasis>
913 You may use Windows Subsystem For Linux v2 to set up a build
914 host using Windows 10.
915 <note>
916 The Yocto Project is not compatible with WSLv1, it is
917 compatible but not officially supported nor validated
918 with WSLv2, if you still decide to use WSL please upgrade
919 to WSLv2.
920 </note>
921 The Windows Subsystem For Linux allows Windows 10 to run a real
922 Linux kernel inside of a lightweight utility virtual
923 machine (VM) using virtualization technology.</para>
924 <para>For information on how to set up a Build Host with
925 WSLv2, see the
926 "<ulink url='&YOCTO_DOCS_DEV_URL;#setting-up-to-use-wsl'>Setting Up to Use Windows Subsystem For Linux</ulink>"
927 section in the Yocto Project Development Tasks Manual.
928 </para></listitem>
929 <listitem><para>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400930 <emphasis>Toaster:</emphasis>
931 Regardless of what your Build Host is running, you can
932 use Toaster to develop software using the Yocto Project.
933 Toaster is a web interface to the Yocto Project's
934 <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>Open-Embedded build system</ulink>.
935 The interface enables you to configure and run your
936 builds.
937 Information about builds is collected and stored in a
938 database.
939 You can use Toaster to configure and start builds on
940 multiple remote build servers.</para>
941
942 <para>For information about and how to use Toaster,
943 see the
944 <ulink url='&YOCTO_DOCS_TOAST_URL;'>Toaster User Manual</ulink>.
945 </para></listitem>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400946 </itemizedlist>
947 </para>
948 </section>
949
950 <section id='reference-embedded-distribution'>
951 <title>Reference Embedded Distribution (Poky)</title>
952
953 <para>
954 "Poky", which is pronounced <emphasis>Pock</emphasis>-ee, is the
955 name of the Yocto Project's reference distribution or Reference OS
956 Kit.
957 Poky contains the
958 <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>OpenEmbedded Build System</ulink>
959 (<ulink url='&YOCTO_DOCS_REF_URL;#bitbake-term'>BitBake</ulink> and
960 <ulink url='&YOCTO_DOCS_REF_URL;#oe-core'>OpenEmbedded-Core</ulink>)
961 as well as a set of
962 <ulink url='&YOCTO_DOCS_REF_URL;#metadata'>metadata</ulink> to get
963 you started building your own distro.
964 In other words, Poky is a base specification of the functionality
965 needed for a typical embedded system as well as the components
966 from the Yocto Project that allow you to build a distribution into
967 a usable binary image.
968 </para>
969
970 <para>
971 Poky is a combined repository of BitBake, OpenEmbedded-Core
972 (which is found in <filename>meta</filename>),
973 <filename>meta-poky</filename>,
974 <filename>meta-yocto-bsp</filename>, and documentation provided
975 all together and known to work well together.
976 You can view these items that make up the Poky repository in the
977 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/'>Source Repositories</ulink>.
978 <note>
979 If you are interested in all the contents of the
980 <filename>poky</filename> Git repository, see the
981 "<ulink url='&YOCTO_DOCS_REF_URL;#structure-core'>Top-Level Core Components</ulink>"
982 section in the Yocto Project Reference Manual.
983 </note>
984 </para>
985
986 <para id='gs-poky-reference-distribution'>
987 The following figure illustrates what generally comprises Poky:
988 <imagedata fileref="figures/poky-reference-distribution.png" format="PNG" align='center' width="8in"/>
989 <itemizedlist>
990 <listitem><para>
991 BitBake is a task executor and scheduler that is the heart of
992 the OpenEmbedded build system.
993 </para></listitem>
994 <listitem><para>
995 <filename>meta-poky</filename>, which is Poky-specific
996 metadata.
997 </para></listitem>
998 <listitem><para>
999 <filename>meta-yocto-bsp</filename>, which are Yocto
1000 Project-specific Board Support Packages (BSPs).
1001 </para></listitem>
1002 <listitem><para>
1003 OpenEmbedded-Core (OE-Core) metadata, which includes
1004 shared configurations, global variable definitions,
1005 shared classes, packaging, and recipes.
1006 Classes define the encapsulation and inheritance of build
1007 logic.
1008 Recipes are the logical units of software and images
1009 to be built.
1010 </para></listitem>
1011 <listitem><para>
1012 Documentation, which contains the Yocto Project source
1013 files used to make the set of user manuals.
1014 </para></listitem>
1015 </itemizedlist>
1016 <note>
1017 While Poky is a "complete" distribution specification and is
1018 tested and put through QA, you cannot use it as a product
1019 "out of the box" in its current form.
1020 </note>
1021 </para>
1022
1023 <para>
1024 To use the Yocto Project tools, you can use Git to clone (download)
1025 the Poky repository then use your local copy of the reference
1026 distribution to bootstrap your own distribution.
1027 <note>
1028 Poky does not contain binary files.
1029 It is a working example of how to build your own custom Linux distribution
1030 from source.
1031 </note>
1032 </para>
1033
1034 <para>
1035 Poky has a regular, well established, six-month release cycle
1036 under its own version.
1037 Major releases occur at the same time major releases (point
1038 releases) occur for the Yocto Project, which are typically in the
1039 Spring and Fall.
1040 For more information on the Yocto Project release schedule and
1041 cadence, see the
1042 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-release-process'>Yocto Project Releases and the Stable Release Process</ulink>"
1043 chapter in the Yocto Project Reference Manual.
1044 </para>
1045
1046 <para>
1047 Much has been said about Poky being a "default configuration."
1048 A default configuration provides a starting image footprint.
1049 You can use Poky out of the box to create an image ranging from a
1050 shell-accessible minimal image all the way up to a Linux
1051 Standard Base-compliant image that uses a GNOME Mobile and
1052 Embedded (GMAE) based reference user interface called Sato.
1053 </para>
1054
1055 <para>
1056 One of the most powerful properties of Poky is that every aspect
1057 of a build is controlled by the metadata.
1058 You can use metadata to augment these base image types by
1059 adding metadata
1060 <link linkend='the-yocto-project-layer-model'>layers</link>
1061 that extend functionality.
1062 These layers can provide, for example, an additional software
1063 stack for an image type, add a board support package (BSP) for
1064 additional hardware, or even create a new image type.
1065 </para>
1066
1067 <para>
1068 Metadata is loosely grouped into configuration files or package
1069 recipes.
1070 A recipe is a collection of non-executable metadata used by
1071 BitBake to set variables or define additional build-time tasks.
1072 A recipe contains fields such as the recipe description, the recipe
1073 version, the license of the package and the upstream source
1074 repository.
1075 A recipe might also indicate that the build process uses autotools,
1076 make, distutils or any other build process, in which case the basic
1077 functionality can be defined by the classes it inherits from
1078 the OE-Core layer's class definitions in
1079 <filename>./meta/classes</filename>.
1080 Within a recipe you can also define additional tasks as well as
1081 task prerequisites.
1082 Recipe syntax through BitBake also supports both
1083 <filename>_prepend</filename> and <filename>_append</filename>
1084 operators as a method of extending task functionality.
1085 These operators inject code into the beginning or end of a task.
1086 For information on these BitBake operators, see the
1087 "<ulink url='&YOCTO_DOCS_BB_URL;#appending-and-prepending-override-style-syntax'>Appending and Prepending (Override Style Syntax)</ulink>"
1088 section in the BitBake User's Manual.
1089 </para>
1090 </section>
1091
1092 <section id='openembedded-build-system-workflow'>
1093 <title>The OpenEmbedded Build System Workflow</title>
1094
1095 <para>
1096 The
1097 <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>OpenEmbedded build system</ulink>
1098 uses a "workflow" to accomplish image and SDK generation.
1099 The following figure overviews that workflow:
1100 <imagedata fileref="figures/YP-flow-diagram.png"
1101 format="PNG" align='center' width="8in"/>
1102 Following is a brief summary of the "workflow":
1103 <orderedlist>
1104 <listitem><para>
1105 Developers specify architecture, policies, patches and
1106 configuration details.
1107 </para></listitem>
1108 <listitem><para>
1109 The build system fetches and downloads the source code
1110 from the specified location.
1111 The build system supports standard methods such as tarballs
1112 or source code repositories systems such as Git.
1113 </para></listitem>
1114 <listitem><para>
1115 Once source code is downloaded, the build system extracts
1116 the sources into a local work area where patches are
1117 applied and common steps for configuring and compiling
1118 the software are run.
1119 </para></listitem>
1120 <listitem><para>
1121 The build system then installs the software into a
1122 temporary staging area where the binary package format you
1123 select (DEB, RPM, or IPK) is used to roll up the software.
1124 </para></listitem>
1125 <listitem><para>
1126 Different QA and sanity checks run throughout entire
1127 build process.
1128 </para></listitem>
1129 <listitem><para>
1130 After the binaries are created, the build system
1131 generates a binary package feed that is used to create
1132 the final root file image.
1133 </para></listitem>
1134 <listitem><para>
1135 The build system generates the file system image and a
Brad Bishopb1114e52019-02-13 07:56:10 -05001136 customized Extensible SDK (eSDK) for application
Brad Bishop316dfdd2018-06-25 12:45:53 -04001137 development in parallel.
1138 </para></listitem>
1139 </orderedlist>
1140 </para>
1141
1142 <para>
1143 For a very detailed look at this workflow, see the
1144 "<link linkend='openembedded-build-system-build-concepts'>OpenEmbedded Build System Concepts</link>"
1145 section.
1146 </para>
1147 </section>
1148
1149
1150 <section id='some-basic-terms'>
1151 <title>Some Basic Terms</title>
1152
1153 <para>
1154 It helps to understand some basic fundamental terms when
1155 learning the Yocto Project.
1156 Although a list of terms exists in the
1157 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-terms'>Yocto Project Terms</ulink>"
1158 section of the Yocto Project Reference Manual, this section
1159 provides the definitions of some terms helpful for getting started:
1160 <itemizedlist>
1161 <listitem><para>
1162 <emphasis>Configuration Files:</emphasis>
1163 Files that hold global definitions of variables,
1164 user-defined variables, and hardware configuration
1165 information.
1166 These files tell the
1167 <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>Open-Embedded build system</ulink>
1168 what to build and what to put into the image to support a
1169 particular platform.
1170 </para></listitem>
1171 <listitem><para>
1172 <emphasis>Extensible Software Development Kit (eSDK):</emphasis>
1173 A custom SDK for application developers.
1174 This eSDK allows developers to incorporate their library
1175 and programming changes back into the image to make
1176 their code available to other application developers.
1177 For information on the eSDK, see the
1178 <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink>
1179 manual.
1180 </para></listitem>
1181 <listitem><para>
1182 <emphasis>Layer:</emphasis>
1183 A collection of related recipes.
1184 Layers allow you to consolidate related metadata to
1185 customize your build.
1186 Layers also isolate information used when building
1187 for multiple architectures.
1188 Layers are hierarchical in their ability to override
1189 previous specifications.
1190 You can include any number of available layers from the
1191 Yocto Project and customize the build by adding your
1192 layers after them.
1193 You can search the Layer Index for layers used within
1194 Yocto Project.</para>
1195
1196 <para>For more detailed information on layers, see the
1197 "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>"
1198 section in the Yocto Project Development Tasks Manual.
1199 For a discussion specifically on BSP Layers, see the
1200 "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>"
1201 section in the Yocto Project Board Support Packages (BSP)
1202 Developer's Guide.
1203 </para></listitem>
1204 <listitem><para>
1205 <emphasis>Metadata:</emphasis>
1206 A key element of the Yocto Project is the Metadata that
1207 is used to construct a Linux distribution and is contained
1208 in the files that the OpenEmbedded build system parses
1209 when building an image.
1210 In general, Metadata includes recipes, configuration
1211 files, and other information that refers to the build
1212 instructions themselves, as well as the data used to
1213 control what things get built and the effects of the
1214 build.
1215 Metadata also includes commands and data used to
1216 indicate what versions of software are used, from
1217 where they are obtained, and changes or additions to the
1218 software itself (patches or auxiliary files) that
1219 are used to fix bugs or customize the software for use
1220 in a particular situation.
1221 OpenEmbedded-Core is an important set of validated
1222 metadata.
1223 </para></listitem>
1224 <listitem><para id='gs-term-openembedded-build-system'>
1225 <emphasis>OpenEmbedded Build System:</emphasis>
1226 The terms "BitBake" and "build system" are sometimes
1227 used for the OpenEmbedded Build System.</para>
1228
1229 <para>BitBake is a task scheduler and execution engine
1230 that parses instructions (i.e. recipes) and configuration
1231 data.
1232 After a parsing phase, BitBake creates a dependency tree
1233 to order the compilation, schedules the compilation of
1234 the included code, and finally executes the building
1235 of the specified custom Linux image (distribution).
1236 BitBake is similar to the <filename>make</filename>
1237 tool.</para>
1238
1239 <para>During a build process, the build system tracks
1240 dependencies and performs a native or cross-compilation
1241 of the package.
1242 As a first step in a cross-build setup, the framework
1243 attempts to create a cross-compiler toolchain
1244 (i.e. Extensible SDK) suited for the target platform.
1245 </para></listitem>
1246 <listitem><para>
1247 <emphasis>OpenEmbedded-Core (OE-Core):</emphasis>
1248 OE-Core is metadata comprised of foundation recipes,
1249 classes, and associated files that are meant to be
1250 common among many different OpenEmbedded-derived systems,
1251 including the Yocto Project.
1252 OE-Core is a curated subset of an original repository
1253 developed by the OpenEmbedded community that has been
1254 pared down into a smaller, core set of continuously
1255 validated recipes.
1256 The result is a tightly controlled and quality-assured
1257 core set of recipes.</para>
1258
1259 <para>You can see the Metadata in the
1260 <filename>meta</filename> directory of the Yocto Project
1261 <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi'>Source Repositories</ulink>.
1262 </para></listitem>
1263 <listitem><para>
1264 <emphasis>Packages:</emphasis>
1265 In the context of the Yocto Project, this term refers to a
1266 recipe's packaged output produced by BitBake (i.e. a
1267 "baked recipe").
1268 A package is generally the compiled binaries produced from the
1269 recipe's sources.
1270 You "bake" something by running it through BitBake.</para>
1271
1272 <para>It is worth noting that the term "package" can,
1273 in general, have subtle meanings.
1274 For example, the packages referred to in the
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08001275 "<ulink url='&YOCTO_DOCS_REF_URL;#required-packages-for-the-build-host'>Required Packages for the Build Host</ulink>"
Brad Bishop316dfdd2018-06-25 12:45:53 -04001276 section in the Yocto Project Reference Manual are compiled
1277 binaries that, when installed, add functionality to your
1278 Linux distribution.</para>
1279
1280 <para>Another point worth noting is that historically within
1281 the Yocto Project, recipes were referred to as packages - thus,
1282 the existence of several BitBake variables that are seemingly
1283 mis-named,
1284 (e.g. <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>,
1285 <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>,
1286 and
1287 <ulink url='&YOCTO_DOCS_REF_URL;#var-PE'><filename>PE</filename></ulink>).
1288 </para></listitem>
1289 <listitem><para>
1290 <emphasis>Poky:</emphasis>
1291 Poky is a reference embedded distribution and a reference
1292 test configuration.
1293 Poky provides the following:
1294 <itemizedlist>
1295 <listitem><para>
1296 A base-level functional distro used to illustrate
1297 how to customize a distribution.
1298 </para></listitem>
1299 <listitem><para>
1300 A means by which to test the Yocto Project
1301 components (i.e. Poky is used to validate
1302 the Yocto Project).
1303 </para></listitem>
1304 <listitem><para>
1305 A vehicle through which you can download
1306 the Yocto Project.
1307 </para></listitem>
1308 </itemizedlist>
1309 Poky is not a product level distro.
1310 Rather, it is a good starting point for customization.
1311 <note>
1312 Poky is an integration layer on top of OE-Core.
1313 </note>
1314 </para></listitem>
1315 <listitem><para>
1316 <emphasis>Recipe:</emphasis>
1317 The most common form of metadata.
1318 A recipe contains a list of settings and tasks
1319 (i.e. instructions) for building packages that are then
1320 used to build the binary image.
1321 A recipe describes where you get source code and which
1322 patches to apply.
1323 Recipes describe dependencies for libraries or for other
1324 recipes as well as configuration and compilation options.
1325 Related recipes are consolidated into a layer.
1326 </para></listitem>
1327 </itemizedlist>
1328 </para>
1329 </section>
1330</chapter>
1331<!--
1332vim: expandtab tw=80 ts=4
1333-->