summaryrefslogtreecommitdiffstats
path: root/documentation/kernel-manual/kernel-how-to.xml
diff options
context:
space:
mode:
authorScott Rifenbark <scott.m.rifenbark@intel.com>2012-12-07 17:25:45 -0600
committerRichard Purdie <richard.purdie@linuxfoundation.org>2012-12-11 16:17:51 +0000
commitacb3f72afaa28ba5d23ca6e5cdf9f1162ea656a3 (patch)
treec4076b9026317277cbdc63a54012382d5850c8ae /documentation/kernel-manual/kernel-how-to.xml
parent72d01bf43da4d6761ee1b5997307c64152ec3517 (diff)
downloadpoky-acb3f72afaa28ba5d23ca6e5cdf9f1162ea656a3.tar.gz
Documentation: kernel-manual - Removed all trailing whitespace.
(From yocto-docs rev: 188e1ad10217ff1a6a8363f100bff4e9ef3b9bf7) Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/kernel-manual/kernel-how-to.xml')
-rw-r--r--documentation/kernel-manual/kernel-how-to.xml344
1 files changed, 172 insertions, 172 deletions
diff --git a/documentation/kernel-manual/kernel-how-to.xml b/documentation/kernel-manual/kernel-how-to.xml
index 9d0ec6a699..f29a0a865a 100644
--- a/documentation/kernel-manual/kernel-how-to.xml
+++ b/documentation/kernel-manual/kernel-how-to.xml
@@ -10,11 +10,11 @@
10<section id='actions-org'> 10<section id='actions-org'>
11 <title>Introduction</title> 11 <title>Introduction</title>
12 <para> 12 <para>
13 This chapter describes how to accomplish tasks involving a kernel's tree structure. 13 This chapter describes how to accomplish tasks involving a kernel's tree structure.
14 The information is designed to help the developer that wants to modify the Yocto 14 The information is designed to help the developer that wants to modify the Yocto
15 Project kernel and contribute changes upstream to the Yocto Project. 15 Project kernel and contribute changes upstream to the Yocto Project.
16 The information covers the following: 16 The information covers the following:
17 <itemizedlist> 17 <itemizedlist>
18 <listitem><para>Tree construction</para></listitem> 18 <listitem><para>Tree construction</para></listitem>
19 <listitem><para>Build strategies</para></listitem> 19 <listitem><para>Build strategies</para></listitem>
20 <listitem><para>Workflow examples</para></listitem> 20 <listitem><para>Workflow examples</para></listitem>
@@ -25,72 +25,72 @@
25 <section id='tree-construction'> 25 <section id='tree-construction'>
26 <title>Tree Construction</title> 26 <title>Tree Construction</title>
27 <para> 27 <para>
28 This section describes construction of the Yocto Project kernel source repositories 28 This section describes construction of the Yocto Project kernel source repositories
29 as accomplished by the Yocto Project team to create kernel repositories. 29 as accomplished by the Yocto Project team to create kernel repositories.
30 These kernel repositories are found under the heading "Yocto Linux Kernel" at 30 These kernel repositories are found under the heading "Yocto Linux Kernel" at
31 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'>&YOCTO_GIT_URL;/cgit.cgi</ulink> 31 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'>&YOCTO_GIT_URL;/cgit.cgi</ulink>
32 and can be shipped as part of a Yocto Project release. 32 and can be shipped as part of a Yocto Project release.
33 The team creates these repositories by 33 The team creates these repositories by
34 compiling and executing the set of feature descriptions for every BSP/feature 34 compiling and executing the set of feature descriptions for every BSP/feature
35 in the product. 35 in the product.
36 Those feature descriptions list all necessary patches, 36 Those feature descriptions list all necessary patches,
37 configuration, branching, tagging and feature divisions found in a kernel. 37 configuration, branching, tagging and feature divisions found in a kernel.
38 Thus, the Yocto Project kernel repository (or tree) is built. 38 Thus, the Yocto Project kernel repository (or tree) is built.
39 </para> 39 </para>
40 <para> 40 <para>
41 The existence of this tree allows you to access and clone a particular 41 The existence of this tree allows you to access and clone a particular
42 Yocto Project kernel repository and use it to build images based on their configurations 42 Yocto Project kernel repository and use it to build images based on their configurations
43 and features. 43 and features.
44 </para> 44 </para>
45 <para> 45 <para>
46 You can find the files used to describe all the valid features and BSPs 46 You can find the files used to describe all the valid features and BSPs
47 in the Yocto Project kernel in any clone of the Yocto Project kernel source repository 47 in the Yocto Project kernel in any clone of the Yocto Project kernel source repository
48 Git tree. 48 Git tree.
49 For example, the following command clones the Yocto Project baseline kernel that 49 For example, the following command clones the Yocto Project baseline kernel that
50 branched off of <filename>linux.org</filename> version 3.4: 50 branched off of <filename>linux.org</filename> version 3.4:
51 <literallayout class='monospaced'> 51 <literallayout class='monospaced'>
52 $ git clone git://git.yoctoproject.org/linux-yocto-3.4 52 $ git clone git://git.yoctoproject.org/linux-yocto-3.4
53 </literallayout> 53 </literallayout>
54 For another example of how to set up a local Git repository of the Yocto Project 54 For another example of how to set up a local Git repository of the Yocto Project
55 kernel files, see the 55 kernel files, see the
56 "<ulink url='&YOCTO_DOCS_DEV_URL;#local-kernel-files'>Yocto Project Kernel</ulink>" bulleted 56 "<ulink url='&YOCTO_DOCS_DEV_URL;#local-kernel-files'>Yocto Project Kernel</ulink>" bulleted
57 item in the Yocto Project Development Manual. 57 item in the Yocto Project Development Manual.
58 </para> 58 </para>
59 <para> 59 <para>
60 Once you have cloned the kernel Git repository on your local machine, you can 60 Once you have cloned the kernel Git repository on your local machine, you can
61 switch to the <filename>meta</filename> branch within the repository. 61 switch to the <filename>meta</filename> branch within the repository.
62 Here is an example that assumes the local Git repository for the kernel is in 62 Here is an example that assumes the local Git repository for the kernel is in
63 a top-level directory named <filename>linux-yocto-3.4</filename>: 63 a top-level directory named <filename>linux-yocto-3.4</filename>:
64 <literallayout class='monospaced'> 64 <literallayout class='monospaced'>
65 $ cd ~/linux-yocto-3.4 65 $ cd ~/linux-yocto-3.4
66 $ git checkout -b meta origin/meta 66 $ git checkout -b meta origin/meta
67 </literallayout> 67 </literallayout>
68 Once you have checked out and switched to the <filename>meta</filename> branch, 68 Once you have checked out and switched to the <filename>meta</filename> branch,
69 you can see a snapshot of all the kernel configuration and feature descriptions that are 69 you can see a snapshot of all the kernel configuration and feature descriptions that are
70 used to build that particular kernel repository. 70 used to build that particular kernel repository.
71 These descriptions are in the form of <filename>.scc</filename> files. 71 These descriptions are in the form of <filename>.scc</filename> files.
72 </para> 72 </para>
73 <para> 73 <para>
74 You should realize, however, that browsing your local kernel repository 74 You should realize, however, that browsing your local kernel repository
75 for feature descriptions and patches is not an effective way to determine what is in a 75 for feature descriptions and patches is not an effective way to determine what is in a
76 particular kernel branch. 76 particular kernel branch.
77 Instead, you should use Git directly to discover the changes in a branch. 77 Instead, you should use Git directly to discover the changes in a branch.
78 Using Git is an efficient and flexible way to inspect changes to the kernel. 78 Using Git is an efficient and flexible way to inspect changes to the kernel.
79 For examples showing how to use Git to inspect kernel commits, see the following sections 79 For examples showing how to use Git to inspect kernel commits, see the following sections
80 in this chapter. 80 in this chapter.
81 <note> 81 <note>
82 Ground up reconstruction of the complete kernel tree is an action only taken by the 82 Ground up reconstruction of the complete kernel tree is an action only taken by the
83 Yocto Project team during an active development cycle. 83 Yocto Project team during an active development cycle.
84 When you create a clone of the kernel Git repository, you are simply making it 84 When you create a clone of the kernel Git repository, you are simply making it
85 efficiently available for building and development. 85 efficiently available for building and development.
86 </note> 86 </note>
87 </para> 87 </para>
88 <para> 88 <para>
89 The following steps describe what happens when the Yocto Project Team constructs 89 The following steps describe what happens when the Yocto Project Team constructs
90 the Yocto Project kernel source Git repository (or tree) found at 90 the Yocto Project kernel source Git repository (or tree) found at
91 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink> given the 91 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink> given the
92 introduction of a new top-level kernel feature or BSP. 92 introduction of a new top-level kernel feature or BSP.
93 These are the actions that effectively create the tree 93 These are the actions that effectively create the tree
94 that includes the new feature, patch or BSP: 94 that includes the new feature, patch or BSP:
95 <orderedlist> 95 <orderedlist>
96 <listitem><para>A top-level kernel feature is passed to the kernel build subsystem. 96 <listitem><para>A top-level kernel feature is passed to the kernel build subsystem.
@@ -103,7 +103,7 @@
103 <listitem><para>Areas pointed to by <filename>SRC_URI</filename> statements 103 <listitem><para>Areas pointed to by <filename>SRC_URI</filename> statements
104 found in recipes</para></listitem> 104 found in recipes</para></listitem>
105 </itemizedlist> 105 </itemizedlist>
106 For a typical build, the target of the search is a 106 For a typical build, the target of the search is a
107 feature description in an <filename>.scc</filename> file 107 feature description in an <filename>.scc</filename> file
108 whose name follows this format: 108 whose name follows this format:
109 <literallayout class='monospaced'> 109 <literallayout class='monospaced'>
@@ -113,19 +113,19 @@
113 <listitem><para>Once located, the feature description is either compiled into a simple script 113 <listitem><para>Once located, the feature description is either compiled into a simple script
114 of actions, or into an existing equivalent script that is already part of the 114 of actions, or into an existing equivalent script that is already part of the
115 shipped kernel.</para></listitem> 115 shipped kernel.</para></listitem>
116 <listitem><para>Extra features are appended to the top-level feature description. 116 <listitem><para>Extra features are appended to the top-level feature description.
117 These features can come from the 117 These features can come from the
118 <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_FEATURES'><filename>KERNEL_FEATURES</filename></ulink> 118 <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_FEATURES'><filename>KERNEL_FEATURES</filename></ulink>
119 variable in recipes.</para></listitem> 119 variable in recipes.</para></listitem>
120 <listitem><para>Each extra feature is located, compiled and appended to the script 120 <listitem><para>Each extra feature is located, compiled and appended to the script
121 as described in step three.</para></listitem> 121 as described in step three.</para></listitem>
122 <listitem><para>The script is executed to produce a series of <filename>meta-*</filename> 122 <listitem><para>The script is executed to produce a series of <filename>meta-*</filename>
123 directories. 123 directories.
124 These directories are descriptions of all the branches, tags, patches and configurations that 124 These directories are descriptions of all the branches, tags, patches and configurations that
125 need to be applied to the base Git repository to completely create the 125 need to be applied to the base Git repository to completely create the
126 source (build) branch for the new BSP or feature.</para></listitem> 126 source (build) branch for the new BSP or feature.</para></listitem>
127 <listitem><para>The base repository is cloned, and the actions 127 <listitem><para>The base repository is cloned, and the actions
128 listed in the <filename>meta-*</filename> directories are applied to the 128 listed in the <filename>meta-*</filename> directories are applied to the
129 tree.</para></listitem> 129 tree.</para></listitem>
130 <listitem><para>The Git repository is left with the desired branch checked out and any 130 <listitem><para>The Git repository is left with the desired branch checked out and any
131 required branching, patching and tagging has been performed.</para></listitem> 131 required branching, patching and tagging has been performed.</para></listitem>
@@ -133,17 +133,17 @@
133 </para> 133 </para>
134 <para> 134 <para>
135 The kernel tree is now ready for developer consumption to be locally cloned, 135 The kernel tree is now ready for developer consumption to be locally cloned,
136 configured, and built into a Yocto Project kernel specific to some target hardware. 136 configured, and built into a Yocto Project kernel specific to some target hardware.
137 <note><para>The generated <filename>meta-*</filename> directories add to the kernel 137 <note><para>The generated <filename>meta-*</filename> directories add to the kernel
138 as shipped with the Yocto Project release. 138 as shipped with the Yocto Project release.
139 Any add-ons and configuration data are applied to the end of an existing branch. 139 Any add-ons and configuration data are applied to the end of an existing branch.
140 The full repository generation that is found in the 140 The full repository generation that is found in the
141 official Yocto Project kernel repositories at 141 official Yocto Project kernel repositories at
142 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'>http://git.yoctoproject.org/cgit.cgi</ulink> 142 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'>http://git.yoctoproject.org/cgit.cgi</ulink>
143 is the combination of all supported boards and configurations.</para> 143 is the combination of all supported boards and configurations.</para>
144 <para>The technique the Yocto Project team uses is flexible and allows for seamless 144 <para>The technique the Yocto Project team uses is flexible and allows for seamless
145 blending of an immutable history with additional patches specific to a 145 blending of an immutable history with additional patches specific to a
146 deployment. 146 deployment.
147 Any additions to the kernel become an integrated part of the branches.</para> 147 Any additions to the kernel become an integrated part of the branches.</para>
148 </note> 148 </note>
149 </para> 149 </para>
@@ -152,15 +152,15 @@
152 <section id='build-strategy'> 152 <section id='build-strategy'>
153 <title>Build Strategy</title> 153 <title>Build Strategy</title>
154 <para> 154 <para>
155 Once a local Git repository of the Yocto Project kernel exists on a development system, 155 Once a local Git repository of the Yocto Project kernel exists on a development system,
156 you can consider the compilation phase of kernel development - building a kernel image. 156 you can consider the compilation phase of kernel development - building a kernel image.
157 Some prerequisites exist that are validated by the build process before compilation 157 Some prerequisites exist that are validated by the build process before compilation
158 starts: 158 starts:
159 </para> 159 </para>
160 160
161 <itemizedlist> 161 <itemizedlist>
162 <listitem><para>The 162 <listitem><para>The
163 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> points 163 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> points
164 to the kernel Git repository.</para></listitem> 164 to the kernel Git repository.</para></listitem>
165 <listitem><para>A BSP build branch exists. 165 <listitem><para>A BSP build branch exists.
166 This branch has the following form: 166 This branch has the following form:
@@ -171,22 +171,22 @@
171 171
172 <para> 172 <para>
173 The OpenEmbedded build system makes sure these conditions exist before attempting compilation. 173 The OpenEmbedded build system makes sure these conditions exist before attempting compilation.
174 Other means, however, do exist, such as as bootstrapping a BSP, see 174 Other means, however, do exist, such as as bootstrapping a BSP, see
175 the "<link linkend='workflow-examples'>Workflow Examples</link>". 175 the "<link linkend='workflow-examples'>Workflow Examples</link>".
176 </para> 176 </para>
177 177
178 <para> 178 <para>
179 Before building a kernel, the build process verifies the tree 179 Before building a kernel, the build process verifies the tree
180 and configures the kernel by processing all of the 180 and configures the kernel by processing all of the
181 configuration "fragments" specified by feature descriptions in the <filename>.scc</filename> 181 configuration "fragments" specified by feature descriptions in the <filename>.scc</filename>
182 files. 182 files.
183 As the features are compiled, associated kernel configuration fragments are noted 183 As the features are compiled, associated kernel configuration fragments are noted
184 and recorded in the <filename>meta-*</filename> series of directories in their compilation order. 184 and recorded in the <filename>meta-*</filename> series of directories in their compilation order.
185 The fragments are migrated, pre-processed and passed to the Linux Kernel 185 The fragments are migrated, pre-processed and passed to the Linux Kernel
186 Configuration subsystem (<filename>lkc</filename>) as raw input in the form 186 Configuration subsystem (<filename>lkc</filename>) as raw input in the form
187 of a <filename>.config</filename> file. 187 of a <filename>.config</filename> file.
188 The <filename>lkc</filename> uses its own internal dependency constraints to do the final 188 The <filename>lkc</filename> uses its own internal dependency constraints to do the final
189 processing of that information and generates the final <filename>.config</filename> file 189 processing of that information and generates the final <filename>.config</filename> file
190 that is used during compilation. 190 that is used during compilation.
191 </para> 191 </para>
192 192
@@ -197,9 +197,9 @@
197 197
198 <para> 198 <para>
199 The other thing that you notice once you configure a kernel is that 199 The other thing that you notice once you configure a kernel is that
200 the build process generates a build tree that is separate from your kernel's local Git 200 the build process generates a build tree that is separate from your kernel's local Git
201 source repository tree. 201 source repository tree.
202 This build tree has a name that uses the following form, where 202 This build tree has a name that uses the following form, where
203 <filename>${MACHINE}</filename> is the metadata name of the machine (BSP) and "kernel_type" is one 203 <filename>${MACHINE}</filename> is the metadata name of the machine (BSP) and "kernel_type" is one
204 of the Yocto Project supported kernel types (e.g. "standard"): 204 of the Yocto Project supported kernel types (e.g. "standard"):
205 <literallayout class='monospaced'> 205 <literallayout class='monospaced'>
@@ -208,13 +208,13 @@
208 </para> 208 </para>
209 209
210 <para> 210 <para>
211 The existing support in the <filename>kernel.org</filename> tree achieves this 211 The existing support in the <filename>kernel.org</filename> tree achieves this
212 default functionality. 212 default functionality.
213 </para> 213 </para>
214 214
215 <para> 215 <para>
216 This behavior means that all the generated files for a particular machine or BSP are now in 216 This behavior means that all the generated files for a particular machine or BSP are now in
217 the build tree directory. 217 the build tree directory.
218 The files include the final <filename>.config</filename> file, all the <filename>.o</filename> 218 The files include the final <filename>.config</filename> file, all the <filename>.o</filename>
219 files, the <filename>.a</filename> files, and so forth. 219 files, the <filename>.a</filename> files, and so forth.
220 Since each machine or BSP has its own separate build directory in its own separate branch 220 Since each machine or BSP has its own separate build directory in its own separate branch
@@ -229,18 +229,18 @@
229 As previously noted, the Yocto Project kernel has built-in Git integration. 229 As previously noted, the Yocto Project kernel has built-in Git integration.
230 However, these utilities are not the only way to work with the kernel repository. 230 However, these utilities are not the only way to work with the kernel repository.
231 The Yocto Project has not made changes to Git or to other tools that 231 The Yocto Project has not made changes to Git or to other tools that
232 would invalidate alternate workflows. 232 would invalidate alternate workflows.
233 Additionally, the way the kernel repository is constructed results in using 233 Additionally, the way the kernel repository is constructed results in using
234 only core Git functionality, thus allowing any number of tools or front ends to use the 234 only core Git functionality, thus allowing any number of tools or front ends to use the
235 resulting tree. 235 resulting tree.
236 </para> 236 </para>
237 237
238 <para> 238 <para>
239 This section contains several workflow examples. 239 This section contains several workflow examples.
240 Many of the examples use Git commands. 240 Many of the examples use Git commands.
241 You can find Git documentation at 241 You can find Git documentation at
242 <ulink url='http://git-scm.com/documentation'></ulink>. 242 <ulink url='http://git-scm.com/documentation'></ulink>.
243 You can find a simple overview of using Git with the Yocto Project in the 243 You can find a simple overview of using Git with the Yocto Project in the
244 "<ulink url='&YOCTO_DOCS_DEV_URL;#git'>Git</ulink>" 244 "<ulink url='&YOCTO_DOCS_DEV_URL;#git'>Git</ulink>"
245 section of the Yocto Project Development Manual. 245 section of the Yocto Project Development Manual.
246 </para> 246 </para>
@@ -249,25 +249,25 @@
249 <title>Change Inspection: Kernel Changes/Commits</title> 249 <title>Change Inspection: Kernel Changes/Commits</title>
250 250
251 <para> 251 <para>
252 A common question when working with a BSP or kernel is: 252 A common question when working with a BSP or kernel is:
253 "What changes have been applied to this tree?" 253 "What changes have been applied to this tree?"
254 </para> 254 </para>
255 255
256 <para> 256 <para>
257 In projects that have a collection of directories that 257 In projects that have a collection of directories that
258 contain patches to the kernel, it is possible to inspect or "grep" the contents 258 contain patches to the kernel, it is possible to inspect or "grep" the contents
259 of the directories to get a general feel for the changes. 259 of the directories to get a general feel for the changes.
260 This sort of patch inspection is not an efficient way to determine what has been done to the 260 This sort of patch inspection is not an efficient way to determine what has been done to the
261 kernel. 261 kernel.
262 The reason it is inefficient is because there are many optional patches that are 262 The reason it is inefficient is because there are many optional patches that are
263 selected based on the kernel type and the feature description. 263 selected based on the kernel type and the feature description.
264 Additionally, patches could exist in directories that are not included in the search. 264 Additionally, patches could exist in directories that are not included in the search.
265 </para> 265 </para>
266 266
267 <para> 267 <para>
268 A more efficient way to determine what has changed in the kernel is to use 268 A more efficient way to determine what has changed in the kernel is to use
269 Git and inspect or search the kernel tree. 269 Git and inspect or search the kernel tree.
270 This method gives you a full view of not only the source code modifications, 270 This method gives you a full view of not only the source code modifications,
271 but also provides the reasons for the changes. 271 but also provides the reasons for the changes.
272 </para> 272 </para>
273 273
@@ -277,11 +277,11 @@
277 <para> 277 <para>
278 Following are a few examples that show how to use Git to examine changes. 278 Following are a few examples that show how to use Git to examine changes.
279 Because the Yocto Project Git repository does not break existing Git 279 Because the Yocto Project Git repository does not break existing Git
280 functionality and because there exists many permutations of these types of 280 functionality and because there exists many permutations of these types of
281 commands, there are many more methods to discover changes. 281 commands, there are many more methods to discover changes.
282 <note> 282 <note>
283 Unless you provide a commit range 283 Unless you provide a commit range
284 (&lt;kernel-type&gt;..&lt;bsp&gt;-&lt;kernel-type&gt;), <filename>kernel.org</filename> history 284 (&lt;kernel-type&gt;..&lt;bsp&gt;-&lt;kernel-type&gt;), <filename>kernel.org</filename> history
285 is blended with Yocto Project changes. 285 is blended with Yocto Project changes.
286 </note> 286 </note>
287 <literallayout class='monospaced'> 287 <literallayout class='monospaced'>
@@ -301,27 +301,27 @@
301 301
302 # determine the change history of a particular file 302 # determine the change history of a particular file
303 &gt; git whatchanged &lt;path to file&gt; 303 &gt; git whatchanged &lt;path to file&gt;
304 304
305 # determine the commits which touch each line in a file 305 # determine the commits which touch each line in a file
306 &gt; git blame &lt;path to file&gt; 306 &gt; git blame &lt;path to file&gt;
307 </literallayout> 307 </literallayout>
308 </para> 308 </para>
309 </section> 309 </section>
310 310
311 <section id='show-a-particular-feature-or-branch-change'> 311 <section id='show-a-particular-feature-or-branch-change'>
312 <title>Show a Particular Feature or Branch Change</title> 312 <title>Show a Particular Feature or Branch Change</title>
313 313
314 <para> 314 <para>
315 Developers use tags in the Yocto Project kernel tree to divide changes for significant 315 Developers use tags in the Yocto Project kernel tree to divide changes for significant
316 features or branches. 316 features or branches.
317 Once you know a particular tag, you can use Git commands 317 Once you know a particular tag, you can use Git commands
318 to show changes associated with the tag and find the branches that contain 318 to show changes associated with the tag and find the branches that contain
319 the feature. 319 the feature.
320 <note> 320 <note>
321 Because BSP branch, <filename>kernel.org</filename>, and feature tags are all 321 Because BSP branch, <filename>kernel.org</filename>, and feature tags are all
322 present, there could be many tags. 322 present, there could be many tags.
323 </note> 323 </note>
324 The <filename>git show &lt;tag&gt;</filename> command shows changes that are tagged by 324 The <filename>git show &lt;tag&gt;</filename> command shows changes that are tagged by
325 a feature. 325 a feature.
326 Here is an example that shows changes tagged by the <filename>systemtap</filename> 326 Here is an example that shows changes tagged by the <filename>systemtap</filename>
327 feature: 327 feature:
@@ -339,7 +339,7 @@
339 339
340 <para> 340 <para>
341 You can use many other comparisons to isolate BSP and kernel changes. 341 You can use many other comparisons to isolate BSP and kernel changes.
342 For example, you can compare against <filename>kernel.org</filename> tags 342 For example, you can compare against <filename>kernel.org</filename> tags
343 such as the <filename>v3.4</filename> tag. 343 such as the <filename>v3.4</filename> tag.
344 </para> 344 </para>
345 </section> 345 </section>
@@ -350,29 +350,29 @@
350 350
351 <para> 351 <para>
352 Another common operation is to build a BSP supplied by the Yocto Project, make some 352 Another common operation is to build a BSP supplied by the Yocto Project, make some
353 changes, rebuild, and then test. 353 changes, rebuild, and then test.
354 Those local changes often need to be exported, shared or otherwise maintained. 354 Those local changes often need to be exported, shared or otherwise maintained.
355 </para> 355 </para>
356 356
357 <para> 357 <para>
358 Since the Yocto Project kernel source tree is backed by Git, this activity is 358 Since the Yocto Project kernel source tree is backed by Git, this activity is
359 much easier as compared to with previous releases. 359 much easier as compared to with previous releases.
360 Because Git tracks file modifications, additions and deletions, it is easy 360 Because Git tracks file modifications, additions and deletions, it is easy
361 to modify the code and later realize that you need to save the changes. 361 to modify the code and later realize that you need to save the changes.
362 It is also easy to determine what has changed. 362 It is also easy to determine what has changed.
363 This method also provides many tools to commit, undo and export those modifications. 363 This method also provides many tools to commit, undo and export those modifications.
364 </para> 364 </para>
365 365
366 <para> 366 <para>
367 This section and its sub-sections, describe general application of Git's 367 This section and its sub-sections, describe general application of Git's
368 <filename>push</filename> and <filename>pull</filename> commands, which are used to 368 <filename>push</filename> and <filename>pull</filename> commands, which are used to
369 get your changes upstream or source your code from an upstream repository. 369 get your changes upstream or source your code from an upstream repository.
370 The Yocto Project provides scripts that help you work in a collaborative development 370 The Yocto Project provides scripts that help you work in a collaborative development
371 environment. 371 environment.
372 For information on these scripts, see the 372 For information on these scripts, see the
373 "<ulink url='&YOCTO_DOCS_DEV_URL;#pushing-a-change-upstream'>Using Scripts to Push a Change 373 "<ulink url='&YOCTO_DOCS_DEV_URL;#pushing-a-change-upstream'>Using Scripts to Push a Change
374 Upstream and Request a Pull</ulink>" and 374 Upstream and Request a Pull</ulink>" and
375 "<ulink url='&YOCTO_DOCS_DEV_URL;#submitting-a-patch'>Using Email to Submit a Patch</ulink>" 375 "<ulink url='&YOCTO_DOCS_DEV_URL;#submitting-a-patch'>Using Email to Submit a Patch</ulink>"
376 sections in the Yocto Project Development Manual. 376 sections in the Yocto Project Development Manual.
377 </para> 377 </para>
378 378
@@ -380,7 +380,7 @@
380 There are many ways to save kernel modifications. 380 There are many ways to save kernel modifications.
381 The technique employed 381 The technique employed
382 depends on the destination for the patches: 382 depends on the destination for the patches:
383 383
384 <itemizedlist> 384 <itemizedlist>
385 <listitem><para>Bulk storage</para></listitem> 385 <listitem><para>Bulk storage</para></listitem>
386 <listitem><para>Internal sharing either through patches or by using Git</para></listitem> 386 <listitem><para>Internal sharing either through patches or by using Git</para></listitem>
@@ -391,7 +391,7 @@
391 </para> 391 </para>
392 392
393 <para> 393 <para>
394 Because of the following list of issues, the destination of the patches also influences 394 Because of the following list of issues, the destination of the patches also influences
395 the method for gathering them: 395 the method for gathering them:
396 396
397 <itemizedlist> 397 <itemizedlist>
@@ -405,24 +405,24 @@
405 <title>Bulk Export</title> 405 <title>Bulk Export</title>
406 406
407 <para> 407 <para>
408 This section describes how you can "bulk" export changes that have not 408 This section describes how you can "bulk" export changes that have not
409 been separated or divided. 409 been separated or divided.
410 This situation works well when you are simply storing patches outside of the kernel 410 This situation works well when you are simply storing patches outside of the kernel
411 source repository, either permanently or temporarily, and you are not committing 411 source repository, either permanently or temporarily, and you are not committing
412 incremental changes during development. 412 incremental changes during development.
413 <note> 413 <note>
414 This technique is not appropriate for full integration of upstream submission 414 This technique is not appropriate for full integration of upstream submission
415 because changes are not properly divided and do not provide an avenue for per-change 415 because changes are not properly divided and do not provide an avenue for per-change
416 commit messages. 416 commit messages.
417 Therefore, this example assumes that changes have not been committed incrementally 417 Therefore, this example assumes that changes have not been committed incrementally
418 during development and that you simply must gather and export them. 418 during development and that you simply must gather and export them.
419 </note> 419 </note>
420 <literallayout class='monospaced'> 420 <literallayout class='monospaced'>
421 # bulk export of ALL modifications without separation or division 421 # bulk export of ALL modifications without separation or division
422 # of the changes 422 # of the changes
423 423
424 $ git add . 424 $ git add .
425 $ git commit -s -a -m &lt;msg&gt; 425 $ git commit -s -a -m &lt;msg&gt;
426 or 426 or
427 $ git commit -s -a # and interact with $EDITOR 427 $ git commit -s -a # and interact with $EDITOR
428 </literallayout> 428 </literallayout>
@@ -447,8 +447,8 @@
447 <para> 447 <para>
448 This section describes how to save modifications when you are making incremental 448 This section describes how to save modifications when you are making incremental
449 commits or practicing planned sharing. 449 commits or practicing planned sharing.
450 The examples in this section assume that you have incrementally committed 450 The examples in this section assume that you have incrementally committed
451 changes to the tree during development and now need to export them. 451 changes to the tree during development and now need to export them.
452 The sections that follow 452 The sections that follow
453 describe how you can export your changes internally through either patches or by 453 describe how you can export your changes internally through either patches or by
454 using Git commands. 454 using Git commands.
@@ -456,7 +456,7 @@
456 456
457 <para> 457 <para>
458 During development, the following commands are of interest. 458 During development, the following commands are of interest.
459 For full Git documentation, refer to the Git documentation at 459 For full Git documentation, refer to the Git documentation at
460 <ulink url='http://github.com'></ulink>. 460 <ulink url='http://github.com'></ulink>.
461 461
462 <literallayout class='monospaced'> 462 <literallayout class='monospaced'>
@@ -476,15 +476,15 @@
476 </para> 476 </para>
477 477
478 <para> 478 <para>
479 Distributed development with Git is possible when you use a universally 479 Distributed development with Git is possible when you use a universally
480 agreed-upon unique commit identifier (set by the creator of the commit) that maps to a 480 agreed-upon unique commit identifier (set by the creator of the commit) that maps to a
481 specific change set with a specific parent. 481 specific change set with a specific parent.
482 This identifier is created for you when 482 This identifier is created for you when
483 you create a commit, and is re-created when you amend, alter or re-apply 483 you create a commit, and is re-created when you amend, alter or re-apply
484 a commit. 484 a commit.
485 As an individual in isolation, this is of no interest. 485 As an individual in isolation, this is of no interest.
486 However, if you 486 However, if you
487 intend to share your tree with normal Git <filename>push</filename> and 487 intend to share your tree with normal Git <filename>push</filename> and
488 <filename>pull</filename> operations for 488 <filename>pull</filename> operations for
489 distributed development, you should consider the ramifications of changing a 489 distributed development, you should consider the ramifications of changing a
490 commit that you have already shared with others. 490 commit that you have already shared with others.
@@ -492,7 +492,7 @@
492 492
493 <para> 493 <para>
494 Assuming that the changes have not been pushed upstream, or pulled into 494 Assuming that the changes have not been pushed upstream, or pulled into
495 another repository, you can update both the commit content and commit messages 495 another repository, you can update both the commit content and commit messages
496 associated with development by using the following commands: 496 associated with development by using the following commands:
497 497
498 <literallayout class='monospaced'> 498 <literallayout class='monospaced'>
@@ -502,7 +502,7 @@
502 </literallayout> 502 </literallayout>
503 </para> 503 </para>
504 504
505 <para> 505 <para>
506 Again, assuming that the changes have not been pushed upstream, and that 506 Again, assuming that the changes have not been pushed upstream, and that
507 no pending works-in-progress exist (use <filename>git status</filename> to check), then 507 no pending works-in-progress exist (use <filename>git status</filename> to check), then
508 you can revert (undo) commits by using the following commands: 508 you can revert (undo) commits by using the following commands:
@@ -521,12 +521,12 @@
521 <para> 521 <para>
522 You can create branches, "cherry-pick" changes, or perform any number of Git 522 You can create branches, "cherry-pick" changes, or perform any number of Git
523 operations until the commits are in good order for pushing upstream 523 operations until the commits are in good order for pushing upstream
524 or for pull requests. 524 or for pull requests.
525 After a <filename>push</filename> or <filename>pull</filename> command, 525 After a <filename>push</filename> or <filename>pull</filename> command,
526 commits are normally considered 526 commits are normally considered
527 "permanent" and you should not modify them. 527 "permanent" and you should not modify them.
528 If the commits need to be changed, you can incrementally do so with new commits. 528 If the commits need to be changed, you can incrementally do so with new commits.
529 These practices follow standard Git workflow and the <filename>kernel.org</filename> best 529 These practices follow standard Git workflow and the <filename>kernel.org</filename> best
530 practices, which is recommended. 530 practices, which is recommended.
531 <note> 531 <note>
532 It is recommended to tag or branch before adding changes to a Yocto Project 532 It is recommended to tag or branch before adding changes to a Yocto Project
@@ -535,26 +535,26 @@
535 reference point to facilitate locating and exporting local changes. 535 reference point to facilitate locating and exporting local changes.
536 </note> 536 </note>
537 </para> 537 </para>
538 538
539 <section id='export-internally-via-patches'> 539 <section id='export-internally-via-patches'>
540 <title>Exporting Changes Internally by Using Patches</title> 540 <title>Exporting Changes Internally by Using Patches</title>
541 541
542 <para> 542 <para>
543 This section describes how you can extract committed changes from a working directory 543 This section describes how you can extract committed changes from a working directory
544 by exporting them as patches. 544 by exporting them as patches.
545 Once the changes have been extracted, you can use the patches for upstream submission, 545 Once the changes have been extracted, you can use the patches for upstream submission,
546 place them in a Yocto Project template for automatic kernel patching, 546 place them in a Yocto Project template for automatic kernel patching,
547 or apply them in many other common uses. 547 or apply them in many other common uses.
548 </para> 548 </para>
549 549
550 <para> 550 <para>
551 This example shows how to create a directory with sequentially numbered patches. 551 This example shows how to create a directory with sequentially numbered patches.
552 Once the directory is created, you can apply it to a repository using the 552 Once the directory is created, you can apply it to a repository using the
553 <filename>git am</filename> command to reproduce the original commit and all 553 <filename>git am</filename> command to reproduce the original commit and all
554 the related information such as author, date, commit log, and so forth. 554 the related information such as author, date, commit log, and so forth.
555 <note> 555 <note>
556 The new commit identifiers (ID) will be generated upon re-application. 556 The new commit identifiers (ID) will be generated upon re-application.
557 This action reflects that the commit is now applied to an underlying commit 557 This action reflects that the commit is now applied to an underlying commit
558 with a different ID. 558 with a different ID.
559 </note> 559 </note>
560 <literallayout class='monospaced'> 560 <literallayout class='monospaced'>
@@ -581,19 +581,19 @@
581 $ git format-patch -o &lt;save dir&gt; &lt;commit id&gt; 581 $ git format-patch -o &lt;save dir&gt; &lt;commit id&gt;
582 $ git format-patch -o &lt;save dir&gt; &lt;rev-list&gt; 582 $ git format-patch -o &lt;save dir&gt; &lt;rev-list&gt;
583 </literallayout> 583 </literallayout>
584 </para> 584 </para>
585 </section> 585 </section>
586 586
587 <section id='export-internally-via-git'> 587 <section id='export-internally-via-git'>
588 <title>Exporting Changes Internally by Using Git</title> 588 <title>Exporting Changes Internally by Using Git</title>
589 589
590 <para> 590 <para>
591 This section describes how you can export changes from a working directory 591 This section describes how you can export changes from a working directory
592 by pushing the changes into a master repository or by making a pull request. 592 by pushing the changes into a master repository or by making a pull request.
593 Once you have pushed the changes to the master repository, you can then 593 Once you have pushed the changes to the master repository, you can then
594 pull those same changes into a new kernel build at a later time. 594 pull those same changes into a new kernel build at a later time.
595 </para> 595 </para>
596 596
597 <para> 597 <para>
598 Use this command form to push the changes: 598 Use this command form to push the changes:
599 <literallayout class='monospaced'> 599 <literallayout class='monospaced'>
@@ -604,7 +604,7 @@
604 604
605 <para> 605 <para>
606 For example, the following command pushes the changes from your local branch 606 For example, the following command pushes the changes from your local branch
607 <filename>yocto/standard/common-pc/base</filename> to the remote branch with the same name 607 <filename>yocto/standard/common-pc/base</filename> to the remote branch with the same name
608 in the master repository <filename>//git.mycompany.com/pub/git/kernel-3.4</filename>. 608 in the master repository <filename>//git.mycompany.com/pub/git/kernel-3.4</filename>.
609 <literallayout class='monospaced'> 609 <literallayout class='monospaced'>
610 $ git push ssh://git.mycompany.com/pub/git/kernel-3.4 \ 610 $ git push ssh://git.mycompany.com/pub/git/kernel-3.4 \
@@ -613,7 +613,7 @@
613 </para> 613 </para>
614 614
615 <para> 615 <para>
616 A pull request entails using the <filename>git request-pull</filename> command to compose 616 A pull request entails using the <filename>git request-pull</filename> command to compose
617 an email to the 617 an email to the
618 maintainer requesting that a branch be pulled into the master repository, see 618 maintainer requesting that a branch be pulled into the master repository, see
619 <ulink url='http://github.com/guides/pull-requests'></ulink> for an example. 619 <ulink url='http://github.com/guides/pull-requests'></ulink> for an example.
@@ -622,7 +622,7 @@
622 changes, but are not covered in this document. 622 changes, but are not covered in this document.
623 </note> 623 </note>
624 </para> 624 </para>
625 </section> 625 </section>
626 </section> 626 </section>
627 627
628 <section id='export-for-external-upstream-submission'> 628 <section id='export-for-external-upstream-submission'>
@@ -636,12 +636,12 @@
636 This method allows easy review and integration of the changes. 636 This method allows easy review and integration of the changes.
637 <note> 637 <note>
638 Before sending patches for review be sure you understand the 638 Before sending patches for review be sure you understand the
639 community standards for submitting and documenting changes and follow their best practices. 639 community standards for submitting and documenting changes and follow their best practices.
640 For example, kernel patches should follow standards such as: 640 For example, kernel patches should follow standards such as:
641 <itemizedlist> 641 <itemizedlist>
642 <listitem><para> 642 <listitem><para>
643 <ulink url='http://linux.yyz.us/patch-format.html'></ulink></para></listitem> 643 <ulink url='http://linux.yyz.us/patch-format.html'></ulink></para></listitem>
644 <listitem><para>Documentation/SubmittingPatches (in any linux 644 <listitem><para>Documentation/SubmittingPatches (in any linux
645 kernel source tree)</para></listitem> 645 kernel source tree)</para></listitem>
646 </itemizedlist> 646 </itemizedlist>
647 </note> 647 </note>
@@ -651,30 +651,30 @@
651 The messages used to commit changes are a large part of these standards. 651 The messages used to commit changes are a large part of these standards.
652 Consequently, be sure that the headers for each commit have the required information. 652 Consequently, be sure that the headers for each commit have the required information.
653 For information on how to follow the Yocto Project commit message standards, see the 653 For information on how to follow the Yocto Project commit message standards, see the
654 "<ulink url='&YOCTO_DOCS_DEV_URL;#how-to-submit-a-change'>How to Submit a 654 "<ulink url='&YOCTO_DOCS_DEV_URL;#how-to-submit-a-change'>How to Submit a
655 Change</ulink>" section in the Yocto Project Development Manual. 655 Change</ulink>" section in the Yocto Project Development Manual.
656 </para> 656 </para>
657 657
658 <para> 658 <para>
659 If the initial commits were not properly documented or do not meet those standards, 659 If the initial commits were not properly documented or do not meet those standards,
660 you can re-base by using the <filename>git rebase -i</filename> command to 660 you can re-base by using the <filename>git rebase -i</filename> command to
661 manipulate the commits and 661 manipulate the commits and
662 get them into the required format. 662 get them into the required format.
663 Other techniques such as branching and cherry-picking commits are also viable options. 663 Other techniques such as branching and cherry-picking commits are also viable options.
664 </para> 664 </para>
665 665
666 <para> 666 <para>
667 Once you complete the commits, you can generate the email that sends the patches 667 Once you complete the commits, you can generate the email that sends the patches
668 to the maintainer(s) or lists that review and integrate changes. 668 to the maintainer(s) or lists that review and integrate changes.
669 The command <filename>git send-email</filename> is commonly used to ensure 669 The command <filename>git send-email</filename> is commonly used to ensure
670 that patches are properly 670 that patches are properly
671 formatted for easy application and avoid mailer-induced patch damage. 671 formatted for easy application and avoid mailer-induced patch damage.
672 </para> 672 </para>
673 673
674 <para> 674 <para>
675 The following is an example of dumping patches for external submission: 675 The following is an example of dumping patches for external submission:
676 <literallayout class='monospaced'> 676 <literallayout class='monospaced'>
677 # dump the last 4 commits 677 # dump the last 4 commits
678 $ git format-patch --thread -n -o ~/rr/ HEAD^^^^ 678 $ git format-patch --thread -n -o ~/rr/ HEAD^^^^
679 $ git send-email --compose --subject '[RFC 0/N] &lt;patch series summary&gt;' \ 679 $ git send-email --compose --subject '[RFC 0/N] &lt;patch series summary&gt;' \
680 --to foo@yoctoproject.org --to bar@yoctoproject.org \ 680 --to foo@yoctoproject.org --to bar@yoctoproject.org \
@@ -690,17 +690,17 @@
690 690
691 <para> 691 <para>
692 When you want to export changes for import into another 692 When you want to export changes for import into another
693 Source Code Manager (SCM), you can use any of the previously discussed 693 Source Code Manager (SCM), you can use any of the previously discussed
694 techniques. 694 techniques.
695 However, if the patches are manually applied to a secondary tree and then 695 However, if the patches are manually applied to a secondary tree and then
696 that tree is checked into the SCM, you can lose change information such as 696 that tree is checked into the SCM, you can lose change information such as
697 commit logs. 697 commit logs.
698 This process is not recommended. 698 This process is not recommended.
699 </para> 699 </para>
700 700
701 <para> 701 <para>
702 Many SCMs can directly import Git commits, or can translate Git patches so that 702 Many SCMs can directly import Git commits, or can translate Git patches so that
703 information is not lost. 703 information is not lost.
704 Those facilities are SCM-dependent and you should use them whenever possible. 704 Those facilities are SCM-dependent and you should use them whenever possible.
705 </para> 705 </para>
706 </section> 706 </section>
@@ -710,15 +710,15 @@
710 <title>Working with the Yocto Project Kernel in Another SCM</title> 710 <title>Working with the Yocto Project Kernel in Another SCM</title>
711 711
712 <para> 712 <para>
713 This section describes kernel development in an SCM other than Git, 713 This section describes kernel development in an SCM other than Git,
714 which is not the same as exporting changes to another SCM described earlier. 714 which is not the same as exporting changes to another SCM described earlier.
715 For this scenario, you use the OpenEmbedded build system to 715 For this scenario, you use the OpenEmbedded build system to
716 develop the kernel in a different SCM. 716 develop the kernel in a different SCM.
717 The following must be true for you to accomplish this: 717 The following must be true for you to accomplish this:
718 <itemizedlist> 718 <itemizedlist>
719 <listitem><para>The delivered Yocto Project kernel must be exported into the second 719 <listitem><para>The delivered Yocto Project kernel must be exported into the second
720 SCM.</para></listitem> 720 SCM.</para></listitem>
721 <listitem><para>Development must be exported from that secondary SCM into a 721 <listitem><para>Development must be exported from that secondary SCM into a
722 format that can be used by the OpenEmbedded build system.</para></listitem> 722 format that can be used by the OpenEmbedded build system.</para></listitem>
723 </itemizedlist> 723 </itemizedlist>
724 </para> 724 </para>
@@ -728,7 +728,7 @@
728 728
729 <para> 729 <para>
730 Depending on the SCM, it might be possible to export the entire Yocto Project 730 Depending on the SCM, it might be possible to export the entire Yocto Project
731 kernel Git repository, branches and all, into a new environment. 731 kernel Git repository, branches and all, into a new environment.
732 This method is preferred because it has the most flexibility and potential to maintain 732 This method is preferred because it has the most flexibility and potential to maintain
733 the meta data associated with each commit. 733 the meta data associated with each commit.
734 </para> 734 </para>
@@ -750,11 +750,11 @@
750 </para> 750 </para>
751 751
752 <para> 752 <para>
753 You could now relocate the CVS repository and use it in a centralized manner. 753 You could now relocate the CVS repository and use it in a centralized manner.
754 </para> 754 </para>
755 755
756 <para> 756 <para>
757 The following commands illustrate how you can condense and merge two BSPs into a 757 The following commands illustrate how you can condense and merge two BSPs into a
758 second SCM: 758 second SCM:
759 <literallayout class='monospaced'> 759 <literallayout class='monospaced'>
760 $ git checkout yocto/standard/common-pc/base 760 $ git checkout yocto/standard/common-pc/base
@@ -768,7 +768,7 @@
768 768
769 <section id='importing-changes-for-build'> 769 <section id='importing-changes-for-build'>
770 <title>Importing Changes for the Build</title> 770 <title>Importing Changes for the Build</title>
771 771
772 <para> 772 <para>
773 Once development has reached a suitable point in the second development 773 Once development has reached a suitable point in the second development
774 environment, you need to export the changes as patches. 774 environment, you need to export the changes as patches.
@@ -782,12 +782,12 @@
782 <title>Creating a BSP Based on an Existing Similar BSP</title> 782 <title>Creating a BSP Based on an Existing Similar BSP</title>
783 783
784 <para> 784 <para>
785 This section overviews the process of creating a BSP based on an 785 This section overviews the process of creating a BSP based on an
786 existing similar BSP. 786 existing similar BSP.
787 The information is introductory in nature and does not provide step-by-step examples. 787 The information is introductory in nature and does not provide step-by-step examples.
788 For detailed information on how to create a new BSP, see 788 For detailed information on how to create a new BSP, see
789 the "<ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-yocto-bsp-script'>Creating a New BSP Layer Using the yocto-bsp Script</ulink>" section in the 789 the "<ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-yocto-bsp-script'>Creating a New BSP Layer Using the yocto-bsp Script</ulink>" section in the
790 Yocto Project Board Support Package (BSP) Developer's Guide, or see the 790 Yocto Project Board Support Package (BSP) Developer's Guide, or see the
791 <ulink url='&YOCTO_WIKI_URL;/wiki/Transcript:_creating_one_generic_Atom_BSP_from_another'>Transcript:_creating_one_generic_Atom_BSP_from_another</ulink> 791 <ulink url='&YOCTO_WIKI_URL;/wiki/Transcript:_creating_one_generic_Atom_BSP_from_another'>Transcript:_creating_one_generic_Atom_BSP_from_another</ulink>
792 wiki page. 792 wiki page.
793 </para> 793 </para>
@@ -796,42 +796,42 @@
796 The basic steps you need to follow are: 796 The basic steps you need to follow are:
797 <orderedlist> 797 <orderedlist>
798 <listitem><para><emphasis>Make sure you have set up a local Source Directory:</emphasis> 798 <listitem><para><emphasis>Make sure you have set up a local Source Directory:</emphasis>
799 You must create a local 799 You must create a local
800 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> 800 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
801 by either creating a Git repository (recommended) or 801 by either creating a Git repository (recommended) or
802 extracting a Yocto Project release tarball.</para></listitem> 802 extracting a Yocto Project release tarball.</para></listitem>
803 <listitem><para><emphasis>Choose an existing BSP available with the Yocto Project:</emphasis> 803 <listitem><para><emphasis>Choose an existing BSP available with the Yocto Project:</emphasis>
804 Try to map your board features as closely to the features of a BSP that is 804 Try to map your board features as closely to the features of a BSP that is
805 already supported and exists in the Yocto Project. 805 already supported and exists in the Yocto Project.
806 Starting with something as close as possible to your board makes developing 806 Starting with something as close as possible to your board makes developing
807 your BSP easier. 807 your BSP easier.
808 You can find all the BSPs that are supported and ship with the Yocto Project 808 You can find all the BSPs that are supported and ship with the Yocto Project
809 on the Yocto Project's Download page at 809 on the Yocto Project's Download page at
810 <ulink url='&YOCTO_HOME_URL;/download'></ulink>.</para></listitem> 810 <ulink url='&YOCTO_HOME_URL;/download'></ulink>.</para></listitem>
811 <listitem><para><emphasis>Be sure you have the Base BSP:</emphasis> 811 <listitem><para><emphasis>Be sure you have the Base BSP:</emphasis>
812 You need to either have a local Git repository of the base BSP set up or 812 You need to either have a local Git repository of the base BSP set up or
813 have downloaded and extracted the files from a release BSP tarball. 813 have downloaded and extracted the files from a release BSP tarball.
814 Either method gives you access to the BSP source files.</para></listitem> 814 Either method gives you access to the BSP source files.</para></listitem>
815 <listitem><para><emphasis>Make a copy of the existing BSP, thus isolating your new 815 <listitem><para><emphasis>Make a copy of the existing BSP, thus isolating your new
816 BSP work:</emphasis> 816 BSP work:</emphasis>
817 Copying the existing BSP file structure gives you a new area in which to work.</para></listitem> 817 Copying the existing BSP file structure gives you a new area in which to work.</para></listitem>
818 <listitem><para><emphasis>Make configuration and recipe changes to your new BSP:</emphasis> 818 <listitem><para><emphasis>Make configuration and recipe changes to your new BSP:</emphasis>
819 Configuration changes involve the files in the BSP's <filename>conf</filename> 819 Configuration changes involve the files in the BSP's <filename>conf</filename>
820 directory. 820 directory.
821 Changes include creating a machine-specific configuration file and editing the 821 Changes include creating a machine-specific configuration file and editing the
822 <filename>layer.conf</filename> file. 822 <filename>layer.conf</filename> file.
823 The configuration changes identify the kernel you will be using. 823 The configuration changes identify the kernel you will be using.
824 Recipe changes include removing, modifying, or adding new recipe files that 824 Recipe changes include removing, modifying, or adding new recipe files that
825 instruct the build process on what features to include in the image.</para></listitem> 825 instruct the build process on what features to include in the image.</para></listitem>
826 <listitem><para><emphasis>Prepare for the build:</emphasis> 826 <listitem><para><emphasis>Prepare for the build:</emphasis>
827 Before you actually initiate the build, you need to set up the build environment 827 Before you actually initiate the build, you need to set up the build environment
828 by sourcing the environment initialization script. 828 by sourcing the environment initialization script.
829 After setting up the environment, you need to make some build configuration 829 After setting up the environment, you need to make some build configuration
830 changes to the <filename>local.conf</filename> and <filename>bblayers.conf</filename> 830 changes to the <filename>local.conf</filename> and <filename>bblayers.conf</filename>
831 files.</para></listitem> 831 files.</para></listitem>
832 <listitem><para><emphasis>Build the image:</emphasis> 832 <listitem><para><emphasis>Build the image:</emphasis>
833 The OpenEmbedded build system uses BitBake to create the image. 833 The OpenEmbedded build system uses BitBake to create the image.
834 You need to decide on the type of image you are going to build (e.g. minimal, base, 834 You need to decide on the type of image you are going to build (e.g. minimal, base,
835 core, sato, and so forth) and then start the build using the <filename>bitbake</filename> 835 core, sato, and so forth) and then start the build using the <filename>bitbake</filename>
836 command.</para></listitem> 836 command.</para></listitem>
837 </orderedlist> 837 </orderedlist>
@@ -851,8 +851,8 @@
851 </para> 851 </para>
852 852
853 <para> 853 <para>
854 You can use the above Git command to report modified, removed, or added files. 854 You can use the above Git command to report modified, removed, or added files.
855 You should commit those changes to the tree regardless of whether they will be saved, 855 You should commit those changes to the tree regardless of whether they will be saved,
856 exported, or used. 856 exported, or used.
857 Once you commit the changes you need to rebuild the kernel. 857 Once you commit the changes you need to rebuild the kernel.
858 </para> 858 </para>