From c11f65a2901f121a49153ead811fcaaed108ea92 Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Thu, 14 Jun 2012 08:16:33 -0700 Subject: documentation/kernel-manual/kernel-how-to.xml: 1.1.2 variables and updates First pass at implementing the poky.ent variables. Also, made some changes to text. (From yocto-docs rev: de0e74de2b69e4e92b3c1404fef83509a1165e83) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- documentation/kernel-manual/kernel-how-to.xml | 96 +++++++++++++++------------ 1 file changed, 53 insertions(+), 43 deletions(-) diff --git a/documentation/kernel-manual/kernel-how-to.xml b/documentation/kernel-manual/kernel-how-to.xml index 9d15db44ab..0977a09896 100644 --- a/documentation/kernel-manual/kernel-how-to.xml +++ b/documentation/kernel-manual/kernel-how-to.xml @@ -1,5 +1,6 @@ +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" +[ %poky; ] > @@ -10,8 +11,8 @@ Introduction This chapter describes how to accomplish tasks involving the kernel's tree structure. - This 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 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: Tree construction @@ -24,10 +25,11 @@
Tree Construction - This section describes construction of the Yocto Project kernel repositories as accomplished - by the Yocto Project team to create kernel repositories, which are found at - http://git.yoctoproject.org/cgit.cgi, - that can be shipped as part of a Yocto Project release. + This section describes construction of the Yocto Project kernel repositories + as accomplished by the Yocto Project team to create kernel repositories. + These kernel repositories are found at + &YOCTO_GIT_URL;/cgit.cgi + 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. @@ -50,19 +52,25 @@ For another example of how to set up a local Git repository of the Linux Yocto kernel files, see the - "Linux Yocto Kernel" bulleted item in - The Yocto Project Development Manual. + "Linux Yocto Kernel" bulleted item in The Yocto Project Development Manual. - Once the Git repository is set up on your local machine, you can switch to the - meta branch within the repository. - Here, you can see a snapshot of all the kernel configuration and feature descriptions that are - used to build the kernel repository. + Once you have cloned the kernel Git repository on your local machine, you can + switch to the meta branch within the repository. + Here is an example that assumes the local Git repository for the kernel is in + a top-level directory named linux-yocto-3.0: + + $ cd ~/linux-yocto-3.0 + $ git checkout -b meta origin/meta + + Once you have checked out and switched to the meta branch, + 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 .scc files. - You should realize, however, that browsing your local snapshot of feature - descriptions and patches is not an effective way to determine what is in a + 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. 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. @@ -76,10 +84,12 @@ - The following steps describe what happens when the Yocto kernel team constructs - the kernel tree 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: + The following steps describe what happens when the Yocto Project Team constructs + the Yocto Linux kernel source Git repository (or tree) found at + 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: A top-level kernel feature is passed to the kernel build subsystem. Normally, this feature is a BSP for a particular kernel type. @@ -126,10 +136,11 @@ 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 - http://git.yoctoproject.org/cgit.cgi + http://git.yoctoproject.org/cgit.cgi is the combination of all supported boards and configurations. The technique the Yocto Project team uses is flexible and allows for seamless - blending of an immutable history with additional deployment specific patches. + blending of an immutable history with additional patches specific to a + deployment. Any additions to the kernel become an integrated part of the branches. @@ -226,10 +237,8 @@ You can find Git documentation at . You can find a simple overview of using Git with the Yocto Project in the - "Git" - section of - The Yocto - Project Development Manual. + "Git" + section of The Yocto Project Development Manual.
@@ -244,8 +253,8 @@ 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. - This sort of patch inspection is not an efficient way to determine what has been done to the - kernel. + 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 selected based on the kernel type and the feature description. Additionally, patches could exist in directories that are not included in the search. @@ -299,9 +308,11 @@ Show a Particular Feature or Branch Change - Significant features or branches are tagged in the Yocto Project tree to divide - changes. - Remember to first determine (or add) the tag of interest. + Developers use tags in the Yocto Project 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. Because BSP branch, kernel.org, and feature tags are all present, there could be many tags. @@ -354,10 +365,10 @@ The Yocto Project provides scripts that help you work in a collaborative development environment. For information on these scripts, see the - "Pushing a Change Upstream and Requesting a Pull" and - "Submitting a Patch Through Email" sections in - The - Yocto Project Development Manual". + "Pushing a Change + Upstream and Requesting a Pull" and + "Submitting a Patch Through + Email" sections in The Yocto Project Development Manual. @@ -637,9 +648,8 @@ 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 - "How to Submit a Change" section in - The - Yocto Project Development Manual". + "How to Submit a + Change" section in The Yocto Project Development Manual. @@ -741,7 +751,8 @@ - The following commands illustrate how you can condense and merge two BSPs into a second SCM: + The following commands illustrate how you can condense and merge two BSPs into a + second SCM: > git checkout yocto/standard/common-pc/base > git merge yocto/standard/common-pc-64/base @@ -772,10 +783,9 @@ existing similar BSP. The information is introductory in nature and does not provide step-by-step examples. For detailed information on how to create a BSP given an existing similar BSP, see - the "BSP Development Example" appendix in - The - Yocto Project Development Manual, or see the - Transcript:_creating_one_generic_Atom_BSP_from_another + the "BSP Development + Example" appendix in the Yocto Project Development Manual, or see the + Transcript:_creating_one_generic_Atom_BSP_from_another wiki page. @@ -792,7 +802,7 @@ 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 - . + . Be sure you have the Base BSP: You need to either have the Yocto Project Git repository set up or download the tarball of the base BSP. -- cgit v1.2.3-54-g00ecf