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

dev-manual: Read-through edits to Chapter 3. 

The changes are a result of a detailed read-through prior to
releasing YP 1.6.  The changes are varied and random.

(From yocto-docs rev: 04c09abf96a04c3ffeea8cdf7be8e1bb1b9055c6)

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 2014-03-17 14:36:17 -06:00 committed by Richard Purdie
parent cee847acf0
commit dd72756230
1 changed files with 159 additions and 104 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -171,7 +171,7 @@
pool similarly to how the developer workstations
contribute.
For information, see the
<link linkend='best-practices-autobuilders'>Autobuilders</link>
"<link linkend='best-practices-autobuilders'>Autobuilders</link>"
section.</para></listitem>
<listitem><para>Build stand-alone tarballs that contain
"missing" system requirements if for some reason
@ -184,8 +184,8 @@
on most distributions.</para></listitem>
<listitem><para>Use a small number of shared,
high performance systems for testing purposes
(e.g. dual six core Xeons with 24GB RAM and plenty of
disk space).
(e.g. dual, six-core Xeons with 24 Gbytes of RAM
and plenty of disk space).
Developers can use these systems for wider, more
extensive testing while they continue to develop
locally using their primary development system.
@ -222,10 +222,8 @@
allows you to work remotely, and then connects back to the
infrastructure.
<note>
For information about BitBake and SCMs, see the
BitBake manual located in the
<filename>bitbake/doc/manual</filename> directory of the
<ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
For information about BitBake, see the
<ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>.
</note>
</para>
@ -238,7 +236,7 @@
being used to generate the web interface that lets you view the
repositories.
The <filename>gitolite</filename> software identifies users
using <filename>ssh</filename> keys and allows branch-based
using SSH keys and allows branch-based
access controls to repositories that you can control as little
or as much as necessary.
</para>
@ -298,8 +296,8 @@
<listitem><para>Allows triggering of automated image booting
and testing under the QuickEMUlator (QEMU).
</para></listitem>
<listitem><para>Supports incremental build testing and from
scratch builds.</para></listitem>
<listitem><para>Supports incremental build testing and
from-scratch builds.</para></listitem>
<listitem><para>Shares output that allows developer
testing and historical regression investigation.
</para></listitem>
@ -365,14 +363,18 @@
See the "<link linkend='understanding-and-creating-layers'>Understanding
and Creating Layers</link>" section for more information on
layers.</para></listitem>
<listitem><para>Separate the project's Metadata and code by using
<listitem><para>
Separate the project's Metadata and code by using
separate Git repositories.
See the "<link linkend='yocto-project-repositories'>Yocto Project
Source Repositories</link>" section for information on these
repositories.
See the "<link linkend='getting-setup'>Getting Set Up</link>" section
for information on how to set up various Yocto Project related
Git repositories.</para></listitem>
See the
"<link linkend='yocto-project-repositories'>Yocto Project Source Repositories</link>"
section for information on these repositories.
See the
"<link linkend='getting-setup'>Getting Set Up</link>"
section for information on how to set up local Git
repositories for related upstream Yocto Project
Git repositories.
</para></listitem>
<listitem><para>Set up the directory for the shared state cache
(<ulink url='&YOCTO_DOCS_REF_URL;#var-SSTATE_DIR'><filename>SSTATE_DIR</filename></ulink>)
where it makes sense.
@ -389,7 +391,7 @@
See the "<link linkend='how-to-submit-a-change'>How to Submit a Change</link>"
section.</para></listitem>
<listitem><para>Send changes to the core sooner than later
as others likely run into the same issues.
as others are likely to run into the same issues.
For some guidance on mailing lists to use, see the list in the
"<link linkend='how-to-submit-a-change'>How to Submit a Change</link>"
section.
@ -415,7 +417,9 @@
From the interface, you can click on any particular item in the "Name"
column and see the URL at the bottom of the page that you need to clone
a Git repository for that particular item.
Having a local Git repository of the Source Directory (poky) allows
Having a local Git repository of the
<link linkend='source-directory'>Source Directory</link>, which is
usually named "poky", allows
you to make changes, contribute to the history, and ultimately enhance
the Yocto Project's tools, Board Support Packages, and so forth.
</para>
@ -447,9 +451,9 @@
<imagedata fileref="figures/source-repos.png" align="center" width="6in" depth="4in" />
</para></listitem>
<listitem><para><anchor id='index-downloads' /><emphasis><ulink url='&YOCTO_DL_URL;/releases/'>Index of /releases:</ulink></emphasis>
This area contains index releases such as
This is an index of releases such as
the <trademark class='trade'>Eclipse</trademark>
Yocto Plug-in, miscellaneous support, poky, pseudo, installers for cross-development toolchains,
Yocto Plug-in, miscellaneous support, Poky, Pseudo, installers for cross-development toolchains,
and all released versions of Yocto Project in the form of images or tarballs.
Downloading and extracting these files does not produce a local copy of the
Git repository but rather a snapshot of a particular release or image.</para>
@ -494,11 +498,11 @@
"<link linkend='using-bbappend-files'>Using .bbappend Files</link>" section.
</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 BitBake documentation
in the <filename>bitbake/doc/manual</filename> directory of the
<link linkend='source-directory'>Source Directory</link>.</para></listitem>
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='build-directory'><emphasis>Build Directory:</emphasis>
This term refers to the area used by the OpenEmbedded build system for builds.
@ -533,8 +537,9 @@
$ cd $HOME
$ source poky/&OE_INIT_FILE; test-builds
</literallayout></para></listitem>
<listitem><para>Provide a directory path and
specifically name the build directory.
<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
@ -557,23 +562,31 @@
<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
"<ulink url='&YOCTO_DOCS_REF_URL;#ref-classes'>Classes</ulink>" chapter of the
Yocto Project Reference Manual.
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
<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
<link linkend='build-directory'>Build Directory</link>
contains user-defined variables that affect each build.
The <filename>meta-yocto/conf/distro/poky.conf</filename> configuration file
defines Yocto "distro" configuration
contains user-defined variables that affect every 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
<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/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.
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 id='cross-development-toolchain'>
<emphasis>Cross-Development Toolchain:</emphasis>
@ -611,10 +624,11 @@
<ulink url='&YOCTO_DOCS_ADT_URL;'>Yocto Project
Application Developer's Guide</ulink>.
</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 run on specific hardware or QEMU
and for specific use cases.
<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 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
"<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>"
chapter in the Yocto Project Reference Manual.</para></listitem>
@ -640,9 +654,12 @@
with OpenEmbedded (OE) that is shared between OE and the Yocto Project.
This Metadata is found in the <filename>meta</filename> directory of the
<link linkend='source-directory'>Source Directory</link>.</para></listitem>
<listitem><para><emphasis>Package:</emphasis> In the context of the Yocto Project,
this term refers to the packaged output from a baked recipe.
A package is generally the compiled binaries produced from the recipe's sources.
<listitem><para><emphasis>Package:</emphasis>
In the context of the Yocto Project, this term refers 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
@ -673,24 +690,35 @@
by OpenedHand. With OpenedHand, poky was developed off of the existing OpenEmbedded
build system becoming a build system for embedded images.
After Intel Corporation acquired OpenedHand, the project poky became the basis for
the Yocto Project's build system.
the Yocto Project's build system.</para>
<para>
Within the Yocto Project source repositories, <filename>poky</filename>
exists as a separate Git repository
that can be cloned to yield a local copy on the host system.
Thus, "poky" can refer to the local copy of the Source Directory used to develop within
the Yocto Project.</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>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
to build, the images to build, and use the
<filename>.bb</filename> file extension.
</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>
@ -708,12 +736,12 @@
<para>When you create a local copy of the Git repository, you
can name the repository anything you like.
Throughout much of the documentation, <filename>poky</filename>
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 <filename>poky</filename>.</para>
folder is also named "poky".</para>
<para>While it is not recommended that you use tarball expansion
to setup the Source Directory, if you do, the top-level
@ -815,18 +843,23 @@
for a standard format for communicating the components, licenses, and copyrights
associated with a software package.
<ulink url='http://opensource.org'>OSI</ulink> is a corporation dedicated to the Open Source
Definition and the effort for reviewing and approving licenses that are OSD-conformant.
Definition and the effort for reviewing and approving licenses that
conform to the Open Source Definition (OSD).
</para>
<para>
You can find a list of the combined SPDX and OSI licenses that the Yocto Project uses
<ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta/files/common-licenses'>here</ulink>.
You can find a list of the combined SPDX and OSI licenses that the
Yocto Project uses in the
<filename>meta/files/common-licenses</filename> directory in your
<link linkend='source-directory'>Source Directory</link>.
</para>
<para>
For information that can help you to maintain compliance with various open source licensing
during the lifecycle of a product created using the Yocto Project, see the
"<link linkend='maintaining-open-source-license-compliance-during-your-products-lifecycle'>Maintaining Open Source License Compliance During Your Product's Lifecycle</link>" section.
For information that can help you maintain compliance with various
open source licensing during the lifecycle of a product created using
the Yocto Project, see the
"<link linkend='maintaining-open-source-license-compliance-during-your-products-lifecycle'>Maintaining Open Source License Compliance During Your Product's Lifecycle</link>"
section.
</para>
</section>
@ -889,12 +922,14 @@
</para>
<para>
It is important to understand that Git tracks content change and not files.
It is important to understand that Git tracks content change and
not files.
Git uses "branches" to organize different development efforts.
For example, the <filename>poky</filename> repository has
<filename>denzil</filename>, <filename>danny</filename>,
<filename>dylan</filename>, <filename>dora</filename>,
and <filename>master</filename> branches among others.
<filename>daisy</filename>, and <filename>master</filename> branches
among others.
You can see all the branches by going to
<ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/'></ulink> and
clicking on the
@ -928,37 +963,38 @@
</literallayout>
In this example, the name of the top-level directory of your local
<link linkend='source-directory'>Source Directory</link>
is <filename>poky</filename>,
and the name of that local working area (local branch) you just
created and checked out is <filename>&DISTRO_NAME;</filename>.
is "poky" and the name of that local working area (local branch)
you just created and checked out is "&DISTRO_NAME;".
The files in your local repository now reflect the same files that
are in the <filename>&DISTRO_NAME;</filename> development
branch of the Yocto Project's <filename>poky</filename>
upstream repository.
are in the "&DISTRO_NAME;" development branch of the
Yocto Project's "poky" upstream repository.
It is important to understand that when you create and checkout a
local working branch based on a branch name,
your local environment matches the "tip" of that development branch
at the time you created your local branch, which could be
different from the files at the time of a similarly named release.
In other words, creating and checking out a local branch based on the
<filename>&DISTRO_NAME;</filename> branch name is not the same as
cloning and checking out the <filename>master</filename> branch.
Keep reading to see how you create a local snapshot of a Yocto Project Release.
In other words, creating and checking out a local branch based on
the "&DISTRO_NAME;" branch name is not the same as
cloning and checking out the "master" branch.
Keep reading to see how you create a local snapshot of a Yocto
Project Release.
</para>
<para>
Git uses "tags" to mark specific changes in a repository.
Typically, a tag is used to mark a special point such as the final change
before a project is released.
You can see the tags used with the <filename>poky</filename> Git repository
by going to <ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/'></ulink> and
Typically, a tag is used to mark a special point such as the final
change before a project is released.
You can see the tags used with the <filename>poky</filename> Git
repository by going to
<ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/'></ulink> and
clicking on the
<filename><ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/refs/tags'>[...]</ulink></filename>
link beneath the "Tag" heading.
</para>
<para>
Some key tags are <filename>bernard-5.0</filename>, <filename>denzil-7.0</filename>,
Some key tags are <filename>dylan-9.0.0</filename>,
<filename>dora-10.0.0</filename>,
and <filename>&DISTRO_NAME;-&POKYVERSION;</filename>.
These tags represent Yocto Project releases.
</para>
@ -1007,7 +1043,7 @@
</para>
<para>
If you don’t know much about Git, you should educate
If you do not know much about Git, you should educate
yourself by visiting the links previously mentioned.
</para>
@ -1019,9 +1055,12 @@
<itemizedlist>
<listitem><para><emphasis><filename>git init</filename>:</emphasis> Initializes an empty Git repository.
You cannot use Git commands unless you have a <filename>.git</filename> repository.</para></listitem>
<listitem><para><emphasis><filename>git clone</filename>:</emphasis> Creates a clone of a repository.
During collaboration, this command allows you to create a local repository that is on
equal footing with a fellow developer’s repository.</para></listitem>
<listitem><para><emphasis><filename>git clone</filename>:</emphasis>
Creates a local clone of a Git repository.
During collaboration, this command allows you to create a
local Git repository that is on equal footing with a fellow
developer’s Git repository.
</para></listitem>
<listitem><para><emphasis><filename>git add</filename>:</emphasis> Stages updated file contents
to the index that
Git uses to track changes.
@ -1111,11 +1150,18 @@
</para>
<para>
The project also has contribution repositories known as "contrib" areas.
These areas temporarily hold changes to the project that have been submitted or committed
by the Yocto Project development team and by community members that contribute to the project.
The maintainer determines if the changes are qualified to be moved from the "contrib" areas
into the "master" branch of the Git repository.
The project also has an upstream contribution Git repository named
<filename>poky-contrib</filename>.
You can see all the branches in this repository using the web interface
of the
<ulink url='&YOCTO_GIT_URL;'>Source Repositories</ulink> organized
within the "Poky Support" area.
These branches temporarily hold changes to the project that have been
submitted or committed by the Yocto Project development team and by
community members who contribute to the project.
The maintainer determines if the changes are qualified to be moved
from the "contrib" branches into the "master" branch of the Git
repository.
</para>
<para>
@ -1143,11 +1189,13 @@
</para>
<para>
To summarize the environment: we have a single point of entry for changes into the project’s
"master" branch of the Git repository, which is controlled by the project’s maintainer.
And, we have a set of developers who independently develop, test, and submit changes
to "contrib" areas for the maintainer to examine.
The maintainer then chooses which changes are going to become a permanent part of the project.
To summarize the environment: a single point of entry exists for
changes into the project’s "master" branch of the Git repository,
which is controlled by the project’s maintainer.
And, a set of developers exist who independently develop, test, and
submit changes to "contrib" areas for the maintainer to examine.
The maintainer then chooses which changes are going to become a
permanent part of the project.
</para>
<para>
@ -1430,19 +1478,20 @@
you used. It may also be helpful if you mention how you tested the change.
Provide as much detail as you can in the body of the commit message.
</para></listitem>
<listitem><para>If the change addresses a specific bug or issue that is
associated with a bug-tracking ID, include a reference to that ID in
your detailed description.
For example, the Yocto Project uses a specific convention for bug
references - any commit that addresses a specific bug should include the
bug ID in the description (typically at the beginning) as follows:
<listitem><para>
If the change addresses a specific bug or issue that is
associated with a bug-tracking ID, include a reference to that
ID in your detailed description.
For example, the Yocto Project uses a specific convention for
bug references - any commit that addresses a specific bug should
use the following form for the detailed description:
<literallayout class='monospaced'>
[YOCTO #&lt;bug-id&gt;]
Fixes [YOCTO #&lt;bug-id&gt;]
&lt;detailed description of change&gt;
</literallayout></para></listitem>
Where &lt;bug-id&gt; is replaced with the specific bug ID from the
Yocto Project Bugzilla instance.
Where &lt;bug-id&gt; is replaced with the specific bug ID from
the Yocto Project Bugzilla instance.
</itemizedlist>
</para>
@ -1466,10 +1515,16 @@
<listitem><para>Make your changes in your local Git repository.</para></listitem>
<listitem><para>Stage your changes by using the <filename>git add</filename>
command on each file you changed.</para></listitem>
<listitem><para>Commit the change by using the <filename>git commit</filename>
command and push it to the "contrib" repository.
Be sure to provide a commit message that follows the project’s commit message standards
as described earlier.</para></listitem>
<listitem><para>
Commit the change by using the
<filename>git commit</filename> command.
Be sure to provide a commit message that follows the
project’s commit message standards as described earlier.
</para></listitem>
<listitem><para>
Push the change to the upstream "contrib" repository by
using the <filename>git push</filename> command.
</para></listitem>
<listitem><para>Notify the maintainer that you have pushed a change by making a pull
request.
The Yocto Project provides two scripts that conveniently let you generate and send