summaryrefslogtreecommitdiffstats
path: root/documentation
diff options
context:
space:
mode:
authorScott Rifenbark <srifenbark@gmail.com>2017-10-03 12:06:51 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2017-10-06 12:06:34 +0100
commit766770aa35626c8598b849346b6c79335ba1f9e4 (patch)
treedd272e5513cfaaa27a1d6aae17b1b892d4c2cd30 /documentation
parentf83991dc04a266375eb0254cb7f8ad9c69e4b944 (diff)
downloadpoky-766770aa35626c8598b849346b6c79335ba1f9e4.tar.gz
kernel-dev: Updated Tree Construction section
The section was using the "meta-*" stuff, which is not how it is done any longer. (From yocto-docs rev: c9d95e85a832a38c3fd099a728693af3fa708d50) Signed-off-by: Scott Rifenbark <srifenbark@gmail.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation')
-rw-r--r--documentation/kernel-dev/kernel-dev-maint-appx.xml157
1 files changed, 100 insertions, 57 deletions
diff --git a/documentation/kernel-dev/kernel-dev-maint-appx.xml b/documentation/kernel-dev/kernel-dev-maint-appx.xml
index 9e6fa99998..4575c90df9 100644
--- a/documentation/kernel-dev/kernel-dev-maint-appx.xml
+++ b/documentation/kernel-dev/kernel-dev-maint-appx.xml
@@ -22,11 +22,13 @@
22 Those feature descriptions list all necessary patches, 22 Those feature descriptions list all necessary patches,
23 configurations, branches, tags, and feature divisions found in a 23 configurations, branches, tags, and feature divisions found in a
24 Yocto Linux kernel. 24 Yocto Linux kernel.
25 Thus, the Yocto Project Linux kernel repository (or tree) is built. 25 Thus, the Yocto Project Linux kernel repository (or tree) and
26 accompanying Metadata in the
27 <filename>yocto-kernel-cache</filename> are built.
26 </para> 28 </para>
27 29
28 <para> 30 <para>
29 The existence of this tree allows you to access and clone a 31 The existence of these repositories allow you to access and clone a
30 particular Yocto Project Linux kernel repository and use it to 32 particular Yocto Project Linux kernel repository and use it to
31 build images based on their configurations and features. 33 build images based on their configurations and features.
32 </para> 34 </para>
@@ -34,12 +36,16 @@
34 <para> 36 <para>
35 You can find the files used to describe all the valid features and 37 You can find the files used to describe all the valid features and
36 BSPs in the Yocto Project Linux kernel in any clone of the Yocto 38 BSPs in the Yocto Project Linux kernel in any clone of the Yocto
37 Project Linux kernel source repository Git tree. 39 Project Linux kernel source repository and
38 For example, the following command clones the Yocto Project 40 <filename>yocto-kernel-cache</filename> Git trees.
41 For example, the following commands clone the Yocto Project
39 baseline Linux kernel that branches off 42 baseline Linux kernel that branches off
40 <filename>linux.org</filename> version 4.12: 43 <filename>linux.org</filename> version 4.12 and the
44 <filename>yocto-kernel-cache</filename>, which contains stores of
45 kernel Metadata:
41 <literallayout class='monospaced'> 46 <literallayout class='monospaced'>
42 $ git clone git://git.yoctoproject.org/linux-yocto-4.12 47 $ git clone git://git.yoctoproject.org/linux-yocto-4.12
48 $ git clone git://git.yoctoproject.org/linux-kernel-cache
43 </literallayout> 49 </literallayout>
44 For more information on how to set up a local Git repository of 50 For more information on how to set up a local Git repository of
45 the Yocto Project Linux kernel files, see the 51 the Yocto Project Linux kernel files, see the
@@ -48,25 +54,33 @@
48 </para> 54 </para>
49 55
50 <para> 56 <para>
51 Once you have cloned the kernel Git repository on your local 57 Once you have cloned the kernel Git repository and the
52 machine, you can discover the branches that are avilable in the 58 cache of Metadata on your local machine, you can discover the
53 repository using the following Git command: 59 branches that are avilable in the repository using the following
60 Git command:
54 <literallayout class='monospaced'> 61 <literallayout class='monospaced'>
55 $ git branch -a 62 $ git branch -a
56 </literallayout> 63 </literallayout>
57 Checking out a branch allows you to work with a particular 64 Checking out a branch allows you to work with a particular
58 Yocto Linux kernel. 65 Yocto Linux kernel.
59 For example, the following command checks out the 66 For example, the following commands check out the
60 <filename>standard/beagleboard</filename> branch of the 67 "standard/beagleboard" branch of the Yocto Linux kernel repository
61 repository: 68 and the "yocto-4.12" branch of the
69 <filename>yocto-kernel-cache</filename> repository:
62 <literallayout class='monospaced'> 70 <literallayout class='monospaced'>
63 $ cd linux-yocto-4.12 71 $ cd ~/linux-yocto-4.12
64 $ git checkout -b my-kernel-4.12 standard/beagleboard 72 $ git checkout -b my-kernel-4.12 remotes/origin/standard/beagleboard
73 $ cd ~/linux-kernel-cache
74 $ git checkout -b my-4.12-metadata remotes/origin/yocto-4.12
65 </literallayout> 75 </literallayout>
66 Once you have checked out and switched to the 76 <note>
67 <filename>standard/beagleboard</filename> branch, 77 Branches in the <filename>yocto-kernel-cache</filename>
78 repository correspond to Yocto Linux kernel versions
79 (e.g. "yocto-4.12", "yocto-4.10", "yocto-4.9", and so forth).
80 </note>
81 Once you have checked out and switched to appropriate branches,
68 you can see a snapshot of all the kernel source files used to 82 you can see a snapshot of all the kernel source files used to
69 used to build that particular Yocto Linux kernel for that 83 used to build that particular Yocto Linux kernel for a
70 particular board. 84 particular board.
71 </para> 85 </para>
72 86
@@ -74,9 +88,9 @@
74 To see the features and configurations for a particular Yocto 88 To see the features and configurations for a particular Yocto
75 Linux kernel, you need to examine the 89 Linux kernel, you need to examine the
76 <filename>yocto-kernel-cache</filename> Git repository. 90 <filename>yocto-kernel-cache</filename> Git repository.
77 Branches in the <filename>yocto-kernel-cache</filename> repository 91 As mentioned, branches in the
78 correspond to Yocto Linux kernel versions (e.g. 92 <filename>yocto-kernel-cache</filename> repository correspond to
79 <filename>yocto-4.12</filename>). 93 Yocto Linux kernel versions (e.g. <filename>yocto-4.12</filename>).
80 Branches contain descriptions in the form of 94 Branches contain descriptions in the form of
81 <filename>.scc</filename> and <filename>.cfg</filename> files. 95 <filename>.scc</filename> and <filename>.cfg</filename> files.
82 </para> 96 </para>
@@ -106,77 +120,106 @@
106 (or tree) found at 120 (or tree) found at
107 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink> given the 121 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink> given the
108 introduction of a new top-level kernel feature or BSP. 122 introduction of a new top-level kernel feature or BSP.
109 These are the actions that effectively create the tree 123 These are the actions that effectively provide the Metadata
110 that includes the new feature, patch or BSP: 124 and create the tree that includes the new feature, patch or BSP:
111 <orderedlist> 125 <orderedlist>
112 <listitem><para> 126 <listitem><para>
127 <emphasis>Pass Feature to Build Subsystem:</emphasis>
113 A top-level kernel feature is passed to the kernel build 128 A top-level kernel feature is passed to the kernel build
114 subsystem. 129 subsystem.
115 Normally, this feature is a BSP for a particular kernel 130 Normally, this feature is a BSP for a particular kernel
116 type. 131 type.
117 </para></listitem> 132 </para></listitem>
118 <listitem><para> 133 <listitem><para>
134 <emphasis>Locate Feature:</emphasis>
119 The file that describes the top-level feature is located 135 The file that describes the top-level feature is located
120 by searching these system directories: 136 by searching these system directories:
121 <itemizedlist> 137 <itemizedlist>
122 <listitem><para> 138 <listitem><para>
123 The in-tree kernel-cache directories, which are 139 The in-tree kernel-cache directories, which are
124 located in 140 located in the
125 <filename>yocto-kernel-cache/cfg/kernel-cache</filename> 141 <filename>yocto-kernel-cache</filename>
142 repository
126 </para></listitem> 143 </para></listitem>
127 <listitem><para> 144 <listitem><para>
128 Areas pointed to by <filename>SRC_URI</filename> 145 Areas pointed to by <filename>SRC_URI</filename>
129 statements found in recipes 146 statements found in kernel recipes
130 </para></listitem> 147 </para></listitem>
131 </itemizedlist> 148 </itemizedlist>
132 For a typical build, the target of the search is a 149 For a typical build, the target of the search is a
133 feature description in an <filename>.scc</filename> file 150 feature description in an <filename>.scc</filename> file
134 whose name follows this format: 151 whose name follows this format:
135
136
137I AM HERE
138
139
140
141 <literallayout class='monospaced'> 152 <literallayout class='monospaced'>
142 <replaceable>bsp_name</replaceable>-<replaceable>kernel_type</replaceable>.scc 153 <replaceable>bsp_name</replaceable>-<replaceable>kernel_type</replaceable>.scc
143 </literallayout> 154 </literallayout>
144 </para></listitem> 155 </para></listitem>
145 <listitem><para>Once located, the feature description is either compiled into a simple script 156 <listitem><para>
146 of actions, or into an existing equivalent script that is already part of the 157 <emphasis>Compile Feature:</emphasis>
147 shipped kernel.</para></listitem> 158 Once located, the feature description is either compiled
148 <listitem><para>Extra features are appended to the top-level feature description. 159 into a simple script of actions, or into an existing
160 equivalent script that is already part of the shipped
161 kernel.
162 </para></listitem>
163 <listitem><para>
164 <emphasis>Append Extra Features:</emphasis>
165 Extra features are appended to the top-level feature
166 description.
149 These features can come from the 167 These features can come from the
150 <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_FEATURES'><filename>KERNEL_FEATURES</filename></ulink> 168 <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_FEATURES'><filename>KERNEL_FEATURES</filename></ulink>
151 variable in recipes.</para></listitem> 169 variable in recipes.
152 <listitem><para>Each extra feature is located, compiled and appended to the script 170 </para></listitem>
153 as described in step three.</para></listitem> 171 <listitem><para>
154 <listitem><para>The script is executed to produce a series of <filename>meta-*</filename> 172 <emphasis>Locate, Compile, and Append Each Feature:</emphasis>
155 directories. 173 Each extra feature is located, compiled and appended to
156 These directories are descriptions of all the branches, tags, patches and configurations that 174 the script as described in step three.
157 need to be applied to the base Git repository to completely create the 175 </para></listitem>
158 source (build) branch for the new BSP or feature.</para></listitem> 176 <listitem><para>
159 <listitem><para>The base repository is cloned, and the actions 177 <emphasis>Execute the Script:</emphasis>
160 listed in the <filename>meta-*</filename> directories are applied to the 178 The script is executed to produce files
161 tree.</para></listitem> 179 <filename>.scc</filename> and <filename>.cfg</filename>
162 <listitem><para>The Git repository is left with the desired branch checked out and any 180 files in appropriate directories of the
163 required branching, patching and tagging has been performed.</para></listitem> 181 <filename>yocto-kernel-cache</filename> repository.
182 These files are descriptions of all the branches, tags,
183 patches and configurations that need to be applied to the
184 base Git repository to completely create the
185 source (build) branch for the new BSP or feature.
186 </para></listitem>
187 <listitem><para>
188 <emphasis>Clone Base Repository:</emphasis>
189 The base repository is cloned, and the actions
190 listed in the <filename>yocto-kernel-cache</filename>
191 irectories are applied to the tree.
192 </para></listitem>
193 <listitem><para>
194 <emphasis>Perform Cleanup:</emphasis>
195 The Git repositories are left with the desired branches
196 checked out and any required branching, patching and
197 tagging has been performed.
198 </para></listitem>
164 </orderedlist> 199 </orderedlist>
165 </para> 200 </para>
201
166 <para> 202 <para>
167 The kernel tree is now ready for developer consumption to be locally cloned, 203 The kernel tree and cache are ready for developer consumption to
168 configured, and built into a Yocto Project kernel specific to some target hardware. 204 be locally cloned, configured, and built into a Yocto Project
169 <note><para>The generated <filename>meta-*</filename> directories add to the kernel 205 kernel specific to some target hardware.
170 as shipped with the Yocto Project release. 206 <note>
171 Any add-ons and configuration data are applied to the end of an existing branch. 207 <para>The generated <filename>yocto-kernel-cache</filename>
208 repository adds to the kernel as shipped with the Yocto Project
209 release.
210 Any add-ons and configuration data are applied to the end of
211 an existing branch.
172 The full repository generation that is found in the 212 The full repository generation that is found in the
173 official Yocto Project kernel repositories at 213 official Yocto Project kernel repositories at
174 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'>http://git.yoctoproject.org/cgit.cgi</ulink> 214 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'>http://git.yoctoproject.org/cgit.cgi</ulink>
175 is the combination of all supported boards and configurations.</para> 215 is the combination of all supported boards and configurations.
176 <para>The technique the Yocto Project team uses is flexible and allows for seamless 216 </para>
177 blending of an immutable history with additional patches specific to a 217
178 deployment. 218 <para>The technique the Yocto Project team uses is flexible
179 Any additions to the kernel become an integrated part of the branches.</para> 219 and allows for seamless blending of an immutable history with
220 additional patches specific to a deployment.
221 Any additions to the kernel become an integrated part of the
222 branches.</para>
180 </note> 223 </note>
181 </para> 224 </para>
182 </section> 225 </section>