summaryrefslogtreecommitdiffstats
path: root/documentation/ref-manual
diff options
context:
space:
mode:
authorScott Rifenbark <srifenbark@gmail.com>2017-08-07 15:30:38 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2017-09-02 00:52:56 +0100
commitd0c89b6d59840f900d1aa9bdde32197eef7cdbb1 (patch)
tree1df6ded1bfc264204b8f73d0d208edf3a45cd266 /documentation/ref-manual
parent4712ba38e52f0e3759049a75f8fee6a9a28c2eba (diff)
downloadpoky-d0c89b6d59840f900d1aa9bdde32197eef7cdbb1.tar.gz
dev-manual: Updates to "Using .bbappend Files in Your Layer"
I did some rewriting for clarity in the "Using .bbappend Files in Your Layer" section. The section needed to be retitled so focus on the layer aspect of .bbappend files. Also, while I was in there, I did more work on the prose in general. Also had to fix some links in the bsp, kernel, and ref manuals that linked into the section whose name I changes. (From yocto-docs rev: 27003c525a05ffa2f810a038c7c8f96bb7535986) Signed-off-by: Scott Rifenbark <srifenbark@gmail.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/ref-manual')
-rw-r--r--documentation/ref-manual/introduction.xml407
1 files changed, 407 insertions, 0 deletions
diff --git a/documentation/ref-manual/introduction.xml b/documentation/ref-manual/introduction.xml
index cec23b6039..e3b4df3a91 100644
--- a/documentation/ref-manual/introduction.xml
+++ b/documentation/ref-manual/introduction.xml
@@ -621,6 +621,413 @@
621 </para> 621 </para>
622</section> 622</section>
623 623
624<section id='yocto-project-terms'>
625 <title>Yocto Project Terms</title>
626
627 <para>
628 Following is a list of terms and definitions users new to the Yocto
629 Project development environment might find helpful.
630 While some of these terms are universal, the list includes them
631 just in case:
632 <itemizedlist>
633 <listitem><para>
634 <emphasis>Append Files:</emphasis>
635 Files that append build information to a recipe file.
636 Append files are known as BitBake append files and
637 <filename>.bbappend</filename> files.
638 The OpenEmbedded build system expects every append file to have
639 a corresponding recipe (<filename>.bb</filename>) file.
640 Furthermore, the append file and corresponding recipe file
641 must use the same root filename.
642 The filenames can differ only in the file type suffix used
643 (e.g.
644 <filename>formfactor_0.0.bb</filename> and
645 <filename>formfactor_0.0.bbappend</filename>).</para>
646
647 <para>Information in append files extends or overrides the
648 information in the similarly-named recipe file.
649 For an example of an append file in use, see the
650 "<ulink url='&YOCTO_DOCS_DEV_URL;#using-bbappend-files'>Using .bbappend Files in Your Layer</ulink>"
651 section in the Yocto Project Development Manual.
652 <note>
653 Append files can also use wildcard patterns in their
654 version numbers so they can be applied to more than one
655 version of the underlying recipe file.
656 </note>
657 </para></listitem>
658 <listitem><para id='bitbake-term'>
659 <emphasis>BitBake:</emphasis>
660 The task executor and scheduler used by the OpenEmbedded build
661 system to build images.
662 For more information on BitBake, see the
663 <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>.
664 </para></listitem>
665 <listitem>
666 <para id='build-directory'>
667 <emphasis>Build Directory:</emphasis>
668 This term refers to the area used by the OpenEmbedded build
669 system for builds.
670 The area is created when you <filename>source</filename> the
671 setup environment script that is found in the Source Directory
672 (i.e. <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>
673 or
674 <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>).
675 The
676 <link linkend='var-TOPDIR'><filename>TOPDIR</filename></link>
677 variable points to the Build Directory.</para>
678
679 <para>You have a lot of flexibility when creating the Build
680 Directory.
681 Following are some examples that show how to create the
682 directory.
683 The examples assume your
684 <link linkend='source-directory'>Source Directory</link> is
685 named <filename>poky</filename>:
686 <itemizedlist>
687 <listitem><para>Create the Build Directory inside your
688 Source Directory and let the name of the Build
689 Directory default to <filename>build</filename>:
690 <literallayout class='monospaced'>
691 $ cd $HOME/poky
692 $ source &OE_INIT_FILE;
693 </literallayout>
694 </para></listitem>
695 <listitem><para>Create the Build Directory inside your
696 home directory and specifically name it
697 <filename>test-builds</filename>:
698 <literallayout class='monospaced'>
699 $ cd $HOME
700 $ source poky/&OE_INIT_FILE; test-builds
701 </literallayout>
702 </para></listitem>
703 <listitem><para>
704 Provide a directory path and specifically name the
705 Build Directory.
706 Any intermediate folders in the pathname must exist.
707 This next example creates a Build Directory named
708 <filename>YP-&POKYVERSION;</filename>
709 in your home directory within the existing
710 directory <filename>mybuilds</filename>:
711 <literallayout class='monospaced'>
712 $cd $HOME
713 $ source $HOME/poky/&OE_INIT_FILE; $HOME/mybuilds/YP-&POKYVERSION;
714 </literallayout>
715 </para></listitem>
716 </itemizedlist>
717 <note>
718 By default, the Build Directory contains
719 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>,
720 which is a temporary directory the build system uses for
721 its work.
722 <filename>TMPDIR</filename> cannot be under NFS.
723 Thus, by default, the Build Directory cannot be under NFS.
724 However, if you need the Build Directory to be under NFS,
725 you can set this up by setting <filename>TMPDIR</filename>
726 in your <filename>local.conf</filename> file
727 to use a local drive.
728 Doing so effectively separates <filename>TMPDIR</filename>
729 from <filename>TOPDIR</filename>, which is the Build
730 Directory.
731 </note>
732 </para></listitem>
733 <listitem><para>
734 <emphasis>Classes:</emphasis>
735 Files that provide for logic encapsulation and inheritance so
736 that commonly used patterns can be defined once and then
737 easily used in multiple recipes.
738 For reference information on the Yocto Project classes, see the
739 "<link linkend='ref-classes'>Classes</link>" chapter.
740 Class files end with the <filename>.bbclass</filename>
741 filename extension.
742 </para></listitem>
743 <listitem><para>
744 <emphasis>Configuration File:</emphasis>
745 Configuration information in various <filename>.conf</filename>
746 files provides global definitions of variables.
747 The <filename>conf/local.conf</filename> configuration file in
748 the
749 <link linkend='build-directory'>Build Directory</link>
750 contains user-defined variables that affect every build.
751 The <filename>meta-poky/conf/distro/poky.conf</filename>
752 configuration file defines Yocto "distro" configuration
753 variables used only when building with this policy.
754 Machine configuration files, which
755 are located throughout the
756 <link linkend='source-directory'>Source Directory</link>, define
757 variables for specific hardware and are only used when building
758 for that target (e.g. the
759 <filename>machine/beaglebone.conf</filename> configuration
760 file defines variables for the Texas Instruments ARM Cortex-A8
761 development board).
762 Configuration files end with a <filename>.conf</filename>
763 filename extension.
764 </para></listitem>
765 <listitem><para id='cross-development-toolchain'>
766 <emphasis>Cross-Development Toolchain:</emphasis>
767 In general, a cross-development toolchain is a collection of
768 software development tools and utilities that run on one
769 architecture and allow you to develop software for a
770 different, or targeted, architecture.
771 These toolchains contain cross-compilers, linkers, and
772 debuggers that are specific to the target architecture.</para>
773
774 <para>The Yocto Project supports two different cross-development
775 toolchains:
776 <itemizedlist>
777 <listitem><para>
778 A toolchain only used by and within
779 BitBake when building an image for a target
780 architecture.
781 </para></listitem>
782 <listitem><para>A relocatable toolchain used outside of
783 BitBake by developers when developing applications
784 that will run on a targeted device.
785 </para></listitem>
786 </itemizedlist></para>
787
788 <para>Creation of these toolchains is simple and automated.
789 For information on toolchain concepts as they apply to the
790 Yocto Project, see the
791 "<link linkend='cross-development-toolchain-generation'>Cross-Development Toolchain Generation</link>"
792 section.
793 You can also find more information on using the
794 relocatable toolchain in the
795 <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Software Development Kit (SDK) Developer's Guide</ulink>.
796 </para></listitem>
797 <listitem><para>
798 <emphasis>Image:</emphasis>
799 An image is an artifact of the BitBake build process given
800 a collection of recipes and related Metadata.
801 Images are the binary output that run on specific hardware or
802 QEMU and are used for specific use-cases.
803 For a list of the supported image types that the Yocto Project
804 provides, see the
805 "<link linkend='ref-images'>Images</link>"
806 chapter.
807 </para></listitem>
808 <listitem><para>
809 <emphasis>Layer:</emphasis>
810 A collection of recipes representing the core,
811 a BSP, or an application stack.
812 For a discussion specifically on BSP Layers, see the
813 "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>"
814 section in the Yocto Project Board Support Packages (BSP)
815 Developer's Guide.
816 </para></listitem>
817 <listitem><para id='metadata'>
818 <emphasis>Metadata:</emphasis>
819 The files that BitBake parses when building an image.
820 In general, Metadata includes recipes, classes, and
821 configuration files.
822 In the context of the kernel ("kernel Metadata"),
823 it refers to Metadata in the <filename>meta</filename>
824 branches of the kernel source Git repositories.
825 </para></listitem>
826 <listitem><para id='oe-core'>
827 <emphasis>OE-Core:</emphasis>
828 A core set of Metadata originating with OpenEmbedded (OE)
829 that is shared between OE and the Yocto Project.
830 This Metadata is found in the <filename>meta</filename>
831 directory of the
832 <link linkend='source-directory'>Source Directory</link>.
833 </para></listitem>
834 <listitem><para id='build-system-term'>
835 <emphasis>OpenEmbedded Build System:</emphasis>
836 The build system specific to the Yocto Project.
837 The OpenEmbedded build system is based on another project known
838 as "Poky", which uses
839 <link linkend='bitbake-term'>BitBake</link> as the task
840 executor.
841 Throughout the Yocto Project documentation set, the
842 OpenEmbedded build system is sometimes referred to simply
843 as "the build system".
844 If other build systems, such as a host or target build system
845 are referenced, the documentation clearly states the
846 difference.
847 <note>
848 For some historical information about Poky, see the
849 <link linkend='poky'>Poky</link> term.
850 </note>
851 </para></listitem>
852 <listitem><para>
853 <emphasis>Package:</emphasis>
854 In the context of the Yocto Project, this term refers to a
855 recipe's packaged output produced by BitBake (i.e. a
856 "baked recipe").
857 A package is generally the compiled binaries produced from the
858 recipe's sources.
859 You "bake" something by running it through BitBake.</para>
860
861 <para>It is worth noting that the term "package" can,
862 in general, have subtle meanings.
863 For example, the packages referred to in the
864 "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Build Host Packages</ulink>"
865 section in the Yocto Project Quick Start are compiled binaries
866 that, when installed, add functionality to your Linux
867 distribution.</para>
868
869 <para>Another point worth noting is that historically within
870 the Yocto Project, recipes were referred to as packages - thus,
871 the existence of several BitBake variables that are seemingly
872 mis-named,
873 (e.g. <link linkend='var-PR'><filename>PR</filename></link>,
874 <link linkend='var-PV'><filename>PV</filename></link>, and
875 <link linkend='var-PE'><filename>PE</filename></link>).
876 </para></listitem>
877 <listitem><para>
878 <emphasis>Package Groups:</emphasis>
879 Arbitrary groups of software Recipes.
880 You use package groups to hold recipes that, when built,
881 usually accomplish a single task.
882 For example, a package group could contain the recipes for a
883 company’s proprietary or value-add software.
884 Or, the package group could contain the recipes that enable
885 graphics.
886 A package group is really just another recipe.
887 Because package group files are recipes, they end with the
888 <filename>.bb</filename> filename extension.
889 </para></listitem>
890 <listitem><para id='poky'>
891 <emphasis>Poky:</emphasis>
892 The term "poky", which is pronounced
893 <emphasis>Pah</emphasis>-kee, can mean several things:
894 <itemizedlist>
895 <listitem><para>
896 In its most general sense, poky is an open-source
897 project that was initially developed by OpenedHand.
898 OpenedHand developed poky off of the existing
899 OpenEmbedded build system to create a commercially
900 supportable build system for embedded Linux.
901 After Intel Corporation acquired OpenedHand, the
902 poky project became the basis for the Yocto Project's
903 build system.
904 </para></listitem>
905 <listitem><para>
906 Within the Yocto Project
907 <ulink url='&YOCTO_GIT_URL;'>Source Repositories</ulink>,
908 "poky" exists as a separate Git
909 repository from which you can clone to yield a local
910 Git repository that is a copy on your host system.
911 Thus, "poky" can refer to the upstream or
912 local copy of the files used for development within
913 the Yocto Project.
914 </para></listitem>
915 <listitem><para>
916 Finally, "poky" can refer to the default
917 <link linkend='var-DISTRO'><filename>DISTRO</filename></link>
918 (i.e. distribution) created when you use the Yocto
919 Project in conjunction with the
920 <filename>poky</filename> repository to build an image.
921 </para></listitem>
922 </itemizedlist>
923 </para></listitem>
924 <listitem><para>
925 <emphasis>Recipe:</emphasis>
926 A set of instructions for building packages.
927 A recipe describes where you get source code, which patches
928 to apply, how to configure the source, how to compile it and so on.
929 Recipes also describe dependencies for libraries or for other
930 recipes.
931 Recipes represent the logical unit of execution, the software
932 to build, the images to build, and use the
933 <filename>.bb</filename> file extension.
934 </para></listitem>
935 <listitem>
936 <para id='source-directory'>
937 <emphasis>Source Directory:</emphasis>
938 This term refers to the directory structure created as a result
939 of creating a local copy of the <filename>poky</filename> Git
940 repository <filename>git://git.yoctoproject.org/poky</filename>
941 or expanding a released <filename>poky</filename> tarball.
942 <note>
943 Creating a local copy of the <filename>poky</filename>
944 Git repository is the recommended method for setting up
945 your Source Directory.
946 </note>
947 Sometimes you might hear the term "poky directory" used to refer
948 to this directory structure.
949 <note>
950 The OpenEmbedded build system does not support file or
951 directory names that contain spaces.
952 Be sure that the Source Directory you use does not contain
953 these types of names.
954 </note></para>
955
956 <para>The Source Directory contains BitBake, Documentation,
957 Metadata and other files that all support the Yocto Project.
958 Consequently, you must have the Source Directory in place on
959 your development system in order to do any development using
960 the Yocto Project.</para>
961
962 <para>When you create a local copy of the Git repository, you
963 can name the repository anything you like.
964 Throughout much of the documentation, "poky"
965 is used as the name of the top-level folder of the local copy of
966 the poky Git repository.
967 So, for example, cloning the <filename>poky</filename> Git
968 repository results in a local Git repository whose top-level
969 folder is also named "poky".</para>
970
971 <para>While it is not recommended that you use tarball expansion
972 to set up the Source Directory, if you do, the top-level
973 directory name of the Source Directory is derived from the
974 Yocto Project release tarball.
975 For example, downloading and unpacking
976 <filename>&YOCTO_POKY_TARBALL;</filename> results in a
977 Source Directory whose root folder is named
978 <filename>&YOCTO_POKY;</filename>.</para>
979
980 <para>It is important to understand the differences between the
981 Source Directory created by unpacking a released tarball as
982 compared to cloning
983 <filename>git://git.yoctoproject.org/poky</filename>.
984 When you unpack a tarball, you have an exact copy of the files
985 based on the time of release - a fixed release point.
986 Any changes you make to your local files in the Source Directory
987 are on top of the release and will remain local only.
988 On the other hand, when you clone the <filename>poky</filename>
989 Git repository, you have an active development repository with
990 access to the upstream repository's branches and tags.
991 In this case, any local changes you make to the local
992 Source Directory can be later applied to active development
993 branches of the upstream <filename>poky</filename> Git
994 repository.</para>
995
996 <para>For more information on concepts related to Git
997 repositories, branches, and tags, see the
998 "<link linkend='repositories-tags-and-branches'>Repositories, Tags, and Branches</link>"
999 section.
1000 </para></listitem>
1001 <listitem><para><emphasis>Task:</emphasis>
1002 A unit of execution for BitBake (e.g.
1003 <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>,
1004 <link linkend='ref-tasks-fetch'><filename>do_fetch</filename></link>,
1005 <link linkend='ref-tasks-patch'><filename>do_patch</filename></link>,
1006 and so forth).
1007 </para></listitem>
1008 <listitem><para id='toaster-term'><emphasis>Toaster:</emphasis>
1009 A web interface to the Yocto Project's
1010 <link linkend='build-system-term'>OpenEmbedded Build System</link>.
1011 The interface enables you to configure and run your builds.
1012 Information about builds is collected and stored in a database.
1013 For information on Toaster, see the
1014 <ulink url='&YOCTO_DOCS_TOAST_URL;'>Yocto Project Toaster Manual</ulink>.
1015 </para></listitem>
1016 <listitem><para>
1017 <emphasis>Upstream:</emphasis>
1018 A reference to source code or repositories
1019 that are not local to the development system but located in a
1020 master area that is controlled by the maintainer of the source
1021 code.
1022 For example, in order for a developer to work on a particular
1023 piece of code, they need to first get a copy of it from an
1024 "upstream" source.
1025 </para></listitem>
1026 </itemizedlist>
1027 </para>
1028</section>
1029
1030>>>>>>> a82bcc9... dev-manual: Updates to "Using .bbappend Files in Your Layer"
624</chapter> 1031</chapter>
625<!-- 1032<!--
626vim: expandtab tw=80 ts=4 1033vim: expandtab tw=80 ts=4
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-11-13 06:10:54 +0000