diff options
Diffstat (limited to 'poky/documentation/ref-manual/ref-terms.xml')
| -rw-r--r-- | poky/documentation/ref-manual/ref-terms.xml | 507 |
1 files changed, 507 insertions, 0 deletions
diff --git a/poky/documentation/ref-manual/ref-terms.xml b/poky/documentation/ref-manual/ref-terms.xml new file mode 100644 index 000000000..cc09d3f8a --- /dev/null +++ b/poky/documentation/ref-manual/ref-terms.xml @@ -0,0 +1,507 @@ +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" +[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > + +<chapter id='ref-terms'> +<title>Yocto Project Terms</title> + + <para> + Following is a list of terms and definitions users new to the Yocto + Project development environment might find helpful. + While some of these terms are universal, the list includes them + just in case: + <itemizedlist> + <listitem><para> + <emphasis>Append Files:</emphasis> + Files that append build information to a recipe file. + Append files are known as BitBake append files and + <filename>.bbappend</filename> files. + The OpenEmbedded build system expects every append file to have + a corresponding recipe (<filename>.bb</filename>) file. + Furthermore, the append file and corresponding recipe file + must use the same root filename. + The filenames can differ only in the file type suffix used + (e.g. + <filename>formfactor_0.0.bb</filename> and + <filename>formfactor_0.0.bbappend</filename>).</para> + + <para>Information in append files extends or overrides the + information in the similarly-named recipe file. + For an example of an append file in use, see the + "<ulink url='&YOCTO_DOCS_DEV_URL;#using-bbappend-files'>Using .bbappend Files in Your Layer</ulink>" + section in the Yocto Project Development Tasks Manual. + <note> + Append files can also use wildcard patterns in their + version numbers so they can be applied to more than one + version of the underlying recipe file. + </note> + </para></listitem> + <listitem><para id='bitbake-term'> + <emphasis>BitBake:</emphasis> + The task executor and scheduler used by the OpenEmbedded build + system to build images. + For more information on BitBake, see the + <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>. + </para></listitem> + <listitem><para id='board-support-package-bsp-term'> + <emphasis>Board Support Package (BSP):</emphasis> + A group of drivers, definitions, and other components that + provide support for a specific hardware configuration. + For more information on BSPs, see the + <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink>. + </para></listitem> + <listitem> + <para id='build-directory'> + <emphasis>Build Directory:</emphasis> + This term refers to the area used by the OpenEmbedded build + system for builds. + The area is created when you <filename>source</filename> the + setup environment script that is found in the Source Directory + (i.e. <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>). + The + <link linkend='var-TOPDIR'><filename>TOPDIR</filename></link> + variable points to the Build Directory.</para> + + <para>You have a lot of flexibility when creating the Build + Directory. + Following are some examples that show how to create the + directory. + The examples assume your + <link linkend='source-directory'>Source Directory</link> is + named <filename>poky</filename>: + <itemizedlist> + <listitem><para>Create the Build Directory inside your + Source Directory and let the name of the Build + Directory default to <filename>build</filename>: + <literallayout class='monospaced'> + $ cd $HOME/poky + $ source &OE_INIT_FILE; + </literallayout> + </para></listitem> + <listitem><para>Create the Build Directory inside your + home directory and specifically name it + <filename>test-builds</filename>: + <literallayout class='monospaced'> + $ cd $HOME + $ source poky/&OE_INIT_FILE; test-builds + </literallayout> + </para></listitem> + <listitem><para> + Provide a directory path and specifically name the + Build Directory. + Any intermediate folders in the pathname must exist. + This next example creates a Build Directory named + <filename>YP-&POKYVERSION;</filename> + in your home directory within the existing + directory <filename>mybuilds</filename>: + <literallayout class='monospaced'> + $cd $HOME + $ source $HOME/poky/&OE_INIT_FILE; $HOME/mybuilds/YP-&POKYVERSION; + </literallayout> + </para></listitem> + </itemizedlist> + <note> + By default, the Build Directory contains + <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>, + which is a temporary directory the build system uses for + its work. + <filename>TMPDIR</filename> cannot be under NFS. + Thus, by default, the Build Directory cannot be under NFS. + However, if you need the Build Directory to be under NFS, + you can set this up by setting <filename>TMPDIR</filename> + in your <filename>local.conf</filename> file + to use a local drive. + Doing so effectively separates <filename>TMPDIR</filename> + from <filename>TOPDIR</filename>, which is the Build + Directory. + </note> + </para></listitem> + <listitem><para id='hardware-build-system-term'> + <emphasis>Build Host:</emphasis> + The system used to build images in a Yocto Project + Development environment. + The build system is sometimes referred to as the + development host. + </para></listitem> + <listitem><para> + <emphasis>Classes:</emphasis> + Files that provide for logic encapsulation and inheritance so + that commonly used patterns can be defined once and then + easily used in multiple recipes. + For reference information on the Yocto Project classes, see the + "<link linkend='ref-classes'>Classes</link>" chapter. + Class files end with the <filename>.bbclass</filename> + filename extension. + </para></listitem> + <listitem><para> + <emphasis>Configuration File:</emphasis> + Files that hold global definitions of variables, + user-defined variables, and hardware configuration + information. + These files tell the OpenEmbedded build system what to + build and what to put into the image to support a + particular platform.</para> + + <para>Configuration files end with a <filename>.conf</filename> + filename extension. + The <filename>conf/local.conf</filename> configuration file in + the + <link linkend='build-directory'>Build Directory</link> + contains user-defined variables that affect every build. + The <filename>meta-poky/conf/distro/poky.conf</filename> + configuration file defines Yocto "distro" configuration + variables used only when building with this policy. + Machine configuration files, which + are located throughout the + <link linkend='source-directory'>Source Directory</link>, define + variables for specific hardware and are only used when building + for that target (e.g. the + <filename>machine/beaglebone.conf</filename> configuration + file defines variables for the Texas Instruments ARM Cortex-A8 + development board). + </para></listitem> + <listitem><para id='term-container-layer'> + <emphasis>Container Layer:</emphasis> + Layers that hold other layers. + An example of a container layer is the + <filename>meta-intel</filename> layer. + This layer contains BSP layers for the Intel-core2-32 + <trademark class='registered'>Intel</trademark> Common Core + (Intel-core2-32) and the Intel-corei7-64 + <trademark class='registered'>Intel</trademark> Common Core + (Intel-corei7-64). + the <filename>meta-intel</filename> layer also contains + the <filename>common/</filename> directory, which contains + common content across those layers. + </para></listitem> + <listitem><para id='cross-development-toolchain'> + <emphasis>Cross-Development Toolchain:</emphasis> + In general, a cross-development toolchain is a collection of + software development tools and utilities that run on one + architecture and allow you to develop software for a + different, or targeted, architecture. + These toolchains contain cross-compilers, linkers, and + debuggers that are specific to the target architecture.</para> + + <para>The Yocto Project supports two different cross-development + toolchains: + <itemizedlist> + <listitem><para> + A toolchain only used by and within + BitBake when building an image for a target + architecture. + </para></listitem> + <listitem><para>A relocatable toolchain used outside of + BitBake by developers when developing applications + that will run on a targeted device. + </para></listitem> + </itemizedlist></para> + + <para>Creation of these toolchains is simple and automated. + For information on toolchain concepts as they apply to the + Yocto Project, see the + "<ulink url='&YOCTO_DOCS_OM_URL;#cross-development-toolchain-generation'>Cross-Development Toolchain Generation</ulink>" + section in the Yocto Project Overview and Concepts Manual. + You can also find more information on using the + relocatable toolchain in the + <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink> + manual. + </para></listitem> + <listitem><para> + <emphasis>Extensible Software Development Kit (eSDK):</emphasis> + A custom SDK for application developers. + This eSDK allows developers to incorporate their library + and programming changes back into the image to make + their code available to other application developers.</para> + + <para>For information on the eSDK, see the + <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink> + manual. + </para></listitem> + <listitem><para> + <emphasis>Image:</emphasis> + An image is an artifact of the BitBake build process given + a collection of recipes and related Metadata. + Images are the binary output that run on specific hardware or + QEMU and are used for specific use-cases. + For a list of the supported image types that the Yocto Project + provides, see the + "<link linkend='ref-images'>Images</link>" + chapter. + </para></listitem> + <listitem><para> + <emphasis>Layer:</emphasis> + A collection of related recipes. + Layers allow you to consolidate related metadata to + customize your build. + Layers also isolate information used when building + for multiple architectures. + Layers are hierarchical in their ability to override + previous specifications. + You can include any number of available layers from the + Yocto Project and customize the build by adding your + layers after them. + You can search the Layer Index for layers used within + Yocto Project.</para> + + <para>For introductory information on layers, see the + "<ulink url='&YOCTO_DOCS_OM_URL;#the-yocto-project-layer-model'>The Yocto Project Layer Model</ulink>" + section in the Yocto Project Overview and Concepts Manual. + For more detailed information on layers, see the + "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>" + section in the Yocto Project Development Tasks Manual. + For a discussion specifically on BSP Layers, see the + "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>" + section in the Yocto Project Board Support Packages (BSP) + Developer's Guide. + </para></listitem> + <listitem><para id='metadata'> + <emphasis>Metadata:</emphasis> + A key element of the Yocto Project is the Metadata that + is used to construct a Linux distribution and is contained + in the files that the + <link linkend='build-system-term'>OpenEmbedded build system</link> + parses when building an image. + In general, Metadata includes recipes, configuration + files, and other information that refers to the build + instructions themselves, as well as the data used to + control what things get built and the effects of the + build. + Metadata also includes commands and data used to + indicate what versions of software are used, from + where they are obtained, and changes or additions to the + software itself (patches or auxiliary files) that + are used to fix bugs or customize the software for use + in a particular situation. + OpenEmbedded-Core is an important set of validated + metadata.</para> + + <para>In the context of the kernel ("kernel Metadata"), the + term refers to the kernel config fragments and features + contained in the + <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/yocto-kernel-cache'><filename>yocto-kernel-cache</filename></ulink> + Git repository. + </para></listitem> + <listitem><para id='oe-core'> + <emphasis>OpenEmbedded-Core (OE-Core):</emphasis> + OE-Core is metadata comprised of foundational recipes, + classes, and associated files that are meant to be + common among many different OpenEmbedded-derived systems, + including the Yocto Project. + OE-Core is a curated subset of an original repository + developed by the OpenEmbedded community that has been + pared down into a smaller, core set of continuously + validated recipes. + The result is a tightly controlled and an quality-assured + core set of recipes.</para> + + <para>You can see the Metadata in the + <filename>meta</filename> directory of the Yocto Project + <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi'>Source Repositories</ulink>. + </para></listitem> + <listitem><para id='build-system-term'> + <emphasis>OpenEmbedded Build System:</emphasis> + The build system specific to the Yocto Project. + The OpenEmbedded build system is based on another project known + as "Poky", which uses + <link linkend='bitbake-term'>BitBake</link> as the task + executor. + Throughout the Yocto Project documentation set, the + OpenEmbedded build system is sometimes referred to simply + as "the build system". + If other build systems, such as a host or target build system + are referenced, the documentation clearly states the + difference. + <note> + For some historical information about Poky, see the + <link linkend='poky'>Poky</link> term. + </note> + </para></listitem> + <listitem><para> + <emphasis>Package:</emphasis> + In the context of the Yocto Project, this term refers to a + recipe's packaged output produced by BitBake (i.e. a + "baked recipe"). + A package is generally the compiled binaries produced from the + recipe's sources. + You "bake" something by running it through BitBake.</para> + + <para>It is worth noting that the term "package" can, + in general, have subtle meanings. + For example, the packages referred to in the + "<link linkend='required-packages-for-the-host-development-system'>Required Packages for the Host Development System</link>" + section are compiled binaries that, when installed, add + functionality to your Linux distribution.</para> + + <para>Another point worth noting is that historically within + the Yocto Project, recipes were referred to as packages - thus, + the existence of several BitBake variables that are seemingly + mis-named, + (e.g. <link linkend='var-PR'><filename>PR</filename></link>, + <link linkend='var-PV'><filename>PV</filename></link>, and + <link linkend='var-PE'><filename>PE</filename></link>). + </para></listitem> + <listitem><para> + <emphasis>Package Groups:</emphasis> + Arbitrary groups of software Recipes. + You use package groups to hold recipes that, when built, + usually accomplish a single task. + For example, a package group could contain the recipes for a + company’s proprietary or value-add software. + Or, the package group could contain the recipes that enable + graphics. + A package group is really just another recipe. + Because package group files are recipes, they end with the + <filename>.bb</filename> filename extension. + </para></listitem> + <listitem><para id='poky'> + <emphasis>Poky:</emphasis> + Poky, which is pronounced <emphasis>Pock</emphasis>-ee, + is a reference embedded distribution and a reference + test configuration. + Poky provides the following: + <itemizedlist> + <listitem><para> + A base-level functional distro used to illustrate + how to customize a distribution. + </para></listitem> + <listitem><para> + A means by which to test the Yocto Project + components (i.e. Poky is used to validate + the Yocto Project). + </para></listitem> + <listitem><para> + A vehicle through which you can download + the Yocto Project. + </para></listitem> + </itemizedlist> + Poky is not a product level distro. + Rather, it is a good starting point for customization. + <note> + Poky began an open-source + project initially developed by OpenedHand. + OpenedHand developed Poky from the existing + OpenEmbedded build system to create a commercially + supportable build system for embedded Linux. + After Intel Corporation acquired OpenedHand, the + poky project became the basis for the Yocto Project's + build system. + </note> + </para></listitem> + <listitem><para> + <emphasis>Recipe:</emphasis> + A set of instructions for building packages. + A recipe describes where you get source code, which patches + to apply, how to configure the source, how to compile it and so on. + Recipes also describe dependencies for libraries or for other + recipes. + Recipes represent the logical unit of execution, the software + to build, the images to build, and use the + <filename>.bb</filename> file extension. + </para></listitem> + <listitem><para id='reference-kit-term'> + <emphasis>Reference Kit:</emphasis> + A working example of a system, which includes a + <link linkend='board-support-package-bsp-term'>BSP</link> + as well as a + <link linkend='hardware-build-system-term'>build host</link> + and other components, that can work on specific hardware. + </para></listitem> + <listitem> + <para id='source-directory'> + <emphasis>Source Directory:</emphasis> + This term refers to the directory structure created as a result + of creating a local copy of the <filename>poky</filename> Git + repository <filename>git://git.yoctoproject.org/poky</filename> + or expanding a released <filename>poky</filename> tarball. + <note> + Creating a local copy of the <filename>poky</filename> + Git repository is the recommended method for setting up + your Source Directory. + </note> + Sometimes you might hear the term "poky directory" used to refer + to this directory structure. + <note> + The OpenEmbedded build system does not support file or + directory names that contain spaces. + Be sure that the Source Directory you use does not contain + these types of names. + </note></para> + + <para>The Source Directory contains BitBake, Documentation, + Metadata and other files that all support the Yocto Project. + Consequently, you must have the Source Directory in place on + your development system in order to do any development using + the Yocto Project.</para> + + <para>When you create a local copy of the Git repository, you + can name the repository anything you like. + Throughout much of the documentation, "poky" + is used as the name of the top-level folder of the local copy of + the poky Git repository. + So, for example, cloning the <filename>poky</filename> Git + repository results in a local Git repository whose top-level + folder is also named "poky".</para> + + <para>While it is not recommended that you use tarball expansion + to set up the Source Directory, if you do, the top-level + directory name of the Source Directory is derived from the + Yocto Project release tarball. + For example, downloading and unpacking + <filename>&YOCTO_POKY_TARBALL;</filename> results in a + Source Directory whose root folder is named + <filename>&YOCTO_POKY;</filename>.</para> + + <para>It is important to understand the differences between the + Source Directory created by unpacking a released tarball as + compared to cloning + <filename>git://git.yoctoproject.org/poky</filename>. + When you unpack a tarball, you have an exact copy of the files + based on the time of release - a fixed release point. + Any changes you make to your local files in the Source Directory + are on top of the release and will remain local only. + On the other hand, when you clone the <filename>poky</filename> + Git repository, you have an active development repository with + access to the upstream repository's branches and tags. + In this case, any local changes you make to the local + Source Directory can be later applied to active development + branches of the upstream <filename>poky</filename> Git + repository.</para> + + <para>For more information on concepts related to Git + repositories, branches, and tags, see the + "<ulink url='&YOCTO_DOCS_OM_URL;#repositories-tags-and-branches'>Repositories, Tags, and Branches</ulink>" + section in the Yocto Project Overview and Concepts Manual. + </para></listitem> + <listitem><para><emphasis>Task:</emphasis> + A unit of execution for BitBake (e.g. + <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>, + <link linkend='ref-tasks-fetch'><filename>do_fetch</filename></link>, + <link linkend='ref-tasks-patch'><filename>do_patch</filename></link>, + and so forth). + </para></listitem> + <listitem><para id='toaster-term'><emphasis>Toaster:</emphasis> + A web interface to the Yocto Project's + <link linkend='build-system-term'>OpenEmbedded Build System</link>. + The interface enables you to configure and run your builds. + Information about builds is collected and stored in a database. + For information on Toaster, see the + <ulink url='&YOCTO_DOCS_TOAST_URL;'>Toaster User Manual</ulink>. + </para></listitem> + <listitem><para> + <emphasis>Upstream:</emphasis> + A reference to source code or repositories + that are not local to the development system but located in a + master area that is controlled by the maintainer of the source + code. + For example, in order for a developer to work on a particular + piece of code, they need to first get a copy of it from an + "upstream" source. + </para></listitem> + </itemizedlist> + </para> + +</chapter> +<!-- +vim: expandtab tw=80 ts=4 +--> |
