ref-manual: remove 'ref' from filenames

All filenames duplicate the 'manual name', which is not needed, and
make all references longer than they should. Rename all files to be as
consise as possible, and fix all references

(From yocto-docs rev: bb7e4783f45a5f67e6e4b39968f3512f43738833)

Signed-off-by: Nicolas Dechesne <nicolas.dechesne@linaro.org>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

1 files changed, 390 insertions, 0 deletions

diff --git a/documentation/ref-manual/terms.rst b/documentation/ref-manual/terms.rst
new file mode 100644
index 0000000000..c07dd4b128
--- /dev/null
+++ b/documentation/ref-manual/terms.rst
@@ -0,0 +1,390 @@
+.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
+
+*******************
+Yocto Project Terms
+*******************
+
+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:
+
+.. glossary::
+
+   :term:`Append Files`
+      Files that append build information to a recipe file.  Append files are
+      known as BitBake append files and ``.bbappend`` files. The OpenEmbedded
+      build system expects every append file to have a corresponding recipe
+      (``.bb``) 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. ``formfactor_0.0.bb`` and
+      ``formfactor_0.0.bbappend``).
+
+      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 ":ref:`dev-manual/common-tasks:Using .bbappend Files in
+      Your Layer`" section in the Yocto Project Development Tasks Manual.
+
+      When you name an append file, you can use the "``%``" wildcard character
+      to allow for matching recipe names. For example, suppose you have an
+      append file named as follows:
+      ::
+      
+         busybox_1.21.%.bbappend
+
+      That append file
+      would match any ``busybox_1.21.``\ x\ ``.bb`` version of the recipe. So,
+      the append file would match any of the following recipe names:
+
+      .. code-block:: shell
+
+         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
+
+      .. note::
+
+         The use of the "%" character is limited in that it only works
+         directly in front of the .bbappend portion of the append file's
+         name. You cannot use the wildcard character in any other location of
+         the name.
+
+   :term:`BitBake`
+      The task executor and scheduler used by the OpenEmbedded build system to
+      build images. For more information on BitBake, see the :doc:`BitBake User
+      Manual <bitbake:index>`.
+
+   :term:`Board Support Package (BSP)`
+      A group of drivers, definitions, and other components that provide support
+      for a specific hardware configuration. For more information on BSPs, see
+      the :doc:`/bsp-guide/index`.
+
+   :term:`Build Directory`
+      This term refers to the area used by the OpenEmbedded build system for
+      builds. The area is created when you ``source`` the setup environment
+      script that is found in the Source Directory
+      (i.e. :ref:`ref-manual/structure:\`\`oe-init-build-env\`\``). The
+      :term:`TOPDIR` variable points to the Build Directory.
+
+      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 :term:`Source Directory` is named ``poky``:
+
+         -  Create the Build Directory inside your Source Directory and let
+            the name of the Build Directory default to ``build``:
+
+            .. code-block:: shell
+
+               $ cd $HOME/poky
+               $ source oe-init-build-env
+
+         -  Create the Build Directory inside your home directory and
+            specifically name it ``test-builds``:
+
+            .. code-block:: shell
+
+               $ cd $HOME
+               $ source poky/oe-init-build-env test-builds
+
+         -  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
+            ``YP-POKYVERSION`` in your home directory within the existing
+            directory ``mybuilds``:
+
+            .. code-block:: shell
+
+               $ cd $HOME
+               $ source $HOME/poky/oe-init-build-env $HOME/mybuilds/YP-POKYVERSION
+
+      .. note::
+
+         By default, the Build Directory contains :term:`TMPDIR`, which is a
+         temporary directory the build system uses for its work. ``TMPDIR`` 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 ``TMPDIR`` in your ``local.conf`` file to use a local
+         drive. Doing so effectively separates ``TMPDIR`` from :term:`TOPDIR`, which is the
+         Build Directory.
+
+   :term:`Build Host`
+      The system used to build images in a Yocto Project Development
+      environment. The build system is sometimes referred to as the development
+      host.
+
+   :term:`Classes`
+      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 ":ref:`ref-manual/classes:Classes`" chapter. Class files end with the
+      ``.bbclass`` filename extension.
+
+   :term:`Configuration File`
+      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.
+
+      Configuration files end with a ``.conf`` filename extension. The
+      :file:`conf/local.conf` configuration file in the :term:`Build Directory`
+      contains user-defined variables that affect every build. The
+      :file:`meta-poky/conf/distro/poky.conf` configuration file defines Yocto
+      "distro" configuration variables used only when building with this
+      policy. Machine configuration files, which are located throughout the
+      :term:`Source Directory`, define variables for specific hardware and are
+      only used when building for that target (e.g. the
+      :file:`machine/beaglebone.conf` configuration file defines variables for
+      the Texas Instruments ARM Cortex-A8 development board).
+
+   :term:`Container Layer`
+      Layers that hold other layers. An example of a container layer is
+      OpenEmbedded's `meta-openembedded
+      <https://github.com/openembedded/meta-openembedded>`_ layer. The
+      ``meta-openembedded`` layer contains many ``meta-*`` layers.
+
+   :term:`Cross-Development Toolchain`
+      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.
+
+      The Yocto Project supports two different cross-development toolchains:
+
+      - A toolchain only used by and within BitBake when building an image for a
+        target architecture.
+
+      - A relocatable toolchain used outside of BitBake by developers when
+        developing applications that will run on a targeted device.
+
+      Creation of these toolchains is simple and automated. For information on
+      toolchain concepts as they apply to the Yocto Project, see the
+      ":ref:`overview-manual/concepts:Cross-Development
+      Toolchain Generation`" section in the Yocto Project Overview and Concepts
+      Manual. You can also find more information on using the relocatable
+      toolchain in the :doc:`/sdk-manual/index` manual.
+
+   :term:`Extensible Software Development Kit (eSDK)`
+      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.
+
+      For information on the eSDK, see the :doc:`/sdk-manual/index` manual.
+
+   :term:`Image`
+      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
+      ":ref:`ref-manual/images:Images`" chapter.
+
+   :term:`Layer`
+      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.
+
+      For introductory information on layers, see the
+      ":ref:`overview-manual/yp-intro:The Yocto Project Layer
+      Model`" section in the Yocto Project Overview and Concepts Manual. For
+      more detailed information on layers, see the
+      ":ref:`dev-manual/common-tasks:Understanding and Creating
+      Layers`" section in the Yocto Project Development Tasks Manual. For a
+      discussion specifically on BSP Layers, see the ":ref:`bsp-guide/bsp:BSP
+      Layers`" section in the Yocto Project Board Support Packages (BSP)
+      Developer's Guide.
+
+   :term:`Metadata`
+      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 :term:`OpenEmbedded Build System`
+      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.
+
+      In the context of the kernel ("kernel Metadata"), the term refers to
+      the kernel config fragments and features contained in the
+      :yocto_git:`yocto-kernel-cache </yocto-kernel-cache>`
+      Git repository.
+
+   :term:`OpenEmbedded-Core (OE-Core)`
+      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.
+
+      You can see the Metadata in the ``meta`` directory of the Yocto
+      Project :yocto_git:`Source Repositories </poky>`.
+
+   :term:`OpenEmbedded Build System`
+      The build system specific to the Yocto
+      Project. The OpenEmbedded build system is based on another project
+      known as "Poky", which uses :term:`BitBake` 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 :term:`Poky` term.
+
+   :term:`Package`
+      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.
+
+      It is worth noting that the term "package" can, in general, have
+      subtle meanings. For example, the packages referred to in the
+      ":ref:`ref-manual/system-requirements:required packages for the build host`"
+      section are compiled binaries that, when installed, add functionality to
+      your Linux distribution.
+
+      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.
+      :term:`PR`, :term:`PV`, and
+      :term:`PE`).
+
+   :term:`Package Groups`
+      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 ``.bb`` filename extension.
+
+   :term:`Poky`
+      Poky, which is pronounced *Pock*-ee, is a reference embedded
+      distribution and a reference test configuration. Poky provides the
+      following:
+
+      -  A base-level functional distro used to illustrate how to customize
+         a distribution.
+
+      -  A means by which to test the Yocto Project components (i.e. Poky
+         is used to validate the Yocto Project).
+
+      -  A vehicle through which you can download the Yocto Project.
+
+      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.
+
+   :term:`Recipe`
+      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 ``.bb`` file extension.
+
+   :term:`Reference Kit`
+      A working example of a system, which includes a
+      :term:`BSP<Board Support Package (BSP)>` as well as a
+      :term:`build host<Build Host>` and other components, that can
+      work on specific hardware.
+
+   :term:`Source Directory`
+     This term refers to the directory structure
+     created as a result of creating a local copy of the ``poky`` Git
+     repository ``git://git.yoctoproject.org/poky`` or expanding a
+     released ``poky`` tarball.
+
+     .. note::
+
+        Creating a local copy of the
+        poky
+        Git repository is the recommended method for setting up your
+        Source Directory.
+
+     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.
+
+     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.
+
+     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 ``poky`` Git
+     repository results in a local Git repository whose top-level folder
+     is also named "poky".
+
+     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
+     :yocto_dl:`/releases/yocto/&DISTRO_REL_TAG;/&YOCTO_POKY;.tar.bz2`
+     results in a Source Directory whose root folder is named ``poky``.
+
+     It is important to understand the differences between the Source
+     Directory created by unpacking a released tarball as compared to
+     cloning ``git://git.yoctoproject.org/poky``. 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 ``poky`` 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 ``poky`` Git
+     repository.
+
+     For more information on concepts related to Git repositories,
+     branches, and tags, see the
+     ":ref:`overview-manual/development-environment:repositories, tags, and branches`"
+     section in the Yocto Project Overview and Concepts Manual.
+
+   :term:`Task`
+      A unit of execution for BitBake (e.g.
+      :ref:`ref-tasks-compile`,
+      :ref:`ref-tasks-fetch`,
+      :ref:`ref-tasks-patch`, and so forth).
+
+   :term:`Toaster`
+      A web interface to the Yocto Project's :term:`OpenEmbedded Build System`.
+      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
+      :doc:`/toaster-manual/index`.
+
+   :term:`Upstream`
+      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.