documentation/dev-manual/dev-manual-newbie.xml: edits and enhancements.
General pass-through for consistency in referencing sections. Also, added Darren Hart's review comments for the "Submitting a Change" section. I added more about the mailing lists and how to submit a proper commit message. (From yocto-docs rev: d9c8f5db8c862b1be724915cc43da6d12b88b97d) Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
This commit is contained in:
parent
90ccadecc3
commit
421c22d32c
|
@ -7,12 +7,12 @@
|
|||
|
||||
<para>
|
||||
This chapter helps you understand the Yocto Project as an open source development project.
|
||||
In general, working in an open-source environment is very different than working in a
|
||||
In general, working in an open source environment is very different as compared to working in a
|
||||
proprietary environment.
|
||||
Additionally, the Yocto Project uses specific tools and constructs as part of its development
|
||||
environment.
|
||||
The chapter specifically addresses open source philosophy, licensing issues, code repositories,
|
||||
the open source distributed version control system Git, and best practices using Yocto Project.
|
||||
the open source distributed version control system Git, and best practices using the Yocto Project.
|
||||
</para>
|
||||
|
||||
<section id='open-source-philosophy'>
|
||||
|
@ -33,23 +33,21 @@
|
|||
stake in the software project.
|
||||
The open source environment contains new copyright, licensing, domain, and consumer issues
|
||||
that differ from the more traditional development environment.
|
||||
In an open source environment the end-product, source material, and documentation are
|
||||
In an open source environment, the end-product, source material, and documentation are
|
||||
all available to the public at no cost.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
A benchmark example of an open source project is the Linux Kernel, which was initially conceived
|
||||
and created by Finnish computer science student Linus Torvalds in 1991.
|
||||
Conversely, a good example of a non-open source project is the Windows family of operating
|
||||
systems developed by Microsoft Corporation.
|
||||
Conversely, a good example of a non-open source project is the
|
||||
<trademark class='registered'>Windows</trademark> family of operating
|
||||
systems developed by <trademark class='registered'>Microsoft</trademark> Corporation.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Wikipedia has a good historical description of the Open Source Philosophy
|
||||
<ulink url='http://en.wikipedia.org/wiki/Open_source'>here</ulink>.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
You can also find helpful information on how to participate in the Linux Community
|
||||
<ulink url='http://ldn.linuxfoundation.org/book/how-participate-linux-community'>here</ulink>.
|
||||
</para>
|
||||
|
@ -66,21 +64,21 @@
|
|||
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 set up a Git repository for
|
||||
that particular item.
|
||||
The ability to create Git repositories of the Yocto Project source allows you to
|
||||
Having a local Git repository of the Yocto Project files allows you to
|
||||
make changes, contribute to the history, and ultimately enhance the Yocto Project's
|
||||
tools, Board Support Packages, and so forth.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Conversely, if you are a developer that is not interested in contributing back to the
|
||||
Yocto Project you have the ability to simply download and extract release tarballs
|
||||
Yocto Project, you have the ability to simply download and extract release tarballs
|
||||
and use them within the Yocto Project environment.
|
||||
All that is required is a particular release of Yocto Project, a kernel, and
|
||||
your application source code.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
For any supported release of Yocto Project you can go to the Yocto Project website’s
|
||||
For any supported release of Yocto Project, you can go to the Yocto Project website’s
|
||||
<ulink url='http://www.yoctoproject.org/download'>download page</ulink> and get a
|
||||
tarball of the release.
|
||||
You can also go to this site to download any supported BSP tarballs.
|
||||
|
@ -104,8 +102,9 @@
|
|||
<imagedata fileref="figures/source-repos.png" align="center" width="6in" depth="4in" />
|
||||
</para></listitem>
|
||||
<listitem><para><anchor id='index-downloads' /><emphasis><ulink url='http://autobuilder.yoctoproject.org/downloads/'>Index of /downloads:</ulink></emphasis>
|
||||
This area contains an index of the Eclipse-plugin, miscellaneous support, poky, pseudo, and
|
||||
all released versions of Yocto Project in the form of images or tarballs.
|
||||
This area contains an index of downloads such as
|
||||
the Eclipse Yocto Plug-in, miscellaneous support, Poky, pseudo, 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 Git repository but rather
|
||||
a snapshot of a particular release or image.
|
||||
[WRITER NOTE: link will be http://downloads.yoctoproject.org.]</para>
|
||||
|
@ -130,12 +129,87 @@
|
|||
<para>
|
||||
Following is a list of terms and definitions users new to the Yocto Project development
|
||||
environment might find helpful.
|
||||
Some terms are universal but are included here just in case:
|
||||
While some of these terms are universal, the list includes them just in case:
|
||||
<itemizedlist>
|
||||
<listitem><para><emphasis>The Yocto Project Files:</emphasis>
|
||||
<listitem><para><emphasis>Append Files:</emphasis> Files that append build information to
|
||||
a recipe file.
|
||||
Information in append files override 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 the
|
||||
<filename>.conf</filename> files provides global definitions of variables.
|
||||
The <filename>conf/local.conf</filename> configuration file in the Yocto Project
|
||||
build directory defines user-defined variables that affect each build.
|
||||
The <filename>distro/poky.conf</filename> configuration file also in the
|
||||
build directory 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 architecure.
|
||||
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/1.1/poky-ref-manual/poky-ref-manual.html#ref-images'>Reference: Images</ulink>"
|
||||
appendix in
|
||||
<ulink url='http://www.yoctoproject.org/docs/1.1/poky-ref-manual/poky-ref-manual.html'>
|
||||
The Yocto Project Reference Manual</ulink>.</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><emphasis>Yocto Project Files:</emphasis>
|
||||
This term refers to the directory structure created as a result of downloading
|
||||
and unpacking a Yocto Project release tarball or setting up a Git repository
|
||||
by cloning <filename>git://git.yoctoproject.org/poky</filename>.</para>
|
||||
by cloning <filename>git://git.yoctoproject.org/poky</filename>.
|
||||
Sometimes the term "the Yocto Project Files structure" is used as well.</para>
|
||||
<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
|
||||
|
@ -143,102 +217,31 @@
|
|||
<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 source tree whose Yocto Project source directory is named
|
||||
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.</para>
|
||||
<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/1.1/dev-manual/dev-manual.html#getting-setup'>Getting
|
||||
Setup</ulink>" section in
|
||||
<ulink url='http://www.yoctoproject.org/docs/1.1/dev-manual/dev-manual.html'>
|
||||
The Yocto Project Development Manual</ulink>.</para></listitem>
|
||||
<listitem><para><emphasis>Yocto Project Build Tree:</emphasis>
|
||||
This term refers to the area where the Yocto Project builds images.
|
||||
Setup</ulink>" section.</para></listitem>
|
||||
<listitem><para><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 tree anywhere you want on your
|
||||
You can create the Yocto Project build directory anywhere you want on your
|
||||
development system.
|
||||
Here is an example that creates the tree in <filename>mybuilds</filename>
|
||||
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'>
|
||||
$ source poky-edison-6.0/oe-init-build-env $HOME/mybuilds/YP-6.0
|
||||
</literallayout>
|
||||
If you don't specifically name the build directory, BitBake creates it
|
||||
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 tree
|
||||
directory as the Yocto Project build directory and populates the build hierarchy
|
||||
beneath it.</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/1.1/poky-ref-manual/poky-ref-manual.html#ref-images'>
|
||||
Reference: Images</ulink> appendix in
|
||||
<ulink url='http://www.yoctoproject.org/docs/1.1/poky-ref-manual/poky-ref-manual.html'>
|
||||
The Yocto Project Reference Manual</ulink>.</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>BitBake</emphasis> - The task executor and scheduler used by 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>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>Layer</emphasis> - A collection of recipes representing the core,
|
||||
a BSP, or an application stack.</para></listitem>
|
||||
<listitem><para><emphasis>Metadata</emphasis> - A term used throughout the Yocto Project
|
||||
documentation that refers to the files that BitBake parses when building an image.
|
||||
Metadata includes recipes, classes, and configuration files.</para></listitem>
|
||||
<listitem><para><emphasis>Meta-Toolchain</emphasis> - A collection of software development
|
||||
tools and utilities that allow you to develop software for targeted architectures.
|
||||
These toolchains contain cross-compilers, linkers, and debuggers that are specific to
|
||||
an architecure.
|
||||
You can use the Yocto Project to build meta-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.</para></listitem>
|
||||
<listitem><para><emphasis>Configuration File</emphasis>: Configuration information in the
|
||||
<filename>.conf</filename> files provides global definitions of variables.
|
||||
The <filename>build/conf/local.conf</filename> configuration file defines user-defined variables
|
||||
that effect each build.
|
||||
The <filename>distro/poky.conf</filename> configuration file defines Yocto ‘distro’ configuration
|
||||
variables used only when building with this policy.
|
||||
The <filename>machine/beagleboard.conf</filename> configuration file defines variables
|
||||
for the Beagleboard and are only used when building for that target
|
||||
(i.e. Texas Instruments ARM Cortex-A8 development board).
|
||||
Configuration files end with a <filename>.conf</filename> filename extension.</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>Append Files</emphasis> - Files that append build information to
|
||||
a recipe file.
|
||||
Information in append files override the information in the similarly-named recipe file.
|
||||
Append files use the <filename>.bbappend</filename> filename suffix.</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>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>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>
|
||||
</itemizedlist>
|
||||
</para>
|
||||
</section>
|
||||
|
@ -247,9 +250,9 @@
|
|||
<title>Licensing</title>
|
||||
|
||||
<para>
|
||||
Because open source projects are open to the public they have different licensing structures in place.
|
||||
Because open source projects are open to the public, they have different licensing structures in place.
|
||||
License evolution for both Open Source and Free Software has an interesting history.
|
||||
If you are interested in the history you can find basic information here:
|
||||
If you are interested in this history, you can find basic information here:
|
||||
<itemizedlist>
|
||||
<listitem><para><ulink url='http://en.wikipedia.org/wiki/Open-source_license'>Open source license history</ulink>
|
||||
</para></listitem>
|
||||
|
@ -275,13 +278,13 @@
|
|||
When you build an image using Yocto Project, the build process uses a known list of licenses to
|
||||
ensure compliance.
|
||||
Once the build completes, the list of all licenses found and used during the build are
|
||||
kept in the resulting build directory at
|
||||
<filename><build_directory>/tmp/deploy/images/licenses</filename>.
|
||||
kept in the Yocto Project build directory at
|
||||
<filename>tmp/deploy/images/licenses</filename>.
|
||||
If a module requires a license that is not in the base list, the build process
|
||||
generates a warning during the build.
|
||||
These tools make it easier for a developer to be certain of the licenses with which
|
||||
their shipped products must comply.
|
||||
However, it is still up to the developer to resolve potential licensing issues.
|
||||
However, even with these tools it is still up to the developer to resolve potential licensing issues.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
|
@ -292,14 +295,13 @@
|
|||
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 are OSD-conformant.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
You can find a list of the combined SPDX and OSI licenses that the Yocto Project uses
|
||||
<ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/poky/tree/meta/files/common-licenses'>here</ulink>.
|
||||
The wiki page discusses the license infrastructure used by the Yocto Project.
|
||||
This wiki page discusses the license infrastructure used by the Yocto Project.
|
||||
</para>
|
||||
</section>
|
||||
|
||||
|
@ -320,7 +322,7 @@
|
|||
You do not have to be an expert in Git to be functional.
|
||||
A good place to look for instruction on a minimal set of Git commands is
|
||||
<ulink url='http://git-scm.com/documentation'>here</ulink>.
|
||||
If you need to download Git you can do so
|
||||
If you need to download Git, you can do so
|
||||
<ulink url='http://git-scm.com/download'>here</ulink>.
|
||||
</para>
|
||||
|
||||
|
@ -332,7 +334,7 @@
|
|||
This methodology also allows for an environment in which you can do lots of
|
||||
experimentation on your project as you develop changes or new features.
|
||||
For example, you can create a “branch”, experiment with some feature, and then
|
||||
if you like the feature you incorporate the branch into the tree.
|
||||
if you like the feature, you incorporate the branch into the tree.
|
||||
If you don’t, you cut the branch off by deleting it.
|
||||
</para>
|
||||
|
||||
|
@ -347,55 +349,63 @@
|
|||
omits the many arguments they support.
|
||||
See the Git documentation for complete descriptions and strategies on how to use these commands:
|
||||
<itemizedlist>
|
||||
<listitem><para><emphasis><filename>git init</filename></emphasis> – Initializes an empty Git repository.
|
||||
<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
|
||||
<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 add</filename></emphasis> – Adds updated file contents to the index that
|
||||
<listitem><para><emphasis><filename>git add</filename>:</emphasis> Adds updated file contents
|
||||
to the index that
|
||||
Git uses to track changes.
|
||||
All files that have changed must be added before they can be committed.</para></listitem>
|
||||
<listitem><para><emphasis><filename>git commit</filename></emphasis> – Creates a “commit” that documents
|
||||
You must add all files that have changed before you can commit them.</para></listitem>
|
||||
<listitem><para><emphasis><filename>git commit</filename>:</emphasis> Creates a “commit” that documents
|
||||
the changes you made.
|
||||
Commits are used for historical purposes, for determining if a maintainer of a project
|
||||
will allow the change, and for ultimately pushing the change from your local Git repository
|
||||
into the project’s upstream (or master) repository.</para></listitem>
|
||||
<listitem><para><emphasis><filename>git status</filename></emphasis> – Reports any modified files that
|
||||
<listitem><para><emphasis><filename>git status</filename>:</emphasis> Reports any modified files that
|
||||
possibly need added and committed.</para></listitem>
|
||||
<listitem><para><emphasis><filename>git checkout <branch-name></filename></emphasis> - Changes
|
||||
your working branch. This command is analogous to “cd”.</para></listitem>
|
||||
<listitem><para><emphasis><filename>git checkout –b <working-branch></filename></emphasis> - Creates
|
||||
<listitem><para><emphasis><filename>git checkout <branch-name></filename>:</emphasis> Changes
|
||||
your working branch.
|
||||
This command is analogous to “cd”.</para></listitem>
|
||||
<listitem><para><emphasis><filename>git checkout –b <working-branch></filename>:</emphasis> Creates
|
||||
a working branch on your local machine where you can isolate work.
|
||||
It is a good idea to use local branches when adding specific features or changes.
|
||||
This way if you don’t like what you have done you can easily get rid of the work.</para></listitem>
|
||||
<listitem><para><emphasis><filename>git branch</filename></emphasis> – Reports existing branches and
|
||||
<listitem><para><emphasis><filename>git branch</filename>:</emphasis> Reports existing branches and
|
||||
tells you which branch in which you are currently working.</para></listitem>
|
||||
<listitem><para><emphasis><filename>git branch -D <branch-name></filename></emphasis> –
|
||||
Deletes an existing branch. You need to be in a branch other than the one you are deleting
|
||||
<listitem><para><emphasis><filename>git branch -D <branch-name></filename>:</emphasis>
|
||||
Deletes an existing branch.
|
||||
You need to be in a branch other than the one you are deleting
|
||||
in order to delete <branch-name>.</para></listitem>
|
||||
<listitem><para><emphasis><filename>git pull</filename></emphasis> – Retrieves information from an upstream Git
|
||||
<listitem><para><emphasis><filename>git pull</filename>:</emphasis> Retrieves information
|
||||
from an upstream Git
|
||||
repository and places it in your local Git repository.
|
||||
You use this command to make sure you are synchronized with the upstream repository
|
||||
from which the project’s maintainer uses to pull changes into the master repository.</para></listitem>
|
||||
<listitem><para><emphasis><filename>git push</filename></emphasis> – Sends all your local changes you
|
||||
have committed to an upstream Git repository.
|
||||
You use this command to make sure you are synchronized with the repository
|
||||
from which you are basing changes (.e.g. the master repository).</para></listitem>
|
||||
<listitem><para><emphasis><filename>git push</filename>:</emphasis> Sends all your local changes you
|
||||
have committed to an upstream Git repository (e.g. a contribution repository).
|
||||
The maintainer of the project draws from these repositories when adding your changes to the
|
||||
project’s master repository.</para></listitem>
|
||||
<listitem><para><emphasis><filename>git merge</filename></emphasis> – Combines or adds changes from one
|
||||
<listitem><para><emphasis><filename>git merge</filename>:</emphasis> Combines or adds changes from one
|
||||
local branch of your repository with another branch.
|
||||
When you create a local Git repository the default branch is named “master”.
|
||||
When you create a local Git repository, the default branch is named “master”.
|
||||
A typical workflow is to create a temporary branch for isolated work, make and commit your
|
||||
changes, switch to the master branch, merge the changes from the temporary branch into the
|
||||
master branch, and then delete the temporary branch</para></listitem>
|
||||
<listitem><para><emphasis><filename>git cherry-pick</filename></emphasis> – Choose and apply specific
|
||||
changes, switch to your local master branch, merge the changes from the temporary branch into the
|
||||
local master branch, and then delete the temporary branch.</para></listitem>
|
||||
<listitem><para><emphasis><filename>git cherry-pick</filename>:</emphasis> Choose and apply specific
|
||||
commits from one branch into another branch.
|
||||
There are times when you might not be able to merge all the changes in one branch with
|
||||
another but need to pick out certain ones.</para></listitem>
|
||||
<listitem><para><emphasis><filename>gitk</filename></emphasis> – Provides a GUI view of the branches
|
||||
<listitem><para><emphasis><filename>gitk</filename>:</emphasis> Provides a GUI view of the branches
|
||||
and changes in your local Git repository.
|
||||
This command is a good way to see where things have diverged in your local repository.</para></listitem>
|
||||
<listitem><para><emphasis><filename>git log</filename></emphasis> – Reports a history of your changes to the
|
||||
This command is a good way to graphically see where things have diverged in your
|
||||
local repository.</para></listitem>
|
||||
<listitem><para><emphasis><filename>git log</filename>:</emphasis> Reports a history of your changes to the
|
||||
repository.</para></listitem>
|
||||
<listitem><para><emphasis><filename>git diff</filename>:</emphasis> Displays line-by-line differences
|
||||
between your local working files and the same files in the upstream Git repository that your
|
||||
branch currently tracks.</para></listitem>
|
||||
</itemizedlist>
|
||||
</para>
|
||||
</section>
|
||||
|
@ -407,14 +417,16 @@
|
|||
This section provides some overview on workflows using Git.
|
||||
In particular, the information covers basic practices that describe roles and actions in a
|
||||
collaborative development environment.
|
||||
Again, if you are familiar with this type of development environment you might want to just skip the section.
|
||||
Again, if you are familiar with this type of development environment, you might want to just
|
||||
skip the section.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The Yocto Project files are maintained using Git in a "master" branch whose Git history
|
||||
tracks every change and whose structure provides branches for all diverging functionality.
|
||||
Although there is no need to use Git, This practice is typical for open-source projects.
|
||||
For the Yocto Project a key individual called the "maintainer" is responsible for "master".
|
||||
Although there is no need to use Git, many open source projects do so.
|
||||
For the Yocto Project, a key individual called the "maintainer" is responsible for "master"
|
||||
branch of the Git repository.
|
||||
The "master" branch is the “upstream” repository where the final builds of the project occur.
|
||||
The maintainer is responsible for allowing changes in from other developers and for
|
||||
organizing the underlying branch structure to reflect release strategies and so forth.
|
||||
|
@ -432,7 +444,7 @@
|
|||
Developers (including contributing community members) create and maintain cloned repositories
|
||||
of the upstream "master" branch.
|
||||
These repositories are local to their development platforms and are used to develop changes.
|
||||
When a developer is satisfied with a particular feature or change they “push” the changes
|
||||
When a developer is satisfied with a particular feature or change, they “push” the changes
|
||||
to the appropriate "contrib" repository.
|
||||
</para>
|
||||
|
||||
|
@ -469,38 +481,38 @@
|
|||
For more detailed information about these strategies see
|
||||
<ulink url='http://www.kernel.org/pub/software/scm/git/docs/gitworkflows.html'>Git Workflows</ulink>.
|
||||
<itemizedlist>
|
||||
<listitem><para><emphasis>Make Small Changes</emphasis> - It is best to keep your changes you commit
|
||||
<listitem><para><emphasis>Make Small Changes:</emphasis> It is best to keep your changes you commit
|
||||
small as compared to bundling many disparate changes into a single commit.
|
||||
This practice not only keeps things manageable but also allows the maintainer
|
||||
to more easily include or refuse changes.</para>
|
||||
<para>It is also good practice to leave the repository in a state that allows you to
|
||||
still successfully build your project.</para></listitem>
|
||||
<listitem><para><emphasis>Use Branches Liberally</emphasis> - It is very easy to create, use, and
|
||||
<listitem><para><emphasis>Use Branches Liberally:</emphasis> It is very easy to create, use, and
|
||||
delete local branches in your working Git repository.
|
||||
You can name these branches anything you like.
|
||||
It is helpful to give them names associated with the particular feature or change
|
||||
on which you are working.
|
||||
Once you are done with a feature or change you simply discard the branch.</para></listitem>
|
||||
<listitem><para><emphasis>Merge Changes</emphasis> - The <filename>git merge</filename>
|
||||
Once you are done with a feature or change, simply discard the branch.</para></listitem>
|
||||
<listitem><para><emphasis>Merge Changes:</emphasis> The <filename>git merge</filename>
|
||||
command allows you to take the
|
||||
changes from one branch and fold them into another branch.
|
||||
This process is especially helpful when more than a single developer might be working
|
||||
on different parts of the same feature.
|
||||
Merging changes also automatically identifies any collisions or “conflicts”
|
||||
that might happen resulting from the same lines of code being altered by two different
|
||||
that might happen as a result of the same lines of code being altered by two different
|
||||
developers.</para></listitem>
|
||||
<listitem><para><emphasis>Manage Branches</emphasis> - Because branches are easy to use, you should
|
||||
<listitem><para><emphasis>Manage Branches:</emphasis> Because branches are easy to use, you should
|
||||
use a system where branches indicate varying levels of code readiness.
|
||||
For example, you can have a “work” branch to develop in, a “test” branch where the code or
|
||||
change is tested, a “stage” branch where changes are ready to be committed, and so forth.
|
||||
As your project develops, you can merge code across the branches to reflect ever-increasing
|
||||
stable states of the development.</para></listitem>
|
||||
<listitem><para><emphasis>Use Push and Pull</emphasis> - The push-pull workflow is based on the
|
||||
<listitem><para><emphasis>Use Push and Pull:</emphasis> The push-pull workflow is based on the
|
||||
concept of developers “pushing” local commits to a remote repository, which is
|
||||
usually a contribution repository.
|
||||
It is also based on the developers “pulling” known states of the project down into their
|
||||
This workflow is also based on developers “pulling” known states of the project down into their
|
||||
local development repositories.
|
||||
This workflow easily allows you to pull changes submitted by other developers from the
|
||||
The workflow easily allows you to pull changes submitted by other developers from the
|
||||
upstream repository into your work area ensuring that you have the most recent software
|
||||
on which to develop.
|
||||
The Yocto Project has two scripts named <filename>create-pull-request</filename> and
|
||||
|
@ -508,7 +520,7 @@
|
|||
workflow.
|
||||
You can find these scripts in the local Yocto Project files Git repository in
|
||||
<filename>scripts</filename>.</para></listitem>
|
||||
<listitem><para><emphasis>Patch Workflow</emphasis> - This workflow allows you to notify the
|
||||
<listitem><para><emphasis>Patch Workflow:</emphasis> This workflow allows you to notify the
|
||||
maintainer through an email that you have a change (or patch) you would like considered
|
||||
for the "master" branch of the Git repository.
|
||||
To send this type of change you format the patch and then send the email using the Git commands
|
||||
|
@ -532,7 +544,7 @@
|
|||
<para>
|
||||
Sometimes it is helpful to submit, investigate, or track a bug against the Yocto Project itself
|
||||
such as when discovering an issue with some component of the build system that acts contrary
|
||||
to the documentation or expectations.
|
||||
to the documentation or your expectations.
|
||||
You can find information
|
||||
for Bugzilla configuration and bug tracking procedures specific to the Yocto Project
|
||||
<ulink url='https://wiki.yoctoproject.org/wiki/Bugzilla_Configuration_and_Bug_Tracking'>here</ulink>.
|
||||
|
@ -548,7 +560,7 @@
|
|||
<para>
|
||||
Here are some things to remember when dealing with bugs against the Yocto Project:
|
||||
<itemizedlist>
|
||||
<listitem><para>The Yocto Project follows a naming bug-naming convention:
|
||||
<listitem><para>The Yocto Project follows a bug-naming convention:
|
||||
<filename>[YOCTO #<number>]</filename>, where <filename><number></filename> is the
|
||||
assigned defect ID used in Bugzilla.
|
||||
So, for example, a valid way to refer to a defect when creating a commit comment
|
||||
|
@ -567,8 +579,34 @@
|
|||
|
||||
<para>
|
||||
Contributions to the Yocto Project are very welcome.
|
||||
You should send patches to the Yocto Project mailing list to get them in front of the
|
||||
Yocto Project Maintainer.
|
||||
You should send patches to the appropriate Yocto Project mailing list to get them
|
||||
in front of the Yocto Project Maintainer.
|
||||
For a list of the Yocto Project mailing lists, see the
|
||||
"<ulink url='http://www.yoctoproject.org/docs/1.1/poky-ref-manual/poky-ref-manual.html#resources-mailinglist'>Mailing lists</ulink>" section in
|
||||
<ulink url='http://www.yoctoproject.org/docs/1.1/poky-ref-manual/poky-ref-manual.html'> The
|
||||
Yocto Project Reference Manual</ulink>.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Following is some guidance on which mailing list to use for what type of defect:
|
||||
<itemizedlist>
|
||||
<listitem><para>For defects against the Yocto Project build system Poky, send
|
||||
your patch to the
|
||||
<ulink url='http://lists.yoctoproject.org/listinfo/poky'></ulink> mailing list.
|
||||
This mailing list corresponds to issues that are not specific to the Yocto Project but
|
||||
are part of the OE-core.
|
||||
For example, a defect against anything in the <filename>meta</filename> layer
|
||||
or the BitBake Manual could be sent to this mailing list.</para></listitem>
|
||||
<listitem><para>For defects against Yocto-specific layers, tools, and Yocto Project
|
||||
documentation use the
|
||||
<ulink url='http://lists.yoctoproject.org/listinfo/yocto'></ulink> mailing list.
|
||||
This mailing list corresponds to Yocto-specific areas such as
|
||||
<filename>meta-yocto</filename>, <filename>meta-intel</filename>,
|
||||
<filename>linux-yocto</filename>, and <filename>documentation</filename>.</para></listitem>
|
||||
</itemizedlist>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
When you send a patch, be sure to include a "signed-off-by:"
|
||||
line in the same style as required by the Linux kernel.
|
||||
Adding this line signifies the developer has agreed to the Developer's Certificate of Origin 1.1
|
||||
|
@ -611,33 +649,38 @@
|
|||
<para>
|
||||
In a collaborative environment, it is necessary to have some sort of standard
|
||||
or method through which you submit changes.
|
||||
Otherwise, things would get quite chaotic.
|
||||
Otherwise, things could get quite chaotic.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
When you form a commit you must follow certain standards established by the
|
||||
When you form a commit, you must follow certain standards established by the
|
||||
Yocto Project development team.
|
||||
For each commit, do the following:
|
||||
For each commit, you must provide a single-line summary of the change and you
|
||||
almost always provide a more detailed description of what you did (i.e. the body
|
||||
of the commit).
|
||||
The only exceptions for not providing a detailed description would be if your
|
||||
change is a simple, self-explanatory change that needs no description.
|
||||
Here are the Yocto Project commit message guidelines:
|
||||
<itemizedlist>
|
||||
<listitem><para>Provide a single-line, short summary of the change.
|
||||
This summary is typically viewable by source control systems.
|
||||
Thus, providing something short and descriptive that gives the reader
|
||||
a summary of the change is useful when viewing a list of many commits.
|
||||
</para></listitem>
|
||||
<listitem><para>If the change addresses a specific bug or issue that is
|
||||
associated with a bug-tracking ID, prefix the single-line commit summary
|
||||
with the bug or issue ID.
|
||||
For example, the Yocto Project tracks bugs using a bug-naming convention.
|
||||
Any commits that address a bug must use a commit summary line in the
|
||||
following form:
|
||||
<literallayout class='monospaced'>
|
||||
YOCTO #<bug-id>: <Brief 40-character or less summary of the change>
|
||||
</literallayout></para></listitem>
|
||||
<listitem><para>For the body of the commit message, provide detailed information
|
||||
that describes what you changed, why you made the change, and the approach
|
||||
you used.
|
||||
Provide as much detail as you want in the body of the commit message.
|
||||
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, prefix your detailed description
|
||||
with the bug or issue ID.
|
||||
For example, the Yocto Project tracks bugs using a bug-naming convention.
|
||||
Any commits that address a bug must start with the bug ID in the description
|
||||
as follows:
|
||||
<literallayout class='monospaced'>
|
||||
YOCTO #<bug-id>: <Detailed description of commit>
|
||||
</literallayout></para></listitem>
|
||||
</itemizedlist>
|
||||
</para>
|
||||
|
||||
|
@ -655,7 +698,7 @@
|
|||
<listitem><para>Stage your commit (or change) by using the <filename>git add</filename>
|
||||
command.</para></listitem>
|
||||
<listitem><para>Commit the change by using the <filename>git commit</filename>
|
||||
command and push it to the upstream "contrib" repository.
|
||||
command and push it to the "contrib" repository.
|
||||
Be sure to provide a commit message that follows the project’s commit standards
|
||||
as described earlier.</para></listitem>
|
||||
<listitem><para>Notify the maintainer that you have pushed a change by making a pull
|
||||
|
@ -696,12 +739,13 @@
|
|||
<listitem><para>Commit the change by using the
|
||||
<filename>git commit --signoff</filename> command.
|
||||
Using the <filename>--signoff</filename> option identifies you as the person
|
||||
making the change.</para>
|
||||
making the change and also satisfies the Developer's Certificate of
|
||||
Origin (DCO) shown earlier.</para>
|
||||
<para>When you form a commit you must follow certain standards established by the
|
||||
Yocto Project development team.
|
||||
See the
|
||||
<link linkend='how-to-submit-a-change'>How to Submit a Change</link> section
|
||||
earlier for Yocto Project commit message standards.</para></listitem>
|
||||
See the earlier section
|
||||
"<link linkend='how-to-submit-a-change'>How to Submit a Change</link>"
|
||||
for Yocto Project commit message standards.</para></listitem>
|
||||
<listitem><para>Format the commit into an email messsage.
|
||||
To format commits, use the <filename>git format-patch</filename> command.
|
||||
When you provide the command, you must include a revision list or a number of patches
|
||||
|
@ -714,9 +758,11 @@
|
|||
</literallayout></para>
|
||||
<para>After the command is run, the current directory contains a
|
||||
numbered <filename>.patch</filename> file for the commit.</para>
|
||||
<para>If you provide several commits as part of the command, it produces a numbered
|
||||
<para>If you provide several commits as part of the command,
|
||||
the <filename>git format-patch</filename> command produces a numbered
|
||||
series of files in the current directory – one for each commit.
|
||||
For information on the <filename>git format-patch</filename> command use the
|
||||
For information on the <filename>git format-patch</filename> command,
|
||||
see <filename>GIT_FORMAT_PATCH(1)</filename> displayed using the
|
||||
<filename>man git-format-patch</filename> command.</para></listitem>
|
||||
<listitem><para>Import the files into your mail client by using the
|
||||
<filename>git send-email</filename> command.
|
||||
|
@ -728,7 +774,10 @@
|
|||
<filename>msmtp</filename>, <filename>sendmail</filename>, or through a direct
|
||||
<filename>smtp</filename> configuration in your Git <filename>config</filename>
|
||||
file.</para>
|
||||
<para>The <filename>git send-email</filename> command has several options that let you
|
||||
<para>The <filename>git send-email</filename> command is the preferred method
|
||||
for sending your patches since there is no risk of compromising whitespace
|
||||
in the body of the message, which can occur when you use your own mail client.
|
||||
The command also has several options that let you
|
||||
specify recipients and perform further editing of the email message.
|
||||
For information on how to use the <filename>git send-email</filename> command,
|
||||
use the <filename>man git-send-email</filename> command.</para></listitem>
|
||||
|
|
Loading…
Reference in New Issue