summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
Diffstat
-rw-r--r--documentation/bsp-guide/bsp.xml2
-rw-r--r--documentation/dev-manual/dev-manual-newbie.xml346
-rw-r--r--documentation/dev-manual/dev-manual-start.xml3
-rw-r--r--documentation/kernel-dev/kernel-dev-advanced.xml2
-rw-r--r--documentation/kernel-dev/kernel-dev-common.xml2
-rw-r--r--documentation/ref-manual/closer-look.xml4
-rw-r--r--documentation/ref-manual/faq.xml4
-rw-r--r--documentation/ref-manual/introduction.xml348
-rw-r--r--documentation/ref-manual/migration.xml2
-rw-r--r--documentation/ref-manual/resources.xml2
-rw-r--r--documentation/ref-manual/technical-details.xml2
-rw-r--r--documentation/ref-manual/usingpoky.xml2
-rw-r--r--documentation/yocto-project-qs/yocto-project-qs.xml2
13 files changed, 362 insertions, 359 deletions
diff --git a/documentation/bsp-guide/bsp.xml b/documentation/bsp-guide/bsp.xml
index cb9940c77a..0dcc65b767 100644
--- a/documentation/bsp-guide/bsp.xml
+++ b/documentation/bsp-guide/bsp.xml
@@ -522,7 +522,7 @@
522 522
523 <para> 523 <para>
524 This file simply makes 524 This file simply makes
525 <ulink url='&YOCTO_DOCS_DEV_URL;#bitbake-term'>BitBake</ulink> 525 <ulink url='&YOCTO_DOCS_REF_URL;#bitbake-term'>BitBake</ulink>
526 aware of the recipes and configuration directories. 526 aware of the recipes and configuration directories.
527 The file must exist so that the OpenEmbedded build system can recognize the BSP. 527 The file must exist so that the OpenEmbedded build system can recognize the BSP.
528 </para> 528 </para>
diff --git a/documentation/dev-manual/dev-manual-newbie.xml b/documentation/dev-manual/dev-manual-newbie.xml
index 00b8c44801..350c6e49a8 100644
--- a/documentation/dev-manual/dev-manual-newbie.xml
+++ b/documentation/dev-manual/dev-manual-newbie.xml
@@ -490,352 +490,6 @@
490 </para> 490 </para>
491</section> 491</section>
492 492
493<section id='yocto-project-terms'>
494 <title>Yocto Project Terms</title>
495
496 <para>
497 Following is a list of terms and definitions users new to the Yocto Project development
498 environment might find helpful.
499 While some of these terms are universal, the list includes them just in case:
500 <itemizedlist>
501 <listitem><para><emphasis>Append Files:</emphasis> Files that append build information to
502 a recipe file.
503 Append files are known as BitBake append files and <filename>.bbappend</filename> files.
504 The OpenEmbedded build system expects every append file to have a corresponding
505 recipe (<filename>.bb</filename>) file.
506 Furthermore, the append file and corresponding recipe file
507 must use the same root filename.
508 The filenames can differ only in the file type suffix used (e.g.
509 <filename>formfactor_0.0.bb</filename> and <filename>formfactor_0.0.bbappend</filename>).
510 </para>
511 <para>Information in append files extends or overrides the
512 information in the similarly-named recipe file.
513 For an example of an append file in use, see the
514 "<link linkend='using-bbappend-files'>Using .bbappend Files</link>" section.
515 <note>
516 Append files can also use wildcard patterns in their version numbers
517 so they can be applied to more than one version of the underlying recipe file.
518 </note>
519 </para></listitem>
520 <listitem><para id='bitbake-term'><emphasis>BitBake:</emphasis>
521 The task executor and scheduler used by the OpenEmbedded build
522 system to build images.
523 For more information on BitBake, see the
524 <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>.
525 </para></listitem>
526 <listitem>
527 <para id='build-directory'><emphasis>Build Directory:</emphasis>
528 This term refers to the area used by the OpenEmbedded build
529 system for builds.
530 The area is created when you <filename>source</filename> the
531 setup environment script that is found in the Source Directory
532 (i.e. <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
533 or
534 <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>).
535 The <ulink url='&YOCTO_DOCS_REF_URL;#var-TOPDIR'><filename>TOPDIR</filename></ulink>
536 variable points to the Build Directory.</para>
537
538 <para>
539 You have a lot of flexibility when creating the Build
540 Directory.
541 Following are some examples that show how to create the
542 directory.
543 The examples assume your
544 <link linkend='source-directory'>Source Directory</link> is
545 named <filename>poky</filename>:
546 <itemizedlist>
547 <listitem><para>Create the Build Directory inside your
548 Source Directory and let the name of the Build
549 Directory default to <filename>build</filename>:
550 <literallayout class='monospaced'>
551 $ cd $HOME/poky
552 $ source &OE_INIT_FILE;
553 </literallayout></para></listitem>
554 <listitem><para>Create the Build Directory inside your
555 home directory and specifically name it
556 <filename>test-builds</filename>:
557 <literallayout class='monospaced'>
558 $ cd $HOME
559 $ source poky/&OE_INIT_FILE; test-builds
560 </literallayout></para></listitem>
561 <listitem><para>
562 Provide a directory path and
563 specifically name the Build Directory.
564 Any intermediate folders in the pathname must
565 exist.
566 This next example creates a Build Directory named
567 <filename>YP-&POKYVERSION;</filename>
568 in your home directory within the existing
569 directory <filename>mybuilds</filename>:
570 <literallayout class='monospaced'>
571 $cd $HOME
572 $ source $HOME/poky/&OE_INIT_FILE; $HOME/mybuilds/YP-&POKYVERSION;
573 </literallayout></para></listitem>
574 </itemizedlist>
575 <note>
576 By default, the Build Directory contains
577 <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>,
578 which is a temporary directory the build system uses for
579 its work.
580 <filename>TMPDIR</filename> cannot be under NFS.
581 Thus, by default, the Build Directory cannot be under NFS.
582 However, if you need the Build Directory to be under NFS,
583 you can set this up by setting <filename>TMPDIR</filename>
584 in your <filename>local.conf</filename> file
585 to use a local drive.
586 Doing so effectively separates <filename>TMPDIR</filename>
587 from <filename>TOPDIR</filename>, which is the Build
588 Directory.
589 </note>
590 </para></listitem>
591 <listitem><para><emphasis>Classes:</emphasis> Files that provide for logic encapsulation
592 and inheritance so that commonly used patterns can be defined once and then easily used
593 in multiple recipes.
594 For reference information on the Yocto Project classes, see the
595 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-classes'>Classes</ulink>" chapter of the
596 Yocto Project Reference Manual.
597 Class files end with the <filename>.bbclass</filename> filename extension.
598 </para></listitem>
599 <listitem><para><emphasis>Configuration File:</emphasis>
600 Configuration information in various <filename>.conf</filename>
601 files provides global definitions of variables.
602 The <filename>conf/local.conf</filename> configuration file in
603 the
604 <link linkend='build-directory'>Build Directory</link>
605 contains user-defined variables that affect every build.
606 The <filename>meta-poky/conf/distro/poky.conf</filename>
607 configuration file defines Yocto "distro" configuration
608 variables used only when building with this policy.
609 Machine configuration files, which
610 are located throughout the
611 <link linkend='source-directory'>Source Directory</link>, define
612 variables for specific hardware and are only used when building
613 for that target (e.g. the
614 <filename>machine/beaglebone.conf</filename> configuration
615 file defines variables for the Texas Instruments ARM Cortex-A8
616 development board).
617 Configuration files end with a <filename>.conf</filename>
618 filename extension.
619 </para></listitem>
620 <listitem><para id='cross-development-toolchain'>
621 <emphasis>Cross-Development Toolchain:</emphasis>
622 In general, a cross-development toolchain is a collection of
623 software development tools and utilities that run on one
624 architecture and allow you to develop software for a
625 different, or targeted, architecture.
626 These toolchains contain cross-compilers, linkers, and
627 debuggers that are specific to the target architecture.
628 </para>
629
630 <para>The Yocto Project supports two different cross-development
631 toolchains:
632 <itemizedlist>
633 <listitem><para>A toolchain only used by and within
634 BitBake when building an image for a target
635 architecture.</para></listitem>
636 <listitem><para>A relocatable toolchain used outside of
637 BitBake by developers when developing applications
638 that will run on a targeted device.
639 </para></listitem>
640 </itemizedlist>
641 </para>
642
643 <para>
644 Creation of these toolchains is simple and automated.
645 For information on toolchain concepts as they apply to the
646 Yocto Project, see the
647 "<ulink url='&YOCTO_DOCS_REF_URL;#cross-development-toolchain-generation'>Cross-Development Toolchain Generation</ulink>"
648 section in the Yocto Project Reference Manual.
649 You can also find more information on using the
650 relocatable toolchain in the
651 <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Software Development Kit (SDK) Developer's Guide</ulink>.
652 </para></listitem>
653 <listitem><para><emphasis>Image:</emphasis>
654 An image is an artifact of the BitBake build process given
655 a collection of recipes and related Metadata.
656 Images are the binary output that run on specific hardware or
657 QEMU and are used for specific use-cases.
658 For a list of the supported image types that the Yocto Project provides, see the
659 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>"
660 chapter in the Yocto Project Reference Manual.</para></listitem>
661 <listitem><para id='layer'><emphasis>Layer:</emphasis> A collection of recipes representing the core,
662 a BSP, or an application stack.
663 For a discussion specifically on BSP Layers, see the
664 "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>"
665 section in the Yocto Project Board Support Packages (BSP)
666 Developer's Guide.</para></listitem>
667 <listitem><para id='metadata'><emphasis>Metadata:</emphasis>
668 The files that BitBake parses when building an image.
669 In general, Metadata includes recipes, classes, and
670 configuration files.
671 In the context of the kernel ("kernel Metadata"),
672 it refers to Metadata in the <filename>meta</filename>
673 branches of the kernel source Git repositories.
674 </para></listitem>
675 <listitem><para id='oe-core'><emphasis>OE-Core:</emphasis> A core set of Metadata originating
676 with OpenEmbedded (OE) that is shared between OE and the Yocto Project.
677 This Metadata is found in the <filename>meta</filename> directory of the
678 <link linkend='source-directory'>Source Directory</link>.</para></listitem>
679 <listitem><para id='build-system-term'><emphasis>OpenEmbedded Build System:</emphasis>
680 The build system specific to the Yocto Project.
681 The OpenEmbedded build system is based on another project known
682 as "Poky", which uses
683 <link linkend='bitbake-term'>BitBake</link> as the task
684 executor.
685 Throughout the Yocto Project documentation set, the
686 OpenEmbedded build system is sometimes referred to simply
687 as "the build system".
688 If other build systems, such as a host or target build system
689 are referenced, the documentation clearly states the
690 difference.
691 <note>
692 For some historical information about Poky, see the
693 <link linkend='poky'>Poky</link> term.
694 </note>
695 </para></listitem>
696 <listitem><para><emphasis>Package:</emphasis>
697 In the context of the Yocto Project, this term refers to a
698 recipe's packaged output produced by BitBake (i.e. a
699 "baked recipe").
700 A package is generally the compiled binaries produced from the
701 recipe's sources.
702 You "bake" something by running it through BitBake.</para>
703 <para>It is worth noting that the term "package" can, in general, have subtle
704 meanings. For example, the packages referred to in the
705 "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Build Host Packages</ulink>" section are
706 compiled binaries that, when installed, add functionality to your Linux
707 distribution.</para>
708 <para>Another point worth noting is that historically within the Yocto Project,
709 recipes were referred to as packages - thus, the existence of several BitBake
710 variables that are seemingly mis-named,
711 (e.g. <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>,
712 <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>, and
713 <ulink url='&YOCTO_DOCS_REF_URL;#var-PE'><filename>PE</filename></ulink>).
714 </para></listitem>
715 <listitem><para><emphasis>Package Groups:</emphasis>
716 Arbitrary groups of software Recipes.
717 You use package groups to hold recipes that, when built,
718 usually accomplish a single task.
719 For example, a package group could contain the recipes for a
720 company’s proprietary or value-add software.
721 Or, the package group could contain the recipes that enable
722 graphics.
723 A package group is really just another recipe.
724 Because package group files are recipes, they end with the
725 <filename>.bb</filename> filename extension.</para></listitem>
726 <listitem><para id='poky'><emphasis>Poky:</emphasis>
727 The term "poky" can mean several things.
728 In its most general sense, it is an open-source
729 project that was initially developed by OpenedHand.
730 With OpenedHand, poky was developed off of the existing
731 OpenEmbedded build system becoming a commercially
732 supportable build system for embedded Linux.
733 After Intel Corporation acquired OpenedHand, the
734 project poky became the basis for the Yocto Project's
735 build system.</para>
736 <para>Within the Yocto Project source repositories,
737 <filename>poky</filename> exists as a separate Git
738 repository you can clone to yield a local copy on your
739 host system.
740 Thus, "poky" can refer to the local copy of the Source
741 Directory used for development within the Yocto
742 Project.</para>
743 <para>Finally, "poky" can refer to the default
744 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO'><filename>DISTRO</filename></ulink>
745 (i.e. distribution) created when you use the Yocto
746 Project in conjunction with the
747 <filename>poky</filename> repository to build an image.
748 </para></listitem>
749 <listitem><para><emphasis>Recipe:</emphasis>
750 A set of instructions for building packages.
751 A recipe describes where you get source code, which patches
752 to apply, how to configure the source, how to compile it and so on.
753 Recipes also describe dependencies for libraries or for other
754 recipes.
755 Recipes represent the logical unit of execution, the software
756 to build, the images to build, and use the
757 <filename>.bb</filename> file extension.
758 </para></listitem>
759 <listitem>
760 <para id='source-directory'><emphasis>Source Directory:</emphasis>
761 This term refers to the directory structure created as a result
762 of creating a local copy of the <filename>poky</filename> Git
763 repository <filename>git://git.yoctoproject.org/poky</filename>
764 or expanding a released <filename>poky</filename> tarball.
765 <note>
766 Creating a local copy of the <filename>poky</filename>
767 Git repository is the recommended method for setting up
768 your Source Directory.
769 </note>
770 Sometimes you might hear the term "poky directory" used to refer
771 to this directory structure.
772 <note>
773 The OpenEmbedded build system does not support file or
774 directory names that contain spaces.
775 Be sure that the Source Directory you use does not contain
776 these types of names.
777 </note></para>
778
779 <para>The Source Directory contains BitBake, Documentation,
780 Metadata and other files that all support the Yocto Project.
781 Consequently, you must have the Source Directory in place on
782 your development system in order to do any development using
783 the Yocto Project.</para>
784
785 <para>When you create a local copy of the Git repository, you
786 can name the repository anything you like.
787 Throughout much of the documentation, "poky"
788 is used as the name of the top-level folder of the local copy of
789 the poky Git repository.
790 So, for example, cloning the <filename>poky</filename> Git
791 repository results in a local Git repository whose top-level
792 folder is also named "poky".</para>
793
794 <para>While it is not recommended that you use tarball expansion
795 to set up the Source Directory, if you do, the top-level
796 directory name of the Source Directory is derived from the
797 Yocto Project release tarball.
798 For example, downloading and unpacking
799 <filename>&YOCTO_POKY_TARBALL;</filename> results in a
800 Source Directory whose root folder is named
801 <filename>&YOCTO_POKY;</filename>.</para>
802
803 <para>It is important to understand the differences between the
804 Source Directory created by unpacking a released tarball as
805 compared to cloning
806 <filename>git://git.yoctoproject.org/poky</filename>.
807 When you unpack a tarball, you have an exact copy of the files
808 based on the time of release - a fixed release point.
809 Any changes you make to your local files in the Source Directory
810 are on top of the release and will remain local only.
811 On the other hand, when you clone the <filename>poky</filename>
812 Git repository, you have an active development repository with
813 access to the upstream repository's branches and tags.
814 In this case, any local changes you make to the local
815 Source Directory can be later applied to active development
816 branches of the upstream <filename>poky</filename> Git
817 repository.</para>
818
819 <para>For more information on concepts related to Git
820 repositories, branches, and tags, see the
821 "<link linkend='repositories-tags-and-branches'>Repositories, Tags, and Branches</link>"
822 section.</para></listitem>
823 <listitem><para><emphasis>Task:</emphasis>
824 A unit of execution for BitBake (e.g.
825 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-compile'><filename>do_compile</filename></ulink>,
826 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-fetch'><filename>do_fetch</filename></ulink>,
827 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-patch'><filename>do_patch</filename></ulink>,
828 and so forth).
829 </para></listitem>
830 <listitem><para><emphasis>Upstream:</emphasis> A reference to source code or repositories
831 that are not local to the development system but located in a master area that is controlled
832 by the maintainer of the source code.
833 For example, in order for a developer to work on a particular piece of code, they need to
834 first get a copy of it from an "upstream" source.</para></listitem>
835 </itemizedlist>
836 </para>
837</section>
838
839<section id='licensing'> 493<section id='licensing'>
840 <title>Licensing</title> 494 <title>Licensing</title>
841 495
diff --git a/documentation/dev-manual/dev-manual-start.xml b/documentation/dev-manual/dev-manual-start.xml
index b8527f670a..0e335e28fc 100644
--- a/documentation/dev-manual/dev-manual-start.xml
+++ b/documentation/dev-manual/dev-manual-start.xml
@@ -34,7 +34,8 @@
34 34
35 <para> 35 <para>
36 You can use the OpenEmbedded build system, which uses 36 You can use the OpenEmbedded build system, which uses
37 <link linkend='bitbake-term'>BitBake</link>, to develop complete Linux 37 <ulink url='&YOCTO_DOCS_REF_URL;#bitbake-term'>BitBake</ulink>,
38 to develop complete Linux
38 images and associated user-space applications for architectures based 39 images and associated user-space applications for architectures based
39 on ARM, MIPS, PowerPC, x86 and x86-64. 40 on ARM, MIPS, PowerPC, x86 and x86-64.
40 <note> 41 <note>
diff --git a/documentation/kernel-dev/kernel-dev-advanced.xml b/documentation/kernel-dev/kernel-dev-advanced.xml
index a5ccfdc300..5c08019655 100644
--- a/documentation/kernel-dev/kernel-dev-advanced.xml
+++ b/documentation/kernel-dev/kernel-dev-advanced.xml
@@ -48,7 +48,7 @@
48 This variable is typically set to the same value as the 48 This variable is typically set to the same value as the
49 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> 49 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
50 variable, which is used by 50 variable, which is used by
51 <ulink url='&YOCTO_DOCS_DEV_URL;#bitbake-term'>BitBake</ulink>. 51 <ulink url='&YOCTO_DOCS_REF_URL;#bitbake-term'>BitBake</ulink>.
52 However, in some cases, the variable might instead refer to the 52 However, in some cases, the variable might instead refer to the
53 underlying platform of the <filename>MACHINE</filename>. 53 underlying platform of the <filename>MACHINE</filename>.
54 </para> 54 </para>
diff --git a/documentation/kernel-dev/kernel-dev-common.xml b/documentation/kernel-dev/kernel-dev-common.xml
index d49aa3ce17..5af0f9a927 100644
--- a/documentation/kernel-dev/kernel-dev-common.xml
+++ b/documentation/kernel-dev/kernel-dev-common.xml
@@ -26,7 +26,7 @@
26 that you create and prepare your own layer in which to do your 26 that you create and prepare your own layer in which to do your
27 work. 27 work.
28 Your layer contains its own 28 Your layer contains its own
29 <ulink url='&YOCTO_DOCS_DEV_URL;#bitbake-term'>BitBake</ulink> 29 <ulink url='&YOCTO_DOCS_REF_URL;#bitbake-term'>BitBake</ulink>
30 append files 30 append files
31 (<filename>.bbappend</filename>) and provides a convenient 31 (<filename>.bbappend</filename>) and provides a convenient
32 mechanism to create your own recipe files 32 mechanism to create your own recipe files
diff --git a/documentation/ref-manual/closer-look.xml b/documentation/ref-manual/closer-look.xml
index 459d571926..c0f1747961 100644
--- a/documentation/ref-manual/closer-look.xml
+++ b/documentation/ref-manual/closer-look.xml
@@ -34,7 +34,7 @@
34 Upstream releases, local projects, and SCMs.</para></listitem> 34 Upstream releases, local projects, and SCMs.</para></listitem>
35 <listitem><para><emphasis>Build System:</emphasis> 35 <listitem><para><emphasis>Build System:</emphasis>
36 Processes under the control of 36 Processes under the control of
37 <ulink url='&YOCTO_DOCS_DEV_URL;#bitbake-term'>BitBake</ulink>. 37 <link linkend='bitbake-term'>BitBake</link>.
38 This block expands on how BitBake fetches source, applies 38 This block expands on how BitBake fetches source, applies
39 patches, completes compilation, analyzes output for package 39 patches, completes compilation, analyzes output for package
40 generation, creates and tests packages, generates images, and 40 generation, creates and tests packages, generates images, and
@@ -727,7 +727,7 @@
727 727
728 <para> 728 <para>
729 The OpenEmbedded build system uses 729 The OpenEmbedded build system uses
730 <ulink url='&YOCTO_DOCS_DEV_URL;#bitbake-term'>BitBake</ulink> 730 <link linkend='bitbake-term'>BitBake</link>
731 to produce images. 731 to produce images.
732 You can see from the 732 You can see from the
733 <link linkend='general-yocto-environment-figure'>general Yocto Project Development Environment figure</link>, 733 <link linkend='general-yocto-environment-figure'>general Yocto Project Development Environment figure</link>,
diff --git a/documentation/ref-manual/faq.xml b/documentation/ref-manual/faq.xml
index 5f3f173495..cdbdd4da24 100644
--- a/documentation/ref-manual/faq.xml
+++ b/documentation/ref-manual/faq.xml
@@ -17,7 +17,7 @@
17 refers to the specific reference build system that 17 refers to the specific reference build system that
18 the Yocto Project provides. 18 the Yocto Project provides.
19 Poky is based on <ulink url='&YOCTO_DOCS_DEV_URL;#oe-core'>OE-Core</ulink> 19 Poky is based on <ulink url='&YOCTO_DOCS_DEV_URL;#oe-core'>OE-Core</ulink>
20 and <ulink url='&YOCTO_DOCS_DEV_URL;#bitbake-term'>BitBake</ulink>. 20 and <link linkend='bitbake-term'>BitBake</link>.
21 Thus, the generic term used here for the build system is 21 Thus, the generic term used here for the build system is
22 the "OpenEmbedded build system." 22 the "OpenEmbedded build system."
23 Development in the Yocto Project using Poky is closely tied to OpenEmbedded, with 23 Development in the Yocto Project using Poky is closely tied to OpenEmbedded, with
@@ -810,7 +810,7 @@
810 <para> 810 <para>
811 This situation results when a build system does 811 This situation results when a build system does
812 not recognize the environment variables supplied to it by 812 not recognize the environment variables supplied to it by
813 <ulink url='&YOCTO_DOCS_DEV_URL;#bitbake-term'>BitBake</ulink>. 813 <link linkend='bitbake-term'>BitBake</link>.
814 The incident that prompted this FAQ entry involved a Makefile 814 The incident that prompted this FAQ entry involved a Makefile
815 that used an environment variable named 815 that used an environment variable named
816 <filename>BINDIR</filename> instead of the more standard 816 <filename>BINDIR</filename> instead of the more standard
diff --git a/documentation/ref-manual/introduction.xml b/documentation/ref-manual/introduction.xml
index 7423467150..58ee073868 100644
--- a/documentation/ref-manual/introduction.xml
+++ b/documentation/ref-manual/introduction.xml
@@ -39,6 +39,354 @@
39 </para> 39 </para>
40</section> 40</section>
41 41
42<section id='yocto-project-terms'>
43 <title>Yocto Project Terms</title>
44
45 <para>
46 Following is a list of terms and definitions users new to the Yocto Project development
47 environment might find helpful.
48 While some of these terms are universal, the list includes them just in case:
49 <itemizedlist>
50 <listitem><para><emphasis>Append Files:</emphasis> Files that append build information to
51 a recipe file.
52 Append files are known as BitBake append files and <filename>.bbappend</filename> files.
53 The OpenEmbedded build system expects every append file to have a corresponding
54 recipe (<filename>.bb</filename>) file.
55 Furthermore, the append file and corresponding recipe file
56 must use the same root filename.
57 The filenames can differ only in the file type suffix used (e.g.
58 <filename>formfactor_0.0.bb</filename> and <filename>formfactor_0.0.bbappend</filename>).
59 </para>
60 <para>Information in append files extends or overrides the
61 information in the similarly-named recipe file.
62 For an example of an append file in use, see the
63 "<ulink url='&YOCTO_DOCS_DEV_URL;#using-bbappend-files'>Using .bbappend Files</ulink>"
64 section in the Yocto Project Development Manual.
65 <note>
66 Append files can also use wildcard patterns in their version numbers
67 so they can be applied to more than one version of the underlying recipe file.
68 </note>
69 </para></listitem>
70 <listitem><para id='bitbake-term'><emphasis>BitBake:</emphasis>
71 The task executor and scheduler used by the OpenEmbedded build
72 system to build images.
73 For more information on BitBake, see the
74 <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>.
75 </para></listitem>
76 <listitem>
77 <para id='build-directory'><emphasis>Build Directory:</emphasis>
78 This term refers to the area used by the OpenEmbedded build
79 system for builds.
80 The area is created when you <filename>source</filename> the
81 setup environment script that is found in the Source Directory
82 (i.e. <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
83 or
84 <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>).
85 The <ulink url='&YOCTO_DOCS_REF_URL;#var-TOPDIR'><filename>TOPDIR</filename></ulink>
86 variable points to the Build Directory.</para>
87
88 <para>
89 You have a lot of flexibility when creating the Build
90 Directory.
91 Following are some examples that show how to create the
92 directory.
93 The examples assume your
94 <link linkend='source-directory'>Source Directory</link> is
95 named <filename>poky</filename>:
96 <itemizedlist>
97 <listitem><para>Create the Build Directory inside your
98 Source Directory and let the name of the Build
99 Directory default to <filename>build</filename>:
100 <literallayout class='monospaced'>
101 $ cd $HOME/poky
102 $ source &OE_INIT_FILE;
103 </literallayout></para></listitem>
104 <listitem><para>Create the Build Directory inside your
105 home directory and specifically name it
106 <filename>test-builds</filename>:
107 <literallayout class='monospaced'>
108 $ cd $HOME
109 $ source poky/&OE_INIT_FILE; test-builds
110 </literallayout></para></listitem>
111 <listitem><para>
112 Provide a directory path and
113 specifically name the Build Directory.
114 Any intermediate folders in the pathname must
115 exist.
116 This next example creates a Build Directory named
117 <filename>YP-&POKYVERSION;</filename>
118 in your home directory within the existing
119 directory <filename>mybuilds</filename>:
120 <literallayout class='monospaced'>
121 $cd $HOME
122 $ source $HOME/poky/&OE_INIT_FILE; $HOME/mybuilds/YP-&POKYVERSION;
123 </literallayout></para></listitem>
124 </itemizedlist>
125 <note>
126 By default, the Build Directory contains
127 <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>,
128 which is a temporary directory the build system uses for
129 its work.
130 <filename>TMPDIR</filename> cannot be under NFS.
131 Thus, by default, the Build Directory cannot be under NFS.
132 However, if you need the Build Directory to be under NFS,
133 you can set this up by setting <filename>TMPDIR</filename>
134 in your <filename>local.conf</filename> file
135 to use a local drive.
136 Doing so effectively separates <filename>TMPDIR</filename>
137 from <filename>TOPDIR</filename>, which is the Build
138 Directory.
139 </note>
140 </para></listitem>
141 <listitem><para><emphasis>Classes:</emphasis> Files that provide for logic encapsulation
142 and inheritance so that commonly used patterns can be defined once and then easily used
143 in multiple recipes.
144 For reference information on the Yocto Project classes, see the
145 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-classes'>Classes</ulink>" chapter of the
146 Yocto Project Reference Manual.
147 Class files end with the <filename>.bbclass</filename> filename extension.
148 </para></listitem>
149 <listitem><para><emphasis>Configuration File:</emphasis>
150 Configuration information in various <filename>.conf</filename>
151 files provides global definitions of variables.
152 The <filename>conf/local.conf</filename> configuration file in
153 the
154 <link linkend='build-directory'>Build Directory</link>
155 contains user-defined variables that affect every build.
156 The <filename>meta-poky/conf/distro/poky.conf</filename>
157 configuration file defines Yocto "distro" configuration
158 variables used only when building with this policy.
159 Machine configuration files, which
160 are located throughout the
161 <link linkend='source-directory'>Source Directory</link>, define
162 variables for specific hardware and are only used when building
163 for that target (e.g. the
164 <filename>machine/beaglebone.conf</filename> configuration
165 file defines variables for the Texas Instruments ARM Cortex-A8
166 development board).
167 Configuration files end with a <filename>.conf</filename>
168 filename extension.
169 </para></listitem>
170 <listitem><para id='cross-development-toolchain'>
171 <emphasis>Cross-Development Toolchain:</emphasis>
172 In general, a cross-development toolchain is a collection of
173 software development tools and utilities that run on one
174 architecture and allow you to develop software for a
175 different, or targeted, architecture.
176 These toolchains contain cross-compilers, linkers, and
177 debuggers that are specific to the target architecture.
178 </para>
179
180 <para>The Yocto Project supports two different cross-development
181 toolchains:
182 <itemizedlist>
183 <listitem><para>A toolchain only used by and within
184 BitBake when building an image for a target
185 architecture.</para></listitem>
186 <listitem><para>A relocatable toolchain used outside of
187 BitBake by developers when developing applications
188 that will run on a targeted device.
189 </para></listitem>
190 </itemizedlist>
191 </para>
192
193 <para>
194 Creation of these toolchains is simple and automated.
195 For information on toolchain concepts as they apply to the
196 Yocto Project, see the
197 "<ulink url='&YOCTO_DOCS_REF_URL;#cross-development-toolchain-generation'>Cross-Development Toolchain Generation</ulink>"
198 section in the Yocto Project Reference Manual.
199 You can also find more information on using the
200 relocatable toolchain in the
201 <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Software Development Kit (SDK) Developer's Guide</ulink>.
202 </para></listitem>
203 <listitem><para><emphasis>Image:</emphasis>
204 An image is an artifact of the BitBake build process given
205 a collection of recipes and related Metadata.
206 Images are the binary output that run on specific hardware or
207 QEMU and are used for specific use-cases.
208 For a list of the supported image types that the Yocto Project provides, see the
209 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>"
210 chapter in the Yocto Project Reference Manual.</para></listitem>
211 <listitem><para id='layer'><emphasis>Layer:</emphasis> A collection of recipes representing the core,
212 a BSP, or an application stack.
213 For a discussion specifically on BSP Layers, see the
214 "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>"
215 section in the Yocto Project Board Support Packages (BSP)
216 Developer's Guide.</para></listitem>
217 <listitem><para id='metadata'><emphasis>Metadata:</emphasis>
218 The files that BitBake parses when building an image.
219 In general, Metadata includes recipes, classes, and
220 configuration files.
221 In the context of the kernel ("kernel Metadata"),
222 it refers to Metadata in the <filename>meta</filename>
223 branches of the kernel source Git repositories.
224 </para></listitem>
225 <listitem><para id='oe-core'><emphasis>OE-Core:</emphasis> A core set of Metadata originating
226 with OpenEmbedded (OE) that is shared between OE and the Yocto Project.
227 This Metadata is found in the <filename>meta</filename> directory of the
228 <link linkend='source-directory'>Source Directory</link>.</para></listitem>
229 <listitem><para id='build-system-term'><emphasis>OpenEmbedded Build System:</emphasis>
230 The build system specific to the Yocto Project.
231 The OpenEmbedded build system is based on another project known
232 as "Poky", which uses
233 <link linkend='bitbake-term'>BitBake</link> as the task
234 executor.
235 Throughout the Yocto Project documentation set, the
236 OpenEmbedded build system is sometimes referred to simply
237 as "the build system".
238 If other build systems, such as a host or target build system
239 are referenced, the documentation clearly states the
240 difference.
241 <note>
242 For some historical information about Poky, see the
243 <link linkend='poky'>Poky</link> term.
244 </note>
245 </para></listitem>
246 <listitem><para><emphasis>Package:</emphasis>
247 In the context of the Yocto Project, this term refers to a
248 recipe's packaged output produced by BitBake (i.e. a
249 "baked recipe").
250 A package is generally the compiled binaries produced from the
251 recipe's sources.
252 You "bake" something by running it through BitBake.</para>
253 <para>It is worth noting that the term "package" can, in general, have subtle
254 meanings. For example, the packages referred to in the
255 "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Build Host Packages</ulink>" section are
256 compiled binaries that, when installed, add functionality to your Linux
257 distribution.</para>
258 <para>Another point worth noting is that historically within the Yocto Project,
259 recipes were referred to as packages - thus, the existence of several BitBake
260 variables that are seemingly mis-named,
261 (e.g. <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>,
262 <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>, and
263 <ulink url='&YOCTO_DOCS_REF_URL;#var-PE'><filename>PE</filename></ulink>).
264 </para></listitem>
265 <listitem><para><emphasis>Package Groups:</emphasis>
266 Arbitrary groups of software Recipes.
267 You use package groups to hold recipes that, when built,
268 usually accomplish a single task.
269 For example, a package group could contain the recipes for a
270 company’s proprietary or value-add software.
271 Or, the package group could contain the recipes that enable
272 graphics.
273 A package group is really just another recipe.
274 Because package group files are recipes, they end with the
275 <filename>.bb</filename> filename extension.</para></listitem>
276 <listitem><para id='poky'><emphasis>Poky:</emphasis>
277 The term "poky" can mean several things.
278 In its most general sense, it is an open-source
279 project that was initially developed by OpenedHand.
280 With OpenedHand, poky was developed off of the existing
281 OpenEmbedded build system becoming a commercially
282 supportable build system for embedded Linux.
283 After Intel Corporation acquired OpenedHand, the
284 project poky became the basis for the Yocto Project's
285 build system.</para>
286 <para>Within the Yocto Project source repositories,
287 <filename>poky</filename> exists as a separate Git
288 repository you can clone to yield a local copy on your
289 host system.
290 Thus, "poky" can refer to the local copy of the Source
291 Directory used for development within the Yocto
292 Project.</para>
293 <para>Finally, "poky" can refer to the default
294 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO'><filename>DISTRO</filename></ulink>
295 (i.e. distribution) created when you use the Yocto
296 Project in conjunction with the
297 <filename>poky</filename> repository to build an image.
298 </para></listitem>
299 <listitem><para><emphasis>Recipe:</emphasis>
300 A set of instructions for building packages.
301 A recipe describes where you get source code, which patches
302 to apply, how to configure the source, how to compile it and so on.
303 Recipes also describe dependencies for libraries or for other
304 recipes.
305 Recipes represent the logical unit of execution, the software
306 to build, the images to build, and use the
307 <filename>.bb</filename> file extension.
308 </para></listitem>
309 <listitem>
310 <para id='source-directory'><emphasis>Source Directory:</emphasis>
311 This term refers to the directory structure created as a result
312 of creating a local copy of the <filename>poky</filename> Git
313 repository <filename>git://git.yoctoproject.org/poky</filename>
314 or expanding a released <filename>poky</filename> tarball.
315 <note>
316 Creating a local copy of the <filename>poky</filename>
317 Git repository is the recommended method for setting up
318 your Source Directory.
319 </note>
320 Sometimes you might hear the term "poky directory" used to refer
321 to this directory structure.
322 <note>
323 The OpenEmbedded build system does not support file or
324 directory names that contain spaces.
325 Be sure that the Source Directory you use does not contain
326 these types of names.
327 </note></para>
328
329 <para>The Source Directory contains BitBake, Documentation,
330 Metadata and other files that all support the Yocto Project.
331 Consequently, you must have the Source Directory in place on
332 your development system in order to do any development using
333 the Yocto Project.</para>
334
335 <para>When you create a local copy of the Git repository, you
336 can name the repository anything you like.
337 Throughout much of the documentation, "poky"
338 is used as the name of the top-level folder of the local copy of
339 the poky Git repository.
340 So, for example, cloning the <filename>poky</filename> Git
341 repository results in a local Git repository whose top-level
342 folder is also named "poky".</para>
343
344 <para>While it is not recommended that you use tarball expansion
345 to set up the Source Directory, if you do, the top-level
346 directory name of the Source Directory is derived from the
347 Yocto Project release tarball.
348 For example, downloading and unpacking
349 <filename>&YOCTO_POKY_TARBALL;</filename> results in a
350 Source Directory whose root folder is named
351 <filename>&YOCTO_POKY;</filename>.</para>
352
353 <para>It is important to understand the differences between the
354 Source Directory created by unpacking a released tarball as
355 compared to cloning
356 <filename>git://git.yoctoproject.org/poky</filename>.
357 When you unpack a tarball, you have an exact copy of the files
358 based on the time of release - a fixed release point.
359 Any changes you make to your local files in the Source Directory
360 are on top of the release and will remain local only.
361 On the other hand, when you clone the <filename>poky</filename>
362 Git repository, you have an active development repository with
363 access to the upstream repository's branches and tags.
364 In this case, any local changes you make to the local
365 Source Directory can be later applied to active development
366 branches of the upstream <filename>poky</filename> Git
367 repository.</para>
368
369 <para>For more information on concepts related to Git
370 repositories, branches, and tags, see the
371 "<ulink url='&YOCTO_DOCS_DEV_URL;#repositories-tags-and-branches'>Repositories, Tags, and Branches</ulink>"
372 section in the Yocto Project Development Manual.
373 </para></listitem>
374 <listitem><para><emphasis>Task:</emphasis>
375 A unit of execution for BitBake (e.g.
376 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-compile'><filename>do_compile</filename></ulink>,
377 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-fetch'><filename>do_fetch</filename></ulink>,
378 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-patch'><filename>do_patch</filename></ulink>,
379 and so forth).
380 </para></listitem>
381 <listitem><para><emphasis>Upstream:</emphasis> A reference to source code or repositories
382 that are not local to the development system but located in a master area that is controlled
383 by the maintainer of the source code.
384 For example, in order for a developer to work on a particular piece of code, they need to
385 first get a copy of it from an "upstream" source.</para></listitem>
386 </itemizedlist>
387 </para>
388</section>
389
42<section id='intro-manualoverview'> 390<section id='intro-manualoverview'>
43 <title>Documentation Overview</title> 391 <title>Documentation Overview</title>
44 <para> 392 <para>
diff --git a/documentation/ref-manual/migration.xml b/documentation/ref-manual/migration.xml
index 442324f1f7..0513b219cd 100644
--- a/documentation/ref-manual/migration.xml
+++ b/documentation/ref-manual/migration.xml
@@ -1218,7 +1218,7 @@
1218 1218
1219 <para> 1219 <para>
1220 The following changes have been made to 1220 The following changes have been made to
1221 <ulink url='&YOCTO_DOCS_DEV_URL;#bitbake-term'>BitBake</ulink>. 1221 <link linkend='bitbake-term'>BitBake</link>.
1222 </para> 1222 </para>
1223 1223
1224 <section id='migration-1.6-matching-branch-requirement-for-git-fetching'> 1224 <section id='migration-1.6-matching-branch-requirement-for-git-fetching'>
diff --git a/documentation/ref-manual/resources.xml b/documentation/ref-manual/resources.xml
index c713ffcf11..aa8408f432 100644
--- a/documentation/ref-manual/resources.xml
+++ b/documentation/ref-manual/resources.xml
@@ -89,7 +89,7 @@
89 Discussion mailing list about OpenEmbedded.</para></listitem> 89 Discussion mailing list about OpenEmbedded.</para></listitem>
90 <listitem><para><ulink url='&OE_LISTS_URL;/listinfo/bitbake-devel'></ulink> - 90 <listitem><para><ulink url='&OE_LISTS_URL;/listinfo/bitbake-devel'></ulink> -
91 Discussion mailing list about the 91 Discussion mailing list about the
92 <ulink url='&YOCTO_DOCS_DEV_URL;#bitbake-term'>BitBake</ulink> 92 <link linkend='bitbake-term'>BitBake</link>
93 build tool.</para></listitem> 93 build tool.</para></listitem>
94 <listitem><para><ulink url='&YOCTO_LISTS_URL;/listinfo/poky'></ulink> - 94 <listitem><para><ulink url='&YOCTO_LISTS_URL;/listinfo/poky'></ulink> -
95 Discussion mailing list about 95 Discussion mailing list about
diff --git a/documentation/ref-manual/technical-details.xml b/documentation/ref-manual/technical-details.xml
index 1964a9a105..0c949880e7 100644
--- a/documentation/ref-manual/technical-details.xml
+++ b/documentation/ref-manual/technical-details.xml
@@ -18,7 +18,7 @@
18 18
19 <para> 19 <para>
20 The 20 The
21 <ulink url='&YOCTO_DOCS_DEV_URL;#bitbake-term'>BitBake</ulink> 21 <link linkend='bitbake-term'>BitBake</link>
22 task executor together with various types of configuration files form 22 task executor together with various types of configuration files form
23 the OpenEmbedded Core. 23 the OpenEmbedded Core.
24 This section overviews these components by describing their use and 24 This section overviews these components by describing their use and
diff --git a/documentation/ref-manual/usingpoky.xml b/documentation/ref-manual/usingpoky.xml
index 4e97e3ec02..d1ac18fb2f 100644
--- a/documentation/ref-manual/usingpoky.xml
+++ b/documentation/ref-manual/usingpoky.xml
@@ -208,7 +208,7 @@
208 (<filename>qemux86</filename>) might be in 208 (<filename>qemux86</filename>) might be in
209 <filename>tmp/work/qemux86-poky-linux/core-image-minimal/1.0-r0/temp/log.do_compile</filename>. 209 <filename>tmp/work/qemux86-poky-linux/core-image-minimal/1.0-r0/temp/log.do_compile</filename>.
210 To see the commands 210 To see the commands
211 <ulink url='&YOCTO_DOCS_DEV_URL;#bitbake-term'>BitBake</ulink> ran 211 <link linkend='bitbake-term'>BitBake</link> ran
212 to generate a log, look at the corresponding 212 to generate a log, look at the corresponding
213 <filename>run.do_</filename><replaceable>taskname</replaceable> 213 <filename>run.do_</filename><replaceable>taskname</replaceable>
214 file in the same directory. 214 file in the same directory.
diff --git a/documentation/yocto-project-qs/yocto-project-qs.xml b/documentation/yocto-project-qs/yocto-project-qs.xml
index 8040702dd1..5b64e0f6fe 100644
--- a/documentation/yocto-project-qs/yocto-project-qs.xml
+++ b/documentation/yocto-project-qs/yocto-project-qs.xml
@@ -60,7 +60,7 @@
60 focus is developers of embedded Linux systems. 60 focus is developers of embedded Linux systems.
61 Among other things, the Yocto Project uses a build host based 61 Among other things, the Yocto Project uses a build host based
62 on the OpenEmbedded (OE) project, which uses the 62 on the OpenEmbedded (OE) project, which uses the
63 <ulink url='&YOCTO_DOCS_DEV_URL;#bitbake-term'>BitBake</ulink> 63 <ulink url='&YOCTO_DOCS_REF_URL;#bitbake-term'>BitBake</ulink>
64 tool, to construct complete Linux images. 64 tool, to construct complete Linux images.
65 The BitBake and OE components are combined together to form 65 The BitBake and OE components are combined together to form
66 a reference build host, historically known as 66 a reference build host, historically known as
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-05-02 04:00:03 +0000