sysmo-bts
/
generic-poky
9
0
Fork 0
Code Pull Requests Releases Activity

documentation/dev-manual/dev-manual-newbie.xml: edits to build dir term 

I beefed up the definition for the term "Yocto Project Build
Directory."  I included the TOPDIR role and also expanded the
discussion on how it is created and the control the user has
over it.

(From yocto-docs rev: d00f30708ccd5fb9e1fc3c8e5240e0ab7a892fe0)

Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
This commit is contained in:
Scott Rifenbark 2012-02-08 17:05:44 -06:00 committed by Richard Purdie
parent 1e608088cd
commit 7b5215b886
1 changed files with 125 additions and 111 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

236
documentation/dev-manual/dev-manual-newbie.xml
View File

@ -130,106 +130,104 @@
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.
Information in append files overrides the information in the similarly-named recipe file.
Append files use the <filename>.bbappend</filename> filename suffix.</para></listitem>
<listitem><para><emphasis>BitBake:</emphasis> The task executor and scheduler used by
the Yocto Project to build images.
For more information on BitBake, see the <ulink url='http://bitbake.berlios.de/manual/'>
BitBake documentation</ulink>.</para></listitem>
<listitem><para><emphasis>Classes:</emphasis> Files that provide for logic encapsulation
and inheritance allowing commonly used patterns to be defined once and easily used
in multiple recipes.
Class files end with the <filename>.bbclass</filename> filename extension.</para></listitem>
<listitem><para><emphasis>Configuration File:</emphasis> Configuration information in various
<filename>.conf</filename> files provides global definitions of variables.
The <filename>conf/local.conf</filename> configuration file in the Yocto Project
build directory contains user-defined variables that affect each build.
The <filename>meta-yocto/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 Yocto Project file structure, define
variables for specific hardware and are only used when building for that target
(e.g. the <filename>machine/beagleboard.conf</filename> configuration file defines
variables for the Texas Instruments ARM Cortex-A8 development board).
Configuration files end with a <filename>.conf</filename> filename extension.</para></listitem>
<listitem><para><emphasis>Cross-Development Toolchain:</emphasis> A collection of software development
tools and utilities that allow you to develop software for targeted architectures.
This toolchain contains cross-compilers, linkers, and debuggers that are specific to
an architecture.
You can use the Yocto Project to build cross-development toolchains in tarball form that when
unpacked contain the development tools you need to cross-compile and test your software.
The Yocto Project ships with images that contain toolchains for supported architectures
as well.
Sometimes this toolchain is referred to as the meta-toolchain.</para></listitem>
<listitem><para><emphasis>Image:</emphasis> An image is the result produced when
BitBake processes a given collection of recipes and related metadata.
Images are the binary output that runs on specific hardware and for specific
use cases.
For a list of the supported image types that the Yocto Project provides, see the
"<ulink url='http://www.yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html#ref-images'>Reference: Images</ulink>"
appendix in The Yocto Project Reference Manual.</para></listitem>
<listitem><para><emphasis>Layer:</emphasis> A collection of recipes representing the core,
a BSP, or an application stack.</para></listitem>
<listitem><para><emphasis>Metadata:</emphasis> The files that BitBake parses when building an image.
Metadata includes recipes, classes, and configuration files.</para></listitem>
<listitem><para><emphasis>OE-Core:</emphasis> A core set of metadata originating
with OpenEmbedded (OE) that is shared between OE and the Yocto Project.
This metadata is found in the <filename>meta</filename> directory of the Yocto Project
files.</para></listitem>
<listitem><para><emphasis>Package:</emphasis> The packaged output from 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></listitem>
<listitem><para><emphasis>Poky:</emphasis> The build tool that the Yocto Project
uses to create images.</para></listitem>
<listitem><para><emphasis>Recipe:</emphasis> A set of instructions for building packages.
A recipe describes where you get source code and which patches to apply.
Recipes describe dependencies for libraries or for other recipes, and they
also contain configuration and compilation options.
Recipes contain the logical unit of execution, the software/images to build, and
use the <filename>.bb</filename> file extension.</para></listitem>
<listitem><para><emphasis>Tasks:</emphasis> Arbitrary groups of software Recipes.
You simply use Tasks to hold recipes that, when built, usually accomplish a single task.
For example, a task could contain the recipes for a company’s proprietary or value-add software.
Or, the task could contain the recipes that enable graphics.
A task is really just another recipe.
Because task files are recipes, they end with the <filename>.bb</filename> filename
extension.</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>
<listitem>
<para id='yocto-project-files'><emphasis>Yocto Project Files:</emphasis>
<itemizedlist>
<listitem><para><emphasis>Append Files:</emphasis> Files that append build information to
a recipe file.
Information in append files overrides the information in the similarly-named recipe file.
Append files use the <filename>.bbappend</filename> filename suffix.
</para></listitem>
<listitem><para><emphasis>BitBake:</emphasis> The task executor and scheduler used by
the Yocto Project to build images.
For more information on BitBake, see the <ulink url='http://bitbake.berlios.de/manual/'>
BitBake documentation</ulink>.</para></listitem>
<listitem><para><emphasis>Classes:</emphasis> Files that provide for logic encapsulation
and inheritance allowing commonly used patterns to be defined once and easily used
in multiple recipes.
Class files end with the <filename>.bbclass</filename> filename extension.
</para></listitem>
<listitem><para><emphasis>Configuration File:</emphasis> Configuration information in various
<filename>.conf</filename> files provides global definitions of variables.
The <filename>conf/local.conf</filename> configuration file in the Yocto Project
build directory contains user-defined variables that affect each build.
The <filename>meta-yocto/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 Yocto Project file structure, define
variables for specific hardware and are only used when building for that target
(e.g. the <filename>machine/beagleboard.conf</filename> configuration file defines
variables for the Texas Instruments ARM Cortex-A8 development board).
Configuration files end with a <filename>.conf</filename> filename extension.
</para></listitem>
<listitem><para><emphasis>Cross-Development Toolchain:</emphasis>
A collection of software development
tools and utilities that allow you to develop software for targeted architectures.
This toolchain contains cross-compilers, linkers, and debuggers that are specific to
an architecture.
You can use the Yocto Project to build cross-development toolchains in tarball form that when
unpacked contain the development tools you need to cross-compile and test your software.
The Yocto Project ships with images that contain toolchains for supported architectures
as well.
Sometimes this toolchain is referred to as the meta-toolchain.</para></listitem>
<listitem><para><emphasis>Image:</emphasis> An image is the result produced when
BitBake processes a given collection of recipes and related metadata.
Images are the binary output that runs on specific hardware and for specific
use cases.
For a list of the supported image types that the Yocto Project provides, see the
"<ulink url='http://www.yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html#ref-images'>Reference: Images</ulink>"
appendix in The Yocto Project Reference Manual.</para></listitem>
<listitem><para><emphasis>Layer:</emphasis> A collection of recipes representing the core,
a BSP, or an application stack.</para></listitem>
<listitem><para><emphasis>Metadata:</emphasis> The files that BitBake parses when building an image.
Metadata includes recipes, classes, and configuration files.</para></listitem>
<listitem><para><emphasis>OE-Core:</emphasis> A core set of metadata originating
with OpenEmbedded (OE) that is shared between OE and the Yocto Project.
This metadata is found in the <filename>meta</filename> directory of the Yocto Project
files.</para></listitem>
<listitem><para><emphasis>Package:</emphasis> The packaged output from 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></listitem>
<listitem><para><emphasis>Poky:</emphasis> The build tool that the Yocto Project
uses to create images.</para></listitem>
<listitem><para><emphasis>Recipe:</emphasis> A set of instructions for building packages.
A recipe describes where you get source code and which patches to apply.
Recipes describe dependencies for libraries or for other recipes, and they
also contain configuration and compilation options.
Recipes contain the logical unit of execution, the software/images to build, and
use the <filename>.bb</filename> file extension.</para></listitem>
<listitem><para><emphasis>Tasks:</emphasis> Arbitrary groups of software Recipes.
You simply use Tasks to hold recipes that, when built, usually accomplish a single task.
For example, a task could contain the recipes for a company’s proprietary or value-add software.
Or, the task could contain the recipes that enable graphics.
A task is really just another recipe.
Because task files are recipes, they end with the <filename>.bb</filename> filename
extension.</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>
<listitem>
<para id='yocto-project-files'><emphasis>Yocto Project Files:</emphasis>
This term refers to the directory structure created as a result of either downloading
and unpacking a Yocto Project release tarball or setting up a Git repository
by cloning <filename>git://git.yoctoproject.org/poky</filename>.
Sometimes the term "the Yocto Project Files structure" is used as well.
</para>
Sometimes the term "the Yocto Project Files structure" is used as well.</para>
<para>
The Yocto Project files contain BitBake, Documentation, metadata and
<para>The Yocto Project files contain BitBake, Documentation, metadata and
other files that all support the development environment.
Consequently, you must have the Yocto Project files in place on your development
system in order to do any development using the Yocto Project.
</para>
system in order to do any development using the Yocto Project.</para>
<para>
The name of the top-level directory of the Yocto Project file structure
<para>The name of the top-level directory of the Yocto Project file structure
is derived from the Yocto Project release tarball.
For example, downloading and unpacking <filename>poky-edison-6.0.tar.bz2</filename>
results in a Yocto Project file structure whose Yocto Project source directory is named
<filename>poky-edison-6.0</filename>.
If you create a Git repository, then you can name the repository anything you like.
By default, your local Git repository is named <filename>poky</filename>.
</para>
By default, your local Git repository is named <filename>poky</filename>.</para>
<para>
It is important to understand the differences between Yocto Project Files created
<para>It is important to understand the differences between Yocto Project Files created
by unpacking a release 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
@ -237,7 +235,9 @@
Any changes you make to your local Yocto Project files are on top of the release.
On the other hand, when you clone the Yocto Project Git repository, you have an
active development repository.
In this case, any local changes you make to the Yocto Project can be later applied to active
creates a build directory named <filename>YP-6.0</filename>
in your home directory within the directory <filename>mybuilds</filename>.
If <filename>mybuilds</filename> does not exist it is created for you. In this case, any local changes you make to the Yocto Project can be later applied to active
development branches of the upstream Yocto Project Git repository.
If you want to track a set of local changes while starting from the same point
as a release tarball, you can create a local Git branch that
@ -245,34 +245,48 @@
You do this using Git tags that are part of the repository.
For more information on concepts, see the section
"<link linkend='repositories-tags-and-branches'>Repositories, Tags, and Branches</link>".
</para>
</para>
<para>
You can find instruction on how to set up the Yocto Project files on your
<para>You can find instruction on how to set up the Yocto Project files on your
host development system by reading
the
"<ulink url='http://www.yoctoproject.org/docs/latest/dev-manual/dev-manual.html#getting-setup'>Getting
Setup</ulink>" section.
</para>
</listitem>
<listitem><para id='yocto-project-build-directory'><emphasis>Yocto Project Build Directory:</emphasis>
This term refers to the area used by the Yocto Project for builds.
The area is created when you <filename>source</filename> the Yocto Project setup
environment script that is found in the Yocto Project files area.
(e.g. <filename>oe-init-build-env</filename>).
You can create the Yocto Project build directory anywhere you want on your
development system.
Here is an example that creates the directory in <filename>mybuilds</filename>
and names the Yocto Project build directory <filename>YP-6.0</filename>:
<literallayout class='monospaced'>
Setup</ulink>" section.</para></listitem>
<listitem>
<para id='yocto-project-build-directory'><emphasis>Yocto Project Build Directory:</emphasis>
This term refers to the area used by the Yocto Project for builds.
The area is created when you <filename>source</filename> the Yocto Project setup
environment script that is found in the Yocto Project files area
(i.e. <filename>oe-init-build-env</filename>).
The <filename>TOPDIR</filename> variable points to the build directory.</para>
<para>You have a lot of flexibility when creating the Yocto Project Build Directory.
Following are some examples that show how to create the directory:
<itemizedlist>
<listitem><para>Create the build directory in your current working directory
and name it <filename>build</filename>.
This is the default behavior.
<literallayout class='monospaced'>
$ cd ~/poky
$ source oe-init-build-env
</literallayout></para></listitem>
<listitem><para>Provide a directory path and specifically name the build
directory.
This next example creates a build directory named <filename>YP-6.0</filename>
in your home directory within the directory <filename>mybuilds</filename>.
If <filename>mybuilds</filename> does not exist, the directory is created for you:
<literallayout class='monospaced'>
$ source poky-edison-6.0/oe-init-build-env $HOME/mybuilds/YP-6.0
</literallayout>
If you don't specifically name the directory, BitBake creates it
in the current directory and uses the name <filename>build</filename>.
Also, if you supply an existing directory, then BitBake uses that
directory as the Yocto Project build directory and populates the build hierarchy
beneath it.</para></listitem>
</itemizedlist>
</literallayout></para></listitem>
<listitem><para>Provide an existing directory to use as the build directory.
This example uses the existing <filename>mybuilds</filename> directory
as the build directory.
<literallayout class='monospaced'>
$ source poky-edison-6.0/oe-init-build-env $HOME/mybuilds/
</literallayout></para></listitem>
</itemizedlist>
</para></listitem>
</itemizedlist>
</para>
</section>