summaryrefslogtreecommitdiffstats
path: root/documentation
diff options
context:
space:
mode:
authorScott Rifenbark <srifenbark@gmail.com>2018-01-05 15:43:42 -0800
committerRichard Purdie <richard.purdie@linuxfoundation.org>2018-02-14 15:25:27 +0000
commit60cfd0785b2d64ec808e08ad9f716047542d8ba9 (patch)
tree7c103c1a8bab35c1e0814566fde3215936596290 /documentation
parentc06a654c1d14f20b31256298543e2e3504acc0a9 (diff)
downloadpoky-60cfd0785b2d64ec808e08ad9f716047542d8ba9.tar.gz
ref-manual: Separated terms into separate chapter
Pulling out some introductory information from the old "Introduction" chapter of the ref-manual has isolated the system requirements and term definitions sections. I have decided to create a new chapter for terms as they are a reference item. This leaves system requirements also alone as a new chapter. So, I dumped the introduction.xml chapter in favor of the two new chapters. (From yocto-docs rev: 35c41b3008845c94e10be19b37409b0d1a469ff5) Signed-off-by: Scott Rifenbark <srifenbark@gmail.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation')
-rw-r--r--documentation/mega-manual/mega-manual.xml5
-rw-r--r--documentation/ref-manual/ref-manual.xml4
-rw-r--r--documentation/ref-manual/ref-system-requirements.xml (renamed from documentation/ref-manual/introduction.xml)455
-rw-r--r--documentation/ref-manual/ref-terms.xml436
4 files changed, 448 insertions, 452 deletions
diff --git a/documentation/mega-manual/mega-manual.xml b/documentation/mega-manual/mega-manual.xml
index 68fb1e17d8..efefa17032 100644
--- a/documentation/mega-manual/mega-manual.xml
+++ b/documentation/mega-manual/mega-manual.xml
@@ -231,7 +231,10 @@
231 </para> 231 </para>
232 232
233 <xi:include 233 <xi:include
234 xmlns:xi="http://www.w3.org/2003/XInclude" href="../ref-manual/introduction.xml"/> 234 xmlns:xi="http://www.w3.org/2003/XInclude" href="../ref-manual/ref-system-requirements.xml"/>
235
236 <xi:include
237 xmlns:xi="http://www.w3.org/2003/XInclude" href="../ref-manual/ref-terms.xml"/>
235 238
236 <xi:include 239 <xi:include
237 xmlns:xi="http://www.w3.org/2003/XInclude" href="../ref-manual/usingpoky.xml"/> 240 xmlns:xi="http://www.w3.org/2003/XInclude" href="../ref-manual/usingpoky.xml"/>
diff --git a/documentation/ref-manual/ref-manual.xml b/documentation/ref-manual/ref-manual.xml
index a24a9e310d..e69ab72c62 100644
--- a/documentation/ref-manual/ref-manual.xml
+++ b/documentation/ref-manual/ref-manual.xml
@@ -166,7 +166,9 @@
166 166
167 </bookinfo> 167 </bookinfo>
168 168
169 <xi:include href="introduction.xml"/> 169 <xi:include href="ref-system-requirements.xml"/>
170
171 <xi:include href="ref-terms.xml"/>
170 172
171 <xi:include href="usingpoky.xml"/> 173 <xi:include href="usingpoky.xml"/>
172 174
diff --git a/documentation/ref-manual/introduction.xml b/documentation/ref-manual/ref-system-requirements.xml
index 098dbc8a22..dfa2c2b6d1 100644
--- a/documentation/ref-manual/introduction.xml
+++ b/documentation/ref-manual/ref-system-requirements.xml
@@ -2,21 +2,18 @@
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" 2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > 3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4 4
5<chapter id='ref-manual-intro'> 5<chapter id='ref-manual-system-requirements'>
6<title>Introduction</title> 6<title>System Requirements</title>
7
8<section id='ref-welcome'>
9 <title>Welcome</title>
10 7
11 <para> 8 <para>
12 Welcome to the Yocto Project Reference Manual. 9 Welcome to the Yocto Project Reference Manual!
13 This manual provides reference information for the current release 10 This manual provides reference information for the current release
14 of the Yocto Project. 11 of the Yocto Project.
15 This manual is best used after you have an understanding 12 The manual is best used after you have an understanding
16 of the basics of the Yocto Project. 13 of the basics of the Yocto Project.
17 The manual is neither meant to be read as a starting point to the 14 The manual is neither meant to be read as a starting point to the
18 Yocto Project nor read from start to finish. 15 Yocto Project nor read from start to finish.
19 Use this manual to find concepts, variable definitions, class 16 Use this manual to find variable definitions, class
20 descriptions, and so forth as needed during the course of using 17 descriptions, and so forth as needed during the course of using
21 the Yocto Project. 18 the Yocto Project.
22 </para> 19 </para>
@@ -41,17 +38,6 @@
41 section. 38 section.
42 </note> 39 </note>
43 </para> 40 </para>
44</section>
45
46<section id='intro-requirements'>
47<title>System Requirements</title>
48 <para>
49 For general Yocto Project system requirements, see the
50 "<ulink url='&YOCTO_DOCS_QS_URL;#yp-resources'>Setting Up to Use the Yocto Project</ulink>" section
51 in the Yocto Project Quick Start.
52 The remainder of this section provides details on system requirements
53 not covered in the Yocto Project Quick Start.
54 </para>
55 41
56 <section id='detailed-supported-distros'> 42 <section id='detailed-supported-distros'>
57 <title>Supported Linux Distributions</title> 43 <title>Supported Linux Distributions</title>
@@ -500,437 +486,6 @@
500 </para> 486 </para>
501 </section> 487 </section>
502 </section> 488 </section>
503</section>
504
505<section id='yocto-project-terms'>
506 <title>Yocto Project Terms</title>
507
508 <para>
509 Following is a list of terms and definitions users new to the Yocto
510 Project development environment might find helpful.
511 While some of these terms are universal, the list includes them
512 just in case:
513 <itemizedlist>
514 <listitem><para>
515 <emphasis>Append Files:</emphasis>
516 Files that append build information to a recipe file.
517 Append files are known as BitBake append files and
518 <filename>.bbappend</filename> files.
519 The OpenEmbedded build system expects every append file to have
520 a corresponding recipe (<filename>.bb</filename>) file.
521 Furthermore, the append file and corresponding recipe file
522 must use the same root filename.
523 The filenames can differ only in the file type suffix used
524 (e.g.
525 <filename>formfactor_0.0.bb</filename> and
526 <filename>formfactor_0.0.bbappend</filename>).</para>
527
528 <para>Information in append files extends or overrides the
529 information in the similarly-named recipe file.
530 For an example of an append file in use, see the
531 "<ulink url='&YOCTO_DOCS_DEV_URL;#using-bbappend-files'>Using .bbappend Files in Your Layer</ulink>"
532 section in the Yocto Project Development Tasks Manual.
533 <note>
534 Append files can also use wildcard patterns in their
535 version numbers so they can be applied to more than one
536 version of the underlying recipe file.
537 </note>
538 </para></listitem>
539 <listitem><para id='bitbake-term'>
540 <emphasis>BitBake:</emphasis>
541 The task executor and scheduler used by the OpenEmbedded build
542 system to build images.
543 For more information on BitBake, see the
544 <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>.
545 </para></listitem>
546 <listitem><para id='board-support-package-bsp-term'>
547 <emphasis>Board Support Package (BSP):</emphasis>
548 A group of drivers, definitions, and other components that
549 provide support for a specific hardware configuration.
550 For more information on BSPs, see the
551 <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink>.
552 </para></listitem>
553 <listitem>
554 <para id='build-directory'>
555 <emphasis>Build Directory:</emphasis>
556 This term refers to the area used by the OpenEmbedded build
557 system for builds.
558 The area is created when you <filename>source</filename> the
559 setup environment script that is found in the Source Directory
560 (i.e. <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>).
561 The
562 <link linkend='var-TOPDIR'><filename>TOPDIR</filename></link>
563 variable points to the Build Directory.</para>
564
565 <para>You have a lot of flexibility when creating the Build
566 Directory.
567 Following are some examples that show how to create the
568 directory.
569 The examples assume your
570 <link linkend='source-directory'>Source Directory</link> is
571 named <filename>poky</filename>:
572 <itemizedlist>
573 <listitem><para>Create the Build Directory inside your
574 Source Directory and let the name of the Build
575 Directory default to <filename>build</filename>:
576 <literallayout class='monospaced'>
577 $ cd $HOME/poky
578 $ source &OE_INIT_FILE;
579 </literallayout>
580 </para></listitem>
581 <listitem><para>Create the Build Directory inside your
582 home directory and specifically name it
583 <filename>test-builds</filename>:
584 <literallayout class='monospaced'>
585 $ cd $HOME
586 $ source poky/&OE_INIT_FILE; test-builds
587 </literallayout>
588 </para></listitem>
589 <listitem><para>
590 Provide a directory path and specifically name the
591 Build Directory.
592 Any intermediate folders in the pathname must exist.
593 This next example creates a Build Directory named
594 <filename>YP-&POKYVERSION;</filename>
595 in your home directory within the existing
596 directory <filename>mybuilds</filename>:
597 <literallayout class='monospaced'>
598 $cd $HOME
599 $ source $HOME/poky/&OE_INIT_FILE; $HOME/mybuilds/YP-&POKYVERSION;
600 </literallayout>
601 </para></listitem>
602 </itemizedlist>
603 <note>
604 By default, the Build Directory contains
605 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>,
606 which is a temporary directory the build system uses for
607 its work.
608 <filename>TMPDIR</filename> cannot be under NFS.
609 Thus, by default, the Build Directory cannot be under NFS.
610 However, if you need the Build Directory to be under NFS,
611 you can set this up by setting <filename>TMPDIR</filename>
612 in your <filename>local.conf</filename> file
613 to use a local drive.
614 Doing so effectively separates <filename>TMPDIR</filename>
615 from <filename>TOPDIR</filename>, which is the Build
616 Directory.
617 </note>
618 </para></listitem>
619 <listitem><para id='hardware-build-system-term'>
620 <emphasis>Build System:</emphasis>
621 The system used to build images in a Yocto Project
622 Development environment.
623 The build system is sometimes referred to as the
624 development host.
625 </para></listitem>
626 <listitem><para>
627 <emphasis>Classes:</emphasis>
628 Files that provide for logic encapsulation and inheritance so
629 that commonly used patterns can be defined once and then
630 easily used in multiple recipes.
631 For reference information on the Yocto Project classes, see the
632 "<link linkend='ref-classes'>Classes</link>" chapter.
633 Class files end with the <filename>.bbclass</filename>
634 filename extension.
635 </para></listitem>
636 <listitem><para>
637 <emphasis>Configuration File:</emphasis>
638 Configuration information in various <filename>.conf</filename>
639 files provides global definitions of variables.
640 The <filename>conf/local.conf</filename> configuration file in
641 the
642 <link linkend='build-directory'>Build Directory</link>
643 contains user-defined variables that affect every build.
644 The <filename>meta-poky/conf/distro/poky.conf</filename>
645 configuration file defines Yocto "distro" configuration
646 variables used only when building with this policy.
647 Machine configuration files, which
648 are located throughout the
649 <link linkend='source-directory'>Source Directory</link>, define
650 variables for specific hardware and are only used when building
651 for that target (e.g. the
652 <filename>machine/beaglebone.conf</filename> configuration
653 file defines variables for the Texas Instruments ARM Cortex-A8
654 development board).
655 Configuration files end with a <filename>.conf</filename>
656 filename extension.
657 </para></listitem>
658 <listitem><para id='cross-development-toolchain'>
659 <emphasis>Cross-Development Toolchain:</emphasis>
660 In general, a cross-development toolchain is a collection of
661 software development tools and utilities that run on one
662 architecture and allow you to develop software for a
663 different, or targeted, architecture.
664 These toolchains contain cross-compilers, linkers, and
665 debuggers that are specific to the target architecture.</para>
666
667 <para>The Yocto Project supports two different cross-development
668 toolchains:
669 <itemizedlist>
670 <listitem><para>
671 A toolchain only used by and within
672 BitBake when building an image for a target
673 architecture.
674 </para></listitem>
675 <listitem><para>A relocatable toolchain used outside of
676 BitBake by developers when developing applications
677 that will run on a targeted device.
678 </para></listitem>
679 </itemizedlist></para>
680
681 <para>Creation of these toolchains is simple and automated.
682 For information on toolchain concepts as they apply to the
683 Yocto Project, see the
684 "<link linkend='cross-development-toolchain-generation'>Cross-Development Toolchain Generation</link>"
685 section.
686 You can also find more information on using the
687 relocatable toolchain in the
688 <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink>
689 manual.
690 </para></listitem>
691 <listitem><para>
692 <emphasis>Image:</emphasis>
693 An image is an artifact of the BitBake build process given
694 a collection of recipes and related Metadata.
695 Images are the binary output that run on specific hardware or
696 QEMU and are used for specific use-cases.
697 For a list of the supported image types that the Yocto Project
698 provides, see the
699 "<link linkend='ref-images'>Images</link>"
700 chapter.
701 </para></listitem>
702 <listitem><para>
703 <emphasis>Layer:</emphasis>
704 A collection of recipes representing the core,
705 a BSP, or an application stack.
706 For a discussion specifically on BSP Layers, see the
707 "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>"
708 section in the Yocto Project Board Support Packages (BSP)
709 Developer's Guide.
710 </para></listitem>
711 <listitem><para id='metadata'>
712 <emphasis>Metadata:</emphasis>
713 The files that BitBake parses when building an image.
714 In general, Metadata includes recipes, classes, and
715 configuration files.
716 In the context of the kernel ("kernel Metadata"), the
717 term refers to the kernel config fragments and features
718 contained in the
719 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/yocto-kernel-cache'><filename>yocto-kernel-cache</filename></ulink>
720 Git repository.
721 </para></listitem>
722 <listitem><para id='oe-core'>
723 <emphasis>OE-Core:</emphasis>
724 A core set of Metadata originating with OpenEmbedded (OE)
725 that is shared between OE and the Yocto Project.
726 This Metadata is found in the <filename>meta</filename>
727 directory of the
728 <link linkend='source-directory'>Source Directory</link>.
729 </para></listitem>
730 <listitem><para id='build-system-term'>
731 <emphasis>OpenEmbedded Build System:</emphasis>
732 The build system specific to the Yocto Project.
733 The OpenEmbedded build system is based on another project known
734 as "Poky", which uses
735 <link linkend='bitbake-term'>BitBake</link> as the task
736 executor.
737 Throughout the Yocto Project documentation set, the
738 OpenEmbedded build system is sometimes referred to simply
739 as "the build system".
740 If other build systems, such as a host or target build system
741 are referenced, the documentation clearly states the
742 difference.
743 <note>
744 For some historical information about Poky, see the
745 <link linkend='poky'>Poky</link> term.
746 </note>
747 </para></listitem>
748 <listitem><para>
749 <emphasis>Package:</emphasis>
750 In the context of the Yocto Project, this term refers to a
751 recipe's packaged output produced by BitBake (i.e. a
752 "baked recipe").
753 A package is generally the compiled binaries produced from the
754 recipe's sources.
755 You "bake" something by running it through BitBake.</para>
756
757 <para>It is worth noting that the term "package" can,
758 in general, have subtle meanings.
759 For example, the packages referred to in the
760 "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Build Host Packages</ulink>"
761 section in the Yocto Project Quick Start are compiled binaries
762 that, when installed, add functionality to your Linux
763 distribution.</para>
764
765 <para>Another point worth noting is that historically within
766 the Yocto Project, recipes were referred to as packages - thus,
767 the existence of several BitBake variables that are seemingly
768 mis-named,
769 (e.g. <link linkend='var-PR'><filename>PR</filename></link>,
770 <link linkend='var-PV'><filename>PV</filename></link>, and
771 <link linkend='var-PE'><filename>PE</filename></link>).
772 </para></listitem>
773 <listitem><para>
774 <emphasis>Package Groups:</emphasis>
775 Arbitrary groups of software Recipes.
776 You use package groups to hold recipes that, when built,
777 usually accomplish a single task.
778 For example, a package group could contain the recipes for a
779 company’s proprietary or value-add software.
780 Or, the package group could contain the recipes that enable
781 graphics.
782 A package group is really just another recipe.
783 Because package group files are recipes, they end with the
784 <filename>.bb</filename> filename extension.
785 </para></listitem>
786 <listitem><para id='poky'>
787 <emphasis>Poky:</emphasis>
788 The term "poky", which is pronounced
789 <emphasis>Pah</emphasis>-kee, can mean several things:
790 <itemizedlist>
791 <listitem><para>
792 In its most general sense, poky is an open-source
793 project that was initially developed by OpenedHand.
794 OpenedHand developed poky off of the existing
795 OpenEmbedded build system to create a commercially
796 supportable build system for embedded Linux.
797 After Intel Corporation acquired OpenedHand, the
798 poky project became the basis for the Yocto Project's
799 build system.
800 </para></listitem>
801 <listitem><para>
802 Within the Yocto Project
803 <ulink url='&YOCTO_GIT_URL;'>Source Repositories</ulink>,
804 "poky" exists as a separate Git
805 repository from which you can clone to yield a local
806 Git repository that is a copy on your host system.
807 Thus, "poky" can refer to the upstream or
808 local copy of the files used for development within
809 the Yocto Project.
810 </para></listitem>
811 <listitem><para>
812 Finally, "poky" can refer to the default
813 <link linkend='var-DISTRO'><filename>DISTRO</filename></link>
814 (i.e. distribution) created when you use the Yocto
815 Project in conjunction with the
816 <filename>poky</filename> repository to build an image.
817 </para></listitem>
818 </itemizedlist>
819 </para></listitem>
820 <listitem><para>
821 <emphasis>Recipe:</emphasis>
822 A set of instructions for building packages.
823 A recipe describes where you get source code, which patches
824 to apply, how to configure the source, how to compile it and so on.
825 Recipes also describe dependencies for libraries or for other
826 recipes.
827 Recipes represent the logical unit of execution, the software
828 to build, the images to build, and use the
829 <filename>.bb</filename> file extension.
830 </para></listitem>
831 <listitem><para id='reference-kit-term'>
832 <emphasis>Reference Kit:</emphasis>
833 A working example of a system, which includes a
834 <link linkend='board-support-package-bsp-term'>BSP</link>
835 as well as a
836 <link linkend='hardware-build-system-term'>build system</link>
837 and other components, that can work on specific hardware.
838 </para></listitem>
839 <listitem>
840 <para id='source-directory'>
841 <emphasis>Source Directory:</emphasis>
842 This term refers to the directory structure created as a result
843 of creating a local copy of the <filename>poky</filename> Git
844 repository <filename>git://git.yoctoproject.org/poky</filename>
845 or expanding a released <filename>poky</filename> tarball.
846 <note>
847 Creating a local copy of the <filename>poky</filename>
848 Git repository is the recommended method for setting up
849 your Source Directory.
850 </note>
851 Sometimes you might hear the term "poky directory" used to refer
852 to this directory structure.
853 <note>
854 The OpenEmbedded build system does not support file or
855 directory names that contain spaces.
856 Be sure that the Source Directory you use does not contain
857 these types of names.
858 </note></para>
859
860 <para>The Source Directory contains BitBake, Documentation,
861 Metadata and other files that all support the Yocto Project.
862 Consequently, you must have the Source Directory in place on
863 your development system in order to do any development using
864 the Yocto Project.</para>
865
866 <para>When you create a local copy of the Git repository, you
867 can name the repository anything you like.
868 Throughout much of the documentation, "poky"
869 is used as the name of the top-level folder of the local copy of
870 the poky Git repository.
871 So, for example, cloning the <filename>poky</filename> Git
872 repository results in a local Git repository whose top-level
873 folder is also named "poky".</para>
874
875 <para>While it is not recommended that you use tarball expansion
876 to set up the Source Directory, if you do, the top-level
877 directory name of the Source Directory is derived from the
878 Yocto Project release tarball.
879 For example, downloading and unpacking
880 <filename>&YOCTO_POKY_TARBALL;</filename> results in a
881 Source Directory whose root folder is named
882 <filename>&YOCTO_POKY;</filename>.</para>
883
884 <para>It is important to understand the differences between the
885 Source Directory created by unpacking a released tarball as
886 compared to cloning
887 <filename>git://git.yoctoproject.org/poky</filename>.
888 When you unpack a tarball, you have an exact copy of the files
889 based on the time of release - a fixed release point.
890 Any changes you make to your local files in the Source Directory
891 are on top of the release and will remain local only.
892 On the other hand, when you clone the <filename>poky</filename>
893 Git repository, you have an active development repository with
894 access to the upstream repository's branches and tags.
895 In this case, any local changes you make to the local
896 Source Directory can be later applied to active development
897 branches of the upstream <filename>poky</filename> Git
898 repository.</para>
899
900 <para>For more information on concepts related to Git
901 repositories, branches, and tags, see the
902 "<ulink url='&YOCTO_DOCS_OVERVIEW_URL;#repositories-tags-and-branches'>Repositories, Tags, and Branches</ulink>"
903 section in the Yocto Project Overview Manual.
904 </para></listitem>
905 <listitem><para><emphasis>Task:</emphasis>
906 A unit of execution for BitBake (e.g.
907 <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>,
908 <link linkend='ref-tasks-fetch'><filename>do_fetch</filename></link>,
909 <link linkend='ref-tasks-patch'><filename>do_patch</filename></link>,
910 and so forth).
911 </para></listitem>
912 <listitem><para id='toaster-term'><emphasis>Toaster:</emphasis>
913 A web interface to the Yocto Project's
914 <link linkend='build-system-term'>OpenEmbedded Build System</link>.
915 The interface enables you to configure and run your builds.
916 Information about builds is collected and stored in a database.
917 For information on Toaster, see the
918 <ulink url='&YOCTO_DOCS_TOAST_URL;'>Yocto Project Toaster Manual</ulink>.
919 </para></listitem>
920 <listitem><para>
921 <emphasis>Upstream:</emphasis>
922 A reference to source code or repositories
923 that are not local to the development system but located in a
924 master area that is controlled by the maintainer of the source
925 code.
926 For example, in order for a developer to work on a particular
927 piece of code, they need to first get a copy of it from an
928 "upstream" source.
929 </para></listitem>
930 </itemizedlist>
931 </para>
932</section>
933
934</chapter> 489</chapter>
935<!-- 490<!--
936vim: expandtab tw=80 ts=4 491vim: expandtab tw=80 ts=4
diff --git a/documentation/ref-manual/ref-terms.xml b/documentation/ref-manual/ref-terms.xml
new file mode 100644
index 0000000000..f5ff7df5fb
--- /dev/null
+++ b/documentation/ref-manual/ref-terms.xml
@@ -0,0 +1,436 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4
5<chapter id='ref-terms'>
6<title>Yocto Project Terms</title>
7
8 <para>
9 Following is a list of terms and definitions users new to the Yocto
10 Project development environment might find helpful.
11 While some of these terms are universal, the list includes them
12 just in case:
13 <itemizedlist>
14 <listitem><para>
15 <emphasis>Append Files:</emphasis>
16 Files that append build information to a recipe file.
17 Append files are known as BitBake append files and
18 <filename>.bbappend</filename> files.
19 The OpenEmbedded build system expects every append file to have
20 a corresponding recipe (<filename>.bb</filename>) file.
21 Furthermore, the append file and corresponding recipe file
22 must use the same root filename.
23 The filenames can differ only in the file type suffix used
24 (e.g.
25 <filename>formfactor_0.0.bb</filename> and
26 <filename>formfactor_0.0.bbappend</filename>).</para>
27
28 <para>Information in append files extends or overrides the
29 information in the similarly-named recipe file.
30 For an example of an append file in use, see the
31 "<ulink url='&YOCTO_DOCS_DEV_URL;#using-bbappend-files'>Using .bbappend Files in Your Layer</ulink>"
32 section in the Yocto Project Development Tasks Manual.
33 <note>
34 Append files can also use wildcard patterns in their
35 version numbers so they can be applied to more than one
36 version of the underlying recipe file.
37 </note>
38 </para></listitem>
39 <listitem><para id='bitbake-term'>
40 <emphasis>BitBake:</emphasis>
41 The task executor and scheduler used by the OpenEmbedded build
42 system to build images.
43 For more information on BitBake, see the
44 <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>.
45 </para></listitem>
46 <listitem><para id='board-support-package-bsp-term'>
47 <emphasis>Board Support Package (BSP):</emphasis>
48 A group of drivers, definitions, and other components that
49 provide support for a specific hardware configuration.
50 For more information on BSPs, see the
51 <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink>.
52 </para></listitem>
53 <listitem>
54 <para id='build-directory'>
55 <emphasis>Build Directory:</emphasis>
56 This term refers to the area used by the OpenEmbedded build
57 system for builds.
58 The area is created when you <filename>source</filename> the
59 setup environment script that is found in the Source Directory
60 (i.e. <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>).
61 The
62 <link linkend='var-TOPDIR'><filename>TOPDIR</filename></link>
63 variable points to the Build Directory.</para>
64
65 <para>You have a lot of flexibility when creating the Build
66 Directory.
67 Following are some examples that show how to create the
68 directory.
69 The examples assume your
70 <link linkend='source-directory'>Source Directory</link> is
71 named <filename>poky</filename>:
72 <itemizedlist>
73 <listitem><para>Create the Build Directory inside your
74 Source Directory and let the name of the Build
75 Directory default to <filename>build</filename>:
76 <literallayout class='monospaced'>
77 $ cd $HOME/poky
78 $ source &OE_INIT_FILE;
79 </literallayout>
80 </para></listitem>
81 <listitem><para>Create the Build Directory inside your
82 home directory and specifically name it
83 <filename>test-builds</filename>:
84 <literallayout class='monospaced'>
85 $ cd $HOME
86 $ source poky/&OE_INIT_FILE; test-builds
87 </literallayout>
88 </para></listitem>
89 <listitem><para>
90 Provide a directory path and specifically name the
91 Build Directory.
92 Any intermediate folders in the pathname must exist.
93 This next example creates a Build Directory named
94 <filename>YP-&POKYVERSION;</filename>
95 in your home directory within the existing
96 directory <filename>mybuilds</filename>:
97 <literallayout class='monospaced'>
98 $cd $HOME
99 $ source $HOME/poky/&OE_INIT_FILE; $HOME/mybuilds/YP-&POKYVERSION;
100 </literallayout>
101 </para></listitem>
102 </itemizedlist>
103 <note>
104 By default, the Build Directory contains
105 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>,
106 which is a temporary directory the build system uses for
107 its work.
108 <filename>TMPDIR</filename> cannot be under NFS.
109 Thus, by default, the Build Directory cannot be under NFS.
110 However, if you need the Build Directory to be under NFS,
111 you can set this up by setting <filename>TMPDIR</filename>
112 in your <filename>local.conf</filename> file
113 to use a local drive.
114 Doing so effectively separates <filename>TMPDIR</filename>
115 from <filename>TOPDIR</filename>, which is the Build
116 Directory.
117 </note>
118 </para></listitem>
119 <listitem><para id='hardware-build-system-term'>
120 <emphasis>Build System:</emphasis>
121 The system used to build images in a Yocto Project
122 Development environment.
123 The build system is sometimes referred to as the
124 development host.
125 </para></listitem>
126 <listitem><para>
127 <emphasis>Classes:</emphasis>
128 Files that provide for logic encapsulation and inheritance so
129 that commonly used patterns can be defined once and then
130 easily used in multiple recipes.
131 For reference information on the Yocto Project classes, see the
132 "<link linkend='ref-classes'>Classes</link>" chapter.
133 Class files end with the <filename>.bbclass</filename>
134 filename extension.
135 </para></listitem>
136 <listitem><para>
137 <emphasis>Configuration File:</emphasis>
138 Configuration information in various <filename>.conf</filename>
139 files provides global definitions of variables.
140 The <filename>conf/local.conf</filename> configuration file in
141 the
142 <link linkend='build-directory'>Build Directory</link>
143 contains user-defined variables that affect every build.
144 The <filename>meta-poky/conf/distro/poky.conf</filename>
145 configuration file defines Yocto "distro" configuration
146 variables used only when building with this policy.
147 Machine configuration files, which
148 are located throughout the
149 <link linkend='source-directory'>Source Directory</link>, define
150 variables for specific hardware and are only used when building
151 for that target (e.g. the
152 <filename>machine/beaglebone.conf</filename> configuration
153 file defines variables for the Texas Instruments ARM Cortex-A8
154 development board).
155 Configuration files end with a <filename>.conf</filename>
156 filename extension.
157 </para></listitem>
158 <listitem><para id='cross-development-toolchain'>
159 <emphasis>Cross-Development Toolchain:</emphasis>
160 In general, a cross-development toolchain is a collection of
161 software development tools and utilities that run on one
162 architecture and allow you to develop software for a
163 different, or targeted, architecture.
164 These toolchains contain cross-compilers, linkers, and
165 debuggers that are specific to the target architecture.</para>
166
167 <para>The Yocto Project supports two different cross-development
168 toolchains:
169 <itemizedlist>
170 <listitem><para>
171 A toolchain only used by and within
172 BitBake when building an image for a target
173 architecture.
174 </para></listitem>
175 <listitem><para>A relocatable toolchain used outside of
176 BitBake by developers when developing applications
177 that will run on a targeted device.
178 </para></listitem>
179 </itemizedlist></para>
180
181 <para>Creation of these toolchains is simple and automated.
182 For information on toolchain concepts as they apply to the
183 Yocto Project, see the
184 "<link linkend='cross-development-toolchain-generation'>Cross-Development Toolchain Generation</link>"
185 section.
186 You can also find more information on using the
187 relocatable toolchain in the
188 <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink>
189 manual.
190 </para></listitem>
191 <listitem><para>
192 <emphasis>Image:</emphasis>
193 An image is an artifact of the BitBake build process given
194 a collection of recipes and related Metadata.
195 Images are the binary output that run on specific hardware or
196 QEMU and are used for specific use-cases.
197 For a list of the supported image types that the Yocto Project
198 provides, see the
199 "<link linkend='ref-images'>Images</link>"
200 chapter.
201 </para></listitem>
202 <listitem><para>
203 <emphasis>Layer:</emphasis>
204 A collection of recipes representing the core,
205 a BSP, or an application stack.
206 For a discussion specifically on BSP Layers, see the
207 "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>"
208 section in the Yocto Project Board Support Packages (BSP)
209 Developer's Guide.
210 </para></listitem>
211 <listitem><para id='metadata'>
212 <emphasis>Metadata:</emphasis>
213 The files that BitBake parses when building an image.
214 In general, Metadata includes recipes, classes, and
215 configuration files.
216 In the context of the kernel ("kernel Metadata"), the
217 term refers to the kernel config fragments and features
218 contained in the
219 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/yocto-kernel-cache'><filename>yocto-kernel-cache</filename></ulink>
220 Git repository.
221 </para></listitem>
222 <listitem><para id='oe-core'>
223 <emphasis>OE-Core:</emphasis>
224 A core set of Metadata originating with OpenEmbedded (OE)
225 that is shared between OE and the Yocto Project.
226 This Metadata is found in the <filename>meta</filename>
227 directory of the
228 <link linkend='source-directory'>Source Directory</link>.
229 </para></listitem>
230 <listitem><para id='build-system-term'>
231 <emphasis>OpenEmbedded Build System:</emphasis>
232 The build system specific to the Yocto Project.
233 The OpenEmbedded build system is based on another project known
234 as "Poky", which uses
235 <link linkend='bitbake-term'>BitBake</link> as the task
236 executor.
237 Throughout the Yocto Project documentation set, the
238 OpenEmbedded build system is sometimes referred to simply
239 as "the build system".
240 If other build systems, such as a host or target build system
241 are referenced, the documentation clearly states the
242 difference.
243 <note>
244 For some historical information about Poky, see the
245 <link linkend='poky'>Poky</link> term.
246 </note>
247 </para></listitem>
248 <listitem><para>
249 <emphasis>Package:</emphasis>
250 In the context of the Yocto Project, this term refers to a
251 recipe's packaged output produced by BitBake (i.e. a
252 "baked recipe").
253 A package is generally the compiled binaries produced from the
254 recipe's sources.
255 You "bake" something by running it through BitBake.</para>
256
257 <para>It is worth noting that the term "package" can,
258 in general, have subtle meanings.
259 For example, the packages referred to in the
260 "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Build Host Packages</ulink>"
261 section in the Yocto Project Quick Start are compiled binaries
262 that, when installed, add functionality to your Linux
263 distribution.</para>
264
265 <para>Another point worth noting is that historically within
266 the Yocto Project, recipes were referred to as packages - thus,
267 the existence of several BitBake variables that are seemingly
268 mis-named,
269 (e.g. <link linkend='var-PR'><filename>PR</filename></link>,
270 <link linkend='var-PV'><filename>PV</filename></link>, and
271 <link linkend='var-PE'><filename>PE</filename></link>).
272 </para></listitem>
273 <listitem><para>
274 <emphasis>Package Groups:</emphasis>
275 Arbitrary groups of software Recipes.
276 You use package groups to hold recipes that, when built,
277 usually accomplish a single task.
278 For example, a package group could contain the recipes for a
279 company’s proprietary or value-add software.
280 Or, the package group could contain the recipes that enable
281 graphics.
282 A package group is really just another recipe.
283 Because package group files are recipes, they end with the
284 <filename>.bb</filename> filename extension.
285 </para></listitem>
286 <listitem><para id='poky'>
287 <emphasis>Poky:</emphasis>
288 The term "poky", which is pronounced
289 <emphasis>Pah</emphasis>-kee, can mean several things:
290 <itemizedlist>
291 <listitem><para>
292 In its most general sense, poky is an open-source
293 project that was initially developed by OpenedHand.
294 OpenedHand developed poky off of the existing
295 OpenEmbedded build system to create a commercially
296 supportable build system for embedded Linux.
297 After Intel Corporation acquired OpenedHand, the
298 poky project became the basis for the Yocto Project's
299 build system.
300 </para></listitem>
301 <listitem><para>
302 Within the Yocto Project
303 <ulink url='&YOCTO_GIT_URL;'>Source Repositories</ulink>,
304 "poky" exists as a separate Git
305 repository from which you can clone to yield a local
306 Git repository that is a copy on your host system.
307 Thus, "poky" can refer to the upstream or
308 local copy of the files used for development within
309 the Yocto Project.
310 </para></listitem>
311 <listitem><para>
312 Finally, "poky" can refer to the default
313 <link linkend='var-DISTRO'><filename>DISTRO</filename></link>
314 (i.e. distribution) created when you use the Yocto
315 Project in conjunction with the
316 <filename>poky</filename> repository to build an image.
317 </para></listitem>
318 </itemizedlist>
319 </para></listitem>
320 <listitem><para>
321 <emphasis>Recipe:</emphasis>
322 A set of instructions for building packages.
323 A recipe describes where you get source code, which patches
324 to apply, how to configure the source, how to compile it and so on.
325 Recipes also describe dependencies for libraries or for other
326 recipes.
327 Recipes represent the logical unit of execution, the software
328 to build, the images to build, and use the
329 <filename>.bb</filename> file extension.
330 </para></listitem>
331 <listitem><para id='reference-kit-term'>
332 <emphasis>Reference Kit:</emphasis>
333 A working example of a system, which includes a
334 <link linkend='board-support-package-bsp-term'>BSP</link>
335 as well as a
336 <link linkend='hardware-build-system-term'>build system</link>
337 and other components, that can work on specific hardware.
338 </para></listitem>
339 <listitem>
340 <para id='source-directory'>
341 <emphasis>Source Directory:</emphasis>
342 This term refers to the directory structure created as a result
343 of creating a local copy of the <filename>poky</filename> Git
344 repository <filename>git://git.yoctoproject.org/poky</filename>
345 or expanding a released <filename>poky</filename> tarball.
346 <note>
347 Creating a local copy of the <filename>poky</filename>
348 Git repository is the recommended method for setting up
349 your Source Directory.
350 </note>
351 Sometimes you might hear the term "poky directory" used to refer
352 to this directory structure.
353 <note>
354 The OpenEmbedded build system does not support file or
355 directory names that contain spaces.
356 Be sure that the Source Directory you use does not contain
357 these types of names.
358 </note></para>
359
360 <para>The Source Directory contains BitBake, Documentation,
361 Metadata and other files that all support the Yocto Project.
362 Consequently, you must have the Source Directory in place on
363 your development system in order to do any development using
364 the Yocto Project.</para>
365
366 <para>When you create a local copy of the Git repository, you
367 can name the repository anything you like.
368 Throughout much of the documentation, "poky"
369 is used as the name of the top-level folder of the local copy of
370 the poky Git repository.
371 So, for example, cloning the <filename>poky</filename> Git
372 repository results in a local Git repository whose top-level
373 folder is also named "poky".</para>
374
375 <para>While it is not recommended that you use tarball expansion
376 to set up the Source Directory, if you do, the top-level
377 directory name of the Source Directory is derived from the
378 Yocto Project release tarball.
379 For example, downloading and unpacking
380 <filename>&YOCTO_POKY_TARBALL;</filename> results in a
381 Source Directory whose root folder is named
382 <filename>&YOCTO_POKY;</filename>.</para>
383
384 <para>It is important to understand the differences between the
385 Source Directory created by unpacking a released tarball as
386 compared to cloning
387 <filename>git://git.yoctoproject.org/poky</filename>.
388 When you unpack a tarball, you have an exact copy of the files
389 based on the time of release - a fixed release point.
390 Any changes you make to your local files in the Source Directory
391 are on top of the release and will remain local only.
392 On the other hand, when you clone the <filename>poky</filename>
393 Git repository, you have an active development repository with
394 access to the upstream repository's branches and tags.
395 In this case, any local changes you make to the local
396 Source Directory can be later applied to active development
397 branches of the upstream <filename>poky</filename> Git
398 repository.</para>
399
400 <para>For more information on concepts related to Git
401 repositories, branches, and tags, see the
402 "<ulink url='&YOCTO_DOCS_OVERVIEW_URL;#repositories-tags-and-branches'>Repositories, Tags, and Branches</ulink>"
403 section in the Yocto Project Overview Manual.
404 </para></listitem>
405 <listitem><para><emphasis>Task:</emphasis>
406 A unit of execution for BitBake (e.g.
407 <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>,
408 <link linkend='ref-tasks-fetch'><filename>do_fetch</filename></link>,
409 <link linkend='ref-tasks-patch'><filename>do_patch</filename></link>,
410 and so forth).
411 </para></listitem>
412 <listitem><para id='toaster-term'><emphasis>Toaster:</emphasis>
413 A web interface to the Yocto Project's
414 <link linkend='build-system-term'>OpenEmbedded Build System</link>.
415 The interface enables you to configure and run your builds.
416 Information about builds is collected and stored in a database.
417 For information on Toaster, see the
418 <ulink url='&YOCTO_DOCS_TOAST_URL;'>Yocto Project Toaster Manual</ulink>.
419 </para></listitem>
420 <listitem><para>
421 <emphasis>Upstream:</emphasis>
422 A reference to source code or repositories
423 that are not local to the development system but located in a
424 master area that is controlled by the maintainer of the source
425 code.
426 For example, in order for a developer to work on a particular
427 piece of code, they need to first get a copy of it from an
428 "upstream" source.
429 </para></listitem>
430 </itemizedlist>
431 </para>
432
433</chapter>
434<!--
435vim: expandtab tw=80 ts=4
436-->
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2026-01-24 14:25:44 +0000