Documentation: kernel-manual - Removed all trailing whitespace.
(From yocto-docs rev: 188e1ad10217ff1a6a8363f100bff4e9ef3b9bf7) 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
72d01bf43d
commit
acb3f72afa
|
@ -146,7 +146,7 @@
|
|||
Yocto Project and provides information
|
||||
on the mechanisms used to achieve that architecture.
|
||||
</para>
|
||||
|
||||
|
||||
<section id='architecture-overview'>
|
||||
<title>Overview</title>
|
||||
<para>
|
||||
|
|
|
@ -10,9 +10,9 @@
|
|||
<title>Introduction</title>
|
||||
<para>
|
||||
The Yocto Project presents kernels as a fully patched, history-clean Git
|
||||
repositories.
|
||||
repositories.
|
||||
Each repository represents selected features, board support,
|
||||
and configurations extensively tested by the Yocto Project.
|
||||
and configurations extensively tested by the Yocto Project.
|
||||
Yocto Project kernels allow the end user to leverage community
|
||||
best practices to seamlessly manage the development, build and debug cycles.
|
||||
</para>
|
||||
|
@ -22,14 +22,14 @@
|
|||
The manual consists of two sections:
|
||||
<itemizedlist>
|
||||
<listitem><para><emphasis>Concepts:</emphasis> Describes concepts behind a kernel.
|
||||
You will understand how a kernel is organized and why it is organized in
|
||||
the way it is. You will understand the benefits of a kernel's organization
|
||||
and the mechanisms used to work with the kernel and how to apply it in your
|
||||
You will understand how a kernel is organized and why it is organized in
|
||||
the way it is. You will understand the benefits of a kernel's organization
|
||||
and the mechanisms used to work with the kernel and how to apply it in your
|
||||
design process.</para></listitem>
|
||||
<listitem><para><emphasis>Using a Kernel:</emphasis> Describes best practices
|
||||
<listitem><para><emphasis>Using a Kernel:</emphasis> Describes best practices
|
||||
and "how-to" information
|
||||
that lets you put a kernel to practical use.
|
||||
Some examples are how to examine changes in a branch and how to
|
||||
that lets you put a kernel to practical use.
|
||||
Some examples are how to examine changes in a branch and how to
|
||||
save kernel modifications.</para></listitem>
|
||||
</itemizedlist>
|
||||
</para>
|
||||
|
@ -39,8 +39,8 @@
|
|||
<itemizedlist>
|
||||
<listitem><para>The Linux Foundation's guide for kernel development
|
||||
process - <ulink url='http://www.linuxfoundation.org/content/1-guide-kernel-development-process'></ulink></para></listitem>
|
||||
<listitem><para>A fairly encompassing guide on Linux kernel development -
|
||||
<ulink url='http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=blob_plain;f=Documentation/HOWTO;hb=HEAD'></ulink></para></listitem>
|
||||
<listitem><para>A fairly encompassing guide on Linux kernel development -
|
||||
<ulink url='http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=blob_plain;f=Documentation/HOWTO;hb=HEAD'></ulink></para></listitem>
|
||||
</itemizedlist>
|
||||
</para>
|
||||
|
||||
|
@ -53,14 +53,14 @@
|
|||
<listitem><para>
|
||||
"<ulink url='&YOCTO_DOCS_DEV_URL;#kernel-modification-workflow'>Kernel Modification Workflow</ulink>"
|
||||
</para></listitem>
|
||||
<listitem><para>
|
||||
<listitem><para>
|
||||
"<ulink url='&YOCTO_DOCS_DEV_URL;#patching-the-kernel'>Patching the Kernel</ulink>"</para></listitem>
|
||||
<listitem><para>
|
||||
<listitem><para>
|
||||
"<ulink url='&YOCTO_DOCS_DEV_URL;#configuring-the-kernel'>Configuring the Kernel</ulink>"</para></listitem>
|
||||
</itemizedlist>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<para>
|
||||
For general information on the Yocto Project, visit the website at
|
||||
<ulink url='&YOCTO_HOME_URL;'></ulink>.
|
||||
</para>
|
||||
|
|
|
@ -10,11 +10,11 @@
|
|||
<section id='actions-org'>
|
||||
<title>Introduction</title>
|
||||
<para>
|
||||
This chapter describes how to accomplish tasks involving a kernel's tree structure.
|
||||
The information is designed to help the developer that wants to modify the Yocto
|
||||
This chapter describes how to accomplish tasks involving a kernel's tree structure.
|
||||
The information is designed to help the developer that wants to modify the Yocto
|
||||
Project kernel and contribute changes upstream to the Yocto Project.
|
||||
The information covers the following:
|
||||
<itemizedlist>
|
||||
<itemizedlist>
|
||||
<listitem><para>Tree construction</para></listitem>
|
||||
<listitem><para>Build strategies</para></listitem>
|
||||
<listitem><para>Workflow examples</para></listitem>
|
||||
|
@ -25,72 +25,72 @@
|
|||
<section id='tree-construction'>
|
||||
<title>Tree Construction</title>
|
||||
<para>
|
||||
This section describes construction of the Yocto Project kernel source repositories
|
||||
This section describes construction of the Yocto Project kernel source repositories
|
||||
as accomplished by the Yocto Project team to create kernel repositories.
|
||||
These kernel repositories are found under the heading "Yocto Linux Kernel" at
|
||||
<ulink url='&YOCTO_GIT_URL;/cgit.cgi'>&YOCTO_GIT_URL;/cgit.cgi</ulink>
|
||||
and can be shipped as part of a Yocto Project release.
|
||||
and can be shipped as part of a Yocto Project release.
|
||||
The team creates these repositories by
|
||||
compiling and executing the set of feature descriptions for every BSP/feature
|
||||
in the product.
|
||||
in the product.
|
||||
Those feature descriptions list all necessary patches,
|
||||
configuration, branching, tagging and feature divisions found in a kernel.
|
||||
Thus, the Yocto Project kernel repository (or tree) is built.
|
||||
</para>
|
||||
<para>
|
||||
The existence of this tree allows you to access and clone a particular
|
||||
The existence of this tree allows you to access and clone a particular
|
||||
Yocto Project kernel repository and use it to build images based on their configurations
|
||||
and features.
|
||||
</para>
|
||||
<para>
|
||||
You can find the files used to describe all the valid features and BSPs
|
||||
in the Yocto Project kernel in any clone of the Yocto Project kernel source repository
|
||||
You can find the files used to describe all the valid features and BSPs
|
||||
in the Yocto Project kernel in any clone of the Yocto Project kernel source repository
|
||||
Git tree.
|
||||
For example, the following command clones the Yocto Project baseline kernel that
|
||||
For example, the following command clones the Yocto Project baseline kernel that
|
||||
branched off of <filename>linux.org</filename> version 3.4:
|
||||
<literallayout class='monospaced'>
|
||||
$ git clone git://git.yoctoproject.org/linux-yocto-3.4
|
||||
</literallayout>
|
||||
For another example of how to set up a local Git repository of the Yocto Project
|
||||
kernel files, see the
|
||||
"<ulink url='&YOCTO_DOCS_DEV_URL;#local-kernel-files'>Yocto Project Kernel</ulink>" bulleted
|
||||
kernel files, see the
|
||||
"<ulink url='&YOCTO_DOCS_DEV_URL;#local-kernel-files'>Yocto Project Kernel</ulink>" bulleted
|
||||
item in the Yocto Project Development Manual.
|
||||
</para>
|
||||
<para>
|
||||
Once you have cloned the kernel Git repository on your local machine, you can
|
||||
<para>
|
||||
Once you have cloned the kernel Git repository on your local machine, you can
|
||||
switch to the <filename>meta</filename> branch within the repository.
|
||||
Here is an example that assumes the local Git repository for the kernel is in
|
||||
Here is an example that assumes the local Git repository for the kernel is in
|
||||
a top-level directory named <filename>linux-yocto-3.4</filename>:
|
||||
<literallayout class='monospaced'>
|
||||
$ cd ~/linux-yocto-3.4
|
||||
$ git checkout -b meta origin/meta
|
||||
</literallayout>
|
||||
Once you have checked out and switched to the <filename>meta</filename> branch,
|
||||
you can see a snapshot of all the kernel configuration and feature descriptions that are
|
||||
you can see a snapshot of all the kernel configuration and feature descriptions that are
|
||||
used to build that particular kernel repository.
|
||||
These descriptions are in the form of <filename>.scc</filename> files.
|
||||
These descriptions are in the form of <filename>.scc</filename> files.
|
||||
</para>
|
||||
<para>
|
||||
You should realize, however, that browsing your local kernel repository
|
||||
for feature descriptions and patches is not an effective way to determine what is in a
|
||||
particular kernel branch.
|
||||
particular kernel branch.
|
||||
Instead, you should use Git directly to discover the changes in a branch.
|
||||
Using Git is an efficient and flexible way to inspect changes to the kernel.
|
||||
Using Git is an efficient and flexible way to inspect changes to the kernel.
|
||||
For examples showing how to use Git to inspect kernel commits, see the following sections
|
||||
in this chapter.
|
||||
<note>
|
||||
Ground up reconstruction of the complete kernel tree is an action only taken by the
|
||||
Yocto Project team during an active development cycle.
|
||||
When you create a clone of the kernel Git repository, you are simply making it
|
||||
Ground up reconstruction of the complete kernel tree is an action only taken by the
|
||||
Yocto Project team during an active development cycle.
|
||||
When you create a clone of the kernel Git repository, you are simply making it
|
||||
efficiently available for building and development.
|
||||
</note>
|
||||
</para>
|
||||
<para>
|
||||
The following steps describe what happens when the Yocto Project Team constructs
|
||||
the Yocto Project kernel source Git repository (or tree) found at
|
||||
<ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink> given the
|
||||
introduction of a new top-level kernel feature or BSP.
|
||||
These are the actions that effectively create the tree
|
||||
the Yocto Project kernel source Git repository (or tree) found at
|
||||
<ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink> given the
|
||||
introduction of a new top-level kernel feature or BSP.
|
||||
These are the actions that effectively create the tree
|
||||
that includes the new feature, patch or BSP:
|
||||
<orderedlist>
|
||||
<listitem><para>A top-level kernel feature is passed to the kernel build subsystem.
|
||||
|
@ -103,7 +103,7 @@
|
|||
<listitem><para>Areas pointed to by <filename>SRC_URI</filename> statements
|
||||
found in recipes</para></listitem>
|
||||
</itemizedlist>
|
||||
For a typical build, the target of the search is a
|
||||
For a typical build, the target of the search is a
|
||||
feature description in an <filename>.scc</filename> file
|
||||
whose name follows this format:
|
||||
<literallayout class='monospaced'>
|
||||
|
@ -113,19 +113,19 @@
|
|||
<listitem><para>Once located, the feature description is either compiled into a simple script
|
||||
of actions, or into an existing equivalent script that is already part of the
|
||||
shipped kernel.</para></listitem>
|
||||
<listitem><para>Extra features are appended to the top-level feature description.
|
||||
These features can come from the
|
||||
<listitem><para>Extra features are appended to the top-level feature description.
|
||||
These features can come from the
|
||||
<ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_FEATURES'><filename>KERNEL_FEATURES</filename></ulink>
|
||||
variable in recipes.</para></listitem>
|
||||
<listitem><para>Each extra feature is located, compiled and appended to the script
|
||||
<listitem><para>Each extra feature is located, compiled and appended to the script
|
||||
as described in step three.</para></listitem>
|
||||
<listitem><para>The script is executed to produce a series of <filename>meta-*</filename>
|
||||
directories.
|
||||
directories.
|
||||
These directories are descriptions of all the branches, tags, patches and configurations that
|
||||
need to be applied to the base Git repository to completely create the
|
||||
source (build) branch for the new BSP or feature.</para></listitem>
|
||||
<listitem><para>The base repository is cloned, and the actions
|
||||
listed in the <filename>meta-*</filename> directories are applied to the
|
||||
listed in the <filename>meta-*</filename> directories are applied to the
|
||||
tree.</para></listitem>
|
||||
<listitem><para>The Git repository is left with the desired branch checked out and any
|
||||
required branching, patching and tagging has been performed.</para></listitem>
|
||||
|
@ -133,17 +133,17 @@
|
|||
</para>
|
||||
<para>
|
||||
The kernel tree is now ready for developer consumption to be locally cloned,
|
||||
configured, and built into a Yocto Project kernel specific to some target hardware.
|
||||
<note><para>The generated <filename>meta-*</filename> directories add to the kernel
|
||||
as shipped with the Yocto Project release.
|
||||
Any add-ons and configuration data are applied to the end of an existing branch.
|
||||
The full repository generation that is found in the
|
||||
configured, and built into a Yocto Project kernel specific to some target hardware.
|
||||
<note><para>The generated <filename>meta-*</filename> directories add to the kernel
|
||||
as shipped with the Yocto Project release.
|
||||
Any add-ons and configuration data are applied to the end of an existing branch.
|
||||
The full repository generation that is found in the
|
||||
official Yocto Project kernel repositories at
|
||||
<ulink url='&YOCTO_GIT_URL;/cgit.cgi'>http://git.yoctoproject.org/cgit.cgi</ulink>
|
||||
is the combination of all supported boards and configurations.</para>
|
||||
<para>The technique the Yocto Project team uses is flexible and allows for seamless
|
||||
blending of an immutable history with additional patches specific to a
|
||||
deployment.
|
||||
<para>The technique the Yocto Project team uses is flexible and allows for seamless
|
||||
blending of an immutable history with additional patches specific to a
|
||||
deployment.
|
||||
Any additions to the kernel become an integrated part of the branches.</para>
|
||||
</note>
|
||||
</para>
|
||||
|
@ -152,15 +152,15 @@
|
|||
<section id='build-strategy'>
|
||||
<title>Build Strategy</title>
|
||||
<para>
|
||||
Once a local Git repository of the Yocto Project kernel exists on a development system,
|
||||
Once a local Git repository of the Yocto Project kernel exists on a development system,
|
||||
you can consider the compilation phase of kernel development - building a kernel image.
|
||||
Some prerequisites exist that are validated by the build process before compilation
|
||||
starts:
|
||||
</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem><para>The
|
||||
<ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> points
|
||||
<listitem><para>The
|
||||
<ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> points
|
||||
to the kernel Git repository.</para></listitem>
|
||||
<listitem><para>A BSP build branch exists.
|
||||
This branch has the following form:
|
||||
|
@ -171,22 +171,22 @@
|
|||
|
||||
<para>
|
||||
The OpenEmbedded build system makes sure these conditions exist before attempting compilation.
|
||||
Other means, however, do exist, such as as bootstrapping a BSP, see
|
||||
Other means, however, do exist, such as as bootstrapping a BSP, see
|
||||
the "<link linkend='workflow-examples'>Workflow Examples</link>".
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Before building a kernel, the build process verifies the tree
|
||||
Before building a kernel, the build process verifies the tree
|
||||
and configures the kernel by processing all of the
|
||||
configuration "fragments" specified by feature descriptions in the <filename>.scc</filename>
|
||||
files.
|
||||
files.
|
||||
As the features are compiled, associated kernel configuration fragments are noted
|
||||
and recorded in the <filename>meta-*</filename> series of directories in their compilation order.
|
||||
and recorded in the <filename>meta-*</filename> series of directories in their compilation order.
|
||||
The fragments are migrated, pre-processed and passed to the Linux Kernel
|
||||
Configuration subsystem (<filename>lkc</filename>) as raw input in the form
|
||||
Configuration subsystem (<filename>lkc</filename>) as raw input in the form
|
||||
of a <filename>.config</filename> file.
|
||||
The <filename>lkc</filename> uses its own internal dependency constraints to do the final
|
||||
processing of that information and generates the final <filename>.config</filename> file
|
||||
processing of that information and generates the final <filename>.config</filename> file
|
||||
that is used during compilation.
|
||||
</para>
|
||||
|
||||
|
@ -197,9 +197,9 @@
|
|||
|
||||
<para>
|
||||
The other thing that you notice once you configure a kernel is that
|
||||
the build process generates a build tree that is separate from your kernel's local Git
|
||||
the build process generates a build tree that is separate from your kernel's local Git
|
||||
source repository tree.
|
||||
This build tree has a name that uses the following form, where
|
||||
This build tree has a name that uses the following form, where
|
||||
<filename>${MACHINE}</filename> is the metadata name of the machine (BSP) and "kernel_type" is one
|
||||
of the Yocto Project supported kernel types (e.g. "standard"):
|
||||
<literallayout class='monospaced'>
|
||||
|
@ -208,13 +208,13 @@
|
|||
</para>
|
||||
|
||||
<para>
|
||||
The existing support in the <filename>kernel.org</filename> tree achieves this
|
||||
The existing support in the <filename>kernel.org</filename> tree achieves this
|
||||
default functionality.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
This behavior means that all the generated files for a particular machine or BSP are now in
|
||||
the build tree directory.
|
||||
This behavior means that all the generated files for a particular machine or BSP are now in
|
||||
the build tree directory.
|
||||
The files include the final <filename>.config</filename> file, all the <filename>.o</filename>
|
||||
files, the <filename>.a</filename> files, and so forth.
|
||||
Since each machine or BSP has its own separate build directory in its own separate branch
|
||||
|
@ -229,18 +229,18 @@
|
|||
As previously noted, the Yocto Project kernel has built-in Git integration.
|
||||
However, these utilities are not the only way to work with the kernel repository.
|
||||
The Yocto Project has not made changes to Git or to other tools that
|
||||
would invalidate alternate workflows.
|
||||
Additionally, the way the kernel repository is constructed results in using
|
||||
only core Git functionality, thus allowing any number of tools or front ends to use the
|
||||
would invalidate alternate workflows.
|
||||
Additionally, the way the kernel repository is constructed results in using
|
||||
only core Git functionality, thus allowing any number of tools or front ends to use the
|
||||
resulting tree.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
This section contains several workflow examples.
|
||||
Many of the examples use Git commands.
|
||||
You can find Git documentation at
|
||||
Many of the examples use Git commands.
|
||||
You can find Git documentation at
|
||||
<ulink url='http://git-scm.com/documentation'></ulink>.
|
||||
You can find a simple overview of using Git with the Yocto Project in the
|
||||
You can find a simple overview of using Git with the Yocto Project in the
|
||||
"<ulink url='&YOCTO_DOCS_DEV_URL;#git'>Git</ulink>"
|
||||
section of the Yocto Project Development Manual.
|
||||
</para>
|
||||
|
@ -249,25 +249,25 @@
|
|||
<title>Change Inspection: Kernel Changes/Commits</title>
|
||||
|
||||
<para>
|
||||
A common question when working with a BSP or kernel is:
|
||||
A common question when working with a BSP or kernel is:
|
||||
"What changes have been applied to this tree?"
|
||||
</para>
|
||||
|
||||
<para>
|
||||
In projects that have a collection of directories that
|
||||
contain patches to the kernel, it is possible to inspect or "grep" the contents
|
||||
of the directories to get a general feel for the changes.
|
||||
contain patches to the kernel, it is possible to inspect or "grep" the contents
|
||||
of the directories to get a general feel for the changes.
|
||||
This sort of patch inspection is not an efficient way to determine what has been done to the
|
||||
kernel.
|
||||
The reason it is inefficient is because there are many optional patches that are
|
||||
The reason it is inefficient is because there are many optional patches that are
|
||||
selected based on the kernel type and the feature description.
|
||||
Additionally, patches could exist in directories that are not included in the search.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
A more efficient way to determine what has changed in the kernel is to use
|
||||
Git and inspect or search the kernel tree.
|
||||
This method gives you a full view of not only the source code modifications,
|
||||
Git and inspect or search the kernel tree.
|
||||
This method gives you a full view of not only the source code modifications,
|
||||
but also provides the reasons for the changes.
|
||||
</para>
|
||||
|
||||
|
@ -277,11 +277,11 @@
|
|||
<para>
|
||||
Following are a few examples that show how to use Git to examine changes.
|
||||
Because the Yocto Project Git repository does not break existing Git
|
||||
functionality and because there exists many permutations of these types of
|
||||
functionality and because there exists many permutations of these types of
|
||||
commands, there are many more methods to discover changes.
|
||||
<note>
|
||||
Unless you provide a commit range
|
||||
(<kernel-type>..<bsp>-<kernel-type>), <filename>kernel.org</filename> history
|
||||
Unless you provide a commit range
|
||||
(<kernel-type>..<bsp>-<kernel-type>), <filename>kernel.org</filename> history
|
||||
is blended with Yocto Project changes.
|
||||
</note>
|
||||
<literallayout class='monospaced'>
|
||||
|
@ -301,27 +301,27 @@
|
|||
|
||||
# determine the change history of a particular file
|
||||
> git whatchanged <path to file>
|
||||
|
||||
|
||||
# determine the commits which touch each line in a file
|
||||
> git blame <path to file>
|
||||
</literallayout>
|
||||
</para>
|
||||
</section>
|
||||
|
||||
|
||||
<section id='show-a-particular-feature-or-branch-change'>
|
||||
<title>Show a Particular Feature or Branch Change</title>
|
||||
|
||||
<para>
|
||||
Developers use tags in the Yocto Project kernel tree to divide changes for significant
|
||||
features or branches.
|
||||
Once you know a particular tag, you can use Git commands
|
||||
Developers use tags in the Yocto Project kernel tree to divide changes for significant
|
||||
features or branches.
|
||||
Once you know a particular tag, you can use Git commands
|
||||
to show changes associated with the tag and find the branches that contain
|
||||
the feature.
|
||||
the feature.
|
||||
<note>
|
||||
Because BSP branch, <filename>kernel.org</filename>, and feature tags are all
|
||||
Because BSP branch, <filename>kernel.org</filename>, and feature tags are all
|
||||
present, there could be many tags.
|
||||
</note>
|
||||
The <filename>git show <tag></filename> command shows changes that are tagged by
|
||||
The <filename>git show <tag></filename> command shows changes that are tagged by
|
||||
a feature.
|
||||
Here is an example that shows changes tagged by the <filename>systemtap</filename>
|
||||
feature:
|
||||
|
@ -339,7 +339,7 @@
|
|||
|
||||
<para>
|
||||
You can use many other comparisons to isolate BSP and kernel changes.
|
||||
For example, you can compare against <filename>kernel.org</filename> tags
|
||||
For example, you can compare against <filename>kernel.org</filename> tags
|
||||
such as the <filename>v3.4</filename> tag.
|
||||
</para>
|
||||
</section>
|
||||
|
@ -350,29 +350,29 @@
|
|||
|
||||
<para>
|
||||
Another common operation is to build a BSP supplied by the Yocto Project, make some
|
||||
changes, rebuild, and then test.
|
||||
changes, rebuild, and then test.
|
||||
Those local changes often need to be exported, shared or otherwise maintained.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Since the Yocto Project kernel source tree is backed by Git, this activity is
|
||||
much easier as compared to with previous releases.
|
||||
Because Git tracks file modifications, additions and deletions, it is easy
|
||||
much easier as compared to with previous releases.
|
||||
Because Git tracks file modifications, additions and deletions, it is easy
|
||||
to modify the code and later realize that you need to save the changes.
|
||||
It is also easy to determine what has changed.
|
||||
It is also easy to determine what has changed.
|
||||
This method also provides many tools to commit, undo and export those modifications.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
This section and its sub-sections, describe general application of Git's
|
||||
<filename>push</filename> and <filename>pull</filename> commands, which are used to
|
||||
get your changes upstream or source your code from an upstream repository.
|
||||
The Yocto Project provides scripts that help you work in a collaborative development
|
||||
environment.
|
||||
This section and its sub-sections, describe general application of Git's
|
||||
<filename>push</filename> and <filename>pull</filename> commands, which are used to
|
||||
get your changes upstream or source your code from an upstream repository.
|
||||
The Yocto Project provides scripts that help you work in a collaborative development
|
||||
environment.
|
||||
For information on these scripts, see the
|
||||
"<ulink url='&YOCTO_DOCS_DEV_URL;#pushing-a-change-upstream'>Using Scripts to Push a Change
|
||||
Upstream and Request a Pull</ulink>" and
|
||||
"<ulink url='&YOCTO_DOCS_DEV_URL;#submitting-a-patch'>Using Email to Submit a Patch</ulink>"
|
||||
"<ulink url='&YOCTO_DOCS_DEV_URL;#pushing-a-change-upstream'>Using Scripts to Push a Change
|
||||
Upstream and Request a Pull</ulink>" and
|
||||
"<ulink url='&YOCTO_DOCS_DEV_URL;#submitting-a-patch'>Using Email to Submit a Patch</ulink>"
|
||||
sections in the Yocto Project Development Manual.
|
||||
</para>
|
||||
|
||||
|
@ -380,7 +380,7 @@
|
|||
There are many ways to save kernel modifications.
|
||||
The technique employed
|
||||
depends on the destination for the patches:
|
||||
|
||||
|
||||
<itemizedlist>
|
||||
<listitem><para>Bulk storage</para></listitem>
|
||||
<listitem><para>Internal sharing either through patches or by using Git</para></listitem>
|
||||
|
@ -391,7 +391,7 @@
|
|||
</para>
|
||||
|
||||
<para>
|
||||
Because of the following list of issues, the destination of the patches also influences
|
||||
Because of the following list of issues, the destination of the patches also influences
|
||||
the method for gathering them:
|
||||
|
||||
<itemizedlist>
|
||||
|
@ -405,24 +405,24 @@
|
|||
<title>Bulk Export</title>
|
||||
|
||||
<para>
|
||||
This section describes how you can "bulk" export changes that have not
|
||||
been separated or divided.
|
||||
This situation works well when you are simply storing patches outside of the kernel
|
||||
source repository, either permanently or temporarily, and you are not committing
|
||||
This section describes how you can "bulk" export changes that have not
|
||||
been separated or divided.
|
||||
This situation works well when you are simply storing patches outside of the kernel
|
||||
source repository, either permanently or temporarily, and you are not committing
|
||||
incremental changes during development.
|
||||
<note>
|
||||
This technique is not appropriate for full integration of upstream submission
|
||||
because changes are not properly divided and do not provide an avenue for per-change
|
||||
commit messages.
|
||||
Therefore, this example assumes that changes have not been committed incrementally
|
||||
commit messages.
|
||||
Therefore, this example assumes that changes have not been committed incrementally
|
||||
during development and that you simply must gather and export them.
|
||||
</note>
|
||||
<literallayout class='monospaced'>
|
||||
# bulk export of ALL modifications without separation or division
|
||||
# of the changes
|
||||
# of the changes
|
||||
|
||||
$ git add .
|
||||
$ git commit -s -a -m <msg>
|
||||
$ git commit -s -a -m <msg>
|
||||
or
|
||||
$ git commit -s -a # and interact with $EDITOR
|
||||
</literallayout>
|
||||
|
@ -447,8 +447,8 @@
|
|||
<para>
|
||||
This section describes how to save modifications when you are making incremental
|
||||
commits or practicing planned sharing.
|
||||
The examples in this section assume that you have incrementally committed
|
||||
changes to the tree during development and now need to export them.
|
||||
The examples in this section assume that you have incrementally committed
|
||||
changes to the tree during development and now need to export them.
|
||||
The sections that follow
|
||||
describe how you can export your changes internally through either patches or by
|
||||
using Git commands.
|
||||
|
@ -456,7 +456,7 @@
|
|||
|
||||
<para>
|
||||
During development, the following commands are of interest.
|
||||
For full Git documentation, refer to the Git documentation at
|
||||
For full Git documentation, refer to the Git documentation at
|
||||
<ulink url='http://github.com'></ulink>.
|
||||
|
||||
<literallayout class='monospaced'>
|
||||
|
@ -476,15 +476,15 @@
|
|||
</para>
|
||||
|
||||
<para>
|
||||
Distributed development with Git is possible when you use a universally
|
||||
Distributed development with Git is possible when you use a universally
|
||||
agreed-upon unique commit identifier (set by the creator of the commit) that maps to a
|
||||
specific change set with a specific parent.
|
||||
specific change set with a specific parent.
|
||||
This identifier is created for you when
|
||||
you create a commit, and is re-created when you amend, alter or re-apply
|
||||
a commit.
|
||||
a commit.
|
||||
As an individual in isolation, this is of no interest.
|
||||
However, if you
|
||||
intend to share your tree with normal Git <filename>push</filename> and
|
||||
intend to share your tree with normal Git <filename>push</filename> and
|
||||
<filename>pull</filename> operations for
|
||||
distributed development, you should consider the ramifications of changing a
|
||||
commit that you have already shared with others.
|
||||
|
@ -492,7 +492,7 @@
|
|||
|
||||
<para>
|
||||
Assuming that the changes have not been pushed upstream, or pulled into
|
||||
another repository, you can update both the commit content and commit messages
|
||||
another repository, you can update both the commit content and commit messages
|
||||
associated with development by using the following commands:
|
||||
|
||||
<literallayout class='monospaced'>
|
||||
|
@ -502,7 +502,7 @@
|
|||
</literallayout>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<para>
|
||||
Again, assuming that the changes have not been pushed upstream, and that
|
||||
no pending works-in-progress exist (use <filename>git status</filename> to check), then
|
||||
you can revert (undo) commits by using the following commands:
|
||||
|
@ -521,12 +521,12 @@
|
|||
<para>
|
||||
You can create branches, "cherry-pick" changes, or perform any number of Git
|
||||
operations until the commits are in good order for pushing upstream
|
||||
or for pull requests.
|
||||
After a <filename>push</filename> or <filename>pull</filename> command,
|
||||
or for pull requests.
|
||||
After a <filename>push</filename> or <filename>pull</filename> command,
|
||||
commits are normally considered
|
||||
"permanent" and you should not modify them.
|
||||
If the commits need to be changed, you can incrementally do so with new commits.
|
||||
These practices follow standard Git workflow and the <filename>kernel.org</filename> best
|
||||
These practices follow standard Git workflow and the <filename>kernel.org</filename> best
|
||||
practices, which is recommended.
|
||||
<note>
|
||||
It is recommended to tag or branch before adding changes to a Yocto Project
|
||||
|
@ -535,26 +535,26 @@
|
|||
reference point to facilitate locating and exporting local changes.
|
||||
</note>
|
||||
</para>
|
||||
|
||||
|
||||
<section id='export-internally-via-patches'>
|
||||
<title>Exporting Changes Internally by Using Patches</title>
|
||||
|
||||
<para>
|
||||
This section describes how you can extract committed changes from a working directory
|
||||
by exporting them as patches.
|
||||
Once the changes have been extracted, you can use the patches for upstream submission,
|
||||
Once the changes have been extracted, you can use the patches for upstream submission,
|
||||
place them in a Yocto Project template for automatic kernel patching,
|
||||
or apply them in many other common uses.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
This example shows how to create a directory with sequentially numbered patches.
|
||||
Once the directory is created, you can apply it to a repository using the
|
||||
<filename>git am</filename> command to reproduce the original commit and all
|
||||
Once the directory is created, you can apply it to a repository using the
|
||||
<filename>git am</filename> command to reproduce the original commit and all
|
||||
the related information such as author, date, commit log, and so forth.
|
||||
<note>
|
||||
The new commit identifiers (ID) will be generated upon re-application.
|
||||
This action reflects that the commit is now applied to an underlying commit
|
||||
The new commit identifiers (ID) will be generated upon re-application.
|
||||
This action reflects that the commit is now applied to an underlying commit
|
||||
with a different ID.
|
||||
</note>
|
||||
<literallayout class='monospaced'>
|
||||
|
@ -581,19 +581,19 @@
|
|||
$ git format-patch -o <save dir> <commit id>
|
||||
$ git format-patch -o <save dir> <rev-list>
|
||||
</literallayout>
|
||||
</para>
|
||||
</section>
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section id='export-internally-via-git'>
|
||||
<title>Exporting Changes Internally by Using Git</title>
|
||||
|
||||
<para>
|
||||
This section describes how you can export changes from a working directory
|
||||
This section describes how you can export changes from a working directory
|
||||
by pushing the changes into a master repository or by making a pull request.
|
||||
Once you have pushed the changes to the master repository, you can then
|
||||
Once you have pushed the changes to the master repository, you can then
|
||||
pull those same changes into a new kernel build at a later time.
|
||||
</para>
|
||||
|
||||
|
||||
<para>
|
||||
Use this command form to push the changes:
|
||||
<literallayout class='monospaced'>
|
||||
|
@ -604,7 +604,7 @@
|
|||
|
||||
<para>
|
||||
For example, the following command pushes the changes from your local branch
|
||||
<filename>yocto/standard/common-pc/base</filename> to the remote branch with the same name
|
||||
<filename>yocto/standard/common-pc/base</filename> to the remote branch with the same name
|
||||
in the master repository <filename>//git.mycompany.com/pub/git/kernel-3.4</filename>.
|
||||
<literallayout class='monospaced'>
|
||||
$ git push ssh://git.mycompany.com/pub/git/kernel-3.4 \
|
||||
|
@ -613,7 +613,7 @@
|
|||
</para>
|
||||
|
||||
<para>
|
||||
A pull request entails using the <filename>git request-pull</filename> command to compose
|
||||
A pull request entails using the <filename>git request-pull</filename> command to compose
|
||||
an email to the
|
||||
maintainer requesting that a branch be pulled into the master repository, see
|
||||
<ulink url='http://github.com/guides/pull-requests'></ulink> for an example.
|
||||
|
@ -622,7 +622,7 @@
|
|||
changes, but are not covered in this document.
|
||||
</note>
|
||||
</para>
|
||||
</section>
|
||||
</section>
|
||||
</section>
|
||||
|
||||
<section id='export-for-external-upstream-submission'>
|
||||
|
@ -636,12 +636,12 @@
|
|||
This method allows easy review and integration of the changes.
|
||||
<note>
|
||||
Before sending patches for review be sure you understand the
|
||||
community standards for submitting and documenting changes and follow their best practices.
|
||||
community standards for submitting and documenting changes and follow their best practices.
|
||||
For example, kernel patches should follow standards such as:
|
||||
<itemizedlist>
|
||||
<listitem><para>
|
||||
<ulink url='http://linux.yyz.us/patch-format.html'></ulink></para></listitem>
|
||||
<listitem><para>Documentation/SubmittingPatches (in any linux
|
||||
<listitem><para>Documentation/SubmittingPatches (in any linux
|
||||
kernel source tree)</para></listitem>
|
||||
</itemizedlist>
|
||||
</note>
|
||||
|
@ -651,30 +651,30 @@
|
|||
The messages used to commit changes are a large part of these standards.
|
||||
Consequently, be sure that the headers for each commit have the required information.
|
||||
For information on how to follow the Yocto Project commit message standards, see the
|
||||
"<ulink url='&YOCTO_DOCS_DEV_URL;#how-to-submit-a-change'>How to Submit a
|
||||
"<ulink url='&YOCTO_DOCS_DEV_URL;#how-to-submit-a-change'>How to Submit a
|
||||
Change</ulink>" section in the Yocto Project Development Manual.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
If the initial commits were not properly documented or do not meet those standards,
|
||||
you can re-base by using the <filename>git rebase -i</filename> command to
|
||||
you can re-base by using the <filename>git rebase -i</filename> command to
|
||||
manipulate the commits and
|
||||
get them into the required format.
|
||||
get them into the required format.
|
||||
Other techniques such as branching and cherry-picking commits are also viable options.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Once you complete the commits, you can generate the email that sends the patches
|
||||
to the maintainer(s) or lists that review and integrate changes.
|
||||
The command <filename>git send-email</filename> is commonly used to ensure
|
||||
that patches are properly
|
||||
Once you complete the commits, you can generate the email that sends the patches
|
||||
to the maintainer(s) or lists that review and integrate changes.
|
||||
The command <filename>git send-email</filename> is commonly used to ensure
|
||||
that patches are properly
|
||||
formatted for easy application and avoid mailer-induced patch damage.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The following is an example of dumping patches for external submission:
|
||||
<literallayout class='monospaced'>
|
||||
# dump the last 4 commits
|
||||
# dump the last 4 commits
|
||||
$ git format-patch --thread -n -o ~/rr/ HEAD^^^^
|
||||
$ git send-email --compose --subject '[RFC 0/N] <patch series summary>' \
|
||||
--to foo@yoctoproject.org --to bar@yoctoproject.org \
|
||||
|
@ -690,17 +690,17 @@
|
|||
|
||||
<para>
|
||||
When you want to export changes for import into another
|
||||
Source Code Manager (SCM), you can use any of the previously discussed
|
||||
Source Code Manager (SCM), you can use any of the previously discussed
|
||||
techniques.
|
||||
However, if the patches are manually applied to a secondary tree and then
|
||||
that tree is checked into the SCM, you can lose change information such as
|
||||
However, if the patches are manually applied to a secondary tree and then
|
||||
that tree is checked into the SCM, you can lose change information such as
|
||||
commit logs.
|
||||
This process is not recommended.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Many SCMs can directly import Git commits, or can translate Git patches so that
|
||||
information is not lost.
|
||||
information is not lost.
|
||||
Those facilities are SCM-dependent and you should use them whenever possible.
|
||||
</para>
|
||||
</section>
|
||||
|
@ -710,15 +710,15 @@
|
|||
<title>Working with the Yocto Project Kernel in Another SCM</title>
|
||||
|
||||
<para>
|
||||
This section describes kernel development in an SCM other than Git,
|
||||
This section describes kernel development in an SCM other than Git,
|
||||
which is not the same as exporting changes to another SCM described earlier.
|
||||
For this scenario, you use the OpenEmbedded build system to
|
||||
For this scenario, you use the OpenEmbedded build system to
|
||||
develop the kernel in a different SCM.
|
||||
The following must be true for you to accomplish this:
|
||||
<itemizedlist>
|
||||
<listitem><para>The delivered Yocto Project kernel must be exported into the second
|
||||
SCM.</para></listitem>
|
||||
<listitem><para>Development must be exported from that secondary SCM into a
|
||||
<listitem><para>Development must be exported from that secondary SCM into a
|
||||
format that can be used by the OpenEmbedded build system.</para></listitem>
|
||||
</itemizedlist>
|
||||
</para>
|
||||
|
@ -728,7 +728,7 @@
|
|||
|
||||
<para>
|
||||
Depending on the SCM, it might be possible to export the entire Yocto Project
|
||||
kernel Git repository, branches and all, into a new environment.
|
||||
kernel Git repository, branches and all, into a new environment.
|
||||
This method is preferred because it has the most flexibility and potential to maintain
|
||||
the meta data associated with each commit.
|
||||
</para>
|
||||
|
@ -750,11 +750,11 @@
|
|||
</para>
|
||||
|
||||
<para>
|
||||
You could now relocate the CVS repository and use it in a centralized manner.
|
||||
You could now relocate the CVS repository and use it in a centralized manner.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The following commands illustrate how you can condense and merge two BSPs into a
|
||||
The following commands illustrate how you can condense and merge two BSPs into a
|
||||
second SCM:
|
||||
<literallayout class='monospaced'>
|
||||
$ git checkout yocto/standard/common-pc/base
|
||||
|
@ -768,7 +768,7 @@
|
|||
|
||||
<section id='importing-changes-for-build'>
|
||||
<title>Importing Changes for the Build</title>
|
||||
|
||||
|
||||
<para>
|
||||
Once development has reached a suitable point in the second development
|
||||
environment, you need to export the changes as patches.
|
||||
|
@ -782,12 +782,12 @@
|
|||
<title>Creating a BSP Based on an Existing Similar BSP</title>
|
||||
|
||||
<para>
|
||||
This section overviews the process of creating a BSP based on an
|
||||
This section overviews the process of creating a BSP based on an
|
||||
existing similar BSP.
|
||||
The information is introductory in nature and does not provide step-by-step examples.
|
||||
The information is introductory in nature and does not provide step-by-step examples.
|
||||
For detailed information on how to create a new BSP, see
|
||||
the "<ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-yocto-bsp-script'>Creating a New BSP Layer Using the yocto-bsp Script</ulink>" section in the
|
||||
Yocto Project Board Support Package (BSP) Developer's Guide, or see the
|
||||
the "<ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-yocto-bsp-script'>Creating a New BSP Layer Using the yocto-bsp Script</ulink>" section in the
|
||||
Yocto Project Board Support Package (BSP) Developer's Guide, or see the
|
||||
<ulink url='&YOCTO_WIKI_URL;/wiki/Transcript:_creating_one_generic_Atom_BSP_from_another'>Transcript:_creating_one_generic_Atom_BSP_from_another</ulink>
|
||||
wiki page.
|
||||
</para>
|
||||
|
@ -796,42 +796,42 @@
|
|||
The basic steps you need to follow are:
|
||||
<orderedlist>
|
||||
<listitem><para><emphasis>Make sure you have set up a local Source Directory:</emphasis>
|
||||
You must create a local
|
||||
<ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
|
||||
by either creating a Git repository (recommended) or
|
||||
You must create a local
|
||||
<ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
|
||||
by either creating a Git repository (recommended) or
|
||||
extracting a Yocto Project release tarball.</para></listitem>
|
||||
<listitem><para><emphasis>Choose an existing BSP available with the Yocto Project:</emphasis>
|
||||
Try to map your board features as closely to the features of a BSP that is
|
||||
already supported and exists in the Yocto Project.
|
||||
Starting with something as close as possible to your board makes developing
|
||||
your BSP easier.
|
||||
You can find all the BSPs that are supported and ship with the Yocto Project
|
||||
on the Yocto Project's Download page at
|
||||
Try to map your board features as closely to the features of a BSP that is
|
||||
already supported and exists in the Yocto Project.
|
||||
Starting with something as close as possible to your board makes developing
|
||||
your BSP easier.
|
||||
You can find all the BSPs that are supported and ship with the Yocto Project
|
||||
on the Yocto Project's Download page at
|
||||
<ulink url='&YOCTO_HOME_URL;/download'></ulink>.</para></listitem>
|
||||
<listitem><para><emphasis>Be sure you have the Base BSP:</emphasis>
|
||||
You need to either have a local Git repository of the base BSP set up or
|
||||
You need to either have a local Git repository of the base BSP set up or
|
||||
have downloaded and extracted the files from a release BSP tarball.
|
||||
Either method gives you access to the BSP source files.</para></listitem>
|
||||
<listitem><para><emphasis>Make a copy of the existing BSP, thus isolating your new
|
||||
<listitem><para><emphasis>Make a copy of the existing BSP, thus isolating your new
|
||||
BSP work:</emphasis>
|
||||
Copying the existing BSP file structure gives you a new area in which to work.</para></listitem>
|
||||
<listitem><para><emphasis>Make configuration and recipe changes to your new BSP:</emphasis>
|
||||
Configuration changes involve the files in the BSP's <filename>conf</filename>
|
||||
directory.
|
||||
Changes include creating a machine-specific configuration file and editing the
|
||||
<filename>layer.conf</filename> file.
|
||||
directory.
|
||||
Changes include creating a machine-specific configuration file and editing the
|
||||
<filename>layer.conf</filename> file.
|
||||
The configuration changes identify the kernel you will be using.
|
||||
Recipe changes include removing, modifying, or adding new recipe files that
|
||||
Recipe changes include removing, modifying, or adding new recipe files that
|
||||
instruct the build process on what features to include in the image.</para></listitem>
|
||||
<listitem><para><emphasis>Prepare for the build:</emphasis>
|
||||
Before you actually initiate the build, you need to set up the build environment
|
||||
by sourcing the environment initialization script.
|
||||
After setting up the environment, you need to make some build configuration
|
||||
by sourcing the environment initialization script.
|
||||
After setting up the environment, you need to make some build configuration
|
||||
changes to the <filename>local.conf</filename> and <filename>bblayers.conf</filename>
|
||||
files.</para></listitem>
|
||||
<listitem><para><emphasis>Build the image:</emphasis>
|
||||
The OpenEmbedded build system uses BitBake to create the image.
|
||||
You need to decide on the type of image you are going to build (e.g. minimal, base,
|
||||
The OpenEmbedded build system uses BitBake to create the image.
|
||||
You need to decide on the type of image you are going to build (e.g. minimal, base,
|
||||
core, sato, and so forth) and then start the build using the <filename>bitbake</filename>
|
||||
command.</para></listitem>
|
||||
</orderedlist>
|
||||
|
@ -851,8 +851,8 @@
|
|||
</para>
|
||||
|
||||
<para>
|
||||
You can use the above Git command to report modified, removed, or added files.
|
||||
You should commit those changes to the tree regardless of whether they will be saved,
|
||||
You can use the above Git command to report modified, removed, or added files.
|
||||
You should commit those changes to the tree regardless of whether they will be saved,
|
||||
exported, or used.
|
||||
Once you commit the changes you need to rebuild the kernel.
|
||||
</para>
|
||||
|
|
|
@ -2,7 +2,7 @@
|
|||
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
|
||||
[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
|
||||
|
||||
<book id='kernel-manual' lang='en'
|
||||
<book id='kernel-manual' lang='en'
|
||||
xmlns:xi="http://www.w3.org/2003/XInclude"
|
||||
xmlns="http://docbook.org/ns/docbook"
|
||||
>
|
||||
|
@ -10,13 +10,13 @@
|
|||
|
||||
<mediaobject>
|
||||
<imageobject>
|
||||
<imagedata fileref='figures/kernel-title.png'
|
||||
format='SVG'
|
||||
<imagedata fileref='figures/kernel-title.png'
|
||||
format='SVG'
|
||||
align='left' scalefit='1' width='100%'/>
|
||||
</imageobject>
|
||||
</imageobject>
|
||||
</mediaobject>
|
||||
|
||||
<title></title>
|
||||
<title></title>
|
||||
|
||||
<authorgroup>
|
||||
<author>
|
||||
|
@ -73,7 +73,7 @@
|
|||
|
||||
<legalnotice>
|
||||
<para>
|
||||
Permission is granted to copy, distribute and/or modify this document under
|
||||
Permission is granted to copy, distribute and/or modify this document under
|
||||
the terms of the <ulink type="http" url="http://creativecommons.org/licenses/by-sa/2.0/uk/">Creative Commons Attribution-Share Alike 2.0 UK: England & Wales</ulink> as published by Creative Commons.
|
||||
</para>
|
||||
<note>
|
||||
|
@ -99,6 +99,6 @@
|
|||
-->
|
||||
|
||||
</book>
|
||||
<!--
|
||||
vim: expandtab tw=80 ts=4
|
||||
<!--
|
||||
vim: expandtab tw=80 ts=4
|
||||
-->
|
||||
|
|
Loading…
Reference in New Issue