summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorScott Rifenbark <srifenbark@gmail.com>2018-02-02 10:11:58 -0800
committerRichard Purdie <richard.purdie@linuxfoundation.org>2018-02-14 15:25:31 +0000
commit813772451fe9045e78b94015950aa26380e46440 (patch)
tree9e2a888df23e4e2bb494c7cd65c87b159aa036f1
parentb509d336c757300b1fc9312f755b3bfd8707bf79 (diff)
downloadpoky-813772451fe9045e78b94015950aa26380e46440.tar.gz
documentation: Moved the detailed build section to concepts-manual.
The section that provides a closer look into the build system has moved from the getting-started manaul to the concepts-manual. I fixed all the links, provided some coded formatting of the entire section, and made general updates. The other manuals had links that needed fixed due to the move. (From yocto-docs rev: b83a5619f56ebd9879fdcadcf474859e68b26d58) Signed-off-by: Scott Rifenbark <srifenbark@gmail.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat
-rw-r--r--documentation/concepts-manual/concepts-manual-concepts.xml1796
-rw-r--r--documentation/dev-manual/dev-manual-common-tasks.xml8
-rw-r--r--documentation/dev-manual/dev-manual-start.xml4
-rw-r--r--documentation/getting-started/getting-started-development-environment.xml1650
-rw-r--r--documentation/ref-manual/ref-classes.xml8
-rw-r--r--documentation/ref-manual/ref-structure.xml10
-rw-r--r--documentation/ref-manual/ref-tasks.xml42
-rw-r--r--documentation/ref-manual/ref-variables.xml43
8 files changed, 1850 insertions, 1711 deletions
diff --git a/documentation/concepts-manual/concepts-manual-concepts.xml b/documentation/concepts-manual/concepts-manual-concepts.xml
index 010eda6191..e59ec6c4b8 100644
--- a/documentation/concepts-manual/concepts-manual-concepts.xml
+++ b/documentation/concepts-manual/concepts-manual-concepts.xml
@@ -52,8 +52,8 @@
52 Following are some brief details on these core components. 52 Following are some brief details on these core components.
53 For additional information on how these components interact during 53 For additional information on how these components interact during
54 a build, see the 54 a build, see the
55 "<ulink url='&YOCTO_DOCS_GS_URL;#development-concepts'>Development Concepts</ulink>" 55 "<link linkend='development-concepts'>Development Concepts</link>"
56 section in the Getting Started With Yocto Project Manual. 56 section.
57 </para> 57 </para>
58 58
59 <section id='usingpoky-components-bitbake'> 59 <section id='usingpoky-components-bitbake'>
@@ -248,6 +248,1798 @@
248 </section> 248 </section>
249 </section> 249 </section>
250 250
251
252
253 <section id="development-concepts">
254 <title>Development Concepts</title>
255
256 <para>
257 This section takes a more detailed look inside the development
258 process.
259 The following diagram represents development at a high level.
260 The remainder of this section expands on the fundamental input,
261 output, process, and
262 <ulink url='&YOCTO_DOCS_REF_URL;#metadata'>Metadata</ulink>) blocks
263 that make up development in the Yocto Project environment.
264 </para>
265
266 <para id='general-yocto-environment-figure'>
267 <imagedata fileref="figures/yocto-environment-ref.png" align="center" width="8in" depth="4.25in" />
268 </para>
269
270 <para>
271 In general, development consists of several functional areas:
272 <itemizedlist>
273 <listitem><para>
274 <emphasis>User Configuration:</emphasis>
275 Metadata you can use to control the build process.
276 </para></listitem>
277 <listitem><para>
278 <emphasis>Metadata Layers:</emphasis>
279 Various layers that provide software, machine, and
280 distro Metadata.
281 </para></listitem>
282 <listitem><para>
283 <emphasis>Source Files:</emphasis>
284 Upstream releases, local projects, and SCMs.
285 </para></listitem>
286 <listitem><para>
287 <emphasis>Build System:</emphasis>
288 Processes under the control of
289 <ulink url='&YOCTO_DOCS_REF_URL;#bitbake-term'>BitBake</ulink>.
290 This block expands on how BitBake fetches source, applies
291 patches, completes compilation, analyzes output for package
292 generation, creates and tests packages, generates images,
293 and generates cross-development tools.
294 </para></listitem>
295 <listitem><para>
296 <emphasis>Package Feeds:</emphasis>
297 Directories containing output packages (RPM, DEB or IPK),
298 which are subsequently used in the construction of an
299 image or SDK, produced by the build system.
300 These feeds can also be copied and shared using a web
301 server or other means to facilitate extending or updating
302 existing images on devices at runtime if runtime package
303 management is enabled.
304 </para></listitem>
305 <listitem><para>
306 <emphasis>Images:</emphasis>
307 Images produced by the development process.
308 </para></listitem>
309 <listitem><para>
310 <emphasis>Application Development SDK:</emphasis>
311 Cross-development tools that are produced along with
312 an image or separately with BitBake.
313 </para></listitem>
314 </itemizedlist>
315 </para>
316
317 <section id="user-configuration">
318 <title>User Configuration</title>
319
320 <para>
321 User configuration helps define the build.
322 Through user configuration, you can tell BitBake the
323 target architecture for which you are building the image,
324 where to store downloaded source, and other build properties.
325 </para>
326
327 <para>
328 The following figure shows an expanded representation of the
329 "User Configuration" box of the
330 <link linkend='general-yocto-environment-figure'>general Yocto Project Development Environment figure</link>:
331 </para>
332
333 <para>
334 <imagedata fileref="figures/user-configuration.png" align="center" width="8in" depth="4.5in" />
335 </para>
336
337 <para>
338 BitBake needs some basic configuration files in order to
339 complete a build.
340 These files are <filename>*.conf</filename> files.
341 The minimally necessary ones reside as example files in the
342 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>.
343 For simplicity, this section refers to the Source Directory as
344 the "Poky Directory."
345 </para>
346
347 <para>
348 When you clone the <filename>poky</filename> Git repository
349 or you download and unpack a Yocto Project release, you
350 can set up the Source Directory to be named anything you want.
351 For this discussion, the cloned repository uses the default
352 name <filename>poky</filename>.
353 <note>
354 The
355 <ulink url='&YOCTO_DOCS_REF_URL;#poky'>Poky</ulink>
356 repository is primarily an aggregation of existing
357 repositories.
358 It is not a canonical upstream source.
359 </note>
360 </para>
361
362 <para>
363 The <filename>meta-poky</filename> layer inside Poky contains
364 a <filename>conf</filename> directory that has example
365 configuration files.
366 These example files are used as a basis for creating actual
367 configuration files when you source the build environment
368 script
369 (i.e.
370 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>).
371 </para>
372
373 <para>
374 Sourcing the build environment script creates a
375 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
376 if one does not already exist.
377 BitBake uses the Build Directory for all its work during
378 builds.
379 The Build Directory has a <filename>conf</filename> directory
380 that contains default versions of your
381 <filename>local.conf</filename> and
382 <filename>bblayers.conf</filename> configuration files.
383 These default configuration files are created only if versions
384 do not already exist in the Build Directory at the time you
385 source the build environment setup script.
386 </para>
387
388 <para>
389 Because the Poky repository is fundamentally an aggregation of
390 existing repositories, some users might be familiar with
391 running the <filename>&OE_INIT_FILE;</filename> script
392 in the context of separate
393 <ulink url='&YOCTO_DOCS_REF_URL;#oe-core'>OpenEmbedded-Core</ulink>
394 and BitBake repositories rather than a single Poky repository.
395 This discussion assumes the script is executed from
396 within a cloned or unpacked version of Poky.
397 </para>
398
399 <para>
400 Depending on where the script is sourced, different
401 sub-scripts are called to set up the Build Directory
402 (Yocto or OpenEmbedded).
403 Specifically, the script
404 <filename>scripts/oe-setup-builddir</filename> inside the
405 poky directory sets up the Build Directory and seeds the
406 directory (if necessary) with configuration files appropriate
407 for the Yocto Project development environment.
408 <note>
409 The <filename>scripts/oe-setup-builddir</filename> script
410 uses the <filename>$TEMPLATECONF</filename> variable to
411 determine which sample configuration files to locate.
412 </note>
413 </para>
414
415 <para>
416 The <filename>local.conf</filename> file provides many
417 basic variables that define a build environment.
418 Here is a list of a few.
419 To see the default configurations in a
420 <filename>local.conf</filename> file created by the build
421 environment script, see the
422 <filename>local.conf.sample</filename> in the
423 <filename>meta-poky</filename> layer:
424 <itemizedlist>
425 <listitem><para>
426 <emphasis>Parallelism Options:</emphasis>
427 Controlled by the
428 <ulink url='&YOCTO_DOCS_REF_URL;#var-BB_NUMBER_THREADS'><filename>BB_NUMBER_THREADS</filename></ulink>,
429 <ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></ulink>,
430 and
431 <ulink url='&YOCTO_DOCS_BB_URL;#var-BB_NUMBER_PARSE_THREADS'><filename>BB_NUMBER_PARSE_THREADS</filename></ulink>
432 variables.
433 </para></listitem>
434 <listitem><para>
435 <emphasis>Target Machine Selection:</emphasis>
436 Controlled by the
437 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
438 variable.
439 </para></listitem>
440 <listitem><para>
441 <emphasis>Download Directory:</emphasis>
442 Controlled by the
443 <ulink url='&YOCTO_DOCS_REF_URL;#var-DL_DIR'><filename>DL_DIR</filename></ulink>
444 variable.
445 </para></listitem>
446 <listitem><para>
447 <emphasis>Shared State Directory:</emphasis>
448 Controlled by the
449 <ulink url='&YOCTO_DOCS_REF_URL;#var-SSTATE_DIR'><filename>SSTATE_DIR</filename></ulink>
450 variable.
451 </para></listitem>
452 <listitem><para>
453 <emphasis>Build Output:</emphasis>
454 Controlled by the
455 <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>
456 variable.
457 </para></listitem>
458 </itemizedlist>
459 <note>
460 Configurations set in the
461 <filename>conf/local.conf</filename> file can also be set
462 in the <filename>conf/site.conf</filename> and
463 <filename>conf/auto.conf</filename> configuration files.
464 </note>
465 </para>
466
467 <para>
468 The <filename>bblayers.conf</filename> file tells BitBake what
469 layers you want considered during the build.
470 By default, the layers listed in this file include layers
471 minimally needed by the build system.
472 However, you must manually add any custom layers you have
473 created.
474 You can find more information on working with the
475 <filename>bblayers.conf</filename> file in the
476 "<ulink url='&YOCTO_DOCS_DEV_URL;#enabling-your-layer'>Enabling Your Layer</ulink>"
477 section in the Yocto Project Development Tasks Manual.
478 </para>
479
480 <para>
481 The files <filename>site.conf</filename> and
482 <filename>auto.conf</filename> are not created by the
483 environment initialization script.
484 If you want the <filename>site.conf</filename> file, you
485 need to create that yourself.
486 The <filename>auto.conf</filename> file is typically created by
487 an autobuilder:
488 <itemizedlist>
489 <listitem><para>
490 <emphasis><filename>site.conf</filename>:</emphasis>
491 You can use the <filename>conf/site.conf</filename>
492 configuration file to configure multiple
493 build directories.
494 For example, suppose you had several build environments
495 and they shared some common features.
496 You can set these default build properties here.
497 A good example is perhaps the packaging format to use
498 through the
499 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></ulink>
500 variable.</para>
501
502 <para>One useful scenario for using the
503 <filename>conf/site.conf</filename> file is to extend
504 your
505 <ulink url='&YOCTO_DOCS_REF_URL;#var-BBPATH'><filename>BBPATH</filename></ulink>
506 variable to include the path to a
507 <filename>conf/site.conf</filename>.
508 Then, when BitBake looks for Metadata using
509 <filename>BBPATH</filename>, it finds the
510 <filename>conf/site.conf</filename> file and applies
511 your common configurations found in the file.
512 To override configurations in a particular build
513 directory, alter the similar configurations within
514 that build directory's
515 <filename>conf/local.conf</filename> file.
516 </para></listitem>
517 <listitem><para>
518 <emphasis><filename>auto.conf</filename>:</emphasis>
519 The file is usually created and written to by
520 an autobuilder.
521 The settings put into the file are typically the
522 same as you would find in the
523 <filename>conf/local.conf</filename> or the
524 <filename>conf/site.conf</filename> files.
525 </para></listitem>
526 </itemizedlist>
527 </para>
528
529 <para>
530 You can edit all configuration files to further define
531 any particular build environment.
532 This process is represented by the "User Configuration Edits"
533 box in the figure.
534 </para>
535
536 <para>
537 When you launch your build with the
538 <filename>bitbake <replaceable>target</replaceable></filename>
539 command, BitBake sorts out the configurations to ultimately
540 define your build environment.
541 It is important to understand that the
542 <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>OpenEmbedded build system</ulink>
543 reads the configuration files in a specific order:
544 <filename>site.conf</filename>, <filename>auto.conf</filename>,
545 and <filename>local.conf</filename>.
546 And, the build system applies the normal assignment statement
547 rules.
548 Because the files are parsed in a specific order, variable
549 assignments for the same variable could be affected.
550 For example, if the <filename>auto.conf</filename> file and
551 the <filename>local.conf</filename> set
552 <replaceable>variable1</replaceable> to different values,
553 because the build system parses <filename>local.conf</filename>
554 after <filename>auto.conf</filename>,
555 <replaceable>variable1</replaceable> is assigned the value from
556 the <filename>local.conf</filename> file.
557 </para>
558 </section>
559
560 <section id="metadata-machine-configuration-and-policy-configuration">
561 <title>Metadata, Machine Configuration, and Policy Configuration</title>
562
563 <para>
564 The previous section described the user configurations that
565 define BitBake's global behavior.
566 This section takes a closer look at the layers the build system
567 uses to further control the build.
568 These layers provide Metadata for the software, machine, and
569 policy.
570 </para>
571
572 <para>
573 In general, three types of layer input exist:
574 <itemizedlist>
575 <listitem><para>
576 <emphasis>Policy Configuration:</emphasis>
577 Distribution Layers provide top-level or general
578 policies for the image or SDK being built.
579 For example, this layer would dictate whether BitBake
580 produces RPM or IPK packages.
581 </para></listitem>
582 <listitem><para>
583 <emphasis>Machine Configuration:</emphasis>
584 Board Support Package (BSP) layers provide machine
585 configurations.
586 This type of information is specific to a particular
587 target architecture.
588 </para></listitem>
589 <listitem><para>
590 <emphasis>Metadata:</emphasis>
591 Software layers contain user-supplied recipe files,
592 patches, and append files.
593 </para></listitem>
594 </itemizedlist>
595 </para>
596
597 <para>
598 The following figure shows an expanded representation of the
599 Metadata, Machine Configuration, and Policy Configuration input
600 (layers) boxes of the
601 <link linkend='general-yocto-environment-figure'>general Yocto Project Development Environment figure</link>:
602 </para>
603
604 <para>
605 <imagedata fileref="figures/layer-input.png" align="center" width="8in" depth="7.5in" />
606 </para>
607
608 <para>
609 In general, all layers have a similar structure.
610 They all contain a licensing file
611 (e.g. <filename>COPYING</filename>) if the layer is to be
612 distributed, a <filename>README</filename> file as good
613 practice and especially if the layer is to be distributed, a
614 configuration directory, and recipe directories.
615 </para>
616
617 <para>
618 The Yocto Project has many layers that can be used.
619 You can see a web-interface listing of them on the
620 <ulink url="http://git.yoctoproject.org/">Source Repositories</ulink>
621 page.
622 The layers appear at the bottom categorized under
623 "Yocto Metadata Layers."
624 These layers are fundamentally a subset of the
625 <ulink url="http://layers.openembedded.org/layerindex/layers/">OpenEmbedded Metadata Index</ulink>,
626 which lists all layers provided by the OpenEmbedded community.
627 <note>
628 Layers exist in the Yocto Project Source Repositories that
629 cannot be found in the OpenEmbedded Metadata Index.
630 These layers are either deprecated or experimental
631 in nature.
632 </note>
633 </para>
634
635 <para>
636 BitBake uses the <filename>conf/bblayers.conf</filename> file,
637 which is part of the user configuration, to find what layers it
638 should be using as part of the build.
639 </para>
640
641 <para>
642 For more information on layers, see the
643 "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>"
644 section in the Yocto Project Development Tasks Manual.
645 </para>
646
647 <section id="distro-layer">
648 <title>Distro Layer</title>
649
650 <para>
651 The distribution layer provides policy configurations for
652 your distribution.
653 Best practices dictate that you isolate these types of
654 configurations into their own layer.
655 Settings you provide in
656 <filename>conf/distro/<replaceable>distro</replaceable>.conf</filename> override
657 similar settings that BitBake finds in your
658 <filename>conf/local.conf</filename> file in the Build
659 Directory.
660 </para>
661
662 <para>
663 The following list provides some explanation and references
664 for what you typically find in the distribution layer:
665 <itemizedlist>
666 <listitem><para>
667 <emphasis>classes:</emphasis>
668 Class files (<filename>.bbclass</filename>) hold
669 common functionality that can be shared among
670 recipes in the distribution.
671 When your recipes inherit a class, they take on the
672 settings and functions for that class.
673 You can read more about class files in the
674 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-classes'>Classes</ulink>"
675 chapter of the Yocto Reference Manual.
676 </para></listitem>
677 <listitem><para>
678 <emphasis>conf:</emphasis>
679 This area holds configuration files for the
680 layer (<filename>conf/layer.conf</filename>),
681 the distribution
682 (<filename>conf/distro/<replaceable>distro</replaceable>.conf</filename>),
683 and any distribution-wide include files.
684 </para></listitem>
685 <listitem><para>
686 <emphasis>recipes-*:</emphasis>
687 Recipes and append files that affect common
688 functionality across the distribution.
689 This area could include recipes and append files
690 to add distribution-specific configuration,
691 initialization scripts, custom image recipes,
692 and so forth.
693 </para></listitem>
694 </itemizedlist>
695 </para>
696 </section>
697
698 <section id="bsp-layer">
699 <title>BSP Layer</title>
700
701 <para>
702 The BSP Layer provides machine configurations.
703 Everything in this layer is specific to the machine for
704 which you are building the image or the SDK.
705 A common structure or form is defined for BSP layers.
706 You can learn more about this structure in the
707 <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink>.
708 <note>
709 In order for a BSP layer to be considered compliant
710 with the Yocto Project, it must meet some structural
711 requirements.
712 </note>
713 </para>
714
715 <para>
716 The BSP Layer's configuration directory contains
717 configuration files for the machine
718 (<filename>conf/machine/<replaceable>machine</replaceable>.conf</filename>)
719 and, of course, the layer
720 (<filename>conf/layer.conf</filename>).
721 </para>
722
723 <para>
724 The remainder of the layer is dedicated to specific recipes
725 by function: <filename>recipes-bsp</filename>,
726 <filename>recipes-core</filename>,
727 <filename>recipes-graphics</filename>, and
728 <filename>recipes-kernel</filename>.
729 Metadata can exist for multiple formfactors, graphics
730 support systems, and so forth.
731 <note>
732 While the figure shows several
733 <filename>recipes-*</filename> directories, not all
734 these directories appear in all BSP layers.
735 </note>
736 </para>
737 </section>
738
739 <section id="software-layer">
740 <title>Software Layer</title>
741
742 <para>
743 The software layer provides the Metadata for additional
744 software packages used during the build.
745 This layer does not include Metadata that is specific to
746 the distribution or the machine, which are found in their
747 respective layers.
748 </para>
749
750 <para>
751 This layer contains any new recipes that your project
752 needs in the form of recipe files.
753 </para>
754 </section>
755 </section>
756
757 <section id="sources-dev-environment">
758 <title>Sources</title>
759
760 <para>
761 In order for the OpenEmbedded build system to create an
762 image or any target, it must be able to access source files.
763 The
764 <link linkend='general-yocto-environment-figure'>general Yocto Project Development Environment figure</link>
765 represents source files using the "Upstream Project Releases",
766 "Local Projects", and "SCMs (optional)" boxes.
767 The figure represents mirrors, which also play a role in
768 locating source files, with the "Source Mirror(s)" box.
769 </para>
770
771 <para>
772 The method by which source files are ultimately organized is
773 a function of the project.
774 For example, for released software, projects tend to use
775 tarballs or other archived files that can capture the
776 state of a release guaranteeing that it is statically
777 represented.
778 On the other hand, for a project that is more dynamic or
779 experimental in nature, a project might keep source files in a
780 repository controlled by a Source Control Manager (SCM) such as
781 Git.
782 Pulling source from a repository allows you to control
783 the point in the repository (the revision) from which you
784 want to build software.
785 Finally, a combination of the two might exist, which would
786 give the consumer a choice when deciding where to get
787 source files.
788 </para>
789
790 <para>
791 BitBake uses the
792 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
793 variable to point to source files regardless of their location.
794 Each recipe must have a <filename>SRC_URI</filename> variable
795 that points to the source.
796 </para>
797
798 <para>
799 Another area that plays a significant role in where source
800 files come from is pointed to by the
801 <ulink url='&YOCTO_DOCS_REF_URL;#var-DL_DIR'><filename>DL_DIR</filename></ulink>
802 variable.
803 This area is a cache that can hold previously downloaded
804 source.
805 You can also instruct the OpenEmbedded build system to create
806 tarballs from Git repositories, which is not the default
807 behavior, and store them in the <filename>DL_DIR</filename>
808 by using the
809 <ulink url='&YOCTO_DOCS_REF_URL;#var-BB_GENERATE_MIRROR_TARBALLS'><filename>BB_GENERATE_MIRROR_TARBALLS</filename></ulink>
810 variable.
811 </para>
812
813 <para>
814 Judicious use of a <filename>DL_DIR</filename> directory can
815 save the build system a trip across the Internet when looking
816 for files.
817 A good method for using a download directory is to have
818 <filename>DL_DIR</filename> point to an area outside of your
819 Build Directory.
820 Doing so allows you to safely delete the Build Directory
821 if needed without fear of removing any downloaded source file.
822 </para>
823
824 <para>
825 The remainder of this section provides a deeper look into the
826 source files and the mirrors.
827 Here is a more detailed look at the source file area of the
828 base figure:
829 <imagedata fileref="figures/source-input.png" align="center" width="7in" depth="7.5in" />
830 </para>
831
832 <section id='upstream-project-releases'>
833 <title>Upstream Project Releases</title>
834
835 <para>
836 Upstream project releases exist anywhere in the form of an
837 archived file (e.g. tarball or zip file).
838 These files correspond to individual recipes.
839 For example, the figure uses specific releases each for
840 BusyBox, Qt, and Dbus.
841 An archive file can be for any released product that can be
842 built using a recipe.
843 </para>
844 </section>
845
846 <section id='local-projects'>
847 <title>Local Projects</title>
848
849 <para>
850 Local projects are custom bits of software the user
851 provides.
852 These bits reside somewhere local to a project - perhaps
853 a directory into which the user checks in items (e.g.
854 a local directory containing a development source tree
855 used by the group).
856 </para>
857
858 <para>
859 The canonical method through which to include a local
860 project is to use the
861 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-externalsrc'><filename>externalsrc</filename></ulink>
862 class to include that local project.
863 You use either the <filename>local.conf</filename> or a
864 recipe's append file to override or set the
865 recipe to point to the local directory on your disk to pull
866 in the whole source tree.
867 </para>
868
869 <para>
870 For information on how to use the
871 <filename>externalsrc</filename> class, see the
872 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-externalsrc'><filename>externalsrc.bbclass</filename></ulink>"
873 section.
874 </para>
875 </section>
876
877 <section id='scms'>
878 <title>Source Control Managers (Optional)</title>
879
880 <para>
881 Another place the build system can get source files from is
882 through an SCM such as Git or Subversion.
883 In this case, a repository is cloned or checked out.
884 The
885 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-fetch'><filename>do_fetch</filename></ulink>
886 task inside BitBake uses
887 the <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
888 variable and the argument's prefix to determine the correct
889 fetcher module.
890 <note>
891 For information on how to have the OpenEmbedded build
892 system generate tarballs for Git repositories and place
893 them in the
894 <ulink url='&YOCTO_DOCS_REF_URL;#var-DL_DIR'><filename>DL_DIR</filename></ulink>
895 directory, see the
896 <ulink url='&YOCTO_DOCS_REF_URL;#var-BB_GENERATE_MIRROR_TARBALLS'><filename>BB_GENERATE_MIRROR_TARBALLS</filename></ulink>
897 variable.
898 </note>
899 </para>
900
901 <para>
902 When fetching a repository, BitBake uses the
903 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCREV'><filename>SRCREV</filename></ulink>
904 variable to determine the specific revision from which to
905 build.
906 </para>
907 </section>
908
909 <section id='source-mirrors'>
910 <title>Source Mirror(s)</title>
911
912 <para>
913 Two kinds of mirrors exist: pre-mirrors and regular
914 mirrors.
915 The
916 <ulink url='&YOCTO_DOCS_REF_URL;#var-PREMIRRORS'><filename>PREMIRRORS</filename></ulink>
917 and
918 <ulink url='&YOCTO_DOCS_REF_URL;#var-MIRRORS'><filename>MIRRORS</filename></ulink>
919 variables point to these, respectively.
920 BitBake checks pre-mirrors before looking upstream for any
921 source files.
922 Pre-mirrors are appropriate when you have a shared
923 directory that is not a directory defined by the
924 <ulink url='&YOCTO_DOCS_REF_URL;#var-DL_DIR'><filename>DL_DIR</filename></ulink>
925 variable.
926 A Pre-mirror typically points to a shared directory that is
927 local to your organization.
928 </para>
929
930 <para>
931 Regular mirrors can be any site across the Internet
932 that is used as an alternative location for source
933 code should the primary site not be functioning for
934 some reason or another.
935 </para>
936 </section>
937 </section>
938
939 <section id="package-feeds-dev-environment">
940 <title>Package Feeds</title>
941
942 <para>
943 When the OpenEmbedded build system generates an image or an
944 SDK, it gets the packages from a package feed area located
945 in the
946 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>.
947 The
948 <link linkend='general-yocto-environment-figure'>general Yocto Project Development Environment figure</link>
949 shows this package feeds area in the upper-right corner.
950 </para>
951
952 <para>
953 This section looks a little closer into the package feeds
954 area used by the build system.
955 Here is a more detailed look at the area:
956 <imagedata fileref="figures/package-feeds.png" align="center" width="7in" depth="6in" />
957 </para>
958
959 <para>
960 Package feeds are an intermediary step in the build process.
961 The OpenEmbedded build system provides classes to generate
962 different package types, and you specify which classes to
963 enable through the
964 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></ulink>
965 variable.
966 Before placing the packages into package feeds,
967 the build process validates them with generated output quality
968 assurance checks through the
969 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-insane'><filename>insane</filename></ulink>
970 class.
971 </para>
972
973 <para>
974 The package feed area resides in the Build Directory.
975 The directory the build system uses to temporarily store
976 packages is determined by a combination of variables and the
977 particular package manager in use.
978 See the "Package Feeds" box in the illustration and note the
979 information to the right of that area.
980 In particular, the following defines where package files are
981 kept:
982 <itemizedlist>
983 <listitem><para>
984 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></ulink>:
985 Defined as <filename>tmp/deploy</filename> in the Build
986 Directory.
987 </para></listitem>
988 <listitem><para>
989 <filename>DEPLOY_DIR_*</filename>:
990 Depending on the package manager used, the package type
991 sub-folder.
992 Given RPM, IPK, or DEB packaging and tarball creation,
993 the
994 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPLOY_DIR_RPM'><filename>DEPLOY_DIR_RPM</filename></ulink>,
995 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPLOY_DIR_IPK'><filename>DEPLOY_DIR_IPK</filename></ulink>,
996 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPLOY_DIR_DEB'><filename>DEPLOY_DIR_DEB</filename></ulink>,
997 or
998 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPLOY_DIR_TAR'><filename>DEPLOY_DIR_TAR</filename></ulink>,
999 variables are used, respectively.
1000 </para></listitem>
1001 <listitem><para>
1002 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></ulink>:
1003 Defines architecture-specific sub-folders.
1004 For example, packages could exist for the i586 or
1005 qemux86 architectures.
1006 </para></listitem>
1007 </itemizedlist>
1008 </para>
1009
1010 <para>
1011 BitBake uses the
1012 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package_write_deb'><filename>do_package_write_*</filename></ulink>
1013 tasks to generate packages and place them into the package
1014 holding area (e.g. <filename>do_package_write_ipk</filename>
1015 for IPK packages).
1016 See the
1017 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package_write_deb'><filename>do_package_write_deb</filename></ulink>",
1018 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package_write_ipk'><filename>do_package_write_ipk</filename></ulink>",
1019 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package_write_rpm'><filename>do_package_write_rpm</filename></ulink>",
1020 and
1021 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package_write_tar'><filename>do_package_write_tar</filename></ulink>"
1022 sections in the Yocto Project Reference Manual
1023 for additional information.
1024 As an example, consider a scenario where an IPK packaging
1025 manager is being used and package architecture support for
1026 both i586 and qemux86 exist.
1027 Packages for the i586 architecture are placed in
1028 <filename>build/tmp/deploy/ipk/i586</filename>, while packages
1029 for the qemux86 architecture are placed in
1030 <filename>build/tmp/deploy/ipk/qemux86</filename>.
1031 </para>
1032 </section>
1033
1034 <section id='bitbake-dev-environment'>
1035 <title>BitBake</title>
1036
1037 <para>
1038 The OpenEmbedded build system uses
1039 <ulink url='&YOCTO_DOCS_REF_URL;#bitbake-term'>BitBake</ulink>
1040 to produce images.
1041 You can see from the
1042 <link linkend='general-yocto-environment-figure'>general Yocto Project Development Environment figure</link>,
1043 the BitBake area consists of several functional areas.
1044 This section takes a closer look at each of those areas.
1045 </para>
1046
1047 <para>
1048 Separate documentation exists for the BitBake tool.
1049 See the
1050 <ulink url='&YOCTO_DOCS_BB_URL;#bitbake-user-manual'>BitBake User Manual</ulink>
1051 for reference material on BitBake.
1052 </para>
1053
1054 <section id='source-fetching-dev-environment'>
1055 <title>Source Fetching</title>
1056
1057 <para>
1058 The first stages of building a recipe are to fetch and
1059 unpack the source code:
1060 <imagedata fileref="figures/source-fetching.png" align="center" width="6.5in" depth="5in" />
1061 </para>
1062
1063 <para>
1064 The
1065 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-fetch'><filename>do_fetch</filename></ulink>
1066 and
1067 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-unpack'><filename>do_unpack</filename></ulink>
1068 tasks fetch the source files and unpack them into the work
1069 directory.
1070 <note>
1071 For every local file (e.g. <filename>file://</filename>)
1072 that is part of a recipe's
1073 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
1074 statement, the OpenEmbedded build system takes a
1075 checksum of the file for the recipe and inserts the
1076 checksum into the signature for the
1077 <filename>do_fetch</filename>.
1078 If any local file has been modified, the
1079 <filename>do_fetch</filename> task and all tasks that
1080 depend on it are re-executed.
1081 </note>
1082 By default, everything is accomplished in the
1083 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>,
1084 which has a defined structure.
1085 For additional general information on the Build Directory,
1086 see the
1087 "<ulink url='&YOCTO_DOCS_REF_URL;#structure-core-build'><filename>build/</filename></ulink>"
1088 section in the Yocto Project Reference Manual.
1089 </para>
1090
1091 <para>
1092 Unpacked source files are pointed to by the
1093 <ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink>
1094 variable.
1095 Each recipe has an area in the Build Directory where the
1096 unpacked source code resides.
1097 The name of that directory for any given recipe is defined
1098 from several different variables.
1099 You can see the variables that define these directories
1100 by looking at the figure:
1101 <itemizedlist>
1102 <listitem><para>
1103 <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>:
1104 The base directory where the OpenEmbedded build
1105 system performs all its work during the build.
1106 </para></listitem>
1107 <listitem><para>
1108 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></ulink>:
1109 The architecture of the built package or packages.
1110 </para></listitem>
1111 <listitem><para>
1112 <ulink url='&YOCTO_DOCS_REF_URL;#var-TARGET_OS'><filename>TARGET_OS</filename></ulink>:
1113 The operating system of the target device.
1114 </para></listitem>
1115 <listitem><para>
1116 <ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink>:
1117 The name of the built package.
1118 </para></listitem>
1119 <listitem><para>
1120 <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>:
1121 The version of the recipe used to build the
1122 package.
1123 </para></listitem>
1124 <listitem><para>
1125 <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>:
1126 The revision of the recipe used to build the
1127 package.
1128 </para></listitem>
1129 <listitem><para>
1130 <ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink>:
1131 The location within <filename>TMPDIR</filename>
1132 where a specific package is built.
1133 </para></listitem>
1134 <listitem><para>
1135 <ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink>:
1136 Contains the unpacked source files for a given
1137 recipe.
1138 </para></listitem>
1139 </itemizedlist>
1140 </para>
1141 </section>
1142
1143 <section id='patching-dev-environment'>
1144 <title>Patching</title>
1145
1146 <para>
1147 Once source code is fetched and unpacked, BitBake locates
1148 patch files and applies them to the source files:
1149 <imagedata fileref="figures/patching.png" align="center" width="6in" depth="5in" />
1150 </para>
1151
1152 <para>
1153 The
1154 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-patch'><filename>do_patch</filename></ulink>
1155 task processes recipes by using the
1156 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
1157 variable to locate applicable patch files, which by default
1158 are <filename>*.patch</filename> or
1159 <filename>*.diff</filename> files, or any file if
1160 "apply=yes" is specified for the file in
1161 <filename>SRC_URI</filename>.
1162 </para>
1163
1164 <para>
1165 BitBake finds and applies multiple patches for a single
1166 recipe in the order in which it finds the patches.
1167 Patches are applied to the recipe's source files located
1168 in the
1169 <ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink>
1170 directory.
1171 </para>
1172
1173 <para>
1174 For more information on how the source directories are
1175 created, see the
1176 "<link linkend='source-fetching-dev-environment'>Source Fetching</link>"
1177 section.
1178 </para>
1179 </section>
1180
1181 <section id='configuration-and-compilation-dev-environment'>
1182 <title>Configuration and Compilation</title>
1183
1184 <para>
1185 After source code is patched, BitBake executes tasks that
1186 configure and compile the source code:
1187 <imagedata fileref="figures/configuration-compile-autoreconf.png" align="center" width="7in" depth="5in" />
1188 </para>
1189
1190 <para>
1191 This step in the build process consists of three tasks:
1192 <itemizedlist>
1193 <listitem><para>
1194 <emphasis><ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-prepare_recipe_sysroot'><filename>do_prepare_recipe_sysroot</filename></ulink></emphasis>:
1195 This task sets up the two sysroots in
1196 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}</filename>
1197 (i.e. <filename>recipe-sysroot</filename> and
1198 <filename>recipe-sysroot-native</filename>) so that
1199 the sysroots contain the contents of the
1200 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></ulink>
1201 tasks of the recipes on which the recipe
1202 containing the tasks depends.
1203 A sysroot exists for both the target and for the
1204 native binaries, which run on the host system.
1205 </para></listitem>
1206 <listitem><para>
1207 <emphasis><filename>do_configure</filename></emphasis>:
1208 This task configures the source by enabling and
1209 disabling any build-time and configuration options
1210 for the software being built.
1211 Configurations can come from the recipe itself as
1212 well as from an inherited class.
1213 Additionally, the software itself might configure
1214 itself depending on the target for which it is
1215 being built.</para>
1216
1217 <para>The configurations handled by the
1218 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-configure'><filename>do_configure</filename></ulink>
1219 task are specific to source code configuration for
1220 the source code being built by the recipe.</para>
1221
1222 <para>If you are using the
1223 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-autotools'><filename>autotools</filename></ulink>
1224 class, you can add additional configuration options
1225 by using the
1226 <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></ulink>
1227 or
1228 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGECONFIG_CONFARGS'><filename>PACKAGECONFIG_CONFARGS</filename></ulink>
1229 variables.
1230 For information on how this variable works within
1231 that class, see the
1232 <filename>meta/classes/autotools.bbclass</filename>
1233 file.
1234 </para></listitem>
1235 <listitem><para>
1236 <emphasis><filename>do_compile</filename></emphasis>:
1237 Once a configuration task has been satisfied, BitBake
1238 compiles the source using the
1239 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-compile'><filename>do_compile</filename></ulink>
1240 task.
1241 Compilation occurs in the directory pointed to by
1242 the
1243 <ulink url='&YOCTO_DOCS_REF_URL;#var-B'><filename>B</filename></ulink>
1244 variable.
1245 Realize that the <filename>B</filename> directory
1246 is, by default, the same as the
1247 <ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink>
1248 directory.
1249 </para></listitem>
1250 <listitem><para>
1251 <emphasis><filename>do_install</filename></emphasis>:
1252 Once compilation is done, BitBake executes the
1253 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-install'><filename>do_install</filename></ulink>
1254 task.
1255 This task copies files from the
1256 <filename>B</filename> directory and places them
1257 in a holding area pointed to by the
1258 <ulink url='&YOCTO_DOCS_REF_URL;#var-D'><filename>D</filename></ulink>
1259 variable.
1260 </para></listitem>
1261 </itemizedlist>
1262 </para>
1263 </section>
1264
1265 <section id='package-splitting-dev-environment'>
1266 <title>Package Splitting</title>
1267
1268 <para>
1269 After source code is configured and compiled, the
1270 OpenEmbedded build system analyzes
1271 the results and splits the output into packages:
1272 <imagedata fileref="figures/analysis-for-package-splitting.png" align="center" width="7in" depth="7in" />
1273 </para>
1274
1275 <para>
1276 The
1277 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package'><filename>do_package</filename></ulink>
1278 and
1279 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-packagedata'><filename>do_packagedata</filename></ulink>
1280 tasks combine to analyze the files found in the
1281 <ulink url='&YOCTO_DOCS_REF_URL;#var-D'><filename>D</filename></ulink>
1282 directory and split them into subsets based on available
1283 packages and files.
1284 The analyzing process involves the following as well as
1285 other items: splitting out debugging symbols, looking at
1286 shared library dependencies between packages, and looking
1287 at package relationships.
1288 The <filename>do_packagedata</filename> task creates
1289 package metadata based on the analysis such that the
1290 OpenEmbedded build system can generate the final packages.
1291 Working, staged, and intermediate results of the analysis
1292 and package splitting process use these areas:
1293 <itemizedlist>
1294 <listitem><para>
1295 <ulink url='&YOCTO_DOCS_REF_URL;#var-PKGD'><filename>PKGD</filename></ulink>:
1296 The destination directory for packages before they
1297 are split.
1298 </para></listitem>
1299 <listitem><para>
1300 <ulink url='&YOCTO_DOCS_REF_URL;#var-PKGDATA_DIR'><filename>PKGDATA_DIR</filename></ulink>:
1301 A shared, global-state directory that holds data
1302 generated during the packaging process.
1303 </para></listitem>
1304 <listitem><para>
1305 <ulink url='&YOCTO_DOCS_REF_URL;#var-PKGDESTWORK'><filename>PKGDESTWORK</filename></ulink>:
1306 A temporary work area used by the
1307 <filename>do_package</filename> task.
1308 </para></listitem>
1309 <listitem><para>
1310 <ulink url='&YOCTO_DOCS_REF_URL;#var-PKGDEST'><filename>PKGDEST</filename></ulink>:
1311 The parent directory for packages after they have
1312 been split.
1313 </para></listitem>
1314 </itemizedlist>
1315 The
1316 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILES'><filename>FILES</filename></ulink>
1317 variable defines the files that go into each package in
1318 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'><filename>PACKAGES</filename></ulink>.
1319 If you want details on how this is accomplished, you can
1320 look at the
1321 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-package'><filename>package</filename></ulink>
1322 class.
1323 </para>
1324
1325 <para>
1326 Depending on the type of packages being created (RPM, DEB,
1327 or IPK), the
1328 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package_write_deb'><filename>do_package_write_*</filename></ulink>
1329 task creates the actual packages and places them in the
1330 Package Feed area, which is
1331 <filename>${TMPDIR}/deploy</filename>.
1332 You can see the
1333 "<link linkend='package-feeds-dev-environment'>Package Feeds</link>"
1334 section for more detail on that part of the build process.
1335 <note>
1336 Support for creating feeds directly from the
1337 <filename>deploy/*</filename> directories does not
1338 exist.
1339 Creating such feeds usually requires some kind of feed
1340 maintenance mechanism that would upload the new
1341 packages into an official package feed (e.g. the
1342 Ångström distribution).
1343 This functionality is highly distribution-specific
1344 and thus is not provided out of the box.
1345 </note>
1346 </para>
1347 </section>
1348
1349 <section id='image-generation-dev-environment'>
1350 <title>Image Generation</title>
1351
1352 <para>
1353 Once packages are split and stored in the Package Feeds
1354 area, the OpenEmbedded build system uses BitBake to
1355 generate the root filesystem image:
1356 <imagedata fileref="figures/image-generation.png" align="center" width="6in" depth="7in" />
1357 </para>
1358
1359 <para>
1360 The image generation process consists of several stages and
1361 depends on several tasks and variables.
1362 The
1363 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-rootfs'><filename>do_rootfs</filename></ulink>
1364 task creates the root filesystem (file and directory
1365 structure) for an image.
1366 This task uses several key variables to help create the
1367 list of packages to actually install:
1368 <itemizedlist>
1369 <listitem><para>
1370 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></ulink>:
1371 Lists out the base set of packages to install from
1372 the Package Feeds area.
1373 </para></listitem>
1374 <listitem><para>
1375 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_EXCLUDE'><filename>PACKAGE_EXCLUDE</filename></ulink>:
1376 Specifies packages that should not be installed.
1377 </para></listitem>
1378 <listitem><para>
1379 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></ulink>:
1380 Specifies features to include in the image.
1381 Most of these features map to additional packages
1382 for installation.
1383 </para></listitem>
1384 <listitem><para>
1385 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></ulink>:
1386 Specifies the package backend to use and
1387 consequently helps determine where to locate
1388 packages within the Package Feeds area.
1389 </para></listitem>
1390 <listitem><para>
1391 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_LINGUAS'><filename>IMAGE_LINGUAS</filename></ulink>:
1392 Determines the language(s) for which additional
1393 language support packages are installed.
1394 </para></listitem>
1395 <listitem><para>
1396 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_INSTALL'><filename>PACKAGE_INSTALL</filename></ulink>:
1397 The final list of packages passed to the package manager
1398 for installation into the image.
1399 </para></listitem>
1400 </itemizedlist>
1401 </para>
1402
1403 <para>
1404 With
1405 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_ROOTFS'><filename>IMAGE_ROOTFS</filename></ulink>
1406 pointing to the location of the filesystem under
1407 construction and the <filename>PACKAGE_INSTALL</filename>
1408 variable providing the final list of packages to install,
1409 the root file system is created.
1410 </para>
1411
1412 <para>
1413 Package installation is under control of the package
1414 manager (e.g. dnf/rpm, opkg, or apt/dpkg) regardless of
1415 whether or not package management is enabled for the
1416 target.
1417 At the end of the process, if package management is not
1418 enabled for the target, the package manager's data files
1419 are deleted from the root filesystem.
1420 As part of the final stage of package installation,
1421 postinstall scripts that are part of the packages are run.
1422 Any scripts that fail to run
1423 on the build host are run on the target when the target
1424 system is first booted.
1425 If you are using a
1426 <ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-read-only-root-filesystem'>read-only root filesystem</ulink>,
1427 all the post installation scripts must succeed during the
1428 package installation phase since the root filesystem is
1429 read-only.
1430 </para>
1431
1432 <para>
1433 The final stages of the <filename>do_rootfs</filename> task
1434 handle post processing.
1435 Post processing includes creation of a manifest file and
1436 optimizations.
1437 </para>
1438
1439 <para>
1440 The manifest file (<filename>.manifest</filename>) resides
1441 in the same directory as the root filesystem image.
1442 This file lists out, line-by-line, the installed packages.
1443 The manifest file is useful for the
1444 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-testimage*'><filename>testimage</filename></ulink>
1445 class, for example, to determine whether or not to run
1446 specific tests.
1447 See the
1448 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_MANIFEST'><filename>IMAGE_MANIFEST</filename></ulink>
1449 variable for additional information.
1450 </para>
1451
1452 <para>
1453 Optimizing processes run across the image include
1454 <filename>mklibs</filename>, <filename>prelink</filename>,
1455 and any other post-processing commands as defined by the
1456 <ulink url='&YOCTO_DOCS_REF_URL;#var-ROOTFS_POSTPROCESS_COMMAND'><filename>ROOTFS_POSTPROCESS_COMMAND</filename></ulink>
1457 variable.
1458 The <filename>mklibs</filename> process optimizes the size
1459 of the libraries, while the <filename>prelink</filename>
1460 process optimizes the dynamic linking of shared libraries
1461 to reduce start up time of executables.
1462 </para>
1463
1464 <para>
1465 After the root filesystem is built, processing begins on
1466 the image through the
1467 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-image'><filename>do_image</filename></ulink>
1468 task.
1469 The build system runs any pre-processing commands as
1470 defined by the
1471 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_PREPROCESS_COMMAND'><filename>IMAGE_PREPROCESS_COMMAND</filename></ulink>
1472 variable.
1473 This variable specifies a list of functions to call before
1474 the OpenEmbedded build system creates the final image
1475 output files.
1476 </para>
1477
1478 <para>
1479 The OpenEmbedded build system dynamically creates
1480 <filename>do_image_*</filename> tasks as needed, based
1481 on the image types specified in the
1482 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></ulink>
1483 variable.
1484 The process turns everything into an image file or a set of
1485 image files and compresses the root filesystem image to
1486 reduce the overall size of the image.
1487 The formats used for the root filesystem depend on the
1488 <filename>IMAGE_FSTYPES</filename> variable.
1489 </para>
1490
1491 <para>
1492 As an example, a dynamically created task when creating a
1493 particular image <replaceable>type</replaceable> would
1494 take the following form:
1495 <literallayout class='monospaced'>
1496 do_image_<replaceable>type</replaceable>[depends]
1497 </literallayout>
1498 So, if the <replaceable>type</replaceable> as specified by
1499 the <filename>IMAGE_FSTYPES</filename> were
1500 <filename>ext4</filename>, the dynamically generated task
1501 would be as follows:
1502 <literallayout class='monospaced'>
1503 do_image_ext4[depends]
1504 </literallayout>
1505 </para>
1506
1507 <para>
1508 The final task involved in image creation is the
1509 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-image-complete'><filename>do_image_complete</filename></ulink>
1510 task.
1511 This task completes the image by applying any image
1512 post processing as defined through the
1513 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_POSTPROCESS_COMMAND'><filename>IMAGE_POSTPROCESS_COMMAND</filename></ulink>
1514 variable.
1515 The variable specifies a list of functions to call once the
1516 OpenEmbedded build system has created the final image
1517 output files.
1518 <note>
1519 The entire image generation process is run under
1520 Pseudo.
1521 Running under Pseudo ensures that the files in the
1522 root filesystem have correct ownership.
1523 </note>
1524 </para>
1525 </section>
1526
1527 <section id='sdk-generation-dev-environment'>
1528 <title>SDK Generation</title>
1529
1530 <para>
1531 The OpenEmbedded build system uses BitBake to generate the
1532 Software Development Kit (SDK) installer script for both
1533 the standard and extensible SDKs:
1534 <imagedata fileref="figures/sdk-generation.png" align="center" />
1535 <note>
1536 For more information on the cross-development toolchain
1537 generation, see the
1538 "<link linkend='cross-development-toolchain-generation'>Cross-Development Toolchain Generation</link>"
1539 section.
1540 For information on advantages gained when building a
1541 cross-development toolchain using the
1542 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-populate_sdk'><filename>do_populate_sdk</filename></ulink>
1543 task, see the
1544 "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-building-an-sdk-installer'>Building an SDK Installer</ulink>"
1545 section in the Yocto Project Application Development
1546 and the Extensible Software Development Kit (SDK)
1547 manual.
1548 </note>
1549 </para>
1550
1551 <para>
1552 Like image generation, the SDK script process consists of
1553 several stages and depends on many variables.
1554 The <filename>do_populate_sdk</filename> and
1555 <filename>do_populate_sdk_ext</filename> tasks use these
1556 key variables to help create the list of packages to
1557 actually install.
1558 For information on the variables listed in the figure,
1559 see the
1560 "<link linkend='sdk-dev-environment'>Application Development SDK</link>"
1561 section.
1562 </para>
1563
1564 <para>
1565 The <filename>do_populate_sdk</filename> task helps create
1566 the standard SDK and handles two parts: a target part and a
1567 host part.
1568 The target part is the part built for the target hardware
1569 and includes libraries and headers.
1570 The host part is the part of the SDK that runs on the
1571 <ulink url='&YOCTO_DOCS_REF_URL;#var-SDKMACHINE'><filename>SDKMACHINE</filename></ulink>.
1572 </para>
1573
1574 <para>
1575 The <filename>do_populate_sdk_ext</filename> task helps
1576 create the extensible SDK and handles host and target parts
1577 differently than its counter part does for the standard SDK.
1578 For the extensible SDK, the task encapsulates the build
1579 system, which includes everything needed (host and target)
1580 for the SDK.
1581 </para>
1582
1583 <para>
1584 Regardless of the type of SDK being constructed, the
1585 tasks perform some cleanup after which a cross-development
1586 environment setup script and any needed configuration files
1587 are created.
1588 The final output is the Cross-development
1589 toolchain installation script (<filename>.sh</filename>
1590 file), which includes the environment setup script.
1591 </para>
1592 </section>
1593
1594 <section id='stamp-files-and-the-rerunning-of-tasks'>
1595 <title>Stamp Files and the Rerunning of Tasks</title>
1596
1597 <para>
1598 For each task that completes successfully, BitBake writes a
1599 stamp file into the
1600 <ulink url='&YOCTO_DOCS_REF_URL;#var-STAMPS_DIR'><filename>STAMPS_DIR</filename></ulink>
1601 directory.
1602 The beginning of the stamp file's filename is determined
1603 by the
1604 <ulink url='&YOCTO_DOCS_REF_URL;#var-STAMP'><filename>STAMP</filename></ulink>
1605 variable, and the end of the name consists of the task's
1606 name and current
1607 <ulink url='&YOCTO_DOCS_CM_URL;#overview-checksums'>input checksum</ulink>.
1608 <note>
1609 This naming scheme assumes that
1610 <ulink url='&YOCTO_DOCS_BB_URL;#var-BB_SIGNATURE_HANDLER'><filename>BB_SIGNATURE_HANDLER</filename></ulink>
1611 is "OEBasicHash", which is almost always the case in
1612 current OpenEmbedded.
1613 </note>
1614 To determine if a task needs to be rerun, BitBake checks
1615 if a stamp file with a matching input checksum exists
1616 for the task.
1617 If such a stamp file exists, the task's output is
1618 assumed to exist and still be valid.
1619 If the file does not exist, the task is rerun.
1620 <note>
1621 <para>The stamp mechanism is more general than the
1622 shared state (sstate) cache mechanism described in the
1623 "<link linkend='setscene-tasks-and-shared-state'>Setscene Tasks and Shared State</link>"
1624 section.
1625 BitBake avoids rerunning any task that has a valid
1626 stamp file, not just tasks that can be accelerated
1627 through the sstate cache.</para>
1628
1629 <para>However, you should realize that stamp files only
1630 serve as a marker that some work has been done and that
1631 these files do not record task output.
1632 The actual task output would usually be somewhere in
1633 <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>
1634 (e.g. in some recipe's
1635 <ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink>.)
1636 What the sstate cache mechanism adds is a way to cache
1637 task output that can then be shared between build
1638 machines.</para>
1639 </note>
1640 Since <filename>STAMPS_DIR</filename> is usually a
1641 subdirectory of <filename>TMPDIR</filename>, removing
1642 <filename>TMPDIR</filename> will also remove
1643 <filename>STAMPS_DIR</filename>, which means tasks will
1644 properly be rerun to repopulate
1645 <filename>TMPDIR</filename>.
1646 </para>
1647
1648 <para>
1649 If you want some task to always be considered "out of
1650 date", you can mark it with the
1651 <ulink url='&YOCTO_DOCS_BB_URL;#variable-flags'><filename>nostamp</filename></ulink>
1652 varflag.
1653 If some other task depends on such a task, then that
1654 task will also always be considered out of date, which
1655 might not be what you want.
1656 </para>
1657
1658 <para>
1659 For details on how to view information about a task's
1660 signature, see the
1661 "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-viewing-task-variable-dependencies'>Viewing Task Variable Dependencies</ulink>"
1662 section in the Yocto Project Development Tasks Manual.
1663 </para>
1664 </section>
1665
1666 <section id='setscene-tasks-and-shared-state'>
1667 <title>Setscene Tasks and Shared State</title>
1668
1669 <para>
1670 The description of tasks so far assumes that BitBake needs
1671 to build everything and there are no prebuilt objects
1672 available.
1673 BitBake does support skipping tasks if prebuilt objects are
1674 available.
1675 These objects are usually made available in the form of a
1676 shared state (sstate) cache.
1677 <note>
1678 For information on variables affecting sstate, see the
1679 <ulink url='&YOCTO_DOCS_REF_URL;#var-SSTATE_DIR'><filename>SSTATE_DIR</filename></ulink>
1680 and
1681 <ulink url='&YOCTO_DOCS_REF_URL;#var-SSTATE_MIRRORS'><filename>SSTATE_MIRRORS</filename></ulink>
1682 variables.
1683 </note>
1684 </para>
1685
1686 <para>
1687 The idea of a setscene task (i.e
1688 <filename>do_</filename><replaceable>taskname</replaceable><filename>_setscene</filename>)
1689 is a version of the task where
1690 instead of building something, BitBake can skip to the end
1691 result and simply place a set of files into specific
1692 locations as needed.
1693 In some cases, it makes sense to have a setscene task
1694 variant (e.g. generating package files in the
1695 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package_write_deb'><filename>do_package_write_*</filename></ulink>
1696 task).
1697 In other cases, it does not make sense, (e.g. a
1698 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-patch'><filename>do_patch</filename></ulink>
1699 task or
1700 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-unpack'><filename>do_unpack</filename></ulink>
1701 task) since the work involved would be equal to or greater
1702 than the underlying task.
1703 </para>
1704
1705 <para>
1706 In the OpenEmbedded build system, the common tasks that
1707 have setscene variants are
1708 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package'><filename>do_package</filename></ulink>,
1709 <filename>do_package_write_*</filename>,
1710 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-deploy'><filename>do_deploy</filename></ulink>,
1711 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-packagedata'><filename>do_packagedata</filename></ulink>,
1712 and
1713 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></ulink>.
1714 Notice that these are most of the tasks whose output is an
1715 end result.
1716 </para>
1717
1718 <para>
1719 The OpenEmbedded build system has knowledge of the
1720 relationship between these tasks and other tasks that
1721 precede them.
1722 For example, if BitBake runs
1723 <filename>do_populate_sysroot_setscene</filename> for
1724 something, there is little point in running any of the
1725 <filename>do_fetch</filename>,
1726 <filename>do_unpack</filename>,
1727 <filename>do_patch</filename>,
1728 <filename>do_configure</filename>,
1729 <filename>do_compile</filename>, and
1730 <filename>do_install</filename> tasks.
1731 However, if <filename>do_package</filename> needs to be
1732 run, BitBake would need to run those other tasks.
1733 </para>
1734
1735 <para>
1736 It becomes more complicated if everything can come
1737 from an sstate cache because some objects are simply
1738 not required at all.
1739 For example, you do not need a compiler or native tools,
1740 such as quilt, if there is nothing to compile or patch.
1741 If the <filename>do_package_write_*</filename> packages
1742 are available from sstate, BitBake does not need the
1743 <filename>do_package</filename> task data.
1744 </para>
1745
1746 <para>
1747 To handle all these complexities, BitBake runs in two
1748 phases.
1749 The first is the "setscene" stage.
1750 During this stage, BitBake first checks the sstate cache
1751 for any targets it is planning to build.
1752 BitBake does a fast check to see if the object exists
1753 rather than a complete download.
1754 If nothing exists, the second phase, which is the setscene
1755 stage, completes and the main build proceeds.
1756 </para>
1757
1758 <para>
1759 If objects are found in the sstate cache, the OpenEmbedded
1760 build system works backwards from the end targets specified
1761 by the user.
1762 For example, if an image is being built, the OpenEmbedded
1763 build system first looks for the packages needed for
1764 that image and the tools needed to construct an image.
1765 If those are available, the compiler is not needed.
1766 Thus, the compiler is not even downloaded.
1767 If something was found to be unavailable, or the
1768 download or setscene task fails, the OpenEmbedded build
1769 system then tries to install dependencies, such as the
1770 compiler, from the cache.
1771 </para>
1772
1773 <para>
1774 The availability of objects in the sstate cache is
1775 handled by the function specified by the
1776 <ulink url='&YOCTO_DOCS_BB_URL;#var-BB_HASHCHECK_FUNCTION'><filename>BB_HASHCHECK_FUNCTION</filename></ulink>
1777 variable and returns a list of the objects that are
1778 available.
1779 The function specified by the
1780 <ulink url='&YOCTO_DOCS_BB_URL;#var-BB_SETSCENE_DEPVALID'><filename>BB_SETSCENE_DEPVALID</filename></ulink>
1781 variable is the function that determines whether a given
1782 dependency needs to be followed, and whether for any given
1783 relationship the function needs to be passed.
1784 The function returns a True or False value.
1785 </para>
1786 </section>
1787 </section>
1788
1789 <section id='images-dev-environment'>
1790 <title>Images</title>
1791
1792 <para>
1793 The images produced by the OpenEmbedded build system
1794 are compressed forms of the
1795 root filesystem that are ready to boot on a target device.
1796 You can see from the
1797 <link linkend='general-yocto-environment-figure'>general Yocto Project Development Environment figure</link>
1798 that BitBake output, in part, consists of images.
1799 This section is going to look more closely at this output:
1800 <imagedata fileref="figures/images.png" align="center" width="5.5in" depth="5.5in" />
1801 </para>
1802
1803 <para>
1804 For a list of example images that the Yocto Project provides,
1805 see the
1806 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>"
1807 chapter in the Yocto Project Reference Manual.
1808 </para>
1809
1810 <para>
1811 Images are written out to the
1812 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
1813 inside the
1814 <filename>tmp/deploy/images/<replaceable>machine</replaceable>/</filename>
1815 folder as shown in the figure.
1816 This folder contains any files expected to be loaded on the
1817 target device.
1818 The
1819 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></ulink>
1820 variable points to the <filename>deploy</filename> directory,
1821 while the
1822 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPLOY_DIR_IMAGE'><filename>DEPLOY_DIR_IMAGE</filename></ulink>
1823 variable points to the appropriate directory containing images
1824 for the current configuration.
1825 <itemizedlist>
1826 <listitem><para>
1827 <filename><replaceable>kernel-image</replaceable></filename>:
1828 A kernel binary file.
1829 The
1830 <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_IMAGETYPE'><filename>KERNEL_IMAGETYPE</filename></ulink>
1831 variable setting determines the naming scheme for the
1832 kernel image file.
1833 Depending on that variable, the file could begin with
1834 a variety of naming strings.
1835 The
1836 <filename>deploy/images/<replaceable>machine</replaceable></filename>
1837 directory can contain multiple image files for the
1838 machine.
1839 </para></listitem>
1840 <listitem><para>
1841 <filename><replaceable>root-filesystem-image</replaceable></filename>:
1842 Root filesystems for the target device (e.g.
1843 <filename>*.ext3</filename> or
1844 <filename>*.bz2</filename> files).
1845 The
1846 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></ulink>
1847 variable setting determines the root filesystem image
1848 type.
1849 The
1850 <filename>deploy/images/<replaceable>machine</replaceable></filename>
1851 directory can contain multiple root filesystems for the
1852 machine.
1853 </para></listitem>
1854 <listitem><para>
1855 <filename><replaceable>kernel-modules</replaceable></filename>:
1856 Tarballs that contain all the modules built for the
1857 kernel.
1858 Kernel module tarballs exist for legacy purposes and
1859 can be suppressed by setting the
1860 <ulink url='&YOCTO_DOCS_REF_URL;#var-MODULE_TARBALL_DEPLOY'><filename>MODULE_TARBALL_DEPLOY</filename></ulink>
1861 variable to "0".
1862 The
1863 <filename>deploy/images/<replaceable>machine</replaceable></filename>
1864 directory can contain multiple kernel module tarballs
1865 for the machine.
1866 </para></listitem>
1867 <listitem><para>
1868 <filename><replaceable>bootloaders</replaceable></filename>:
1869 Bootloaders supporting the image, if applicable to the
1870 target machine.
1871 The <filename>deploy/images/<replaceable>machine</replaceable></filename>
1872 directory can contain multiple bootloaders for the
1873 machine.
1874 </para></listitem>
1875 <listitem><para>
1876 <filename><replaceable>symlinks</replaceable></filename>:
1877 The
1878 <filename>deploy/images/<replaceable>machine</replaceable></filename>
1879 folder contains a symbolic link that points to the
1880 most recently built file for each machine.
1881 These links might be useful for external scripts that
1882 need to obtain the latest version of each file.
1883 </para></listitem>
1884 </itemizedlist>
1885 </para>
1886 </section>
1887
1888 <section id='sdk-dev-environment'>
1889 <title>Application Development SDK</title>
1890
1891 <para>
1892 In the
1893 <link linkend='general-yocto-environment-figure'>general Yocto Project Development Environment figure</link>,
1894 the output labeled "Application Development SDK" represents an
1895 SDK.
1896 The SDK generation process differs depending on whether you
1897 build a standard SDK (e.g.
1898 <filename>bitbake -c populate_sdk</filename> <replaceable>imagename</replaceable>)
1899 or an extensible SDK (e.g.
1900 <filename>bitbake -c populate_sdk_ext</filename> <replaceable>imagename</replaceable>).
1901 This section is going to take a closer look at this output:
1902 <imagedata fileref="figures/sdk.png" align="center" width="9in" depth="7.25in" />
1903 </para>
1904
1905 <para>
1906 The specific form of this output is a self-extracting
1907 SDK installer (<filename>*.sh</filename>) that, when run,
1908 installs the SDK, which consists of a cross-development
1909 toolchain, a set of libraries and headers, and an SDK
1910 environment setup script.
1911 Running this installer essentially sets up your
1912 cross-development environment.
1913 You can think of the cross-toolchain as the "host"
1914 part because it runs on the SDK machine.
1915 You can think of the libraries and headers as the "target"
1916 part because they are built for the target hardware.
1917 The environment setup script is added so that you can
1918 initialize the environment before using the tools.
1919 </para>
1920
1921 <note><title>Notes</title>
1922 <itemizedlist>
1923 <listitem><para>
1924 The Yocto Project supports several methods by which
1925 you can set up this cross-development environment.
1926 These methods include downloading pre-built SDK
1927 installers or building and installing your own SDK
1928 installer.
1929 </para></listitem>
1930 <listitem><para>
1931 For background information on cross-development
1932 toolchains in the Yocto Project development
1933 environment, see the
1934 "<link linkend='cross-development-toolchain-generation'>Cross-Development Toolchain Generation</link>"
1935 section.
1936 </para></listitem>
1937 <listitem><para>
1938 For information on setting up a cross-development
1939 environment, see the
1940 <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink>
1941 manual.
1942 </para></listitem>
1943 </itemizedlist>
1944 </note>
1945
1946 <para>
1947 Once built, the SDK installers are written out to the
1948 <filename>deploy/sdk</filename> folder inside the
1949 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
1950 as shown in the figure at the beginning of this section.
1951 Depending on the type of SDK, several variables exist that help
1952 configure these files.
1953 The following list shows the variables associated with
1954 a standard SDK:
1955 <itemizedlist>
1956 <listitem><para>
1957 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></ulink>:
1958 Points to the <filename>deploy</filename>
1959 directory.
1960 </para></listitem>
1961 <listitem><para>
1962 <ulink url='&YOCTO_DOCS_REF_URL;#var-SDKMACHINE'><filename>SDKMACHINE</filename></ulink>:
1963 Specifies the architecture of the machine
1964 on which the cross-development tools are run to
1965 create packages for the target hardware.
1966 </para></listitem>
1967 <listitem><para>
1968 <ulink url='&YOCTO_DOCS_REF_URL;#var-SDKIMAGE_FEATURES'><filename>SDKIMAGE_FEATURES</filename></ulink>:
1969 Lists the features to include in the "target" part
1970 of the SDK.
1971 </para></listitem>
1972 <listitem><para>
1973 <ulink url='&YOCTO_DOCS_REF_URL;#var-TOOLCHAIN_HOST_TASK'><filename>TOOLCHAIN_HOST_TASK</filename></ulink>:
1974 Lists packages that make up the host
1975 part of the SDK (i.e. the part that runs on
1976 the <filename>SDKMACHINE</filename>).
1977 When you use
1978 <filename>bitbake -c populate_sdk <replaceable>imagename</replaceable></filename>
1979 to create the SDK, a set of default packages
1980 apply.
1981 This variable allows you to add more packages.
1982 </para></listitem>
1983 <listitem><para>
1984 <ulink url='&YOCTO_DOCS_REF_URL;#var-TOOLCHAIN_TARGET_TASK'><filename>TOOLCHAIN_TARGET_TASK</filename></ulink>:
1985 Lists packages that make up the target part
1986 of the SDK (i.e. the part built for the
1987 target hardware).
1988 </para></listitem>
1989 <listitem><para>
1990 <ulink url='&YOCTO_DOCS_REF_URL;#var-SDKPATH'><filename>SDKPATH</filename></ulink>:
1991 Defines the default SDK installation path offered
1992 by the installation script.
1993 </para></listitem>
1994 </itemizedlist>
1995 This next list, shows the variables associated with an
1996 extensible SDK:
1997 <itemizedlist>
1998 <listitem><para>
1999 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></ulink>:
2000 Points to the <filename>deploy</filename> directory.
2001 </para></listitem>
2002 <listitem><para>
2003 <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_EXT_TYPE'><filename>SDK_EXT_TYPE</filename></ulink>:
2004 Controls whether or not shared state artifacts are
2005 copied into the extensible SDK.
2006 By default, all required shared state artifacts are
2007 copied into the SDK.
2008 </para></listitem>
2009 <listitem><para>
2010 <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_INCLUDE_PKGDATA'><filename>SDK_INCLUDE_PKGDATA</filename></ulink>:
2011 Specifies whether or not packagedata will be
2012 included in the extensible SDK for all recipes in
2013 the "world" target.
2014 </para></listitem>
2015 <listitem><para>
2016 <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_INCLUDE_TOOLCHAIN'><filename>SDK_INCLUDE_TOOLCHAIN</filename></ulink>:
2017 Specifies whether or not the toolchain will be included
2018 when building the extensible SDK.
2019 </para></listitem>
2020 <listitem><para>
2021 <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_LOCAL_CONF_WHITELIST'><filename>SDK_LOCAL_CONF_WHITELIST</filename></ulink>:
2022 A list of variables allowed through from the build
2023 system configuration into the extensible SDK
2024 configuration.
2025 </para></listitem>
2026 <listitem><para>
2027 <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_LOCAL_CONF_BLACKLIST'><filename>SDK_LOCAL_CONF_BLACKLIST</filename></ulink>:
2028 A list of variables not allowed through from the build
2029 system configuration into the extensible SDK
2030 configuration.
2031 </para></listitem>
2032 <listitem><para>
2033 <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_INHERIT_BLACKLIST'><filename>SDK_INHERIT_BLACKLIST</filename></ulink>:
2034 A list of classes to remove from the
2035 <ulink url='&YOCTO_DOCS_REF_URL;#var-INHERIT'><filename>INHERIT</filename></ulink>
2036 value globally within the extensible SDK configuration.
2037 </para></listitem>
2038 </itemizedlist>
2039 </para>
2040 </section>
2041 </section>
2042
251 <section id="cross-development-toolchain-generation"> 2043 <section id="cross-development-toolchain-generation">
252 <title>Cross-Development Toolchain Generation</title> 2044 <title>Cross-Development Toolchain Generation</title>
253 2045
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index dbbe67657d..8e8b06fba1 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -1815,8 +1815,8 @@
1815 Your recipe must have a <filename>SRC_URI</filename> variable 1815 Your recipe must have a <filename>SRC_URI</filename> variable
1816 that points to where the source is located. 1816 that points to where the source is located.
1817 For a graphical representation of source locations, see the 1817 For a graphical representation of source locations, see the
1818 "<ulink url='&YOCTO_DOCS_GS_URL;#sources-dev-environment'>Sources</ulink>" 1818 "<ulink url='&YOCTO_DOCS_CM_URL;#sources-dev-environment'>Sources</ulink>"
1819 section in the Getting Started With Yocto Project Manual. 1819 section in the Yocto Project Concepts Manual.
1820 </para> 1820 </para>
1821 1821
1822 <para> 1822 <para>
@@ -11457,8 +11457,8 @@ Some notes from Cal:
11457 <filename>-c</filename>, BitBake will only run the task if it 11457 <filename>-c</filename>, BitBake will only run the task if it
11458 considers it "out of date". 11458 considers it "out of date".
11459 See the 11459 See the
11460 "<ulink url='&YOCTO_DOCS_GS_URL;#stamp-files-and-the-rerunning-of-tasks'>Stamp Files and the Rerunning of Tasks</ulink>" 11460 "<ulink url='&YOCTO_DOCS_CM_URL;#stamp-files-and-the-rerunning-of-tasks'>Stamp Files and the Rerunning of Tasks</ulink>"
11461 section in the Getting Started With Yocto Project Manual for 11461 section in the Yocto Project Concepts Manual for
11462 how BitBake determines whether a task is "out of date". 11462 how BitBake determines whether a task is "out of date".
11463 </para> 11463 </para>
11464 11464
diff --git a/documentation/dev-manual/dev-manual-start.xml b/documentation/dev-manual/dev-manual-start.xml
index f14a91f94b..39d36fa0f1 100644
--- a/documentation/dev-manual/dev-manual-start.xml
+++ b/documentation/dev-manual/dev-manual-start.xml
@@ -741,8 +741,8 @@
741 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink> 741 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
742 under <filename>tmp/deploy/images</filename>. 742 under <filename>tmp/deploy/images</filename>.
743 For detailed information on the build process using BitBake, see the 743 For detailed information on the build process using BitBake, see the
744 "<ulink url='&YOCTO_DOCS_GS_URL;#images-dev-environment'>Images</ulink>" 744 "<ulink url='&YOCTO_DOCS_CM_URL;#images-dev-environment'>Images</ulink>"
745 section in the Getting Started With Yocto Project Manual. 745 section in the Yocto Project Concepts Manual.
746 </para> 746 </para>
747 747
748 <para> 748 <para>
diff --git a/documentation/getting-started/getting-started-development-environment.xml b/documentation/getting-started/getting-started-development-environment.xml
index 096517b729..5d6491c51b 100644
--- a/documentation/getting-started/getting-started-development-environment.xml
+++ b/documentation/getting-started/getting-started-development-environment.xml
@@ -937,1656 +937,6 @@
937 section in the Yocto Project Development Tasks Manual. 937 section in the Yocto Project Development Tasks Manual.
938 </para> 938 </para>
939</section> 939</section>
940
941<section id="development-concepts">
942 <title>Development Concepts</title>
943
944 <para>
945 This section takes a more detailed look inside the development
946 process.
947 The following diagram represents development at a high level.
948 The remainder of this chapter expands on the fundamental input, output,
949 process, and
950 <ulink url='&YOCTO_DOCS_REF_URL;#metadata'>Metadata</ulink>) blocks
951 that make up development in the Yocto Project environment.
952 </para>
953
954 <para id='general-yocto-environment-figure'>
955 <imagedata fileref="figures/yocto-environment-ref.png" align="center" width="8in" depth="4.25in" />
956 </para>
957
958 <para>
959 In general, development consists of several functional areas:
960 <itemizedlist>
961 <listitem><para><emphasis>User Configuration:</emphasis>
962 Metadata you can use to control the build process.
963 </para></listitem>
964 <listitem><para><emphasis>Metadata Layers:</emphasis>
965 Various layers that provide software, machine, and
966 distro Metadata.</para></listitem>
967 <listitem><para><emphasis>Source Files:</emphasis>
968 Upstream releases, local projects, and SCMs.</para></listitem>
969 <listitem><para><emphasis>Build System:</emphasis>
970 Processes under the control of
971 <ulink url='&YOCTO_DOCS_REF_URL;#bitbake-term'>BitBake</ulink>.
972 This block expands on how BitBake fetches source, applies
973 patches, completes compilation, analyzes output for package
974 generation, creates and tests packages, generates images, and
975 generates cross-development tools.</para></listitem>
976 <listitem><para><emphasis>Package Feeds:</emphasis>
977 Directories containing output packages (RPM, DEB or IPK),
978 which are subsequently used in the construction of an image or
979 SDK, produced by the build system.
980 These feeds can also be copied and shared using a web server or
981 other means to facilitate extending or updating existing
982 images on devices at runtime if runtime package management is
983 enabled.</para></listitem>
984 <listitem><para><emphasis>Images:</emphasis>
985 Images produced by the development process.
986 </para></listitem>
987 <listitem><para><emphasis>Application Development SDK:</emphasis>
988 Cross-development tools that are produced along with an image
989 or separately with BitBake.</para></listitem>
990 </itemizedlist>
991 </para>
992
993 <section id="user-configuration">
994 <title>User Configuration</title>
995
996 <para>
997 User configuration helps define the build.
998 Through user configuration, you can tell BitBake the
999 target architecture for which you are building the image,
1000 where to store downloaded source, and other build properties.
1001 </para>
1002
1003 <para>
1004 The following figure shows an expanded representation of the
1005 "User Configuration" box of the
1006 <link linkend='general-yocto-environment-figure'>general Yocto Project Development Environment figure</link>:
1007 </para>
1008
1009 <para>
1010 <imagedata fileref="figures/user-configuration.png" align="center" width="8in" depth="4.5in" />
1011 </para>
1012
1013 <para>
1014 BitBake needs some basic configuration files in order to complete
1015 a build.
1016 These files are <filename>*.conf</filename> files.
1017 The minimally necessary ones reside as example files in the
1018 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>.
1019 For simplicity, this section refers to the Source Directory as
1020 the "Poky Directory."
1021 </para>
1022
1023 <para>
1024 When you clone the <filename>poky</filename> Git repository or you
1025 download and unpack a Yocto Project release, you can set up the
1026 Source Directory to be named anything you want.
1027 For this discussion, the cloned repository uses the default
1028 name <filename>poky</filename>.
1029 <note>
1030 The Poky repository is primarily an aggregation of existing
1031 repositories.
1032 It is not a canonical upstream source.
1033 </note>
1034 </para>
1035
1036 <para>
1037 The <filename>meta-poky</filename> layer inside Poky contains
1038 a <filename>conf</filename> directory that has example
1039 configuration files.
1040 These example files are used as a basis for creating actual
1041 configuration files when you source the build environment
1042 script
1043 (i.e.
1044 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>).
1045 </para>
1046
1047 <para>
1048 Sourcing the build environment script creates a
1049 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
1050 if one does not already exist.
1051 BitBake uses the Build Directory for all its work during builds.
1052 The Build Directory has a <filename>conf</filename> directory that
1053 contains default versions of your <filename>local.conf</filename>
1054 and <filename>bblayers.conf</filename> configuration files.
1055 These default configuration files are created only if versions
1056 do not already exist in the Build Directory at the time you
1057 source the build environment setup script.
1058 </para>
1059
1060 <para>
1061 Because the Poky repository is fundamentally an aggregation of
1062 existing repositories, some users might be familiar with running
1063 the <filename>&OE_INIT_FILE;</filename> script in the context
1064 of separate OpenEmbedded-Core and BitBake repositories rather than a
1065 single Poky repository.
1066 This discussion assumes the script is executed from within a cloned
1067 or unpacked version of Poky.
1068 </para>
1069
1070 <para>
1071 Depending on where the script is sourced, different sub-scripts
1072 are called to set up the Build Directory (Yocto or OpenEmbedded).
1073 Specifically, the script
1074 <filename>scripts/oe-setup-builddir</filename> inside the
1075 poky directory sets up the Build Directory and seeds the directory
1076 (if necessary) with configuration files appropriate for the
1077 Yocto Project development environment.
1078 <note>
1079 The <filename>scripts/oe-setup-builddir</filename> script
1080 uses the <filename>$TEMPLATECONF</filename> variable to
1081 determine which sample configuration files to locate.
1082 </note>
1083 </para>
1084
1085 <para>
1086 The <filename>local.conf</filename> file provides many
1087 basic variables that define a build environment.
1088 Here is a list of a few.
1089 To see the default configurations in a <filename>local.conf</filename>
1090 file created by the build environment script, see the
1091 <filename>local.conf.sample</filename> in the
1092 <filename>meta-poky</filename> layer:
1093 <itemizedlist>
1094 <listitem><para><emphasis>Parallelism Options:</emphasis>
1095 Controlled by the
1096 <ulink url='&YOCTO_DOCS_REF_URL;#var-BB_NUMBER_THREADS'><filename>BB_NUMBER_THREADS</filename></ulink>,
1097 <ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></ulink>,
1098 and
1099 <ulink url='&YOCTO_DOCS_BB_URL;#var-BB_NUMBER_PARSE_THREADS'><filename>BB_NUMBER_PARSE_THREADS</filename></ulink>
1100 variables.</para></listitem>
1101 <listitem><para><emphasis>Target Machine Selection:</emphasis>
1102 Controlled by the
1103 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
1104 variable.</para></listitem>
1105 <listitem><para><emphasis>Download Directory:</emphasis>
1106 Controlled by the
1107 <ulink url='&YOCTO_DOCS_REF_URL;#var-DL_DIR'><filename>DL_DIR</filename></ulink>
1108 variable.</para></listitem>
1109 <listitem><para><emphasis>Shared State Directory:</emphasis>
1110 Controlled by the
1111 <ulink url='&YOCTO_DOCS_REF_URL;#var-SSTATE_DIR'><filename>SSTATE_DIR</filename></ulink>
1112 variable.</para></listitem>
1113 <listitem><para><emphasis>Build Output:</emphasis>
1114 Controlled by the
1115 <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>
1116 variable.</para></listitem>
1117 </itemizedlist>
1118 <note>
1119 Configurations set in the <filename>conf/local.conf</filename>
1120 file can also be set in the
1121 <filename>conf/site.conf</filename> and
1122 <filename>conf/auto.conf</filename> configuration files.
1123 </note>
1124 </para>
1125
1126 <para>
1127 The <filename>bblayers.conf</filename> file tells BitBake what
1128 layers you want considered during the build.
1129 By default, the layers listed in this file include layers
1130 minimally needed by the build system.
1131 However, you must manually add any custom layers you have created.
1132 You can find more information on working with the
1133 <filename>bblayers.conf</filename> file in the
1134 "<ulink url='&YOCTO_DOCS_DEV_URL;#enabling-your-layer'>Enabling Your Layer</ulink>"
1135 section in the Yocto Project Development Tasks Manual.
1136 </para>
1137
1138 <para>
1139 The files <filename>site.conf</filename> and
1140 <filename>auto.conf</filename> are not created by the environment
1141 initialization script.
1142 If you want the <filename>site.conf</filename> file, you need to
1143 create that yourself.
1144 The <filename>auto.conf</filename> file is typically created by
1145 an autobuilder:
1146 <itemizedlist>
1147 <listitem><para><emphasis><filename>site.conf</filename>:</emphasis>
1148 You can use the <filename>conf/site.conf</filename>
1149 configuration file to configure multiple build directories.
1150 For example, suppose you had several build environments and
1151 they shared some common features.
1152 You can set these default build properties here.
1153 A good example is perhaps the packaging format to use
1154 through the
1155 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></ulink>
1156 variable.</para>
1157 <para>One useful scenario for using the
1158 <filename>conf/site.conf</filename> file is to extend your
1159 <ulink url='&YOCTO_DOCS_REF_URL;#var-BBPATH'><filename>BBPATH</filename></ulink>
1160 variable to include the path to a
1161 <filename>conf/site.conf</filename>.
1162 Then, when BitBake looks for Metadata using
1163 <filename>BBPATH</filename>, it finds the
1164 <filename>conf/site.conf</filename> file and applies your
1165 common configurations found in the file.
1166 To override configurations in a particular build directory,
1167 alter the similar configurations within that build
1168 directory's <filename>conf/local.conf</filename> file.
1169 </para></listitem>
1170 <listitem><para><emphasis><filename>auto.conf</filename>:</emphasis>
1171 The file is usually created and written to by
1172 an autobuilder.
1173 The settings put into the file are typically the same as
1174 you would find in the <filename>conf/local.conf</filename>
1175 or the <filename>conf/site.conf</filename> files.
1176 </para></listitem>
1177 </itemizedlist>
1178 </para>
1179
1180 <para>
1181 You can edit all configuration files to further define
1182 any particular build environment.
1183 This process is represented by the "User Configuration Edits"
1184 box in the figure.
1185 </para>
1186
1187 <para>
1188 When you launch your build with the
1189 <filename>bitbake <replaceable>target</replaceable></filename>
1190 command, BitBake sorts out the configurations to ultimately
1191 define your build environment.
1192 It is important to understand that the OpenEmbedded build system
1193 reads the configuration files in a specific order:
1194 <filename>site.conf</filename>, <filename>auto.conf</filename>,
1195 and <filename>local.conf</filename>.
1196 And, the build system applies the normal assignment statement
1197 rules.
1198 Because the files are parsed in a specific order, variable
1199 assignments for the same variable could be affected.
1200 For example, if the <filename>auto.conf</filename> file and
1201 the <filename>local.conf</filename> set
1202 <replaceable>variable1</replaceable> to different values, because
1203 the build system parses <filename>local.conf</filename> after
1204 <filename>auto.conf</filename>,
1205 <replaceable>variable1</replaceable> is assigned the value from
1206 the <filename>local.conf</filename> file.
1207 </para>
1208 </section>
1209
1210 <section id="metadata-machine-configuration-and-policy-configuration">
1211 <title>Metadata, Machine Configuration, and Policy Configuration</title>
1212
1213 <para>
1214 The previous section described the user configurations that
1215 define BitBake's global behavior.
1216 This section takes a closer look at the layers the build system
1217 uses to further control the build.
1218 These layers provide Metadata for the software, machine, and
1219 policy.
1220 </para>
1221
1222 <para>
1223 In general, three types of layer input exist:
1224 <itemizedlist>
1225 <listitem><para><emphasis>Policy Configuration:</emphasis>
1226 Distribution Layers provide top-level or general
1227 policies for the image or SDK being built.
1228 For example, this layer would dictate whether BitBake
1229 produces RPM or IPK packages.</para></listitem>
1230 <listitem><para><emphasis>Machine Configuration:</emphasis>
1231 Board Support Package (BSP) layers provide machine
1232 configurations.
1233 This type of information is specific to a particular
1234 target architecture.</para></listitem>
1235 <listitem><para><emphasis>Metadata:</emphasis>
1236 Software layers contain user-supplied recipe files,
1237 patches, and append files.
1238 </para></listitem>
1239 </itemizedlist>
1240 </para>
1241
1242 <para>
1243 The following figure shows an expanded representation of the
1244 Metadata, Machine Configuration, and Policy Configuration input
1245 (layers) boxes of the
1246 <link linkend='general-yocto-environment-figure'>general Yocto Project Development Environment figure</link>:
1247 </para>
1248
1249 <para>
1250 <imagedata fileref="figures/layer-input.png" align="center" width="8in" depth="7.5in" />
1251 </para>
1252
1253 <para>
1254 In general, all layers have a similar structure.
1255 They all contain a licensing file
1256 (e.g. <filename>COPYING</filename>) if the layer is to be
1257 distributed, a <filename>README</filename> file as good practice
1258 and especially if the layer is to be distributed, a
1259 configuration directory, and recipe directories.
1260 </para>
1261
1262 <para>
1263 The Yocto Project has many layers that can be used.
1264 You can see a web-interface listing of them on the
1265 <ulink url="http://git.yoctoproject.org/">Source Repositories</ulink>
1266 page.
1267 The layers are shown at the bottom categorized under
1268 "Yocto Metadata Layers."
1269 These layers are fundamentally a subset of the
1270 <ulink url="http://layers.openembedded.org/layerindex/layers/">OpenEmbedded Metadata Index</ulink>,
1271 which lists all layers provided by the OpenEmbedded community.
1272 <note>
1273 Layers exist in the Yocto Project Source Repositories that
1274 cannot be found in the OpenEmbedded Metadata Index.
1275 These layers are either deprecated or experimental in nature.
1276 </note>
1277 </para>
1278
1279 <para>
1280 BitBake uses the <filename>conf/bblayers.conf</filename> file,
1281 which is part of the user configuration, to find what layers it
1282 should be using as part of the build.
1283 </para>
1284
1285 <para>
1286 For more information on layers, see the
1287 "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>"
1288 section in the Yocto Project Development Tasks Manual.
1289 </para>
1290
1291 <section id="distro-layer">
1292 <title>Distro Layer</title>
1293
1294 <para>
1295 The distribution layer provides policy configurations for your
1296 distribution.
1297 Best practices dictate that you isolate these types of
1298 configurations into their own layer.
1299 Settings you provide in
1300 <filename>conf/distro/<replaceable>distro</replaceable>.conf</filename> override
1301 similar
1302 settings that BitBake finds in your
1303 <filename>conf/local.conf</filename> file in the Build
1304 Directory.
1305 </para>
1306
1307 <para>
1308 The following list provides some explanation and references
1309 for what you typically find in the distribution layer:
1310 <itemizedlist>
1311 <listitem><para><emphasis>classes:</emphasis>
1312 Class files (<filename>.bbclass</filename>) hold
1313 common functionality that can be shared among
1314 recipes in the distribution.
1315 When your recipes inherit a class, they take on the
1316 settings and functions for that class.
1317 You can read more about class files in the
1318 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-classes'>Classes</ulink>"
1319 section of the Yocto Reference Manual.
1320 </para></listitem>
1321 <listitem><para><emphasis>conf:</emphasis>
1322 This area holds configuration files for the
1323 layer (<filename>conf/layer.conf</filename>),
1324 the distribution
1325 (<filename>conf/distro/<replaceable>distro</replaceable>.conf</filename>),
1326 and any distribution-wide include files.
1327 </para></listitem>
1328 <listitem><para><emphasis>recipes-*:</emphasis>
1329 Recipes and append files that affect common
1330 functionality across the distribution.
1331 This area could include recipes and append files
1332 to add distribution-specific configuration,
1333 initialization scripts, custom image recipes,
1334 and so forth.</para></listitem>
1335 </itemizedlist>
1336 </para>
1337 </section>
1338
1339 <section id="bsp-layer">
1340 <title>BSP Layer</title>
1341
1342 <para>
1343 The BSP Layer provides machine configurations.
1344 Everything in this layer is specific to the machine for which
1345 you are building the image or the SDK.
1346 A common structure or form is defined for BSP layers.
1347 You can learn more about this structure in the
1348 <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink>.
1349 <note>
1350 In order for a BSP layer to be considered compliant with the
1351 Yocto Project, it must meet some structural requirements.
1352 </note>
1353 </para>
1354
1355 <para>
1356 The BSP Layer's configuration directory contains
1357 configuration files for the machine
1358 (<filename>conf/machine/<replaceable>machine</replaceable>.conf</filename>) and,
1359 of course, the layer (<filename>conf/layer.conf</filename>).
1360 </para>
1361
1362 <para>
1363 The remainder of the layer is dedicated to specific recipes
1364 by function: <filename>recipes-bsp</filename>,
1365 <filename>recipes-core</filename>,
1366 <filename>recipes-graphics</filename>, and
1367 <filename>recipes-kernel</filename>.
1368 Metadata can exist for multiple formfactors, graphics
1369 support systems, and so forth.
1370 <note>
1371 While the figure shows several <filename>recipes-*</filename>
1372 directories, not all these directories appear in all
1373 BSP layers.
1374 </note>
1375 </para>
1376 </section>
1377
1378 <section id="software-layer">
1379 <title>Software Layer</title>
1380
1381 <para>
1382 The software layer provides the Metadata for additional
1383 software packages used during the build.
1384 This layer does not include Metadata that is specific to the
1385 distribution or the machine, which are found in their
1386 respective layers.
1387 </para>
1388
1389 <para>
1390 This layer contains any new recipes that your project needs
1391 in the form of recipe files.
1392 </para>
1393 </section>
1394 </section>
1395
1396 <section id="sources-dev-environment">
1397 <title>Sources</title>
1398
1399 <para>
1400 In order for the OpenEmbedded build system to create an image or
1401 any target, it must be able to access source files.
1402 The
1403 <link linkend='general-yocto-environment-figure'>general Yocto Project Development Environment figure</link>
1404 represents source files using the "Upstream Project Releases",
1405 "Local Projects", and "SCMs (optional)" boxes.
1406 The figure represents mirrors, which also play a role in locating
1407 source files, with the "Source Mirror(s)" box.
1408 </para>
1409
1410 <para>
1411 The method by which source files are ultimately organized is
1412 a function of the project.
1413 For example, for released software, projects tend to use tarballs
1414 or other archived files that can capture the state of a release
1415 guaranteeing that it is statically represented.
1416 On the other hand, for a project that is more dynamic or
1417 experimental in nature, a project might keep source files in a
1418 repository controlled by a Source Control Manager (SCM) such as
1419 Git.
1420 Pulling source from a repository allows you to control
1421 the point in the repository (the revision) from which you want to
1422 build software.
1423 Finally, a combination of the two might exist, which would give the
1424 consumer a choice when deciding where to get source files.
1425 </para>
1426
1427 <para>
1428 BitBake uses the
1429 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
1430 variable to point to source files regardless of their location.
1431 Each recipe must have a <filename>SRC_URI</filename> variable
1432 that points to the source.
1433 </para>
1434
1435 <para>
1436 Another area that plays a significant role in where source files
1437 come from is pointed to by the
1438 <ulink url='&YOCTO_DOCS_REF_URL;#var-DL_DIR'><filename>DL_DIR</filename></ulink>
1439 variable.
1440 This area is a cache that can hold previously downloaded source.
1441 You can also instruct the OpenEmbedded build system to create
1442 tarballs from Git repositories, which is not the default behavior,
1443 and store them in the <filename>DL_DIR</filename> by using the
1444 <ulink url='&YOCTO_DOCS_REF_URL;#var-BB_GENERATE_MIRROR_TARBALLS'><filename>BB_GENERATE_MIRROR_TARBALLS</filename></ulink>
1445 variable.
1446 </para>
1447
1448 <para>
1449 Judicious use of a <filename>DL_DIR</filename> directory can
1450 save the build system a trip across the Internet when looking
1451 for files.
1452 A good method for using a download directory is to have
1453 <filename>DL_DIR</filename> point to an area outside of your
1454 Build Directory.
1455 Doing so allows you to safely delete the Build Directory
1456 if needed without fear of removing any downloaded source file.
1457 </para>
1458
1459 <para>
1460 The remainder of this section provides a deeper look into the
1461 source files and the mirrors.
1462 Here is a more detailed look at the source file area of the
1463 base figure:
1464 <imagedata fileref="figures/source-input.png" align="center" width="7in" depth="7.5in" />
1465 </para>
1466
1467 <section id='upstream-project-releases'>
1468 <title>Upstream Project Releases</title>
1469
1470 <para>
1471 Upstream project releases exist anywhere in the form of an
1472 archived file (e.g. tarball or zip file).
1473 These files correspond to individual recipes.
1474 For example, the figure uses specific releases each for
1475 BusyBox, Qt, and Dbus.
1476 An archive file can be for any released product that can be
1477 built using a recipe.
1478 </para>
1479 </section>
1480
1481 <section id='local-projects'>
1482 <title>Local Projects</title>
1483
1484 <para>
1485 Local projects are custom bits of software the user provides.
1486 These bits reside somewhere local to a project - perhaps
1487 a directory into which the user checks in items (e.g.
1488 a local directory containing a development source tree
1489 used by the group).
1490 </para>
1491
1492 <para>
1493 The canonical method through which to include a local project
1494 is to use the
1495 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-externalsrc'><filename>externalsrc</filename></ulink>
1496 class to include that local project.
1497 You use either the <filename>local.conf</filename> or a
1498 recipe's append file to override or set the
1499 recipe to point to the local directory on your disk to pull
1500 in the whole source tree.
1501 </para>
1502
1503 <para>
1504 For information on how to use the
1505 <filename>externalsrc</filename> class, see the
1506 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-externalsrc'><filename>externalsrc.bbclass</filename></ulink>"
1507 section.
1508 </para>
1509 </section>
1510
1511 <section id='scms'>
1512 <title>Source Control Managers (Optional)</title>
1513
1514 <para>
1515 Another place the build system can get source files from is
1516 through an SCM such as Git or Subversion.
1517 In this case, a repository is cloned or checked out.
1518 The
1519 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-fetch'><filename>do_fetch</filename></ulink>
1520 task inside BitBake uses
1521 the <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
1522 variable and the argument's prefix to determine the correct
1523 fetcher module.
1524 </para>
1525
1526 <note>
1527 For information on how to have the OpenEmbedded build system
1528 generate tarballs for Git repositories and place them in the
1529 <ulink url='&YOCTO_DOCS_REF_URL;#var-DL_DIR'><filename>DL_DIR</filename></ulink>
1530 directory, see the
1531 <ulink url='&YOCTO_DOCS_REF_URL;#var-BB_GENERATE_MIRROR_TARBALLS'><filename>BB_GENERATE_MIRROR_TARBALLS</filename></ulink>
1532 variable.
1533 </note>
1534
1535 <para>
1536 When fetching a repository, BitBake uses the
1537 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCREV'><filename>SRCREV</filename></ulink>
1538 variable to determine the specific revision from which to
1539 build.
1540 </para>
1541 </section>
1542
1543 <section id='source-mirrors'>
1544 <title>Source Mirror(s)</title>
1545
1546 <para>
1547 Two kinds of mirrors exist: pre-mirrors and regular mirrors.
1548 The
1549 <ulink url='&YOCTO_DOCS_REF_URL;#var-PREMIRRORS'><filename>PREMIRRORS</filename></ulink>
1550 and
1551 <ulink url='&YOCTO_DOCS_REF_URL;#var-MIRRORS'><filename>MIRRORS</filename></ulink>
1552 variables point to these, respectively.
1553 BitBake checks pre-mirrors before looking upstream for any
1554 source files.
1555 Pre-mirrors are appropriate when you have a shared directory
1556 that is not a directory defined by the
1557 <ulink url='&YOCTO_DOCS_REF_URL;#var-DL_DIR'><filename>DL_DIR</filename></ulink>
1558 variable.
1559 A Pre-mirror typically points to a shared directory that is
1560 local to your organization.
1561 </para>
1562
1563 <para>
1564 Regular mirrors can be any site across the Internet that is
1565 used as an alternative location for source code should the
1566 primary site not be functioning for some reason or another.
1567 </para>
1568 </section>
1569 </section>
1570
1571 <section id="package-feeds-dev-environment">
1572 <title>Package Feeds</title>
1573
1574 <para>
1575 When the OpenEmbedded build system generates an image or an SDK,
1576 it gets the packages from a package feed area located in the
1577 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>.
1578 The
1579 <link linkend='general-yocto-environment-figure'>general Yocto Project Development Environment figure</link>
1580 shows this package feeds area in the upper-right corner.
1581 </para>
1582
1583 <para>
1584 This section looks a little closer into the package feeds area used
1585 by the build system.
1586 Here is a more detailed look at the area:
1587 <imagedata fileref="figures/package-feeds.png" align="center" width="7in" depth="6in" />
1588 </para>
1589
1590 <para>
1591 Package feeds are an intermediary step in the build process.
1592 The OpenEmbedded build system provides classes to generate
1593 different package types, and you specify which classes to enable
1594 through the
1595 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></ulink>
1596 variable.
1597 Before placing the packages into package feeds,
1598 the build process validates them with generated output quality
1599 assurance checks through the
1600 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-insane'><filename>insane</filename></ulink>
1601 class.
1602 </para>
1603
1604 <para>
1605 The package feed area resides in the Build Directory.
1606 The directory the build system uses to temporarily store packages
1607 is determined by a combination of variables and the particular
1608 package manager in use.
1609 See the "Package Feeds" box in the illustration and note the
1610 information to the right of that area.
1611 In particular, the following defines where package files are
1612 kept:
1613 <itemizedlist>
1614 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></ulink>:
1615 Defined as <filename>tmp/deploy</filename> in the Build
1616 Directory.
1617 </para></listitem>
1618 <listitem><para><filename>DEPLOY_DIR_*</filename>:
1619 Depending on the package manager used, the package type
1620 sub-folder.
1621 Given RPM, IPK, or DEB packaging and tarball creation, the
1622 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPLOY_DIR_RPM'><filename>DEPLOY_DIR_RPM</filename></ulink>,
1623 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPLOY_DIR_IPK'><filename>DEPLOY_DIR_IPK</filename></ulink>,
1624 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPLOY_DIR_DEB'><filename>DEPLOY_DIR_DEB</filename></ulink>,
1625 or
1626 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPLOY_DIR_TAR'><filename>DEPLOY_DIR_TAR</filename></ulink>,
1627 variables are used, respectively.
1628 </para></listitem>
1629 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></ulink>:
1630 Defines architecture-specific sub-folders.
1631 For example, packages could exist for the i586 or qemux86
1632 architectures.
1633 </para></listitem>
1634 </itemizedlist>
1635 </para>
1636
1637 <para>
1638 BitBake uses the <filename>do_package_write_*</filename> tasks to
1639 generate packages and place them into the package holding area (e.g.
1640 <filename>do_package_write_ipk</filename> for IPK packages).
1641 See the
1642 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package_write_deb'><filename>do_package_write_deb</filename></ulink>",
1643 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package_write_ipk'><filename>do_package_write_ipk</filename></ulink>",
1644 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package_write_rpm'><filename>do_package_write_rpm</filename></ulink>",
1645 and
1646 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package_write_tar'><filename>do_package_write_tar</filename></ulink>"
1647 sections for additional information.
1648 As an example, consider a scenario where an IPK packaging manager
1649 is being used and package architecture support for both i586
1650 and qemux86 exist.
1651 Packages for the i586 architecture are placed in
1652 <filename>build/tmp/deploy/ipk/i586</filename>, while packages for
1653 the qemux86 architecture are placed in
1654 <filename>build/tmp/deploy/ipk/qemux86</filename>.
1655 </para>
1656 </section>
1657
1658 <section id='bitbake-dev-environment'>
1659 <title>BitBake</title>
1660
1661 <para>
1662 The OpenEmbedded build system uses
1663 <ulink url='&YOCTO_DOCS_REF_URL;#bitbake-term'>BitBake</ulink>
1664 to produce images.
1665 You can see from the
1666 <link linkend='general-yocto-environment-figure'>general Yocto Project Development Environment figure</link>,
1667 the BitBake area consists of several functional areas.
1668 This section takes a closer look at each of those areas.
1669 </para>
1670
1671 <para>
1672 Separate documentation exists for the BitBake tool.
1673 See the
1674 <ulink url='&YOCTO_DOCS_BB_URL;#bitbake-user-manual'>BitBake User Manual</ulink>
1675 for reference material on BitBake.
1676 </para>
1677
1678 <section id='source-fetching-dev-environment'>
1679 <title>Source Fetching</title>
1680
1681 <para>
1682 The first stages of building a recipe are to fetch and unpack
1683 the source code:
1684 <imagedata fileref="figures/source-fetching.png" align="center" width="6.5in" depth="5in" />
1685 </para>
1686
1687 <para>
1688 The
1689 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-fetch'><filename>do_fetch</filename></ulink>
1690 and
1691 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-unpack'><filename>do_unpack</filename></ulink>
1692 tasks fetch the source files and unpack them into the work
1693 directory.
1694 <note>
1695 For every local file (e.g. <filename>file://</filename>)
1696 that is part of a recipe's
1697 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
1698 statement, the OpenEmbedded build system takes a checksum
1699 of the file for the recipe and inserts the checksum into
1700 the signature for the <filename>do_fetch</filename>.
1701 If any local file has been modified, the
1702 <filename>do_fetch</filename> task and all tasks that
1703 depend on it are re-executed.
1704 </note>
1705 By default, everything is accomplished in the
1706 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>,
1707 which has a defined structure.
1708 For additional general information on the Build Directory,
1709 see the
1710 "<ulink url='&YOCTO_DOCS_REF_URL;#structure-core-build'><filename>build/</filename></ulink>"
1711 section in the Yocto Project Reference Manual.
1712 </para>
1713
1714 <para>
1715 Unpacked source files are pointed to by the
1716 <ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink>
1717 variable.
1718 Each recipe has an area in the Build Directory where the
1719 unpacked source code resides.
1720 The name of that directory for any given recipe is defined from
1721 several different variables.
1722 You can see the variables that define these directories
1723 by looking at the figure:
1724 <itemizedlist>
1725 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink> -
1726 The base directory where the OpenEmbedded build system
1727 performs all its work during the build.
1728 </para></listitem>
1729 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></ulink> -
1730 The architecture of the built package or packages.
1731 </para></listitem>
1732 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-TARGET_OS'><filename>TARGET_OS</filename></ulink> -
1733 The operating system of the target device.
1734 </para></listitem>
1735 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink> -
1736 The name of the built package.
1737 </para></listitem>
1738 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink> -
1739 The version of the recipe used to build the package.
1740 </para></listitem>
1741 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink> -
1742 The revision of the recipe used to build the package.
1743 </para></listitem>
1744 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink> -
1745 The location within <filename>TMPDIR</filename> where
1746 a specific package is built.
1747 </para></listitem>
1748 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink> -
1749 Contains the unpacked source files for a given recipe.
1750 </para></listitem>
1751 </itemizedlist>
1752 </para>
1753 </section>
1754
1755 <section id='patching-dev-environment'>
1756 <title>Patching</title>
1757
1758 <para>
1759 Once source code is fetched and unpacked, BitBake locates
1760 patch files and applies them to the source files:
1761 <imagedata fileref="figures/patching.png" align="center" width="6in" depth="5in" />
1762 </para>
1763
1764 <para>
1765 The
1766 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-patch'><filename>do_patch</filename></ulink>
1767 task processes recipes by
1768 using the
1769 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
1770 variable to locate applicable patch files, which by default
1771 are <filename>*.patch</filename> or
1772 <filename>*.diff</filename> files, or any file if
1773 "apply=yes" is specified for the file in
1774 <filename>SRC_URI</filename>.
1775 </para>
1776
1777 <para>
1778 BitBake finds and applies multiple patches for a single recipe
1779 in the order in which it finds the patches.
1780 Patches are applied to the recipe's source files located in the
1781 <ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink>
1782 directory.
1783 </para>
1784
1785 <para>
1786 For more information on how the source directories are
1787 created, see the
1788 "<link linkend='source-fetching-dev-environment'>Source Fetching</link>"
1789 section.
1790 </para>
1791 </section>
1792
1793 <section id='configuration-and-compilation-dev-environment'>
1794 <title>Configuration and Compilation</title>
1795
1796 <para>
1797 After source code is patched, BitBake executes tasks that
1798 configure and compile the source code:
1799 <imagedata fileref="figures/configuration-compile-autoreconf.png" align="center" width="7in" depth="5in" />
1800 </para>
1801
1802 <para>
1803 This step in the build process consists of three tasks:
1804 <itemizedlist>
1805 <listitem><para>
1806 <emphasis><ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-prepare_recipe_sysroot'><filename>do_prepare_recipe_sysroot</filename></ulink>:</emphasis>
1807 This task sets up the two sysroots in
1808 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}</filename>
1809 (i.e. <filename>recipe-sysroot</filename> and
1810 <filename>recipe-sysroot-native</filename>) so that
1811 the sysroots contain the contents of the
1812 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></ulink>
1813 tasks of the recipes on which the recipe
1814 containing the tasks depends.
1815 A sysroot exists for both the target and for the native
1816 binaries, which run on the host system.
1817 </para></listitem>
1818 <listitem><para><emphasis><filename>do_configure</filename>:</emphasis>
1819 This task configures the source by enabling and
1820 disabling any build-time and configuration options for
1821 the software being built.
1822 Configurations can come from the recipe itself as well
1823 as from an inherited class.
1824 Additionally, the software itself might configure itself
1825 depending on the target for which it is being built.
1826 </para>
1827
1828 <para>The configurations handled by the
1829 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-configure'><filename>do_configure</filename></ulink>
1830 task are specific
1831 to source code configuration for the source code
1832 being built by the recipe.</para>
1833
1834 <para>If you are using the
1835 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-autotools'><filename>autotools</filename></ulink>
1836 class,
1837 you can add additional configuration options by using
1838 the
1839 <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></ulink>
1840 or
1841 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGECONFIG_CONFARGS'><filename>PACKAGECONFIG_CONFARGS</filename></ulink>
1842 variables.
1843 For information on how this variable works within
1844 that class, see the
1845 <filename>meta/classes/autotools.bbclass</filename> file.
1846 </para></listitem>
1847 <listitem><para><emphasis><filename>do_compile</filename>:</emphasis>
1848 Once a configuration task has been satisfied, BitBake
1849 compiles the source using the
1850 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-compile'><filename>do_compile</filename></ulink>
1851 task.
1852 Compilation occurs in the directory pointed to by the
1853 <ulink url='&YOCTO_DOCS_REF_URL;#var-B'><filename>B</filename></ulink>
1854 variable.
1855 Realize that the <filename>B</filename> directory is, by
1856 default, the same as the
1857 <ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink>
1858 directory.</para></listitem>
1859 <listitem><para><emphasis><filename>do_install</filename>:</emphasis>
1860 Once compilation is done, BitBake executes the
1861 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-install'><filename>do_install</filename></ulink>
1862 task.
1863 This task copies files from the <filename>B</filename>
1864 directory and places them in a holding area pointed to
1865 by the
1866 <ulink url='&YOCTO_DOCS_REF_URL;#var-D'><filename>D</filename></ulink>
1867 variable.</para></listitem>
1868 </itemizedlist>
1869 </para>
1870 </section>
1871
1872 <section id='package-splitting-dev-environment'>
1873 <title>Package Splitting</title>
1874
1875 <para>
1876 After source code is configured and compiled, the
1877 OpenEmbedded build system analyzes
1878 the results and splits the output into packages:
1879 <imagedata fileref="figures/analysis-for-package-splitting.png" align="center" width="7in" depth="7in" />
1880 </para>
1881
1882 <para>
1883 The
1884 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package'><filename>do_package</filename></ulink>
1885 and
1886 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-packagedata'><filename>do_packagedata</filename></ulink>
1887 tasks combine to analyze
1888 the files found in the
1889 <ulink url='&YOCTO_DOCS_REF_URL;#var-D'><filename>D</filename></ulink> directory
1890 and split them into subsets based on available packages and
1891 files.
1892 The analyzing process involves the following as well as other
1893 items: splitting out debugging symbols,
1894 looking at shared library dependencies between packages,
1895 and looking at package relationships.
1896 The <filename>do_packagedata</filename> task creates package
1897 metadata based on the analysis such that the
1898 OpenEmbedded build system can generate the final packages.
1899 Working, staged, and intermediate results of the analysis
1900 and package splitting process use these areas:
1901 <itemizedlist>
1902 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-PKGD'><filename>PKGD</filename></ulink> -
1903 The destination directory for packages before they are
1904 split.
1905 </para></listitem>
1906 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-PKGDATA_DIR'><filename>PKGDATA_DIR</filename></ulink> -
1907 A shared, global-state directory that holds data
1908 generated during the packaging process.
1909 </para></listitem>
1910 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-PKGDESTWORK'><filename>PKGDESTWORK</filename></ulink> -
1911 A temporary work area used by the
1912 <filename>do_package</filename> task.
1913 </para></listitem>
1914 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-PKGDEST'><filename>PKGDEST</filename></ulink> -
1915 The parent directory for packages after they have
1916 been split.
1917 </para></listitem>
1918 </itemizedlist>
1919 The <ulink url='&YOCTO_DOCS_REF_URL;#var-FILES'><filename>FILES</filename></ulink>
1920 variable defines the files that go into each package in
1921 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'><filename>PACKAGES</filename></ulink>.
1922 If you want details on how this is accomplished, you can
1923 look at the
1924 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-package'><filename>package</filename></ulink>
1925 class.
1926 </para>
1927
1928 <para>
1929 Depending on the type of packages being created (RPM, DEB, or
1930 IPK), the <filename>do_package_write_*</filename> task
1931 creates the actual packages and places them in the
1932 Package Feed area, which is
1933 <filename>${TMPDIR}/deploy</filename>.
1934 You can see the
1935 "<link linkend='package-feeds-dev-environment'>Package Feeds</link>"
1936 section for more detail on that part of the build process.
1937 <note>
1938 Support for creating feeds directly from the
1939 <filename>deploy/*</filename> directories does not exist.
1940 Creating such feeds usually requires some kind of feed
1941 maintenance mechanism that would upload the new packages
1942 into an official package feed (e.g. the
1943 Ångström distribution).
1944 This functionality is highly distribution-specific
1945 and thus is not provided out of the box.
1946 </note>
1947 </para>
1948 </section>
1949
1950 <section id='image-generation-dev-environment'>
1951 <title>Image Generation</title>
1952
1953 <para>
1954 Once packages are split and stored in the Package Feeds area,
1955 the OpenEmbedded build system uses BitBake to generate the
1956 root filesystem image:
1957 <imagedata fileref="figures/image-generation.png" align="center" width="6in" depth="7in" />
1958 </para>
1959
1960 <para>
1961 The image generation process consists of several stages and
1962 depends on several tasks and variables.
1963 The
1964 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-rootfs'><filename>do_rootfs</filename></ulink>
1965 task creates the root filesystem (file and directory structure)
1966 for an image.
1967 This task uses several key variables to help create the list
1968 of packages to actually install:
1969 <itemizedlist>
1970 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></ulink>:
1971 Lists out the base set of packages to install from
1972 the Package Feeds area.</para></listitem>
1973 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_EXCLUDE'><filename>PACKAGE_EXCLUDE</filename></ulink>:
1974 Specifies packages that should not be installed.
1975 </para></listitem>
1976 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></ulink>:
1977 Specifies features to include in the image.
1978 Most of these features map to additional packages for
1979 installation.</para></listitem>
1980 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></ulink>:
1981 Specifies the package backend to use and consequently
1982 helps determine where to locate packages within the
1983 Package Feeds area.</para></listitem>
1984 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_LINGUAS'><filename>IMAGE_LINGUAS</filename></ulink>:
1985 Determines the language(s) for which additional
1986 language support packages are installed.
1987 </para></listitem>
1988 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_INSTALL'><filename>PACKAGE_INSTALL</filename></ulink>:
1989 The final list of packages passed to the package manager
1990 for installation into the image.
1991 </para></listitem>
1992 </itemizedlist>
1993 </para>
1994
1995 <para>
1996 With
1997 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_ROOTFS'><filename>IMAGE_ROOTFS</filename></ulink>
1998 pointing to the location of the filesystem under construction and
1999 the <filename>PACKAGE_INSTALL</filename> variable providing the
2000 final list of packages to install, the root file system is
2001 created.
2002 </para>
2003
2004 <para>
2005 Package installation is under control of the package manager
2006 (e.g. dnf/rpm, opkg, or apt/dpkg) regardless of whether or
2007 not package management is enabled for the target.
2008 At the end of the process, if package management is not
2009 enabled for the target, the package manager's data files
2010 are deleted from the root filesystem.
2011 As part of the final stage of package installation, postinstall
2012 scripts that are part of the packages are run.
2013 Any scripts that fail to run
2014 on the build host are run on the target when the target system
2015 is first booted.
2016 If you are using a
2017 <ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-read-only-root-filesystem'>read-only root filesystem</ulink>,
2018 all the post installation scripts must succeed during the
2019 package installation phase since the root filesystem is
2020 read-only.
2021 </para>
2022
2023 <para>
2024 The final stages of the <filename>do_rootfs</filename> task
2025 handle post processing.
2026 Post processing includes creation of a manifest file and
2027 optimizations.
2028 </para>
2029
2030 <para>
2031 The manifest file (<filename>.manifest</filename>) resides
2032 in the same directory as the root filesystem image.
2033 This file lists out, line-by-line, the installed packages.
2034 The manifest file is useful for the
2035 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-testimage*'><filename>testimage</filename></ulink>
2036 class, for example, to determine whether or not to run
2037 specific tests.
2038 See the
2039 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_MANIFEST'><filename>IMAGE_MANIFEST</filename></ulink>
2040 variable for additional information.
2041 </para>
2042
2043 <para>
2044 Optimizing processes run across the image include
2045 <filename>mklibs</filename>, <filename>prelink</filename>,
2046 and any other post-processing commands as defined by the
2047 <ulink url='&YOCTO_DOCS_REF_URL;#var-ROOTFS_POSTPROCESS_COMMAND'><filename>ROOTFS_POSTPROCESS_COMMAND</filename></ulink>
2048 variable.
2049 The <filename>mklibs</filename> process optimizes the size
2050 of the libraries, while the
2051 <filename>prelink</filename> process optimizes the dynamic
2052 linking of shared libraries to reduce start up time of
2053 executables.
2054 </para>
2055
2056 <para>
2057 After the root filesystem is built, processing begins on
2058 the image through the
2059 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-image'><filename>do_image</filename></ulink>
2060 task.
2061 The build system runs any pre-processing commands as defined
2062 by the
2063 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_PREPROCESS_COMMAND'><filename>IMAGE_PREPROCESS_COMMAND</filename></ulink>
2064 variable.
2065 This variable specifies a list of functions to call before
2066 the OpenEmbedded build system creates the final image output
2067 files.
2068 </para>
2069
2070 <para>
2071 The OpenEmbedded build system dynamically creates
2072 <filename>do_image_*</filename> tasks as needed, based
2073 on the image types specified in the
2074 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></ulink>
2075 variable.
2076 The process turns everything into an image file or a set of
2077 image files and compresses the root filesystem image to reduce
2078 the overall size of the image.
2079 The formats used for the root filesystem depend on the
2080 <filename>IMAGE_FSTYPES</filename> variable.
2081 </para>
2082
2083 <para>
2084 As an example, a dynamically created task when creating a
2085 particular image <replaceable>type</replaceable> would take the
2086 following form:
2087 <literallayout class='monospaced'>
2088 do_image_<replaceable>type</replaceable>[depends]
2089 </literallayout>
2090 So, if the <replaceable>type</replaceable> as specified by the
2091 <filename>IMAGE_FSTYPES</filename> were
2092 <filename>ext4</filename>, the dynamically generated task
2093 would be as follows:
2094 <literallayout class='monospaced'>
2095 do_image_ext4[depends]
2096 </literallayout>
2097 </para>
2098
2099 <para>
2100 The final task involved in image creation is the
2101 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-image-complete'><filename>do_image_complete</filename></ulink>
2102 task.
2103 This task completes the image by applying any image
2104 post processing as defined through the
2105 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_POSTPROCESS_COMMAND'><filename>IMAGE_POSTPROCESS_COMMAND</filename></ulink>
2106 variable.
2107 The variable specifies a list of functions to call once the
2108 OpenEmbedded build system has created the final image output
2109 files.
2110 </para>
2111
2112 <note>
2113 The entire image generation process is run under Pseudo.
2114 Running under Pseudo ensures that the files in the root
2115 filesystem have correct ownership.
2116 </note>
2117 </section>
2118
2119 <section id='sdk-generation-dev-environment'>
2120 <title>SDK Generation</title>
2121
2122 <para>
2123 The OpenEmbedded build system uses BitBake to generate the
2124 Software Development Kit (SDK) installer script for both the
2125 standard and extensible SDKs:
2126 <imagedata fileref="figures/sdk-generation.png" align="center" />
2127 </para>
2128
2129 <note>
2130 For more information on the cross-development toolchain
2131 generation, see the
2132 "<ulink url='&YOCTO_DOCS_CM_URL;#cross-development-toolchain-generation'>Cross-Development Toolchain Generation</ulink>"
2133 section in the Yocto Project Concepts Manual.
2134 For information on advantages gained when building a
2135 cross-development toolchain using the
2136 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-populate_sdk'><filename>do_populate_sdk</filename></ulink>
2137 task, see the
2138 "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-building-an-sdk-installer'>Building an SDK Installer</ulink>"
2139 section in the Yocto Project Application Development and the
2140 Extensible Software Development Kit (SDK) manual.
2141 </note>
2142
2143 <para>
2144 Like image generation, the SDK script process consists of
2145 several stages and depends on many variables.
2146 The <filename>do_populate_sdk</filename> and
2147 <filename>do_populate_sdk_ext</filename> tasks use these
2148 key variables to help create the list of packages to actually
2149 install.
2150 For information on the variables listed in the figure, see the
2151 "<link linkend='sdk-dev-environment'>Application Development SDK</link>"
2152 section.
2153 </para>
2154
2155 <para>
2156 The <filename>do_populate_sdk</filename> task helps create
2157 the standard SDK and handles two parts: a target part and a
2158 host part.
2159 The target part is the part built for the target hardware and
2160 includes libraries and headers.
2161 The host part is the part of the SDK that runs on the
2162 <ulink url='&YOCTO_DOCS_REF_URL;#var-SDKMACHINE'><filename>SDKMACHINE</filename></ulink>.
2163 </para>
2164
2165 <para>
2166 The <filename>do_populate_sdk_ext</filename> task helps create
2167 the extensible SDK and handles host and target parts
2168 differently than its counter part does for the standard SDK.
2169 For the extensible SDK, the task encapsulates the build system,
2170 which includes everything needed (host and target) for the SDK.
2171 </para>
2172
2173 <para>
2174 Regardless of the type of SDK being constructed, the
2175 tasks perform some cleanup after which a cross-development
2176 environment setup script and any needed configuration files
2177 are created.
2178 The final output is the Cross-development
2179 toolchain installation script (<filename>.sh</filename> file),
2180 which includes the environment setup script.
2181 </para>
2182 </section>
2183
2184 <section id='stamp-files-and-the-rerunning-of-tasks'>
2185 <title>Stamp Files and the Rerunning of Tasks</title>
2186
2187 <para>
2188 For each task that completes successfully, BitBake writes a
2189 stamp file into the
2190 <ulink url='&YOCTO_DOCS_REF_URL;#var-STAMPS_DIR'><filename>STAMPS_DIR</filename></ulink>
2191 directory.
2192 The beginning of the stamp file's filename is determined by the
2193 <ulink url='&YOCTO_DOCS_REF_URL;#var-STAMP'><filename>STAMP</filename></ulink>
2194 variable, and the end of the name consists of the task's name
2195 and current
2196 <ulink url='&YOCTO_DOCS_CM_URL;#overview-checksums'>input checksum</ulink>.
2197 <note>
2198 This naming scheme assumes that
2199 <ulink url='&YOCTO_DOCS_BB_URL;#var-BB_SIGNATURE_HANDLER'><filename>BB_SIGNATURE_HANDLER</filename></ulink>
2200 is "OEBasicHash", which is almost always the case in
2201 current OpenEmbedded.
2202 </note>
2203 To determine if a task needs to be rerun, BitBake checks if a
2204 stamp file with a matching input checksum exists for the task.
2205 If such a stamp file exists, the task's output is assumed to
2206 exist and still be valid.
2207 If the file does not exist, the task is rerun.
2208 <note>
2209 <para>The stamp mechanism is more general than the shared
2210 state (sstate) cache mechanism described in the
2211 "<link linkend='setscene-tasks-and-shared-state'>Setscene Tasks and Shared State</link>"
2212 section.
2213 BitBake avoids rerunning any task that has a valid
2214 stamp file, not just tasks that can be accelerated through
2215 the sstate cache.</para>
2216 <para>However, you should realize that stamp files only
2217 serve as a marker that some work has been done and that
2218 these files do not record task output.
2219 The actual task output would usually be somewhere in
2220 <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>
2221 (e.g. in some recipe's
2222 <ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink>.)
2223 What the sstate cache mechanism adds is a way to cache task
2224 output that can then be shared between build machines.
2225 </para>
2226 </note>
2227 Since <filename>STAMPS_DIR</filename> is usually a subdirectory
2228 of <filename>TMPDIR</filename>, removing
2229 <filename>TMPDIR</filename> will also remove
2230 <filename>STAMPS_DIR</filename>, which means tasks will
2231 properly be rerun to repopulate <filename>TMPDIR</filename>.
2232 </para>
2233
2234 <para>
2235 If you want some task to always be considered "out of date",
2236 you can mark it with the
2237 <ulink url='&YOCTO_DOCS_BB_URL;#variable-flags'><filename>nostamp</filename></ulink>
2238 varflag.
2239 If some other task depends on such a task, then that task will
2240 also always be considered out of date, which might not be what
2241 you want.
2242 </para>
2243
2244 <para>
2245 For details on how to view information about a task's
2246 signature, see the
2247 "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-viewing-task-variable-dependencies'>Viewing Task Variable Dependencies</ulink>"
2248 section in the Yocto Project Development Tasks Manual.
2249 </para>
2250 </section>
2251
2252 <section id='setscene-tasks-and-shared-state'>
2253 <title>Setscene Tasks and Shared State</title>
2254
2255 <para>
2256 The description of tasks so far assumes that BitBake needs to
2257 build everything and there are no prebuilt objects available.
2258 BitBake does support skipping tasks if prebuilt objects are
2259 available.
2260 These objects are usually made available in the form of a
2261 shared state (sstate) cache.
2262 <note>
2263 For information on variables affecting sstate, see the
2264 <ulink url='&YOCTO_DOCS_REF_URL;#var-SSTATE_DIR'><filename>SSTATE_DIR</filename></ulink>
2265 and
2266 <ulink url='&YOCTO_DOCS_REF_URL;#var-SSTATE_MIRRORS'><filename>SSTATE_MIRRORS</filename></ulink>
2267 variables.
2268 </note>
2269 </para>
2270
2271 <para>
2272 The idea of a setscene task (i.e
2273 <filename>do_</filename><replaceable>taskname</replaceable><filename>_setscene</filename>)
2274 is a version of the task where
2275 instead of building something, BitBake can skip to the end
2276 result and simply place a set of files into specific locations
2277 as needed.
2278 In some cases, it makes sense to have a setscene task variant
2279 (e.g. generating package files in the
2280 <filename>do_package_write_*</filename> task).
2281 In other cases, it does not make sense, (e.g. a
2282 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-patch'><filename>do_patch</filename></ulink>
2283 task or
2284 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-unpack'><filename>do_unpack</filename></ulink>
2285 task) since the work involved would be equal to or greater than
2286 the underlying task.
2287 </para>
2288
2289 <para>
2290 In the OpenEmbedded build system, the common tasks that have
2291 setscene variants are
2292 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package'><filename>do_package</filename></ulink>,
2293 <filename>do_package_write_*</filename>,
2294 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-deploy'><filename>do_deploy</filename></ulink>,
2295 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-packagedata'><filename>do_packagedata</filename></ulink>,
2296 and
2297 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></ulink>.
2298 Notice that these are most of the tasks whose output is an
2299 end result.
2300 </para>
2301
2302 <para>
2303 The OpenEmbedded build system has knowledge of the relationship
2304 between these tasks and other tasks that precede them.
2305 For example, if BitBake runs
2306 <filename>do_populate_sysroot_setscene</filename> for
2307 something, there is little point in running any of the
2308 <filename>do_fetch</filename>, <filename>do_unpack</filename>,
2309 <filename>do_patch</filename>,
2310 <filename>do_configure</filename>,
2311 <filename>do_compile</filename>, and
2312 <filename>do_install</filename> tasks.
2313 However, if <filename>do_package</filename> needs to be run,
2314 BitBake would need to run those other tasks.
2315 </para>
2316
2317 <para>
2318 It becomes more complicated if everything can come from an
2319 sstate cache because some objects are simply not required at
2320 all.
2321 For example, you do not need a compiler or native tools, such
2322 as quilt, if there is nothing to compile or patch.
2323 If the <filename>do_package_write_*</filename> packages are
2324 available from sstate, BitBake does not need the
2325 <filename>do_package</filename> task data.
2326 </para>
2327
2328 <para>
2329 To handle all these complexities, BitBake runs in two phases.
2330 The first is the "setscene" stage.
2331 During this stage, BitBake first checks the sstate cache for
2332 any targets it is planning to build.
2333 BitBake does a fast check to see if the object exists rather
2334 than a complete download.
2335 If nothing exists, the second phase, which is the setscene
2336 stage, completes and the main build proceeds.
2337 </para>
2338
2339 <para>
2340 If objects are found in the sstate cache, the OpenEmbedded
2341 build system works backwards from the end targets specified
2342 by the user.
2343 For example, if an image is being built, the OpenEmbedded build
2344 system first looks for the packages needed for that image and
2345 the tools needed to construct an image.
2346 If those are available, the compiler is not needed.
2347 Thus, the compiler is not even downloaded.
2348 If something was found to be unavailable, or the download or
2349 setscene task fails, the OpenEmbedded build system then tries
2350 to install dependencies, such as the compiler, from the cache.
2351 </para>
2352
2353 <para>
2354 The availability of objects in the sstate cache is handled by
2355 the function specified by the
2356 <ulink url='&YOCTO_DOCS_BB_URL;#var-BB_HASHCHECK_FUNCTION'><filename>BB_HASHCHECK_FUNCTION</filename></ulink>
2357 variable and returns a list of the objects that are available.
2358 The function specified by the
2359 <ulink url='&YOCTO_DOCS_BB_URL;#var-BB_SETSCENE_DEPVALID'><filename>BB_SETSCENE_DEPVALID</filename></ulink>
2360 variable is the function that determines whether a given
2361 dependency needs to be followed, and whether for any given
2362 relationship the function needs to be passed.
2363 The function returns a True or False value.
2364 </para>
2365 </section>
2366 </section>
2367
2368 <section id='images-dev-environment'>
2369 <title>Images</title>
2370
2371 <para>
2372 The images produced by the OpenEmbedded build system
2373 are compressed forms of the
2374 root filesystem that are ready to boot on a target device.
2375 You can see from the
2376 <link linkend='general-yocto-environment-figure'>general Yocto Project Development Environment figure</link>
2377 that BitBake output, in part, consists of images.
2378 This section is going to look more closely at this output:
2379 <imagedata fileref="figures/images.png" align="center" width="5.5in" depth="5.5in" />
2380 </para>
2381
2382 <para>
2383 For a list of example images that the Yocto Project provides,
2384 see the
2385 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>"
2386 chapter in the Yocto Project Reference Manual.
2387 </para>
2388
2389 <para>
2390 Images are written out to the
2391 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
2392 inside the
2393 <filename>tmp/deploy/images/<replaceable>machine</replaceable>/</filename>
2394 folder as shown in the figure.
2395 This folder contains any files expected to be loaded on the
2396 target device.
2397 The
2398 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></ulink>
2399 variable points to the <filename>deploy</filename> directory,
2400 while the
2401 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPLOY_DIR_IMAGE'><filename>DEPLOY_DIR_IMAGE</filename></ulink>
2402 variable points to the appropriate directory containing images for
2403 the current configuration.
2404 <itemizedlist>
2405 <listitem><para><filename><replaceable>kernel-image</replaceable></filename>:
2406 A kernel binary file.
2407 The
2408 <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_IMAGETYPE'><filename>KERNEL_IMAGETYPE</filename></ulink>
2409 variable setting determines the naming scheme for the
2410 kernel image file.
2411 Depending on that variable, the file could begin with
2412 a variety of naming strings.
2413 The <filename>deploy/images/<replaceable>machine</replaceable></filename>
2414 directory can contain multiple image files for the
2415 machine.</para></listitem>
2416 <listitem><para><filename><replaceable>root-filesystem-image</replaceable></filename>:
2417 Root filesystems for the target device (e.g.
2418 <filename>*.ext3</filename> or <filename>*.bz2</filename>
2419 files).
2420 The
2421 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></ulink>
2422 variable setting determines the root filesystem image
2423 type.
2424 The <filename>deploy/images/<replaceable>machine</replaceable></filename>
2425 directory can contain multiple root filesystems for the
2426 machine.</para></listitem>
2427 <listitem><para><filename><replaceable>kernel-modules</replaceable></filename>:
2428 Tarballs that contain all the modules built for the kernel.
2429 Kernel module tarballs exist for legacy purposes and
2430 can be suppressed by setting the
2431 <ulink url='&YOCTO_DOCS_REF_URL;#var-MODULE_TARBALL_DEPLOY'><filename>MODULE_TARBALL_DEPLOY</filename></ulink>
2432 variable to "0".
2433 The <filename>deploy/images/<replaceable>machine</replaceable></filename>
2434 directory can contain multiple kernel module tarballs
2435 for the machine.</para></listitem>
2436 <listitem><para><filename><replaceable>bootloaders</replaceable></filename>:
2437 Bootloaders supporting the image, if applicable to the
2438 target machine.
2439 The <filename>deploy/images/<replaceable>machine</replaceable></filename>
2440 directory can contain multiple bootloaders for the
2441 machine.</para></listitem>
2442 <listitem><para><filename><replaceable>symlinks</replaceable></filename>:
2443 The <filename>deploy/images/<replaceable>machine</replaceable></filename>
2444 folder contains
2445 a symbolic link that points to the most recently built file
2446 for each machine.
2447 These links might be useful for external scripts that
2448 need to obtain the latest version of each file.
2449 </para></listitem>
2450 </itemizedlist>
2451 </para>
2452 </section>
2453
2454 <section id='sdk-dev-environment'>
2455 <title>Application Development SDK</title>
2456
2457 <para>
2458 In the
2459 <link linkend='general-yocto-environment-figure'>general Yocto Project Development Environment figure</link>,
2460 the output labeled "Application Development SDK" represents an
2461 SDK.
2462 The SDK generation process differs depending on whether you build
2463 a standard SDK
2464 (e.g. <filename>bitbake -c populate_sdk</filename> <replaceable>imagename</replaceable>)
2465 or an extensible SDK
2466 (e.g. <filename>bitbake -c populate_sdk_ext</filename> <replaceable>imagename</replaceable>).
2467 This section is going to take a closer look at this output:
2468 <imagedata fileref="figures/sdk.png" align="center" width="9in" depth="7.25in" />
2469 </para>
2470
2471 <para>
2472 The specific form of this output is a self-extracting
2473 SDK installer (<filename>*.sh</filename>) that, when run,
2474 installs the SDK, which consists of a cross-development
2475 toolchain, a set of libraries and headers, and an SDK
2476 environment setup script.
2477 Running this installer essentially sets up your
2478 cross-development environment.
2479 You can think of the cross-toolchain as the "host"
2480 part because it runs on the SDK machine.
2481 You can think of the libraries and headers as the "target"
2482 part because they are built for the target hardware.
2483 The environment setup script is added so that you can initialize
2484 the environment before using the tools.
2485 </para>
2486
2487 <note><title>Notes</title>
2488 <itemizedlist>
2489 <listitem><para>
2490 The Yocto Project supports several methods by which you can
2491 set up this cross-development environment.
2492 These methods include downloading pre-built SDK installers
2493 or building and installing your own SDK installer.
2494 </para></listitem>
2495 <listitem><para>
2496 For background information on cross-development toolchains
2497 in the Yocto Project development environment, see the
2498 "<ulink url='&YOCTO_DOCS_CM_URL;#cross-development-toolchain-generation'>Cross-Development Toolchain Generation</ulink>"
2499 section in the Yocto Projects Concepts Manual.
2500 </para></listitem>
2501 <listitem><para>
2502 For information on setting up a cross-development
2503 environment, see the
2504 <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink>
2505 manual.
2506 </para></listitem>
2507 </itemizedlist>
2508 </note>
2509
2510 <para>
2511 Once built, the SDK installers are written out to the
2512 <filename>deploy/sdk</filename> folder inside the
2513 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
2514 as shown in the figure at the beginning of this section.
2515 Depending on the type of SDK, several variables exist that help
2516 configure these files.
2517 The following list shows the variables associated with a standard
2518 SDK:
2519 <itemizedlist>
2520 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></ulink>:
2521 Points to the <filename>deploy</filename>
2522 directory.</para></listitem>
2523 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-SDKMACHINE'><filename>SDKMACHINE</filename></ulink>:
2524 Specifies the architecture of the machine
2525 on which the cross-development tools are run to
2526 create packages for the target hardware.
2527 </para></listitem>
2528 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-SDKIMAGE_FEATURES'><filename>SDKIMAGE_FEATURES</filename></ulink>:
2529 Lists the features to include in the "target" part
2530 of the SDK.
2531 </para></listitem>
2532 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-TOOLCHAIN_HOST_TASK'><filename>TOOLCHAIN_HOST_TASK</filename></ulink>:
2533 Lists packages that make up the host
2534 part of the SDK (i.e. the part that runs on
2535 the <filename>SDKMACHINE</filename>).
2536 When you use
2537 <filename>bitbake -c populate_sdk <replaceable>imagename</replaceable></filename>
2538 to create the SDK, a set of default packages
2539 apply.
2540 This variable allows you to add more packages.
2541 </para></listitem>
2542 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-TOOLCHAIN_TARGET_TASK'><filename>TOOLCHAIN_TARGET_TASK</filename></ulink>:
2543 Lists packages that make up the target part
2544 of the SDK (i.e. the part built for the
2545 target hardware).
2546 </para></listitem>
2547 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-SDKPATH'><filename>SDKPATH</filename></ulink>:
2548 Defines the default SDK installation path offered by the
2549 installation script.
2550 </para></listitem>
2551 </itemizedlist>
2552 This next list, shows the variables associated with an extensible
2553 SDK:
2554 <itemizedlist>
2555 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></ulink>:
2556 Points to the <filename>deploy</filename> directory.
2557 </para></listitem>
2558 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_EXT_TYPE'><filename>SDK_EXT_TYPE</filename></ulink>:
2559 Controls whether or not shared state artifacts are copied
2560 into the extensible SDK.
2561 By default, all required shared state artifacts are copied
2562 into the SDK.
2563 </para></listitem>
2564 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_INCLUDE_PKGDATA'><filename>SDK_INCLUDE_PKGDATA</filename></ulink>:
2565 Specifies whether or not packagedata will be included in
2566 the extensible SDK for all recipes in the "world" target.
2567 </para></listitem>
2568 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_INCLUDE_TOOLCHAIN'><filename>SDK_INCLUDE_TOOLCHAIN</filename></ulink>:
2569 Specifies whether or not the toolchain will be included
2570 when building the extensible SDK.
2571 </para></listitem>
2572 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_LOCAL_CONF_WHITELIST'><filename>SDK_LOCAL_CONF_WHITELIST</filename></ulink>:
2573 A list of variables allowed through from the build system
2574 configuration into the extensible SDK configuration.
2575 </para></listitem>
2576 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_LOCAL_CONF_BLACKLIST'><filename>SDK_LOCAL_CONF_BLACKLIST</filename></ulink>:
2577 A list of variables not allowed through from the build
2578 system configuration into the extensible SDK configuration.
2579 </para></listitem>
2580 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_INHERIT_BLACKLIST'><filename>SDK_INHERIT_BLACKLIST</filename></ulink>:
2581 A list of classes to remove from the
2582 <ulink url='&YOCTO_DOCS_REF_URL;#var-INHERIT'><filename>INHERIT</filename></ulink>
2583 value globally within the extensible SDK configuration.
2584 </para></listitem>
2585 </itemizedlist>
2586 </para>
2587 </section>
2588</section>
2589
2590</chapter> 940</chapter>
2591<!-- 941<!--
2592vim: expandtab tw=80 ts=4 942vim: expandtab tw=80 ts=4
diff --git a/documentation/ref-manual/ref-classes.xml b/documentation/ref-manual/ref-classes.xml
index ff13213fad..8dfa0851cd 100644
--- a/documentation/ref-manual/ref-classes.xml
+++ b/documentation/ref-manual/ref-classes.xml
@@ -1251,8 +1251,8 @@
1251 "<ulink url='&YOCTO_DOCS_DEV_URL;#usingpoky-extend-customimage'>Customizing Images</ulink>" 1251 "<ulink url='&YOCTO_DOCS_DEV_URL;#usingpoky-extend-customimage'>Customizing Images</ulink>"
1252 section in the Yocto Project Development Tasks Manual. 1252 section in the Yocto Project Development Tasks Manual.
1253 For information on how images are created, see the 1253 For information on how images are created, see the
1254 "<ulink url='&YOCTO_DOCS_GS_URL;#images-dev-environment'>Images</ulink>" 1254 "<ulink url='&YOCTO_DOCS_CM_URL;#images-dev-environment'>Images</ulink>"
1255 section in the Getting Started With Yocto Project Manual. 1255 section in the Yocto Project Concpets Manual.
1256 </para> 1256 </para>
1257</section> 1257</section>
1258 1258
@@ -3020,8 +3020,8 @@ This check was removed for YP 2.3 release
3020 3020
3021 <para> 3021 <para>
3022 For information on how root filesystem images are created, see the 3022 For information on how root filesystem images are created, see the
3023 "<ulink url='&YOCTO_DOCS_GS_URL;#image-generation-dev-environment'>Image Generation</ulink>" 3023 "<ulink url='&YOCTO_DOCS_CM_URL;#image-generation-dev-environment'>Image Generation</ulink>"
3024 section in the Getting Started With Yocto Project Manual. 3024 section in the Yocto Project Concepts Manual.
3025 </para> 3025 </para>
3026</section> 3026</section>
3027 3027
diff --git a/documentation/ref-manual/ref-structure.xml b/documentation/ref-manual/ref-structure.xml
index 1a409909bf..5d30987956 100644
--- a/documentation/ref-manual/ref-structure.xml
+++ b/documentation/ref-manual/ref-structure.xml
@@ -520,10 +520,10 @@
520 variable points to this directory. 520 variable points to this directory.
521 For more detail on the contents of the <filename>deploy</filename> 521 For more detail on the contents of the <filename>deploy</filename>
522 directory, see the 522 directory, see the
523 "<ulink url='&YOCTO_DOCS_GS_URL;#images-dev-environment'>Images</ulink>" 523 "<ulink url='&YOCTO_DOCS_CM_URL;#images-dev-environment'>Images</ulink>"
524 and 524 and
525 "<ulink url='&YOCTO_DOCS_GS_URL;#sdk-dev-environment'>Application Development SDK</ulink>" 525 "<ulink url='&YOCTO_DOCS_CM_URL;#sdk-dev-environment'>Application Development SDK</ulink>"
526 sections in the Getting Started With Yocto Project Manual. 526 sections in the Yocto Project Concepts Manual.
527 </para> 527 </para>
528 </section> 528 </section>
529 529
@@ -696,8 +696,8 @@
696 <para> 696 <para>
697 For information on how BitBake uses stamp files to determine if 697 For information on how BitBake uses stamp files to determine if
698 a task should be rerun, see the 698 a task should be rerun, see the
699 "<ulink url='&YOCTO_DOCS_GS_URL;#stamp-files-and-the-rerunning-of-tasks'>Stamp Files and the Rerunning of Tasks</ulink>" 699 "<ulink url='&YOCTO_DOCS_CM_URL;#stamp-files-and-the-rerunning-of-tasks'>Stamp Files and the Rerunning of Tasks</ulink>"
700 section in the Getting Started With Yocto Project Manual. 700 section in the Yocto Project Concepts Manual.
701 </para> 701 </para>
702 </section> 702 </section>
703 703
diff --git a/documentation/ref-manual/ref-tasks.xml b/documentation/ref-manual/ref-tasks.xml
index 007d08f112..a463717fe7 100644
--- a/documentation/ref-manual/ref-tasks.xml
+++ b/documentation/ref-manual/ref-tasks.xml
@@ -220,8 +220,8 @@
220 220
221 <para> 221 <para>
222 For more information on image creation, see the 222 For more information on image creation, see the
223 "<ulink url='&YOCTO_DOCS_GS_URL;#image-generation-dev-environment'>Image Generation</ulink>" 223 "<ulink url='&YOCTO_DOCS_CM_URL;#image-generation-dev-environment'>Image Generation</ulink>"
224 section in the Getting Started With Yocto Project Manual. 224 section in the Yocto Project Concepts Manual.
225 </para> 225 </para>
226 </section> 226 </section>
227 227
@@ -246,8 +246,8 @@
246 246
247 <para> 247 <para>
248 For more information on image creation, see the 248 For more information on image creation, see the
249 "<ulink url='&YOCTO_DOCS_GS_URL;#image-generation-dev-environment'>Image Generation</ulink>" 249 "<ulink url='&YOCTO_DOCS_CM_URL;#image-generation-dev-environment'>Image Generation</ulink>"
250 section in the Getting Started With Yocto Project Manual. 250 section in the Yocto Project Concepts Manual.
251 </para> 251 </para>
252 </section> 252 </section>
253 253
@@ -367,8 +367,8 @@
367 <filename>${</filename><link linkend='var-DEPLOY_DIR_DEB'><filename>DEPLOY_DIR_DEB</filename></link><filename>}</filename> 367 <filename>${</filename><link linkend='var-DEPLOY_DIR_DEB'><filename>DEPLOY_DIR_DEB</filename></link><filename>}</filename>
368 directory in the package feeds area. 368 directory in the package feeds area.
369 For more information, see the 369 For more information, see the
370 "<ulink url='&YOCTO_DOCS_GS_URL;#package-feeds-dev-environment'>Package Feeds</ulink>" 370 "<ulink url='&YOCTO_DOCS_CM_URL;#package-feeds-dev-environment'>Package Feeds</ulink>"
371 section in the Getting Started With Yocto Project Manual. 371 section in the Yocto Project Concepts Manual.
372 </para> 372 </para>
373 </section> 373 </section>
374 374
@@ -381,8 +381,8 @@
381 <filename>${</filename><link linkend='var-DEPLOY_DIR_IPK'><filename>DEPLOY_DIR_IPK</filename></link><filename>}</filename> 381 <filename>${</filename><link linkend='var-DEPLOY_DIR_IPK'><filename>DEPLOY_DIR_IPK</filename></link><filename>}</filename>
382 directory in the package feeds area. 382 directory in the package feeds area.
383 For more information, see the 383 For more information, see the
384 "<ulink url='&YOCTO_DOCS_GS_URL;#package-feeds-dev-environment'>Package Feeds</ulink>" 384 "<ulink url='&YOCTO_DOCS_CM_URL;#package-feeds-dev-environment'>Package Feeds</ulink>"
385 section in the Getting Started With Yocto Project Manual. 385 section in the Yocto Project Concepts Manual.
386 </para> 386 </para>
387 </section> 387 </section>
388 388
@@ -395,8 +395,8 @@
395 <filename>${</filename><link linkend='var-DEPLOY_DIR_RPM'><filename>DEPLOY_DIR_RPM</filename></link><filename>}</filename> 395 <filename>${</filename><link linkend='var-DEPLOY_DIR_RPM'><filename>DEPLOY_DIR_RPM</filename></link><filename>}</filename>
396 directory in the package feeds area. 396 directory in the package feeds area.
397 For more information, see the 397 For more information, see the
398 "<ulink url='&YOCTO_DOCS_GS_URL;#package-feeds-dev-environment'>Package Feeds</ulink>" 398 "<ulink url='&YOCTO_DOCS_CM_URL;#package-feeds-dev-environment'>Package Feeds</ulink>"
399 section in the Getting Started With Yocto Project Manual. 399 section in the Yocto Project Concepts Manual.
400 </para> 400 </para>
401 </section> 401 </section>
402 402
@@ -408,8 +408,8 @@
408 <filename>${</filename><link linkend='var-DEPLOY_DIR_TAR'><filename>DEPLOY_DIR_TAR</filename></link><filename>}</filename> 408 <filename>${</filename><link linkend='var-DEPLOY_DIR_TAR'><filename>DEPLOY_DIR_TAR</filename></link><filename>}</filename>
409 directory in the package feeds area. 409 directory in the package feeds area.
410 For more information, see the 410 For more information, see the
411 "<ulink url='&YOCTO_DOCS_GS_URL;#package-feeds-dev-environment'>Package Feeds</ulink>" 411 "<ulink url='&YOCTO_DOCS_CM_URL;#package-feeds-dev-environment'>Package Feeds</ulink>"
412 section Getting Started With Yocto Project Manual. 412 section Yocto Project Concepts Manual.
413 </para> 413 </para>
414 </section> 414 </section>
415 415
@@ -431,8 +431,8 @@
431 <para> 431 <para>
432 Locates patch files and applies them to the source code. 432 Locates patch files and applies them to the source code.
433 See the 433 See the
434 "<ulink url='&YOCTO_DOCS_GS_URL;#patching-dev-environment'>Patching</ulink>" 434 "<ulink url='&YOCTO_DOCS_CM_URL;#patching-dev-environment'>Patching</ulink>"
435 section in the Getting Started With Yocto Project Manual for more 435 section in the Yocto Project Concepts Manual for more
436 information. 436 information.
437 </para> 437 </para>
438 </section> 438 </section>
@@ -452,8 +452,8 @@
452 <para> 452 <para>
453 Creates the file and directory structure for an installable SDK. 453 Creates the file and directory structure for an installable SDK.
454 See the 454 See the
455 "<ulink url='&YOCTO_DOCS_GS_URL;#sdk-generation-dev-environment'>SDK Generation</ulink>" 455 "<ulink url='&YOCTO_DOCS_CM_URL;#sdk-generation-dev-environment'>SDK Generation</ulink>"
456 section in the Getting Started With Yocto Project Manual for more 456 section in the Yocto Project Concepts Manual for more
457 information. 457 information.
458 </para> 458 </para>
459 </section> 459 </section>
@@ -540,8 +540,8 @@
540 <link linkend='var-S'><filename>S</filename></link> variable also 540 <link linkend='var-S'><filename>S</filename></link> variable also
541 plays a role in where unpacked source files ultimately reside. 541 plays a role in where unpacked source files ultimately reside.
542 For more information on how source files are unpacked, see the 542 For more information on how source files are unpacked, see the
543 "<ulink url='&YOCTO_DOCS_GS_URL;#source-fetching-dev-environment'>Source Fetching</ulink>" 543 "<ulink url='&YOCTO_DOCS_CM_URL;#source-fetching-dev-environment'>Source Fetching</ulink>"
544 section in the Getting Started With Yocto Project Manual and also 544 section in the Yocto Project Concepts Manual and also
545 see the <filename>WORKDIR</filename> and 545 see the <filename>WORKDIR</filename> and
546 <filename>S</filename> variable descriptions. 546 <filename>S</filename> variable descriptions.
547 </para> 547 </para>
@@ -762,7 +762,7 @@
762 762
763 <para> 763 <para>
764 Creates or updates the index in the 764 Creates or updates the index in the
765 <ulink url='&YOCTO_DOCS_GS_URL;#package-feeds-dev-environment'>Package Feeds</ulink> 765 <ulink url='&YOCTO_DOCS_CM_URL;#package-feeds-dev-environment'>Package Feeds</ulink>
766 area. 766 area.
767 <note> 767 <note>
768 This task is not triggered with the 768 This task is not triggered with the
@@ -814,8 +814,8 @@
814 Creates the root filesystem (file and directory structure) for an 814 Creates the root filesystem (file and directory structure) for an
815 image. 815 image.
816 See the 816 See the
817 "<ulink url='&YOCTO_DOCS_GS_URL;#image-generation-dev-environment'>Image Generation</ulink>" 817 "<ulink url='&YOCTO_DOCS_CM_URL;#image-generation-dev-environment'>Image Generation</ulink>"
818 section in the Getting Started With Yocto Project Manual for more 818 section in the Yocto Project Concepts Manual for more
819 information on how the root filesystem is created. 819 information on how the root filesystem is created.
820 </para> 820 </para>
821 </section> 821 </section>
diff --git a/documentation/ref-manual/ref-variables.xml b/documentation/ref-manual/ref-variables.xml
index f2497249b5..137a556d92 100644
--- a/documentation/ref-manual/ref-variables.xml
+++ b/documentation/ref-manual/ref-variables.xml
@@ -3329,13 +3329,11 @@
3329 section. 3329 section.
3330 For more detail on the contents of the 3330 For more detail on the contents of the
3331 <filename>deploy</filename> directory, see the 3331 <filename>deploy</filename> directory, see the
3332 "<ulink url='&YOCTO_DOCS_GS_URL;#images-dev-environment'>Images</ulink>" 3332 "<ulink url='&YOCTO_DOCS_CM_URL;#images-dev-environment'>Images</ulink>",
3333 section, the 3333 "<ulink url='&YOCTO_DOCS_CM_URL;#package-feeds-dev-environment'>Package Feeds</ulink>",
3334 "<ulink url='&YOCTO_DOCS_GS_URL;#package-feeds-dev-environment'>Package Feeds</ulink>" 3334 and
3335 section, and the 3335 "<ulink url='&YOCTO_DOCS_CM_URL;#sdk-dev-environment'>Application Development SDK</ulink>"
3336 "<ulink url='&YOCTO_DOCS_GS_URL;#sdk-dev-environment'>Application Development SDK</ulink>" 3336 sections all in the Yocto Project Concepts Manual.
3337 sections all in the Getting Started With Yocto Project
3338 Manual.
3339 </para> 3337 </para>
3340 </glossdef> 3338 </glossdef>
3341 </glossentry> 3339 </glossentry>
@@ -3374,8 +3372,8 @@
3374 <link linkend='ref-tasks-package_write_deb'><filename>do_package_write_deb</filename></link> 3372 <link linkend='ref-tasks-package_write_deb'><filename>do_package_write_deb</filename></link>
3375 task writes Debian packages into the appropriate folder. 3373 task writes Debian packages into the appropriate folder.
3376 For more information on how packaging works, see the 3374 For more information on how packaging works, see the
3377 "<ulink url='&YOCTO_DOCS_GS_URL;#package-feeds-dev-environment'>Package Feeds</ulink>" 3375 "<ulink url='&YOCTO_DOCS_CM_URL;#package-feeds-dev-environment'>Package Feeds</ulink>"
3378 section in the Getting Started With Yocto Project Manual. 3376 section in the Yocto Project Concepts Manual.
3379 </para> 3377 </para>
3380 </glossdef> 3378 </glossdef>
3381 </glossentry> 3379 </glossentry>
@@ -3404,11 +3402,10 @@
3404 section. 3402 section.
3405 For more detail on the contents of the 3403 For more detail on the contents of the
3406 <filename>deploy</filename> directory, see the 3404 <filename>deploy</filename> directory, see the
3407 "<ulink url='&YOCTO_DOCS_GS_URL;#images-dev-environment'>Images</ulink>" 3405 "<ulink url='&YOCTO_DOCS_CM_URL;#images-dev-environment'>Images</ulink>"
3408 and 3406 and
3409 "<ulink url='&YOCTO_DOCS_GS_URL;#sdk-dev-environment'>Application Development SDK</ulink>" 3407 "<ulink url='&YOCTO_DOCS_CM_URL;#sdk-dev-environment'>Application Development SDK</ulink>"
3410 sections both in the Getting Started With Yocto Project 3408 sections both in the Yocto Project Concepts Manual.
3411 Manual.
3412 </para> 3409 </para>
3413 </glossdef> 3410 </glossdef>
3414 </glossentry> 3411 </glossentry>
@@ -3446,8 +3443,8 @@
3446 <link linkend='ref-tasks-package_write_ipk'><filename>do_package_write_ipk</filename></link> 3443 <link linkend='ref-tasks-package_write_ipk'><filename>do_package_write_ipk</filename></link>
3447 task writes IPK packages into the appropriate folder. 3444 task writes IPK packages into the appropriate folder.
3448 For more information on how packaging works, see the 3445 For more information on how packaging works, see the
3449 "<ulink url='&YOCTO_DOCS_GS_URL;#package-feeds-dev-environment'>Package Feeds</ulink>" 3446 "<ulink url='&YOCTO_DOCS_CM_URL;#package-feeds-dev-environment'>Package Feeds</ulink>"
3450 section in the Getting Started With Yocto Project Manual. 3447 section in the Yocto Project Concepts Manual.
3451 </para> 3448 </para>
3452 </glossdef> 3449 </glossdef>
3453 </glossentry> 3450 </glossentry>
@@ -3485,8 +3482,8 @@
3485 <link linkend='ref-tasks-package_write_rpm'><filename>do_package_write_rpm</filename></link> 3482 <link linkend='ref-tasks-package_write_rpm'><filename>do_package_write_rpm</filename></link>
3486 task writes RPM packages into the appropriate folder. 3483 task writes RPM packages into the appropriate folder.
3487 For more information on how packaging works, see the 3484 For more information on how packaging works, see the
3488 "<ulink url='&YOCTO_DOCS_GS_URL;#package-feeds-dev-environment'>Package Feeds</ulink>" 3485 "<ulink url='&YOCTO_DOCS_CM_URL;#package-feeds-dev-environment'>Package Feeds</ulink>"
3489 section. 3486 section in the Yocto Project Concepts Manual.
3490 </para> 3487 </para>
3491 </glossdef> 3488 </glossdef>
3492 </glossentry> 3489 </glossentry>
@@ -3524,8 +3521,8 @@
3524 <link linkend='ref-tasks-package_write_tar'><filename>do_package_write_tar</filename></link> 3521 <link linkend='ref-tasks-package_write_tar'><filename>do_package_write_tar</filename></link>
3525 task writes TAR packages into the appropriate folder. 3522 task writes TAR packages into the appropriate folder.
3526 For more information on how packaging works, see the 3523 For more information on how packaging works, see the
3527 "<ulink url='&YOCTO_DOCS_GS_URL;#package-feeds-dev-environment'>Package Feeds</ulink>" 3524 "<ulink url='&YOCTO_DOCS_CM_URL;#package-feeds-dev-environment'>Package Feeds</ulink>"
3528 section in the Getting Started With Yocto Project Manual. 3525 section in the Yocto Project Concepts Manual.
3529 </para> 3526 </para>
3530 </glossdef> 3527 </glossdef>
3531 </glossentry> 3528 </glossentry>
@@ -6086,8 +6083,8 @@
6086 variables. 6083 variables.
6087 You can find information on how the image 6084 You can find information on how the image
6088 is created in the 6085 is created in the
6089 "<ulink url='&YOCTO_DOCS_GS_URL;#image-generation-dev-environment'>Image Generation</ulink>" 6086 "<ulink url='&YOCTO_DOCS_CM_URL;#image-generation-dev-environment'>Image Generation</ulink>"
6090 section in the Getting Started With Yocto Project Manual. 6087 section in the Yocto Project Concepts Manual.
6091 </para> 6088 </para>
6092 </glossdef> 6089 </glossdef>
6093 </glossentry> 6090 </glossentry>
@@ -13697,8 +13694,8 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
13697 <para> 13694 <para>
13698 For information on how BitBake uses stamp files to determine 13695 For information on how BitBake uses stamp files to determine
13699 if a task should be rerun, see the 13696 if a task should be rerun, see the
13700 "<ulink url='&YOCTO_DOCS_GS_URL;#stamp-files-and-the-rerunning-of-tasks'>Stamp Files and the Rerunning of Tasks</ulink>" 13697 "<ulink url='&YOCTO_DOCS_CM_URL;#stamp-files-and-the-rerunning-of-tasks'>Stamp Files and the Rerunning of Tasks</ulink>"
13701 section in the Getting Started With Yocto Project Manual. 13698 section in the Yocto Project Concepts Manual.
13702 </para> 13699 </para>
13703 13700
13704 <para> 13701 <para>
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2026-01-21 23:56:49 +0000