summaryrefslogtreecommitdiffstats
path: root/documentation/concepts-manual
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 /documentation/concepts-manual
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 (limited to 'documentation/concepts-manual')
-rw-r--r--documentation/concepts-manual/concepts-manual-concepts.xml1796
1 files changed, 1794 insertions, 2 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
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2026-08-03 15:40:07 +0000