From 45b16e35b606cfd2c4ab7f89ebe91e43995acb2a Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Tue, 13 Jun 2017 16:14:51 -0700 Subject: documentation: Fixed links to "bitbake-term" Fixes [YOCTO #11630] Moving the "Yocto Project Terms" section from the dev-manual to the ref-manual. Doing so caused all the links to the id "bitbake-term" to break. These had to be individually fixed. Discovered two unresolved references that were a consequence of moving that section to the ref-manual. These were fixed as well. (From yocto-docs rev: 829ca6b64562f00a69f3956e9636c7edaa90ce16) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- documentation/ref-manual/closer-look.xml | 4 +- documentation/ref-manual/faq.xml | 4 +- documentation/ref-manual/introduction.xml | 348 +++++++++++++++++++++++++ documentation/ref-manual/migration.xml | 2 +- documentation/ref-manual/resources.xml | 2 +- documentation/ref-manual/technical-details.xml | 2 +- documentation/ref-manual/usingpoky.xml | 2 +- 7 files changed, 356 insertions(+), 8 deletions(-) (limited to 'documentation/ref-manual') diff --git a/documentation/ref-manual/closer-look.xml b/documentation/ref-manual/closer-look.xml index 459d571926..c0f1747961 100644 --- a/documentation/ref-manual/closer-look.xml +++ b/documentation/ref-manual/closer-look.xml @@ -34,7 +34,7 @@ Upstream releases, local projects, and SCMs. Build System: Processes under the control of - BitBake. + BitBake. This block expands on how BitBake fetches source, applies patches, completes compilation, analyzes output for package generation, creates and tests packages, generates images, and @@ -727,7 +727,7 @@ The OpenEmbedded build system uses - BitBake + BitBake to produce images. You can see from the general Yocto Project Development Environment figure, diff --git a/documentation/ref-manual/faq.xml b/documentation/ref-manual/faq.xml index 5f3f173495..cdbdd4da24 100644 --- a/documentation/ref-manual/faq.xml +++ b/documentation/ref-manual/faq.xml @@ -17,7 +17,7 @@ refers to the specific reference build system that the Yocto Project provides. Poky is based on OE-Core - and BitBake. + and BitBake. Thus, the generic term used here for the build system is the "OpenEmbedded build system." Development in the Yocto Project using Poky is closely tied to OpenEmbedded, with @@ -810,7 +810,7 @@ This situation results when a build system does not recognize the environment variables supplied to it by - BitBake. + BitBake. The incident that prompted this FAQ entry involved a Makefile that used an environment variable named BINDIR instead of the more standard diff --git a/documentation/ref-manual/introduction.xml b/documentation/ref-manual/introduction.xml index 7423467150..58ee073868 100644 --- a/documentation/ref-manual/introduction.xml +++ b/documentation/ref-manual/introduction.xml @@ -39,6 +39,354 @@ +
+ 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" + 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 of the + Yocto Project Reference Manual. + 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 in the Yocto Project Reference Manual. + 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 in the Yocto Project Reference Manual. + 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 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" can mean several things. + In its most general sense, it is an open-source + project that was initially developed by OpenedHand. + With OpenedHand, poky was developed off of the existing + OpenEmbedded build system becoming a commercially + supportable build system for embedded Linux. + After Intel Corporation acquired OpenedHand, the + project poky became the basis for the Yocto Project's + build system. + Within the Yocto Project source repositories, + poky exists as a separate Git + repository you can clone to yield a local copy on your + host system. + Thus, "poky" can refer to the local copy of the Source + Directory 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 in the Yocto Project Development Manual. + + Task: + A unit of execution for BitBake (e.g. + do_compile, + do_fetch, + do_patch, + and so forth). + + 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. + + +
+
Documentation Overview diff --git a/documentation/ref-manual/migration.xml b/documentation/ref-manual/migration.xml index 442324f1f7..0513b219cd 100644 --- a/documentation/ref-manual/migration.xml +++ b/documentation/ref-manual/migration.xml @@ -1218,7 +1218,7 @@ The following changes have been made to - BitBake. + BitBake.
diff --git a/documentation/ref-manual/resources.xml b/documentation/ref-manual/resources.xml index c713ffcf11..aa8408f432 100644 --- a/documentation/ref-manual/resources.xml +++ b/documentation/ref-manual/resources.xml @@ -89,7 +89,7 @@ Discussion mailing list about OpenEmbedded. - Discussion mailing list about the - BitBake + BitBake build tool. - Discussion mailing list about diff --git a/documentation/ref-manual/technical-details.xml b/documentation/ref-manual/technical-details.xml index 1964a9a105..0c949880e7 100644 --- a/documentation/ref-manual/technical-details.xml +++ b/documentation/ref-manual/technical-details.xml @@ -18,7 +18,7 @@ The - BitBake + BitBake task executor together with various types of configuration files form the OpenEmbedded Core. This section overviews these components by describing their use and diff --git a/documentation/ref-manual/usingpoky.xml b/documentation/ref-manual/usingpoky.xml index 4e97e3ec02..d1ac18fb2f 100644 --- a/documentation/ref-manual/usingpoky.xml +++ b/documentation/ref-manual/usingpoky.xml @@ -208,7 +208,7 @@ (qemux86) might be in tmp/work/qemux86-poky-linux/core-image-minimal/1.0-r0/temp/log.do_compile. To see the commands - BitBake ran + BitBake ran to generate a log, look at the corresponding run.do_taskname file in the same directory. -- cgit v1.2.3-54-g00ecf