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