From 7eccfa6849a3ee870ceb59a28f590f6cfcb305fb Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Wed, 9 Jan 2013 17:26:01 -0800 Subject: kernel-dev: Created super section for Branches. 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 Signed-off-by: Richard Purdie --- documentation/kernel-dev/kernel-dev-advanced.xml | 218 ++++++++++++----------- 1 file changed, 115 insertions(+), 103 deletions(-) (limited to 'documentation') diff --git a/documentation/kernel-dev/kernel-dev-advanced.xml b/documentation/kernel-dev/kernel-dev-advanced.xml index ff8374c635..d02654f13a 100644 --- a/documentation/kernel-dev/kernel-dev-advanced.xml +++ b/documentation/kernel-dev/kernel-dev-advanced.xml @@ -1373,47 +1373,58 @@ the KTYPE has changed, now set to "tiny". -
- Machine Branches +
+ Working with Branches - The "Using Kernel Metadata in a Recipe" - section introduced the KBRANCH variable, which - defines the source branch to 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: "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. + We need a top-level section here that introduces branches in general. + There is information that can be pulled from the embedded machine + and feature sections to introduce this stuff. + The two subsections should deal with each type of specific branch + that can be used. - - 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 - "Patches" and - "BSP Descriptions" sections. - +
+ Machine Branches - - 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 - KBRANCH to use for this board. - You can do this in the recipe with the - KBRANCH variable: - + + The "Using Kernel Metadata in a Recipe" + section introduced the KBRANCH variable, which + defines the source branch to 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: "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. + + + + 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 + "Patches" and + "BSP Descriptions" sections. + + + + 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 + KBRANCH to use for this board. + You can do this in the recipe with the + KBRANCH variable: + KBRANCH = "mynewbranch" - - or in the BSP description using the "branch" command: - + + or in the BSP description using the "branch" command: + mybsp.scc: define KMACHINE mybsp define KTYPE standard @@ -1423,35 +1434,35 @@ the KTYPE has changed, now set to "tiny". branch mynewbranch include mybsp-hw.scc - - + + - - The approach you take, feature or branch, is entirely up to you - and depends on what works best for your development model. - If you are actively working on board support, you may find that - working within a branch is more practical than trying to continually - reintegrate your patches into a feature. - 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 - encapsulated feature to be appropriate as it does not require the - additional complexity of branching in your Linux kernel sources. - + + The approach you take, feature or branch, is entirely up to you + and depends on what works best for your development model. + If you are actively working on board support, you may find that + working within a branch is more practical than trying to continually + reintegrate your patches into a feature. + 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 + encapsulated feature to be appropriate as it does not require the + additional complexity of branching in your Linux kernel sources. + - - If you are supporting multiple boards and architectures and find - yourself with numerous branches, you might consider using a - hierarchical branching system similar to what the linux-yocto Linux - kernel repositories use: - + + If you are supporting multiple boards and architectures and find + yourself with numerous branches, you might consider using a + hierarchical branching system similar to what the linux-yocto Linux + kernel repositories use: + <common>/<ktype>/<machine> - - + + - - If you had two ktypes, standard and small for instance, and three - machines, your Git tree might look like this: - + + If you had two ktypes, standard and small for instance, and three + machines, your Git tree might look like this: + common/base common/standard/base common/standard/machine_a @@ -1459,27 +1470,27 @@ the KTYPE has changed, now set to "tiny". common/standard/machine_c common/small/base common/small/machine_a - - + + - - This organization can help clarify the relationship of the branches to - each other. - In this case, "common/standard/machine_a" would include everything in - "common/base" and "common/standard/base". - The "standard" and "small" branches add sources specific to those - kernel types that for whatever reason are not appropriate for the - other branches. - The "base" branches are an artifact of the way Git manages - its data internally on the filesystem: it will not allow you to use - "common/standard" and "common/standard/machine_a" because it - would have to create a file and a directory named "standard". - - + + This organization can help clarify the relationship of the branches to + each other. + In this case, "common/standard/machine_a" would include everything in + "common/base" and "common/standard/base". + The "standard" and "small" branches add sources specific to those + kernel types that for whatever reason are not appropriate for the + other branches. + The "base" branches are an artifact of the way Git manages + its data internally on the filesystem: it will not allow you to use + "common/standard" and "common/standard/machine_a" because it + would have to create a file and a directory named "standard". + + - - Original text: - + + Original text: + 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 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 "common/standard" and "common/standard/machine_a" because it would have to create a file and a directory named "standard". - - -
+ + +
-
- Feature Branches +
+ Feature Branches - - 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 regularly updated. - The Yocto Project Linux kernel tools provide for this with - the git merge command. - + + 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 regularly updated. + The Yocto Project Linux kernel tools provide for this with + the git merge command. + - - To merge a feature branch into a BSP, insert the - git merge command after any - branch commands: - + + To merge a feature branch into a BSP, insert the + git merge command after any + branch commands: + mybsp.scc: define KMACHINE mybsp define KTYPE standard @@ -1578,12 +1589,12 @@ Note: The "base" branches are an artifact of the way git manages its data git merge myfeature include mybsp-hw.scc - - + + - - Original text: - + + Original text: + 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 regularly updated. The Yocto Project Linux kernel tools provide for this with @@ -1602,8 +1613,9 @@ mybsp.scc: git merge myfeature include mybsp.scc - - + + +
-- cgit v1.2.3-54-g00ecf