diff options
Diffstat (limited to 'documentation/ref-manual/ref-terms.xml')
| -rw-r--r-- | documentation/ref-manual/ref-terms.xml | 525 |
1 files changed, 0 insertions, 525 deletions
diff --git a/documentation/ref-manual/ref-terms.xml b/documentation/ref-manual/ref-terms.xml deleted file mode 100644 index d2605c62a8..0000000000 --- a/documentation/ref-manual/ref-terms.xml +++ /dev/null @@ -1,525 +0,0 @@ -<!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; ] > -<!--SPDX-License-Identifier: CC-BY-2.0-UK--> - -<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.</para> - - <para>When you name an append file, you can use the - "<filename>%</filename>" wildcard character to allow for - matching recipe names. - For example, suppose you have an append file named as follows: - <literallayout class='monospaced'> - busybox_1.21.%.bbappend - </literallayout> - That append file would match any - <filename>busybox_1.21.</filename><replaceable>x</replaceable><filename>.bb</filename> - version of the recipe. - So, the append file would match any of the following recipe names: - <literallayout class='monospaced'> - busybox_1.21.1.bb - busybox_1.21.2.bb - busybox_1.21.3.bb - busybox_1.21.10.bb - busybox_1.21.25.bb - </literallayout> - <note><title>Important</title> - The use of the "<filename>%</filename>" character - is limited in that it only works directly in front of the - <filename>.bbappend</filename> portion of the append file's - name. - You cannot use the wildcard character in any other - location of the name. - </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 - <firstterm>development host</firstterm>. - </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 OpenEmbedded's - <ulink url='https://github.com/openembedded/meta-openembedded'><filename>meta-openembedded</filename></ulink> - layer. - The <filename>meta-openembedded</filename> layer contains - many <filename>meta-*</filename> 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-build-host'>Required Packages for the Build Host</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 as 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 ---> |