documentation/kernel-manual/kernel-how-to.xml: Tree Construction section further explained

Added text to help put tree construction into context with the developer. The section felt as if the developer needed to be taking action on the steps when in reality the steps are describing a lot of "behind-the-scenes" stuff that happens when the YP tree is constructed. (From yocto-docs rev: 1aafca94f3f3d5e07a0b2244ff5dbfe4a2c1ba8f) Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
author: Scott Rifenbark <scott.m.rifenbark@intel.com> 2011-07-14 14:17:49 -0700
committer: Richard Purdie <richard.purdie@linuxfoundation.org> 2011-07-21 10:59:21 +0100
commit: 51b3a231b0cd36d5f1597e4be2a276387cf8789b (patch)
tree: d0a8163923864c7a67cff295f83a795cd29e2975 /documentation/kernel-manual
parent: 0a7b3f8fdd031e8563f50446706566b2758afb2d (diff)
download: poky-51b3a231b0cd36d5f1597e4be2a276387cf8789b.tar.gz
1 files changed, 54 insertions, 32 deletions
diff --git a/documentation/kernel-manual/kernel-how-to.xml b/documentation/kernel-manual/kernel-how-to.xml
index 852fbb1a90..bf45ae1729 100644
--- a/documentation/kernel-manual/kernel-how-to.xml
+++ b/documentation/kernel-manual/kernel-how-to.xml
@@ -40,12 +40,24 @@
            in the product. 
            Those feature descriptions list all necessary patches,
            configuration, branching, tagging and feature divisions found in the kernel.
+            Thus, the Yocto Project kernel repository (or tree) is built.
+            The existence of this tree allows you to build images based on your 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 kernel Git tree.  
+            kernel in any clone of the kernel Git tree.
-            The directory <filename>meta/cfg/kernel-cache/</filename> is a snapshot of all the kernel
+            For example, the following command clones the Yocto Project baseline kernel that 
-            configuration and feature descriptions (.scc) used to build the kernel repository.
+            branched off of linux.org version 2.6.37:
+            <literallayout class='monospaced'>
+     $ git clone http://git.yoctoproject.org/cgit/cgit.cgi/linux-yocto-2.6.37
+            </literallayout>  
+            After you switch to the <filename>meta</filename> branch within the repository
+            you can see a snapshot of all the kernel configuration and feature descriptions that are 
+            used to build the kernel repository.
+            These descriptions are in the form of <filename>.scc</filename> files. 
+        </para>
+        <para>
            You should realize, however, that browsing the snapshot of feature
            descriptions and patches is not an effective way to determine what is in a
            particular kernel branch. 
@@ -62,46 +74,56 @@
            and development.
        </para></note>
        <para>
-            The general flow for constructing a project-specific kernel tree is as follows:
+            The following steps describe what happens during tree construction given the introduction
-        <orderedlist>
+            of a new top-level kernel feature or BSP. 
-            <listitem><para>A top-level kernel feature is passed to the kernel build subsystem.
+            These are the actions that effectively create the tree that includes the new feature, patch, 
-            Normally, this is a BSP for a particular kernel type.</para></listitem>
+            or BSP:
+            <orderedlist>
+                <listitem><para>A top-level kernel feature is passed to the kernel build subsystem.
+                    Normally, this is a BSP for a particular kernel type.</para></listitem>
-            <listitem><para>The file that describes the top-level feature is located by searching
+                <listitem><para>The file that describes the top-level feature is located by searching
-            these system directories:</para>
+                    these system directories:
-                <itemizedlist>
+                    <itemizedlist>
-                    <listitem><para>The in-tree kernel-cache directories</para></listitem>
+                        <listitem><para>The in-tree kernel-cache directories, which are located
+                            in <filename>meta/cfg/kernel-cache</filename></para></listitem>
 <!--            <listitem><para>kernel-*-cache directories in layers</para></listitem> -->
-                    <listitem><para>Recipe SRC_URIs</para></listitem>
+                        <listitem><para>Areas pointed to by <filename>SRC_URI</filename> statements
+                            found in recipes</para></listitem>
 <!--            <listitem><para>configured and default templates</para></listitem> -->
