summaryrefslogtreecommitdiffstats
path: root/documentation/ref-manual/closer-look.xml
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/ref-manual/closer-look.xml')
-rw-r--r--documentation/ref-manual/closer-look.xml1050
1 files changed, 1050 insertions, 0 deletions
diff --git a/documentation/ref-manual/closer-look.xml b/documentation/ref-manual/closer-look.xml
new file mode 100644
index 0000000000..8c3ceb7210
--- /dev/null
+++ b/documentation/ref-manual/closer-look.xml
@@ -0,0 +1,1050 @@
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
5<chapter id='closer-look'>
6<title>A Closer Look at the Yocto Project Development Environment</title>
7
8 <para>
9 This chapter takes a more detailed look at the Yocto Project
10 development environment.
11 The following diagram represents the development environment at a
12 high level.
13 The remainder of this chapter expands on the fundamental input, output,
14 process, and
15 <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>) blocks
16 in the Yocto Project development environment.
17 </para>
18
19 <para id='general-yocto-environment-figure'>
20 <imagedata fileref="figures/yocto-environment-ref.png" align="center" width="8in" depth="4.25in" />
21 </para>
22
23 <para>
24 The generalized Yocto Project Development Environment consists of
25 several functional areas:
26 <itemizedlist>
27 <listitem><para><emphasis>User Configuration:</emphasis>
28 Metadata you can use to control the build process.
29 </para></listitem>
30 <listitem><para><emphasis>Metadata Layers:</emphasis>
31 Various layers that provide software, machine, and
32 distro Metadata.</para></listitem>
33 <listitem><para><emphasis>Source Files:</emphasis>
34 Upstream releases, local projects, and SCMs.</para></listitem>
35 <listitem><para><emphasis>Build System:</emphasis>
36 Processes under the control of BitBake.
37 This block expands on how BitBake fetches source, applies
38 patches, completes compilation, analyzes output for package
39 generation, creates and tests packages, generates images, and
40 generates cross-development tools.</para></listitem>
41 <listitem><para><emphasis>Package Feeds:</emphasis>
42 Directories containing output packages (rpm, deb or ipk),
43 which are subsequently used in the construction of an image or
44 SDK, produced by the build system.
45 These feeds can also be copied and shared using a web server or
46 other means to facilitate extending or updating existing
47 images on devices at runtime if runtime package management is
48 enabled.</para></listitem>
49 <listitem><para><emphasis>Images:</emphasis>
50 Images produced by the development process.
51 Where do they go?
52 Can you mess with them (i.e. freely delete them or move them?).
53 </para></listitem>
54 <listitem><para><emphasis>Application Development SDK:</emphasis>
55 Cross-development tools that are produced along with an image
56 or separately with BitBake.</para></listitem>
57 </itemizedlist>
58 </para>
59
60 <section id="user-configuration">
61 <title>User Configuration</title>
62
63 <para>
64 User configuration helps define the build.
65 Through user configuration, you can tell BitBake the
66 target architecture for which you are building the image,
67 where to store downloaded source, and other build properties.
68 </para>
69
70 <para>
71 The following figure shows an expanded representation of the
72 "User Configuration" box of the
73 <link linkend='general-yocto-environment-figure'>general Yocto Project Development Environment figure</link>:
74 </para>
75
76 <para>
77 <imagedata fileref="figures/user-configuration.png" align="center" width="5.5in" depth="3.5in" />
78 </para>
79
80 <para>
81 BitBake needs some basic configuration files in order to complete
82 a build.
83 These files are <filename>*.conf</filename> files.
84 The minimally necessary ones reside as example files in the
85 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
86 For simplicity, this section refers to the Source Directory as
87 the "Poky Directory."
88 </para>
89
90 <para>
91 When you clone the <filename>poky</filename> Git repository or you
92 download and unpack a Yocto Project release, you can set up the
93 Source Directory to be named anything you want.
94 For this discussion, the cloned repository uses the default
95 name <filename>poky</filename>.
96 <note>
97 The Poky repository is primarily an aggregation of existing
98 repositories.
99 It is not a canonical upstream source.
100 </note>
101 </para>
102
103 <para>
104 The <filename>meta-yocto</filename> layer inside Poky contains
105 a <filename>conf</filename> directory that has example
106 configuration files.
107 These example files are used as a basis for creating actual
108 configuration files when you source the build environment
109 script <filename>oe-init-build-env</filename>.
110 </para>
111
112 <para>
113 Sourcing the build environment script creates a
114 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
115 if one does not already exist.
116 BitBake uses the Build Directory for all its work during builds.
117 The Build Directory has a <filename>conf</filename> directory that
118 contains default versions of your <filename>local.conf</filename>
119 and <filename>bblayers.conf</filename> configuration files.
120 These default configuration files are created only if versions
121 do not already exist in the Build Directory at the time you
122 source the <filename>oe-init-build-env</filename> script.
123 </para>
124
125 <para>
126 Because the Poky repository is fundamentally an aggregation of
127 existing repositories, some users might be familiar with running
128 the <filename>oe-init-build-env</filename> script in the context of
129 separate OpenEmbedded-Core and BitBake repositories rather than a
130 single Poky repository.
131 This discussion assumes the script is executed from within a cloned
132 or unpacked version of Poky.
133 </para>
134
135 <para>
136 Depending on where the script is sourced, different sub-scripts
137 are called to set up the Build Directory (Yocto or OpenEmbedded).
138 Specifically, the script
139 <filename>scripts/oe-setup-builddir</filename> inside the
140 poky directory sets up the Build Directory and seeds the directory
141 (if necessary) with configuration files appropriate for the
142 Yocto Project development environment.
143 <note>
144 The <filename>scripts/oe-setup-builddir</filename> script
145 uses the <filename>$TEMPLATECONF</filename> variable to
146 determine which sample configuration files to locate.
147 </note>
148 </para>
149
150 <para>
151 The <filename>local.conf</filename> file provides many
152 basic variables that define a build environment.
153 Here is a list of a few.
154 To see the default configurations in a <filename>local.conf</filename>
155 file created by the build environment script, see the
156 <filename>local.conf.sample</filename> in the
157 <filename>meta-yocto</filename> layer:
158 <itemizedlist>
159 <listitem><para><emphasis>Parallelism Options:</emphasis>
160 Controlled by the
161 <link linkend='var-BB_NUMBER_THREADS'><filename>BB_NUMBER_THREADS</filename></link>
162 and
163 <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link>
164 variables.</para></listitem>
165 <listitem><para><emphasis>Target Machine Selection:</emphasis>
166 Controlled by the
167 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>
168 variable.</para></listitem>
169 <listitem><para><emphasis>Download Directory:</emphasis>
170 Controlled by the
171 <link linkend='var-DL_DIR'><filename>DL_DIR</filename></link>
172 variable.</para></listitem>
173 <listitem><para><emphasis>Shared State Directory:</emphasis>
174 Controlled by the
175 <link linkend='var-SSTATE_DIR'><filename>SSTATE_DIR</filename></link>
176 variable.</para></listitem>
177 <listitem><para><emphasis>Build Output:</emphasis>
178 Controlled by the
179 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>
180 variable.</para></listitem>
181 </itemizedlist>
182 <note>
183 Configurations set in the <filename>conf/local.conf</filename>
184 file can also be set in the
185 <filename>conf/site.conf</filename> and
186 <filename>conf/auto.conf</filename> configuration files.
187 </note>
188 </para>
189
190 <para>
191 The <filename>bblayers.conf</filename> file tells BitBake what
192 layers you want considered during the build.
193 By default, the layers listed in this file include layers
194 minimally needed by the build system.
195 However, you must manually add any custom layers you have created.
196 You can find more information on working with the
197 <filename>bblayers.conf</filename> file in the
198 "<ulink url='&YOCTO_DOCS_DEV_URL;#enabling-your-layer'>Enabling Your Layer</ulink>"
199 section in the Yocto Project Development Manual.
200 </para>
201
202 <para>
203 The files <filename>site.conf</filename> and
204 <filename>auto.conf</filename> are not created by the environment
205 initialization script.
206 If you want these configuration files, you must create them
207 yourself:
208 <itemizedlist>
209 <listitem><para><emphasis><filename>site.conf</filename>:</emphasis>
210 You can use the <filename>conf/site.conf</filename>
211 configuration file to configure multiple build directories.
212 For example, suppose you had several build environments and
213 they shared some common features.
214 You can set these default build properties here.
215 A good example is perhaps the level of parallelism you want
216 to use through the
217 <link linkend='var-BB_NUMBER_THREADS'><filename>BB_NUMBER_THREADS</filename></link>
218 and
219 <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link>
220 variables.</para>
221 <para>One useful scenario for using the
222 <filename>conf/site.conf</filename> file is to extend your
223 <link linkend='var-BBPATH'><filename>BBPATH</filename></link>
224 variable to include the path to a
225 <filename>conf/site.conf</filename>.
226 Then, when BitBake looks for Metadata using
227 <filename>BBPATH</filename>, it finds the
228 <filename>conf/site.conf</filename> file and applies your
229 common configurations found in the file.
230 To override configurations in a particular build directory,
231 alter the similar configurations within that build
232 directory's <filename>conf/local.conf</filename> file.
233 </para></listitem>
234 <listitem><para><emphasis><filename>auto.conf</filename>:</emphasis>
235 This file is not hand-created.
236 Rather, the file is usually created and written to by
237 an autobuilder.
238 The settings put into the file are typically the same as
239 you would find in the <filename>conf/local.conf</filename>
240 or the <filename>conf/site.conf</filename> files.
241 </para></listitem>
242 </itemizedlist>
243 </para>
244
245 <para>
246 You can edit all configuration files to further define
247 any particular build environment.
248 This process is represented by the "User Configuration Edits"
249 box in the figure.
250 </para>
251
252 <para>
253 When you launch your build with the
254 <filename>bitbake &lt;target&gt;</filename> command, BitBake
255 sorts out the configurations to ultimately define your build
256 environment.
257 </para>
258 </section>
259
260 <section id="metadata-machine-configuration-and-policy-configuration">
261 <title>Metadata, Machine Configuration, and Policy Configuration</title>
262
263 <para>
264 The previous section described the user configurations that
265 define the BitBake's global behavior.
266 This section takes a closer look at the layers the build system
267 uses to further control the build.
268 These layers provide Metadata for the software, machine, and
269 policy.
270 </para>
271
272 <para>
273 In general, three types of layer input exist:
274 <itemizedlist>
275 <listitem><para><emphasis>Policy Configuration:</emphasis>
276 Distribution Layers provide top-level or general
277 policies for the image or SDK being built.
278 For example, this layer would dictate whether BitBake
279 produces RPM or IPK packages.</para></listitem>
280 <listitem><para><emphasis>Machine Configuration:</emphasis>
281 Board Support Package (BSP) layers provide machine
282 configurations.
283 This type of information is specific to a particular
284 target architecture.</para></listitem>
285 <listitem><para><emphasis>Metadata:</emphasis>
286 Software layers contain user-supplied recipe files,
287 patches, and append files.
288 </para></listitem>
289 </itemizedlist>
290 </para>
291
292 <para>
293 The following figure shows an expanded representation of the
294 Metadata, Machine Configuration, and Policy Configuration input
295 (layers) boxes of the
296 <link linkend='general-yocto-environment-figure'>general Yocto Project Development Environment figure</link>:
297 </para>
298
299 <para>
300 <imagedata fileref="figures/layer-input.png" align="center" width="8in" depth="7.5in" />
301 </para>
302
303 <para>
304 In general, all layers have a similar structure.
305 They all contain a licensing file
306 (e.g. <filename>COPYING</filename>) if the layer is to be
307 distributed, a <filename>README</filename> file as good practice
308 and especially if the layer is to be distributed, a
309 configuration directory, and recipe directories.
310 </para>
311
312 <para>
313 The Yocto Project has many layers that can be used.
314 You can see a web-interface listing of them on the
315 <ulink url="http://git.yoctoproject.org/">Source Repositories</ulink>
316 page.
317 The layers are shown at the bottom categorized under
318 "Yocto Metadata Layers."
319 These layers are fundamentally a subset of the
320 <ulink url="http://layers.openembedded.org/layerindex/layers/">OpenEmbedded Metadata Index</ulink>,
321 which lists all layers provided by the OpenEmbedded community.
322 <note>
323 Layers exist in the Yocto Project Source Repositories that
324 cannot be found in the OpenEmbedded Metadata Index.
325 These layers are either deprecated or experimental in nature.
326 </note>
327 </para>
328
329 <para>
330 BitBake uses the <filename>conf/bblayers.conf</filename> file,
331 which is part of the user configuration, to find what layers it
332 should be using as part of the build.
333 </para>
334
335 <para>
336 For more information on layers, see the
337 "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>"
338 section in the Yocto Project Development Manual.
339 </para>
340
341 <section id="distro-layer">
342 <title>Distro Layer</title>
343
344 <para>
345 The distribution layer provides policy configurations for your
346 distribution.
347 Best practices dictate that you isolate these types of
348 configurations into their own layer.
349 Settings you provide in
350 <filename>conf/&lt;distro&gt;.conf</filename> override similar
351 settings that BitBake finds in your
352 <filename>conf/local.conf</filename> file in the Build
353 Directory.
354 </para>
355
356 <para>
357 The following list provides some explanation and references
358 for what you typically find in the distribution layer:
359 <itemizedlist>
360 <listitem><para><emphasis>classes:</emphasis>
361 Class files (<filename>.bbclass</filename>) holds
362 common functionality that can be shared among
363 recipes in the distribution.
364 When your recipes inherit a class, they take on the
365 settings and functions for that class.
366 You can read more about class files in the
367 "<link linkend='ref-classes'>Classes</link>" section.
368 </para></listitem>
369 <listitem><para><emphasis>conf:</emphasis>
370 This area holds configuration files for the
371 layer (<filename>conf/layer.conf</filename>),
372 the distribution
373 (<filename>conf/distro/&lt;distro&gt;.conf</filename>),
374 and any distribution-wide include files.
375 </para></listitem>
376 <listitem><para><emphasis>recipes-*:</emphasis>
377 Recipes and append files that affect common
378 functionality across the distribution.
379 This area could include recipes and append files to
380 to add distribution-specific configuration,
381 initialization scripts, custom image recipes,
382 and so forth.</para></listitem>
383 </itemizedlist>
384 </para>
385 </section>
386
387 <section id="bsp-layer">
388 <title>BSP Layer</title>
389
390 <para>
391 The BSP Layer provides machine configurations.
392 Everything in this layer is specific to the machine for which
393 you are building the image or the SDK.
394 A common structure or form is defined for BSP layers.
395 You can learn more about this structure in the
396 <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink>.
397 <note>
398 In order for a BSP layer to be considered compliant with the
399 Yocto Project, it must meet some structural requirements.
400 </note>
401 </para>
402
403 <para>
404 The BSP Layer's configuration directory contains
405 configuration files for the machine
406 (<filename>conf/machine/&lt;machine&gt;.conf</filename>) and,
407 of course, the layer (<filename>conf/layer.conf</filename>).
408 </para>
409
410 <para>
411 The remainder of the layer is dedicated to specific recipes
412 by function: <filename>recipes-bsp</filename>,
413 <filename>recipes-core</filename>,
414 <filename>recipes-graphics</filename>, and
415 <filename>recipes-kernel</filename>.
416 Metadata can exist for multiple formfactors, graphics
417 support systems, and so forth.
418 <note>
419 While the figure shows several <filename>recipe-*</filename>
420 directories, not all these directories appear in all
421 BSP layers.
422 </note>
423 </para>
424 </section>
425
426 <section id="software-layer">
427 <title>Software Layer</title>
428
429 <para>
430 The software layer provides the Metadata for additional
431 software packages used during the build.
432 This layer does not include Metadata that is specific to the
433 distribution or the machine, which are found in their
434 respective layers.
435 </para>
436
437 <para>
438 This layer contains any new recipes that your project needs
439 in the form of recipe files.
440 </para>
441 </section>
442 </section>
443
444 <section id="sources-dev-environment">
445 <title>Sources</title>
446
447 <para>
448 In order for the OpenEmbedded build system to create an image or
449 any target, it must be able to access source files.
450 The
451 <link linkend='general-yocto-environment-figure'>general Yocto Project Development Environment figure</link>
452 represents source files using the "Upstream Project Releases",
453 "Local Projects", and "SCMs (optional)" boxes.
454 The figure represents mirrors, which also play a role in locating
455 source files, with the "Source Mirror(s)" box.
456 </para>
457
458 <para>
459 The method by which source files are ultimately organized is
460 a function of the project.
461 For example, for released software, projects tend to use tarballs
462 or other archived files that can capture the state of a release
463 guaranteeing that it is statically represented.
464 On the other hand, for a project that is more dynamic or
465 experimental in nature, a project might keep source files in a
466 repository controlled by a Source Control Manager (SCM) such as
467 Git.
468 Pulling source from a repository allows you to control
469 the point in the repository (the revision) from which you want to
470 build software.
471 Finally, a combination of the two might exist, which would give the
472 consumer a choice when deciding where to get source files.
473 </para>
474
475 <para>
476 BitBake uses the
477 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
478 variable to point to source files regardless of their location.
479 Each recipe must have a <filename>SRC_URI</filename> variable
480 that points to the source.
481 </para>
482
483 <para>
484 Another area that plays a significant role in where source files
485 comes from is pointed to by the
486 <link linkend='var-DL_DIR'><filename>DL_DIR</filename></link>
487 variable.
488 This area is a cache that can hold previously downloaded source.
489 Judicious use of a <filename>DL_DIR</filename> directory can
490 save the build system a trip across the Internet when looking
491 for files.
492 A good method for using a download directory is to have
493 <filename>DL_DIR</filename> point to an area outside of your
494 Build Directory.
495 Doing so allows you to safely delete the Build Directory
496 if needed without fear of removing any downloaded source file.
497 </para>
498
499 <para>
500 The remainder of this section provides a deeper look into the
501 source files and the mirrors.
502 Here is a more detailed look at the source file area of the
503 base figure:
504 <imagedata fileref="figures/source-input.png" align="center" width="7in" depth="7.5in" />
505 </para>
506
507 <section id='upstream-project-releases'>
508 <title>Upstream Project Releases</title>
509
510 <para>
511 Upstream project releases exist anywhere in the form of an
512 archived file (e.g. tarball or zip file).
513 These files correspond to individual recipes.
514 For example, the figure uses specific releases each for
515 BusyBox, Qt, and Dbus.
516 An archive file can be for any released product that can be
517 built using a recipe.
518 </para>
519 </section>
520
521 <section id='local-projects'>
522 <title>Local Projects</title>
523
524 <para>
525 Local projects are custom bits of software the user provides.
526 These bits reside somewhere local to a project - perhaps
527 a directory into which the user checks in items (e.g.
528 a local directory containing a development source tree
529 used by the group).
530 </para>
531
532 <para>
533 The canonical method through which to include a local project
534 is to use the
535 <link linkend='ref-classes-externalsrc'><filename>externalsrc.bbclass</filename></link>
536 class to include local project.
537 You use either the <filename>local.conf</filename> or a
538 recipe's append file to override or set the
539 recipe to point to the local directory on your disk to pull
540 in the whole source tree.
541 </para>
542
543 <para>
544 For information on how to use the
545 <filename>externalsrc.bbclass</filename>, see the
546 "<link linkend='ref-classes-externalsrc'><filename>externalsrc.bbclass</filename></link>"
547 section.
548 </para>
549 </section>
550
551 <section id='scms'>
552 <title>Source Control Managers (Optional)</title>
553
554 <para>
555 Another place the build system can get source files from is
556 through an SCM such as Git or Subversion.
557 In this case, a repository is cloned or checked out.
558 The <filename>do_fetch</filename> task inside BitBake uses
559 the <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
560 variable and the argument's prefix to determine the correct
561 fetcher module.
562 </para>
563
564 <para>
565 When fetching a repository, BitBake uses the
566 <link linkend='var-SRCREV'><filename>SRCREV</filename></link>
567 variable to determine the specific revision from which to
568 build.
569 </para>
570 </section>
571
572 <section id='source-mirrors'>
573 <title>Source Mirror(s)</title>
574
575 <para>
576 Two kinds of mirrors exist: pre-mirrors and regular mirrors.
577 The <link linkend='var-PREMIRRORS'><filename>PREMIRRORS</filename></link>
578 and
579 <link linkend='var-MIRRORS'><filename>MIRRORS</filename></link>
580 variables point to these, respectively.
581 BitBake checks pre-mirrors before looking upstream for any
582 source files.
583 Pre-mirrors are appropriate when you have a shared directory
584 that is not a directory defined by the
585 <link linkend='var-DL_DIR'><filename>DL_DIR</filename></link>
586 variable.
587 A Pre-mirror typically points to a shared directory that is
588 local to your organization.
589 </para>
590
591 <para>
592 Regular mirrors can be any site across the Internet that is
593 used as an alternative location for source code should the
594 primary site not be functioning for some reason or another.
595 </para>
596 </section>
597 </section>
598
599 <section id='bitbake-dev-environment'>
600 <title>BitBake</title>
601
602 <para>
603 The OpenEmbedded build system uses BitBake to produce images.
604 You can see from the
605 <link linkend='general-yocto-environment-figure'>general Yocto Project Development Environment figure</link>,
606 the BitBake area consists of several functional areas.
607 This section takes a closer look at each of those areas.
608 </para>
609
610 <section id='source-fetching-dev-environment'>
611 <title>Source Fetching</title>
612
613 <para>
614 The first stages of building a recipe are to fetch and unpack
615 the source code:
616 <imagedata fileref="figures/source-fetching.png" align="center" width="6.5in" depth="4in" />
617 </para>
618
619 <para>
620 The <filename>do_fetch</filename> and
621 <filename>do_unpack</filename> tasks fetch the source files
622 and unpack them into a working directory.
623 By default, everything is accomplished in the
624 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>,
625 which has a defined structure.
626 For additional general information on the Build Directory,
627 see the
628 "<link linkend='structure-core-build'><filename>build/</filename></link>"
629 section.
630 </para>
631
632 <para>
633 Unpacked source source files are pointed to by the
634 <link linkend='var-S'><filename>S</filename></link> variable.
635 Each recipe has an area in the Build Directory where the
636 unpacked source code resides.
637 The name of directory for any given recipe is defined from
638 several different variables.
639 You can see the variables that define these directories
640 by looking at the figure:
641 <itemizedlist>
642 <listitem><para><link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>
643 </para></listitem>
644 <listitem><para><link linkend='var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></link>
645 </para></listitem>
646 <listitem><para><link linkend='var-TARGET_OS'><filename>TARGET_OS</filename></link>
647 </para></listitem>
648 <listitem><para><link linkend='var-PN'><filename>PN</filename></link>
649 </para></listitem>
650 <listitem><para><link linkend='var-PV'><filename>PV</filename></link>
651 </para></listitem>
652 <listitem><para><link linkend='var-PR'><filename>PR</filename></link>
653 </para></listitem>
654 <listitem><para><link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>
655 </para></listitem>
656 <listitem><para><link linkend='var-S'><filename>S</filename></link>
657 </para></listitem>
658 </itemizedlist>
659 </para>
660
661 <para>
662 Briefly, the <filename>S</filename> directory contains the
663 unpacked source files for a recipe.
664 The <filename>WORKDIR</filename> directory is where all the
665 building goes on for a given recipe.
666 </para>
667 </section>
668
669 <section id='patching-dev-environment'>
670 <title>Patching</title>
671
672 <para>
673 Once source code is fetched and unpacked, BitBake locates
674 patch files and applies them to the source files:
675 <imagedata fileref="figures/patching.png" align="center" width="6in" depth="5in" />
676 </para>
677
678 <para>
679 The <filename>do_patch</filename> task processes recipes by
680 using the
681 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
682 variable to locate applicable patch files, which by default
683 are <filename>*.patch</filename> or
684 <filename>*.diff</filename> files, or any file if
685 "apply=yes" is specified for the file in
686 <filename>SRC_URI</filename>.
687 </para>
688
689 <para>
690 BitBake finds and applies multiple patches for a single recipe
691 in the order in which it finds the patches.
692 Patches are applied to the recipe's source files located in the
693 <link linkend='var-S'><filename>S</filename></link> directory.
694 </para>
695
696 <para>
697 For more information on how the source directories are
698 created, see the
699 "<link linkend='source-fetching-dev-environment'>Source Fetching</link>"
700 section.
701 </para>
702 </section>
703
704 <section id='configuration-and-compilation-dev-environment'>
705 <title>Configuration and Compilation</title>
706
707 <para>
708 After source code is patched, BitBake executes tasks that
709 configure and compile the source code:
710 <imagedata fileref="figures/configuration-compile-autoreconf.png" align="center" width="7in" depth="5in" />
711 </para>
712
713 <para>
714 This step in the build process consists of three tasks:
715 <itemizedlist>
716 <listitem><para><emphasis><filename>do_configure</filename>:</emphasis>
717 This task configures the source by enabling and
718 disabling any build-time and configuration options for
719 the software being built.
720 Configurations can come from the recipe itself as well
721 as from an inherited class.
722 Additionally, the software itself might configure itself
723 depending on the target for which it is being built.
724 </para>
725
726 <para>The configurations handled by the
727 <filename>do_configure</filename> task are specific
728 to source code configuration for the source code
729 being built by the recipe.</para>
730
731 <para>If you are using
732 <link linkend='ref-classes-autotools'><filename>autotools.bbclass</filename></link>,
733 you can add additional configuration options by using
734 the <link linkend='var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></link>
735 variable.
736 For information on how this variable works within
737 that class, see the
738 <filename>meta/classes/autotools.bbclass</filename>.
739 </para></listitem>
740 <listitem><para><emphasis><filename>do_compile</filename>:</emphasis>
741 Once a configuration task has been satisfied, BitBake
742 compiles the source using the
743 <filename>do_compile</filename> task.
744 Compilation occurs in the directory pointed to by the
745 <link linkend='var-B'><filename>B</filename></link>
746 variable.
747 Realize that the <filename>B</filename> directory, by
748 default, is the same as the
749 <link linkend='var-S'><filename>S</filename></link>
750 directory.</para></listitem>
751 <listitem><para><emphasis><filename>do_install</filename>:</emphasis>
752 Once compilation is done, BitBake executes the
753 <filename>do_install</filename> task.
754 This task copies files from the <filename>B</filename>
755 directory and places them in a holding area pointed to
756 by the
757 <link linkend='var-D'><filename>D</filename></link>
758 variable.</para></listitem>
759 </itemizedlist>
760 </para>
761 </section>
762
763 <section id='package-splitting-dev-environment'>
764 <title>Package Splitting</title>
765
766 <para>
767 After source code is configured and compiled, the
768 OpenEmbedded build system analyzes
769 the results and splits the output into packages:
770 <imagedata fileref="figures/analysis-for-package-splitting.png" align="center" width="7in" depth="7in" />
771 </para>
772
773 <para>
774 The <filename>do_package</filename> and
775 <filename>do_packagedata</filename> tasks combine to analyze
776 the files found in the
777 <link linkend='var-D'><filename>D</filename></link> directory
778 and split them into subsets based on available packages and
779 files.
780 The analyzing process involves the following as well as other
781 items: splitting out debugging symbols,
782 looking at shared library dependencies between packages,
783 and looking at package relationships.
784 The <filename>do_packagedata</filename> task creates package
785 metadata based on the analysis such that the
786 OpenEmbedded build system can generate the final packages.
787 Working, staged, and intermediate results of the analysis
788 and package splitting process use these areas:
789 <itemizedlist>
790 <listitem><para><link linkend='var-PKGD'><filename>PKGD</filename></link>
791 </para></listitem>
792 <listitem><para><link linkend='var-PKGDATA_DIR'><filename>PKGDATA_DIR</filename></link>
793 </para></listitem>
794 <listitem><para><link linkend='var-PKGDESTWORK'><filename>PKGDESTWORK</filename></link>
795 </para></listitem>
796 <listitem><para><link linkend='var-PKGDEST'><filename>PKGDEST</filename></link>
797 </para></listitem>
798 </itemizedlist>
799 The <link linkend='var-FILES'><filename>FILES</filename></link>
800 variable defines the files that go into each package in
801 <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>.
802 If you want details on how this is accomplished, you can
803 look at
804 <link linkend='ref-classes-package'><filename>package.bbclass</filename></link>.
805 </para>
806
807 <para>
808 Depending on the type of packages being created (RPM, DEB, or
809 IPK), the <filename>do_package_write_*</filename> task
810 creates the actual packages and places them in the
811 Package Feed area, which is
812 <filename>${TMPDIR}/deploy</filename>.
813 You can see the
814 "<link linkend='package-feeds-dev-environment'>Package Feeds</link>"
815 section for more detail on that part of the build process.
816 <note>
817 Support for creating feeds directly from the
818 <filename>deploy/*</filename> directories does not exist.
819 Creating such feeds usually requires some kind of feed
820 maintenance mechanism that would upload the new packages
821 into an official package feed (e.g. the
822 Ångström distribution).
823 This functionality is highly distribution-specific
824 and thus is not provided out of the box.
825 </note>
826 </para>
827 </section>
828 </section>
829
830 <section id="package-feeds-dev-environment">
831 <title>Package Feeds</title>
832
833 <para>
834 When the OpenEmbedded build system generates an image or an SDK,
835 it gets the packages from a package feed area located in the
836 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
837 The
838 <link linkend='general-yocto-environment-figure'>general Yocto Project Development Environment figure</link>
839 shows this package feeds area in the upper-right corner.
840 </para>
841
842 <para>
843 This section looks a little closer into the package feeds area used
844 by the build system.
845 Here is a more detailed look at the area:
846 <imagedata fileref="figures/package-feeds.png" align="center" width="7in" depth="6in" />
847 </para>
848
849 <para>
850 Package feeds are an intermediary step in the build process.
851 BitBake generates packages whose type is defined by the
852 <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>
853 variable.
854 Before placing the packages into package feeds,
855 the build process validates them with generated output quality
856 assurance checks through the
857 <link linkend='ref-classes-insane'><filename>insane.bbclass</filename></link>
858 class.
859 </para>
860
861 <para>
862 The package feed area resides in
863 <filename>tmp/deploy</filename> of the Build Directory.
864 Folders are created that correspond to the package type
865 (IPK, DEB, or RPM) created.
866 Further organization is derived through the value of the
867 <link linkend='var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></link>
868 variable for each package.
869 For example, packages can exist for the i586 or qemux86
870 architectures.
871 The package files themselves reside within the appropriate
872 architecture folder.
873 </para>
874
875 <para>
876 BitBake uses the <filename>do_package_write_*</filename> task to
877 place generated packages into the package holding area (e.g.
878 <filename>do_package_write_ipk</filename> for IPK packages).
879 </para>
880 </section>
881
882 <section id='images-dev-environment'>
883 <title>Images</title>
884
885 <para>
886 The images produced by the OpenEmbedded build system
887 are compressed forms of the
888 root filesystems that are ready to boot on a target device.
889 You can see from the
890 <link linkend='general-yocto-environment-figure'>general Yocto Project Development Environment figure</link>
891 that BitBake output in part consists of images.
892 This section is going to look more closely at this output:
893 <imagedata fileref="figures/images.png" align="center" width="5.5in" depth="5.5in" />
894 </para>
895
896 <para>
897 For a list of example images that the Yocto Project provides,
898 the
899 "<link linkend='ref-images'>Images</link>" chapter.
900 </para>
901
902 <para>
903 Images are written out to the
904 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
905 inside the <filename>deploy/images</filename> folder as shown
906 in the figure.
907 This folder contains any files expected to be loaded on the
908 target device.
909 The
910 <link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link>
911 variable points to the <filename>deploy</filename> directory.
912 <itemizedlist>
913 <listitem><para><filename>&lt;kernel-image&gt;</filename>:
914 A kernel binary file.
915 The <link linkend='var-KERNEL_IMAGETYPE'><filename>KERNEL_IMAGETYPE</filename></link>
916 variable setting determines the naming scheme for the
917 kernel image file.
918 Depending on that variable, the file could begin with
919 a variety of naming strings.
920 The <filename>deploy/images</filename> directory can
921 contain multiple image files.</para></listitem>
922 <listitem><para><filename>&lt;root-filesystem-image&gt;</filename>:
923 Root filesystems for the target device (e.g.
924 <filename>*.ext3</filename> or <filename>*.bz2</filename>
925 files).
926 The <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
927 variable setting determines the root filesystem image
928 type.
929 The <filename>deploy/images</filename> directory can
930 contain multiple root filesystems.</para></listitem>
931 <listitem><para><filename>&lt;kernel-modules&gt;</filename>:
932 Tarballs that contain all the modules built for the kernel.
933 Kernel module tarballs exist for legacy purposes and
934 can be suppressed by setting the
935 <link linkend='var-MODULE_TARBALL_DEPLOY'><filename>MODULE_TARBALL_DEPLOY</filename></link>
936 variable to "0".
937 The <filename>deploy/images</filename> directory can
938 contain multiple kernel module tarballs.
939 </para></listitem>
940 <listitem><para><filename>&lt;bootloaders&gt;</filename>:
941 Bootloaders supporting the image, if applicable to the
942 target machine.
943 The <filename>deploy/images</filename> directory can
944 contain multiple bootloaders.
945 </para></listitem>
946 <listitem><para><filename>&lt;symlinks&gt;</filename>:
947 The <filename>deploy/images</filename> folder contains
948 a symbolic link that points to the most recently built file
949 for each machine.
950 These links might be useful for external scripts that
951 need to obtain the latest version of each file.
952 </para></listitem>
953 </itemizedlist>
954 </para>
955 </section>
956
957 <section id='sdk-dev-environment'>
958 <title>Application Development SDK</title>
959
960 <para>
961 In the
962 <link linkend='general-yocto-environment-figure'>general Yocto Project Development Environment figure</link>,
963 the output labeled "Application Development SDK" represents an
964 SDK.
965 This section is going to take a closer look at this output:
966 <imagedata fileref="figures/sdk.png" align="center" width="5in" depth="4in" />
967 </para>
968
969 <para>
970 The specific form of this output is a self-extracting
971 SDK installer (<filename>*.sh</filename>) that, when run,
972 installs the SDK, which consists of a cross-development
973 toolchain, a set of libraries and headers, and an SDK
974 environment setup script.
975 Running this installer essentially sets up your
976 cross-development environment.
977 You can think of the cross-toolchain as the "host"
978 part because it runs on the SDK machine.
979 You can think of the libraries and headers as the "target"
980 part because they are built for the target hardware.
981 The setup script is added so that you can initialize the
982 environment before using the tools.
983 </para>
984
985 <note>
986 <para>
987 The Yocto Project supports several methods by which you can
988 set up this cross-development environment.
989 These methods include downloading pre-built SDK installers,
990 building and installing your own SDK installer, or running
991 an Application Development Toolkit (ADT) installer to
992 install not just cross-development toolchains
993 but also additional tools to help in this type of
994 development.
995 </para>
996
997 <para>
998 For background information on cross-development toolchains
999 in the Yocto Project development environment, see the
1000 "<link linkend='cross-development-toolchain-generation'>Cross-Development Toolchain Generation</link>"
1001 section.
1002 For information on setting up a cross-development
1003 environment, see the
1004 "<ulink url='&YOCTO_DOCS_ADT_URL;#installing-the-adt'>Installing the ADT and Toolchains</ulink>"
1005 section in the Yocto Project Application Developer's Guide.
1006 </para>
1007 </note>
1008
1009 <para>
1010 Once built, the SDK installers are written out to the
1011 <filename>deploy/sdk</filename> folder inside the
1012 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
1013 as shown in the figure at the beginning of this section.
1014 Several variables exist that help configure these files:
1015 <itemizedlist>
1016 <listitem><para><link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link>:
1017 Points to the <filename>deploy</filename>
1018 directory.</para></listitem>
1019 <listitem><para><link linkend='var-SDKMACHINE'><filename>SDKMACHINE</filename></link>:
1020 Specifies the architecture of the machine
1021 on which the cross-development tools are run to
1022 create packages for the target hardware.
1023 </para></listitem>
1024 <listitem><para><link linkend='var-SDKIMAGE_FEATURES'><filename>SDKIMAGE_FEATURES</filename></link>:
1025 Lists the features to include in the "target" part
1026 of the SDK.
1027 </para></listitem>
1028 <listitem><para><link linkend='var-TOOLCHAIN_HOST_TASK'><filename>TOOLCHAIN_HOST_TASK</filename></link>:
1029 Lists packages that make up the host
1030 part of the SDK (i.e. the part that runs on
1031 the <filename>SDKMACHINE</filename>).
1032 When you use
1033 <filename>bitbake -c populate_sdk &lt;imagename&gt;</filename>
1034 to create the SDK, a set of default packages
1035 apply.
1036 This variable allows you to add more packages.
1037 </para></listitem>
1038 <listitem><para><link linkend='var-TOOLCHAIN_TARGET_TASK'><filename>TOOLCHAIN_TARGET_TASK</filename></link>:
1039 Lists packages that make up the target part
1040 of the SDK (i.e. the part built for the
1041 target hardware).
1042 </para></listitem>
1043 </itemizedlist>
1044 </para>
1045 </section>
1046
1047</chapter>
1048<!--
1049vim: expandtab tw=80 ts=4
1050-->
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-11-15 18:51:03 +0000