diff options
Diffstat (limited to 'documentation/overview-manual/overview-manual-yp-intro.xml')
-rw-r--r-- | documentation/overview-manual/overview-manual-yp-intro.xml | 1333 |
1 files changed, 0 insertions, 1333 deletions
diff --git a/documentation/overview-manual/overview-manual-yp-intro.xml b/documentation/overview-manual/overview-manual-yp-intro.xml deleted file mode 100644 index a2a1f494bb..0000000000 --- a/documentation/overview-manual/overview-manual-yp-intro.xml +++ /dev/null | |||
@@ -1,1333 +0,0 @@ | |||
1 | <!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 | <!--SPDX-License-Identifier: CC-BY-2.0-UK--> | ||
5 | |||
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 | ||
229 | "<ulink url='&YOCTO_DOCS_URL;/what-i-wish-id-known/'>What I wish I'd Known</ulink>" | ||
230 | and | ||
231 | "<ulink url='&YOCTO_DOCS_URL;/transitioning-to-a-custom-environment/'>Transitioning to a Custom Environment for Systems Development</ulink>" | ||
232 | 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> | ||
441 | <ulink url='https://github.com/crops/poky-container/'>CROPS</ulink> | ||
442 | 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. | ||
462 | As with the OpenEmbedded build system, "recipes" | ||
463 | 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 | ||
475 | a "workspace" directory under the eSDK. | ||
476 | 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> | ||
506 | <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í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 | ||
601 | cross-prelink project extends the prelink software's | ||
602 | 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 | ||
623 | due to the reliance on the target device's dynamic | ||
624 | 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 | ||
716 | BitBake, OE-Core, script "glue", and documentation | ||
717 | 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 | ||
794 | of Debian's policy manual regarding control files. | ||
795 | </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 | ||
887 | <ulink url='https://github.com/crops/poky-container/'>CROPS</ulink>, | ||
888 | 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> | ||
912 | <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> | ||
930 | <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> | ||
946 | </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 | ||
1136 | customized Extensible SDK (eSDK) for application | ||
1137 | 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 | ||
1275 | "<ulink url='&YOCTO_DOCS_REF_URL;#required-packages-for-the-build-host'>Required Packages for the Build Host</ulink>" | ||
1276 | 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 | <!-- | ||
1332 | vim: expandtab tw=80 ts=4 | ||
1333 | --> | ||