mirrors/poky
1
0
Fork 0
mirror of https://git.yoctoproject.org/poky synced 2026-05-30 00:20:08 +00:00
Code Issues Projects Releases Wiki Activity

kernel-dev: Created super section for Branches.

Browse Source 
The sections for "Machine Branches" and "Feature Branches" really
should be encapsulated within a section on branching.  Much of
the text in the "Machine Branches" section presents the rationale
behind both types of branches.  I have created a larger section
to contain these and will edit the text to fit.

(From yocto-docs rev: c7c67f5867f22ebbbd49cab79bb2d4e52422ecac)

Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
This commit is contained in:
Scott Rifenbark
2013-01-09 17:26:01 -08:00
committed by Richard Purdie
parent f42c87a1ac
commit 7eccfa6849
1 changed files with 115 additions and 103 deletions
Download Patch File Download Diff File Expand all files Collapse all files
documentation/kernel-dev/kernel-dev-advanced.xml
+115 -103
View File
@@ -1373,47 +1373,58 @@ the KTYPE has changed, now set to "tiny".
</section> </section>
</section> </section>
<section id='machine-branches'> <section id='working-with-branches'>
<title>Machine Branches</title> <title>Working with Branches</title>
<para> <para>
The "<link linkend='using-kernel-metadata-in-a-recipe'>Using Kernel Metadata in a Recipe</link>" We need a top-level section here that introduces branches in general.
section introduced the <filename>KBRANCH</filename> variable, which There is information that can be pulled from the embedded machine
defines the source branch to use from the Linux kernel Git repository and feature sections to introduce this stuff.
you are using. The two subsections should deal with each type of specific branch
Many linux-yocto-custom derived recipes will be using Linux kernel that can be used.
sources with only a single branch: "master".
However, when you are working with multiple boards and architectures,
you are likely to run into the situation where a series of patches
are needed for one board to boot.
Sometimes, these patches are works-in-progress or fundamentally wrong,
yet still necessary for specific boards.
In these situations, you most likely do not want to include these
patches in every kernel you build.
You have a couple of options.
</para> </para>
<para> <section id='machine-branches'>
First, you could encapsulate these patches in a feature description <title>Machine Branches</title>
and only include them in the BSP description for the board(s) that
require them.
For more information, see the
"<link linkend='patches'>Patches</link>" and
"<link linkend='bsp-descriptions'>BSP Descriptions</link>" sections.
</para>
<para> <para>
Alternatively, you can create a branch in your Linux kernel sources The "<link linkend='using-kernel-metadata-in-a-recipe'>Using Kernel Metadata in a Recipe</link>"
and apply the patches there. section introduced the <filename>KBRANCH</filename> variable, which
You can then specify this new branch as the defines the source branch to use from the Linux kernel Git repository
<filename>KBRANCH</filename> to use for this board. you are using.
You can do this in the recipe with the Many linux-yocto-custom derived recipes will be using Linux kernel
<filename>KBRANCH</filename> variable: sources with only a single branch: "master".
<literallayout class='monospaced'> However, when you are working with multiple boards and architectures,
you are likely to run into the situation where a series of patches
are needed for one board to boot.
Sometimes, these patches are works-in-progress or fundamentally wrong,
yet still necessary for specific boards.
In these situations, you most likely do not want to include these
patches in every kernel you build.
You have a couple of options.
</para>
<para>
First, you could encapsulate these patches in a feature description
and only include them in the BSP description for the board(s) that
require them.
For more information, see the
"<link linkend='patches'>Patches</link>" and
"<link linkend='bsp-descriptions'>BSP Descriptions</link>" sections.
</para>
<para>
Alternatively, you can create a branch in your Linux kernel sources
and apply the patches there.
You can then specify this new branch as the
<filename>KBRANCH</filename> to use for this board.
You can do this in the recipe with the
<filename>KBRANCH</filename> variable:
<literallayout class='monospaced'>
KBRANCH = "mynewbranch" KBRANCH = "mynewbranch"
</literallayout> </literallayout>
or in the BSP description using the "branch" command: or in the BSP description using the "branch" command:
<literallayout class='monospaced'> <literallayout class='monospaced'>
mybsp.scc: mybsp.scc:
define KMACHINE mybsp define KMACHINE mybsp
define KTYPE standard define KTYPE standard
@@ -1423,35 +1434,35 @@ the KTYPE has changed, now set to "tiny".
branch mynewbranch branch mynewbranch
include mybsp-hw.scc include mybsp-hw.scc
</literallayout> </literallayout>
</para> </para>
<para> <para>
The approach you take, feature or branch, is entirely up to you The approach you take, feature or branch, is entirely up to you
and depends on what works best for your development model. and depends on what works best for your development model.
If you are actively working on board support, you may find that If you are actively working on board support, you may find that
working within a branch is more practical than trying to continually working within a branch is more practical than trying to continually
reintegrate your patches into a feature. reintegrate your patches into a feature.
On the other hand, if you are simply reusing some patches from an On the other hand, if you are simply reusing some patches from an
external tree and are not working on them, you may find the external tree and are not working on them, you may find the
encapsulated feature to be appropriate as it does not require the encapsulated feature to be appropriate as it does not require the
additional complexity of branching in your Linux kernel sources. additional complexity of branching in your Linux kernel sources.
</para> </para>
<para> <para>
If you are supporting multiple boards and architectures and find If you are supporting multiple boards and architectures and find
yourself with numerous branches, you might consider using a yourself with numerous branches, you might consider using a
hierarchical branching system similar to what the linux-yocto Linux hierarchical branching system similar to what the linux-yocto Linux
kernel repositories use: kernel repositories use:
<literallayout class='monospaced'> <literallayout class='monospaced'>
&lt;common&gt;/&lt;ktype&gt;/&lt;machine&gt; &lt;common&gt;/&lt;ktype&gt;/&lt;machine&gt;
</literallayout> </literallayout>
</para> </para>
<para> <para>
If you had two ktypes, standard and small for instance, and three If you had two ktypes, standard and small for instance, and three
machines, your Git tree might look like this: machines, your Git tree might look like this:
<literallayout class='monospaced'> <literallayout class='monospaced'>
common/base common/base
common/standard/base common/standard/base
common/standard/machine_a common/standard/machine_a
@@ -1459,27 +1470,27 @@ the KTYPE has changed, now set to "tiny".
common/standard/machine_c common/standard/machine_c
common/small/base common/small/base
common/small/machine_a common/small/machine_a
</literallayout> </literallayout>
</para> </para>
<para> <para>
This organization can help clarify the relationship of the branches to This organization can help clarify the relationship of the branches to
each other. each other.
In this case, "common/standard/machine_a" would include everything in In this case, "common/standard/machine_a" would include everything in
"common/base" and "common/standard/base". "common/base" and "common/standard/base".
The "standard" and "small" branches add sources specific to those The "standard" and "small" branches add sources specific to those
kernel types that for whatever reason are not appropriate for the kernel types that for whatever reason are not appropriate for the
other branches. other branches.
<note>The "base" branches are an artifact of the way Git manages <note>The "base" branches are an artifact of the way Git manages
its data internally on the filesystem: it will not allow you to use its data internally on the filesystem: it will not allow you to use
"common/standard" and "common/standard/machine_a" because it "common/standard" and "common/standard/machine_a" because it
would have to create a file and a directory named "standard". would have to create a file and a directory named "standard".
</note> </note>
</para> </para>
<para> <para>
Original text: Original text:
<literallayout class='monospaced'> <literallayout class='monospaced'>
Section 3.1 introduced the KBRANCH variable which defines the source branch to Section 3.1 introduced the KBRANCH variable which defines the source branch to
use from the Linux kernel git repository you are using. Many linux-yocto-custom use from the Linux kernel git repository you are using. Many linux-yocto-custom
derived recipes will be using Linux kernel sources with only a single branch: derived recipes will be using Linux kernel sources with only a single branch:
@@ -1548,26 +1559,26 @@ Note: The "base" branches are an artifact of the way git manages its data
internally on the filesystem: it will not allow you to use internally on the filesystem: it will not allow you to use
"common/standard" and "common/standard/machine_a" because it would have to "common/standard" and "common/standard/machine_a" because it would have to
create a file and a directory named "standard". create a file and a directory named "standard".
</literallayout> </literallayout>
</para> </para>
</section> </section>
<section id='feature-branches'> <section id='feature-branches'>
<title>Feature Branches</title> <title>Feature Branches</title>
<para> <para>
During active development a new feature, it can be more efficient During active development a new feature, it can be more efficient
to work with that feature as a branch, rather than as a set of to work with that feature as a branch, rather than as a set of
patches which have to be regularly updated. patches which have to be regularly updated.
The Yocto Project Linux kernel tools provide for this with The Yocto Project Linux kernel tools provide for this with
the <filename>git merge</filename> command. the <filename>git merge</filename> command.
</para> </para>
<para> <para>
To merge a feature branch into a BSP, insert the To merge a feature branch into a BSP, insert the
<filename>git merge</filename> command after any <filename>git merge</filename> command after any
<filename>branch</filename> commands: <filename>branch</filename> commands:
<literallayout class='monospaced'> <literallayout class='monospaced'>
mybsp.scc: mybsp.scc:
define KMACHINE mybsp define KMACHINE mybsp
define KTYPE standard define KTYPE standard
@@ -1578,12 +1589,12 @@ Note: The "base" branches are an artifact of the way git manages its data
git merge myfeature git merge myfeature
include mybsp-hw.scc include mybsp-hw.scc
</literallayout> </literallayout>
</para> </para>
<para> <para>
Original text: Original text:
<literallayout class='monospaced'> <literallayout class='monospaced'>
During active development a new feature, it can be more efficient to work with During active development a new feature, it can be more efficient to work with
that feature as a branch, rather than as a set of patches which have to be that feature as a branch, rather than as a set of patches which have to be
regularly updated. The Yocto Project Linux kernel tools provide for this with regularly updated. The Yocto Project Linux kernel tools provide for this with
@@ -1602,8 +1613,9 @@ mybsp.scc:
git merge myfeature git merge myfeature
include mybsp.scc include mybsp.scc
</literallayout> </literallayout>
</para> </para>
</section>
</section> </section>
<section id='scc-reference'> <section id='scc-reference'>