-                </itemizedlist>
+                    </itemizedlist>
-            <para>For a typical build a feature description of the format:
+                    For a typical build, the target of the search is a 
-            &lt;bsp name&gt;-&lt;kernel type&gt;.scc is the target of the search.
+                    feature description in an <filename>.scc</filename> file
-            </para></listitem>
+                    whose name follows this format:
+                    <literallayout class='monospaced'>
+     &lt;bsp_name&gt;-&lt;kernel_type&gt;.scc
+                    </literallayout>
+                </para></listitem>
-            <listitem><para>Once located, the feature description is either compiled into a simple script
+                <listitem><para>Once located, the feature description is either compiled into a simple script
-            of actions, or an existing equivalent script that was part of the
+                    of actions, or into an existing equivalent script that is already part of the
-            shipped kernel is located.</para></listitem>
+                    shipped kernel.</para></listitem>
-            <listitem><para>Extra features are appended to the top-level feature description. 
+                <listitem><para>Extra features are appended to the top-level feature description. 
-            These features can come from the KERNEL_FEATURES variable in recipes.</para></listitem>
+                    These features can come from the <filename>KERNEL_FEATURES</filename> variable in 
+                    recipes.</para></listitem>
-            <listitem><para>Each extra feature is located, compiled and appended to the script from
+                <listitem><para>Each extra feature is located, compiled and appended to the script 
-            step #3</para></listitem>
+                    as described in step three.</para></listitem>
-            <listitem><para>The script is executed, and a meta-series is produced. 
+                <listitem><para>The script is executed to produce a meta-series. 
-            The meta-series is a description of all the branches, tags, patches and configurations that
+                    The meta-series is a description of all the branches, tags, patches and configurations that
-            need to be applied to the base Git repository to completely create the
+                    need to be applied to the base Git repository to completely create the
-            BSP source (build) branch.</para></listitem>
+                    source (build) branch for the new BSP or feature.</para></listitem>
-            <listitem><para>The base repository is cloned, and the actions
+                <listitem><para>The base repository is cloned, and the actions
-            listed in the meta-series are applied to the tree.</para></listitem>
+                    listed in the meta-series are applied to the tree.</para></listitem>
-            <listitem><para>The Git repository is left with the desired branch checked out and any
+                <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>
+                    required branching, patching and tagging has been performed.</para></listitem>
-        </orderedlist>
+            </orderedlist>
        </para>
        <para>
author	Scott Rifenbark <scott.m.rifenbark@intel.com>	2011-07-14 14:17:49 -0700
committer	Richard Purdie <richard.purdie@linuxfoundation.org>	2011-07-21 10:59:21 +0100
commit	51b3a231b0cd36d5f1597e4be2a276387cf8789b (patch)
tree	d0a8163923864c7a67cff295f83a795cd29e2975 /documentation/kernel-manual
parent	0a7b3f8fdd031e8563f50446706566b2758afb2d (diff)
download	poky-51b3a231b0cd36d5f1597e4be2a276387cf8789b.tar.gz

diff --git a/documentation/kernel-manual/kernel-how-to.xml b/documentation/kernel-manual/kernel-how-to.xml index 852fbb1a90..bf45ae1729 100644 --- a/documentation/kernel-manual/kernel-how-to.xml +++ b/documentation/kernel-manual/kernel-how-to.xml
@@ -40,12 +40,24 @@
40	in the product.	40	in the product.
41	Those feature descriptions list all necessary patches,	41	Those feature descriptions list all necessary patches,
42	configuration, branching, tagging and feature divisions found in the kernel.	42	configuration, branching, tagging and feature divisions found in the kernel.
		43	Thus, the Yocto Project kernel repository (or tree) is built.
		44	The existence of this tree allows you to build images based on your configurations
		45	and features.
43	</para>	46	</para>
44	<para>	47	<para>
45	You can find the files used to describe all the valid features and BSPs in the Yocto Project	48	You can find the files used to describe all the valid features and BSPs in the Yocto Project
46	kernel in any clone of the kernel Git tree.	49	kernel in any clone of the kernel Git tree.
47	The directory <filename>meta/cfg/kernel-cache/</filename> is a snapshot of all the kernel	50	For example, the following command clones the Yocto Project baseline kernel that
48	configuration and feature descriptions (.scc) used to build the kernel repository.	51	branched off of linux.org version 2.6.37:
		52	<literallayout class='monospaced'>
		53	$ git clone http://git.yoctoproject.org/cgit/cgit.cgi/linux-yocto-2.6.37
		54	</literallayout>
		55	After you switch to the <filename>meta</filename> branch within the repository
		56	you can see a snapshot of all the kernel configuration and feature descriptions that are
		57	used to build the kernel repository.
		58	These descriptions are in the form of <filename>.scc</filename> files.
		59	</para>
		60	<para>
