diff --git a/documentation/bsp-guide/bsp.xml b/documentation/bsp-guide/bsp.xml
index cb9940c77a..a92e6115b1 100644
--- a/documentation/bsp-guide/bsp.xml
+++ b/documentation/bsp-guide/bsp.xml
@@ -936,7 +936,7 @@
Create a .bbappend
file for the modified recipe.
For information on using append files, see the
- "Using .bbappend Files"
+ "Using .bbappend Files in Your Layer"
section in the Yocto Project Development Manual.
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index 76a2c654dd..6e6577220d 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -685,37 +685,46 @@
- Using .bbappend Files
+ Using .bbappend Files in Your Layer
- Recipes used to append Metadata to other recipes are called
- BitBake append files.
- BitBake append files use the .bbappend file
- type suffix, while the corresponding recipes to which Metadata
- is being appended use the .bb file type
- suffix.
+ A recipe that appends Metadata to another recipe is called a
+ BitBake append file.
+ A BitBake append file uses the .bbappend
+ file type suffix, while the corresponding recipe to which
+ Metadata is being appended uses the .bb
+ file type suffix.
- A .bbappend file allows your layer to make
- additions or changes to the content of another layer's recipe
- without having to copy the other recipe into your layer.
+ You can use a .bbappend file in your
+ layer to make additions or changes to the content of another
+ layer's recipe without having to copy the other layer's
+ recipe into your layer.
Your .bbappend file resides in your layer,
while the main .bb recipe file to
which you are appending Metadata resides in a different layer.
- Append files must have the same root names as their corresponding
- recipes.
+ Being able to append information to an existing recipe not only
+ avoids duplication, but also automatically applies recipe
+ changes from a different layer into your layer.
+ If you were copying recipes, you would have to manually merge
+ changes as they occur.
+
+
+
+ When you create an append file, you must use the same root
+ name as the corresponding recipe file.
For example, the append file
someapp_&DISTRO;.bbappend must apply to
someapp_&DISTRO;.bb.
- This means the original recipe and append file names are version
- number-specific.
+ This means the original recipe and append file names are
+ version number-specific.
If the corresponding recipe is renamed to update to a newer
- version, the corresponding .bbappend file must
- be renamed (and possibly updated) as well.
+ version, you must also rename and possibly update
+ the corresponding .bbappend as well.
During the build process, BitBake displays an error on starting
if it detects a .bbappend file that does
not have a corresponding recipe with a matching name.
@@ -724,14 +733,6 @@
variable for information on how to handle this error.
-
- Being able to append information to an existing recipe not only
- avoids duplication, but also automatically applies recipe
- changes in a different layer to your layer.
- If you were copying recipes, you would have to manually merge
- changes as they occur.
-
-
As an example, consider the main formfactor recipe and a
corresponding formfactor append file both from the
@@ -744,8 +745,7 @@
SUMMARY = "Device formfactor information"
SECTION = "base"
LICENSE = "MIT"
- LIC_FILES_CHKSUM = "file://${COREBASE}/LICENSE;md5=4d92cd373abda3937c2bc47fbc49d690 \
- file://${COREBASE}/meta/COPYING.MIT;md5=3da9cfbcb788c80a0384361b4de20420"
+ LIC_FILES_CHKSUM = "file://${COREBASE}/meta/COPYING.MIT;md5=3da9cfbcb788c80a0384361b4de20420"
PR = "r45"
SRC_URI = "file://config file://machconfig"
@@ -761,8 +761,7 @@
if [ -s "${S}/machconfig" ]; then
install -m 0644 ${S}/machconfig ${D}${sysconfdir}/formfactor/
fi
- }
-
+ }
In the main recipe, note the
SRC_URI
variable, which tells the OpenEmbedded build system where to
@@ -774,7 +773,8 @@
formfactor_0.0.bbappend and is from the
Raspberry Pi BSP Layer named
meta-raspberrypi.
- The file is in recipes-bsp/formfactor:
+ The file is in the layer at
+ recipes-bsp/formfactor:
FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
@@ -794,12 +794,13 @@
- The statement in this example extends the directories to include
+ The statement in this example extends the directories to
+ include
${THISDIR}/${PN},
which resolves to a directory named
formfactor in the same directory
in which the append file resides (i.e.
- meta-raspberrypi/recipes-bsp/formfactor/formfactor.
+ meta-raspberrypi/recipes-bsp/formfactor.
This implies that you must have the supporting directory
structure set up that will contain any files or patches you
will be including from the layer.
@@ -807,8 +808,8 @@
Using the immediate expansion assignment operator
- := is important because of the reference to
- THISDIR.
+ := is important because of the reference
+ to THISDIR.
The trailing colon character is important as it ensures that
items in the list remain colon-separated.
@@ -6571,7 +6572,7 @@
and SRC_URI
statements enable the OpenEmbedded build system to find the patch file.
For more information on using append files, see the
- "Using .bbappend Files"
+ "Using .bbappend Files in Your Layer"
section.
Put the patch file in your layer:
@@ -7050,7 +7051,7 @@
Add a psplash
append file for a branded splash screen.
For information on append files, see the
- "Using .bbappend Files"
+ "Using .bbappend Files in Your Layer"
section.Add any other append files to make
custom changes that are specific to individual
diff --git a/documentation/kernel-dev/kernel-dev-faq.xml b/documentation/kernel-dev/kernel-dev-faq.xml
index 2b99ad2dde..9e0517d4af 100644
--- a/documentation/kernel-dev/kernel-dev-faq.xml
+++ b/documentation/kernel-dev/kernel-dev-faq.xml
@@ -72,7 +72,7 @@
RDEPENDS_kernel-base to include or not
include "kernel-image".See the
- "Using .bbappend Files"
+ "Using .bbappend Files in Your Layer"
section in the Yocto Project Development Manual for information on
how to use an append file to override metadata.
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 @@
+
+ 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:
+
+
+ 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
+ "Using .bbappend Files in Your Layer"
+ section in the Yocto Project Development Manual.
+
+ 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.
+
+
+
+ BitBake:
+ The task executor and scheduler used by the OpenEmbedded build
+ system to build images.
+ For more information on BitBake, see the
+ BitBake User Manual.
+
+
+
+ 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. &OE_INIT_FILE;
+ or
+ oe-init-build-env-memres).
+ The
+ 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
+ Source Directory is
+ named poky:
+
+ Create the Build Directory inside your
+ Source Directory and let the name of the Build
+ Directory default to build:
+
+ $ cd $HOME/poky
+ $ source &OE_INIT_FILE;
+
+
+ Create the Build Directory inside your
+ home directory and specifically name it
+ test-builds:
+
+ $ cd $HOME
+ $ source poky/&OE_INIT_FILE; 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:
+
+ $cd $HOME
+ $ source $HOME/poky/&OE_INIT_FILE; $HOME/mybuilds/YP-&POKYVERSION;
+
+
+
+
+ By default, the Build Directory contains
+ 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 TOPDIR, which is the Build
+ Directory.
+
+
+
+ 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
+ "Classes" chapter.
+ Class files end with the .bbclass
+ filename extension.
+
+
+ Configuration File:
+ Configuration information in various .conf
+ files provides global definitions of variables.
+ The conf/local.conf configuration file in
+ the
+ Build Directory
+ contains user-defined variables that affect every build.
+ The 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
+ Source Directory, define
+ variables for specific hardware and are only used when building
+ for that target (e.g. the
+ machine/beaglebone.conf configuration
+ file defines variables for the Texas Instruments ARM Cortex-A8
+ development board).
+ Configuration files end with a .conf
+ filename extension.
+
+
+ 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
+ "Cross-Development Toolchain Generation"
+ section.
+ You can also find more information on using the
+ relocatable toolchain in the
+ Yocto Project Software Development Kit (SDK) Developer's Guide.
+
+
+ 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
+ "Images"
+ chapter.
+
+
+ Layer:
+ A collection of recipes representing the core,
+ a BSP, or an application stack.
+ For a discussion specifically on BSP Layers, see the
+ "BSP Layers"
+ section in the Yocto Project Board Support Packages (BSP)
+ Developer's Guide.
+
+
+ Metadata:
+ The files that BitBake parses when building an image.
+ In general, Metadata includes recipes, classes, and
+ configuration files.
+ In the context of the kernel ("kernel Metadata"),
+ it refers to Metadata in the meta
+ branches of the kernel source Git repositories.
+
+
+ OE-Core:
+ A core set of Metadata originating with OpenEmbedded (OE)
+ that is shared between OE and the Yocto Project.
+ This Metadata is found in the meta
+ directory of the
+ Source Directory.
+
+
+ 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
+ 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.
+
+ For some historical information about Poky, see the
+ Poky 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
+ "The Build Host Packages"
+ section in the Yocto Project Quick Start 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. PR,
+ PV, and
+ PE).
+
+
+ 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.
+
+
+ Poky:
+ The term "poky", which is pronounced
+ Pah-kee, can mean several things:
+
+
+ In its most general sense, poky is an open-source
+ project that was initially developed by OpenedHand.
+ OpenedHand developed poky off of 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.
+
+
+ Within the Yocto Project
+ Source Repositories,
+ "poky" exists as a separate Git
+ repository from which you can clone to yield a local
+ Git repository that is a copy on your host system.
+ Thus, "poky" can refer to the upstream or
+ local copy of the files used for development within
+ the Yocto Project.
+
+
+ Finally, "poky" can refer to the default
+ DISTRO
+ (i.e. distribution) created when you use the Yocto
+ Project in conjunction with the
+ poky repository to build an image.
+
+
+
+
+ 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.
+
+
+
+ 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.
+
+ 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.
+
+ 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_POKY_TARBALL; results in a
+ Source Directory whose root folder is named
+ &YOCTO_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
+ "Repositories, Tags, and Branches"
+ section.
+
+ Task:
+ A unit of execution for BitBake (e.g.
+ do_compile,
+ do_fetch,
+ do_patch,
+ and so forth).
+
+ Toaster:
+ A web interface to the Yocto Project's
+ 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
+ Yocto Project Toaster Manual.
+
+
+ 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.
+
+
+
+
+
+>>>>>>> a82bcc9... dev-manual: Updates to "Using .bbappend Files in Your Layer"