49	You should realize, however, that browsing the snapshot of feature	61	You should realize, however, that browsing the snapshot of feature
50	descriptions and patches is not an effective way to determine what is in a	62	descriptions and patches is not an effective way to determine what is in a
51	particular kernel branch.	63	particular kernel branch.
@@ -62,46 +74,56 @@
62	and development.	74	and development.
63	</para></note>	75	</para></note>
64	<para>	76	<para>
65	The general flow for constructing a project-specific kernel tree is as follows:	77	The following steps describe what happens during tree construction given the introduction
66	<orderedlist>	78	of a new top-level kernel feature or BSP.
67	<listitem><para>A top-level kernel feature is passed to the kernel build subsystem.	79	These are the actions that effectively create the tree that includes the new feature, patch,
68	Normally, this is a BSP for a particular kernel type.</para></listitem>	80	or BSP:
		81	<orderedlist>
		82	<listitem><para>A top-level kernel feature is passed to the kernel build subsystem.
		83	Normally, this is a BSP for a particular kernel type.</para></listitem>
69		84
70	<listitem><para>The file that describes the top-level feature is located by searching	85	<listitem><para>The file that describes the top-level feature is located by searching
71	these system directories:</para>	86	these system directories:
72		87
73	<itemizedlist>	88	<itemizedlist>
74	<listitem><para>The in-tree kernel-cache directories</para></listitem>	89	<listitem><para>The in-tree kernel-cache directories, which are located
		90	in <filename>meta/cfg/kernel-cache</filename></para></listitem>
75	<!-- <listitem><para>kernel-*-cache directories in layers</para></listitem> -->	91	<!-- <listitem><para>kernel-*-cache directories in layers</para></listitem> -->
76	<listitem><para>Recipe SRC_URIs</para></listitem>	92	<listitem><para>Areas pointed to by <filename>SRC_URI</filename> statements
		93	found in recipes</para></listitem>
77	<!-- <listitem><para>configured and default templates</para></listitem> -->	94	<!-- <listitem><para>configured and default templates</para></listitem> -->
78	</itemizedlist>	95	</itemizedlist>
79		96
80	<para>For a typical build a feature description of the format:	97	For a typical build, the target of the search is a
81	<bsp name>-<kernel type>.scc is the target of the search.	98	feature description in an <filename>.scc</filename> file
82	</para></listitem>	99	whose name follows this format:
		100	<literallayout class='monospaced'>
		101	<bsp_name>-<kernel_type>.scc
		102	</literallayout>
		103	</para></listitem>
83		104
84	<listitem><para>Once located, the feature description is either compiled into a simple script	105	<listitem><para>Once located, the feature description is either compiled into a simple script
85	of actions, or an existing equivalent script that was part of the	106	of actions, or into an existing equivalent script that is already part of the
86	shipped kernel is located.</para></listitem>	107	shipped kernel.</para></listitem>
87		108
88	<listitem><para>Extra features are appended to the top-level feature description.	109	<listitem><para>Extra features are appended to the top-level feature description.
89	These features can come from the KERNEL_FEATURES variable in recipes.</para></listitem>	110	These features can come from the <filename>KERNEL_FEATURES</filename> variable in
		111	recipes.</para></listitem>
90		112
91	<listitem><para>Each extra feature is located, compiled and appended to the script from	113	<listitem><para>Each extra feature is located, compiled and appended to the script
92	step #3</para></listitem>	114	as described in step three.</para></listitem>
93		115
94	<listitem><para>The script is executed, and a meta-series is produced.	116	<listitem><para>The script is executed to produce a meta-series.
95	The meta-series is a description of all the branches, tags, patches and configurations that	117	The meta-series is a description of all the branches, tags, patches and configurations that
96	need to be applied to the base Git repository to completely create the	118	need to be applied to the base Git repository to completely create the
97	BSP source (build) branch.</para></listitem>	119	source (build) branch for the new BSP or feature.</para></listitem>
98		120
99	<listitem><para>The base repository is cloned, and the actions	121	<listitem><para>The base repository is cloned, and the actions
100	listed in the meta-series are applied to the tree.</para></listitem>	122	listed in the meta-series are applied to the tree.</para></listitem>
101		123
102	<listitem><para>The Git repository is left with the desired branch checked out and any	124	<listitem><para>The Git repository is left with the desired branch checked out and any
103	required branching, patching and tagging has been performed.</para></listitem>	125	required branching, patching and tagging has been performed.</para></listitem>
104	</orderedlist>	126	</orderedlist>
105	</para>	127	</para>
106		128
107	<para>	129	<para>