summaryrefslogtreecommitdiffstats
path: root/documentation/kernel-manual/kernel-how-to.xml
diff options
context:
space:
mode:
authorScott Rifenbark <scott.m.rifenbark@intel.com>2010-11-29 17:31:24 -0800
committerSaul Wold <Saul.Wold@intel.com>2010-12-10 22:01:19 -0800
commit5bda926c80d825470ac3ba72f3682b469308dcad (patch)
tree6d11016ba997986c431157fb19d8138007be23f2 /documentation/kernel-manual/kernel-how-to.xml
parent1722898e16f8132df957442bb62b1e504b6bd67d (diff)
downloadpoky-5bda926c80d825470ac3ba72f3682b469308dcad.tar.gz
documentation/kernel-manual/kerenel-how-to.xml: Edits to clean up text.
Re-writing up to the "Export for External (Upstream) Submission" section. I am cleaning up the English and style. Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
Diffstat (limited to 'documentation/kernel-manual/kernel-how-to.xml')
-rw-r--r--documentation/kernel-manual/kernel-how-to.xml779
1 files changed, 438 insertions, 341 deletions
diff --git a/documentation/kernel-manual/kernel-how-to.xml b/documentation/kernel-manual/kernel-how-to.xml
index 7f3eac3d3b..d32ea20b34 100644
--- a/documentation/kernel-manual/kernel-how-to.xml
+++ b/documentation/kernel-manual/kernel-how-to.xml
@@ -17,15 +17,15 @@
17<!-- <listitem><para>Series &amp; Configuration Compiler</para></listitem> 17<!-- <listitem><para>Series &amp; Configuration Compiler</para></listitem>
18 <listitem><para>kgit</para></listitem> --> 18 <listitem><para>kgit</para></listitem> -->
19 <listitem><para>Workflow examples</para></listitem> 19 <listitem><para>Workflow examples</para></listitem>
20 <listitem><para>Source Code Manager (SCM)</para></listitem> 20<!-- <listitem><para>Source Code Manager (SCM)</para></listitem>
21<!-- <listitem><para>Board Support Package (BSP) template migration</para></listitem> --> 21 <listitem><para>Board Support Package (BSP) template migration</para></listitem>
22 <listitem><para>BSP creation</para></listitem> 22 <listitem><para>BSP creation</para></listitem>
23 <listitem><para>Patching</para></listitem> 23 <listitem><para>Patching</para></listitem>
24 <listitem><para>Updating BSP patches and configuration</para></listitem> 24 <listitem><para>Updating BSP patches and configuration</para></listitem>
25<!-- <listitem><para>guilt</para></listitem> 25 <listitem><para>guilt</para></listitem>
26 <listitem><para>scc file example</para></listitem> --> 26 <listitem><para>scc file example</para></listitem>
27 <listitem><para>"dirty" string</para></listitem> 27 <listitem><para>"dirty" string</para></listitem>
28<!-- <listitem><para>Transition kernel layer</para></listitem> --> 28 <listitem><para>Transition kernel layer</para></listitem> -->
29 </itemizedlist> 29 </itemizedlist>
30 </para> 30 </para>
31</section> 31</section>
@@ -33,90 +33,91 @@
33 <section id='tree-construction'> 33 <section id='tree-construction'>
34 <title>Tree Construction</title> 34 <title>Tree Construction</title>
35 <para> 35 <para>
36The Yocto Project kernel repository, as shipped with the product, is created by 36 The Yocto Project kernel repository, as shipped with the product, is created by
37compiling and executing the set of feature descriptions for every BSP/feature 37 compiling and executing the set of feature descriptions for every BSP/feature
38in the product. Those feature descriptions list all necessary patches, 38 in the product.
39configuration, branching, tagging and feature divisions found in the kernel. 39 Those feature descriptions list all necessary patches,
40</para> 40 configuration, branching, tagging and feature divisions found in the kernel.
41<para> 41 </para>
42The files used to describe all the valid features and BSPs in the Yocto Project 42 <para>
43kernel can be found in any clone of the kernel git tree. The directory 43 You can find the files used to describe all the valid features and BSPs in the Yocto Project
44wrs/cfg/kernel-cache/ is a snapshot of all the kernel configuration and 44 kernel in any clone of the kernel git tree.
45feature descriptions (.scc) that were used to build the kernel repository. 45 The directory <filename>wrs/cfg/kernel-cache/</filename> is a snapshot of all the kernel
46It should however be noted, that browsing the snapshot of feature 46 configuration and feature descriptions (.scc) used to build the kernel repository.
47descriptions and patches is not an effective way to determine what is in a 47 You should realize, however, that browsing the snapshot of feature
48particular kernel branch. Using git directly to get insight into the changes 48 descriptions and patches is not an effective way to determine what is in a
49in a branch is more efficient and a more flexible way to inspect changes to 49 particular kernel branch.
50the kernel. Examples of using git to inspect kernel commits are in the 50 Instead, you should use git directly to discover the changes
51following sections. 51 in a branch.
52</para> 52 Using git is a efficient and flexible way to inspect changes to the kernel.
53<para> 53 For examples showing how to use git to inspect kernel commits, see the following sections
54As a reminder, it is envisioned that a ground up reconstruction of the 54 in this chapter.
55complete kernel tree is an action only taken by Yocto Project team during an 55 </para>
56active development cycle. When an end user creates a project, it takes 56 <note><para>
57advantage of this complete tree in order to efficiently place a git tree 57 Ground up reconstruction of the complete kernel tree is an action only taken by the
58within their project. 58 Yocto Project team during an active development cycle.
59</para> 59 Creating a project takes advantage of this complete tree in order to
60<para> 60 place efficiently a git tree within the project.
61The general flow of the project specific kernel tree construction is as follows: 61 </para></note>
62<orderedlist> 62 <para>
63 <listitem><para>a top level kernel feature is passed to the kernel build subsystem, 63 The general flow for constructing a project-specific kernel tree is as follows:
64 normally this is a BSP for a particular kernel type.</para></listitem> 64 <orderedlist>
65 65 <listitem><para>A top-level kernel feature is passed to the kernel build subsystem.
66 <listitem><para>the file that describes the top level feature is located by searching 66 Normally, this is a BSP for a particular kernel type.</para></listitem>
67 system directories:</para>
68
69 <itemizedlist>
70 <listitem><para>the kernel-cache under linux/wrs/cfg/kernel-cache</para></listitem>
71<!-- <listitem><para>kernel-*-cache directories in layers</para></listitem> -->
72 <listitem><para>recipe SRC_URIs</para></listitem>
73<!-- <listitem><para>configured and default templates</para></listitem> -->
74 </itemizedlist>
75 67
76 <para>In a typical build a feature description of the format: 68 <listitem><para>The file that describes the top-level feature is located by searching
77 &lt;bsp name&gt;-&lt;kernel type&gt;.scc is the target of the search. 69 these system directories:</para>
78 </para></listitem>
79 70
80 <listitem><para>once located, the feature description is compiled into a simple script 71 <itemizedlist>
81 of actions, or an existing equivalent script which was part of the 72 <listitem><para>The kernel-cache under
82 shipped kernel is located.</para></listitem> 73 <filename>linux/wrs/cfg/kernel-cache</filename></para></listitem>
74<!-- <listitem><para>kernel-*-cache directories in layers</para></listitem> -->
75 <listitem><para>Recipe SRC_URIs</para></listitem>
76<!-- <listitem><para>configured and default templates</para></listitem> -->
77 </itemizedlist>
83 78
84 <listitem><para>extra features are appended to the top level feature description. Extra 79 <para>For a typical build a feature description of the format:
85 features can come from the KERNEL_FEATURES variable in recipes.</para></listitem> 80 &lt;bsp name&gt;-&lt;kernel type&gt;.scc is the target of the search.
81 </para></listitem>
86 82
87 <listitem><para>each extra feature is located, compiled and appended to the script from 83 <listitem><para>Once located, the feature description is either compiled into a simple script
88 step #3</para></listitem> 84 of actions, or an existing equivalent script that was part of the
85 shipped kernel is located.</para></listitem>
89 86
90 <listitem><para>the script is executed, and a meta-series is produced. The meta-series 87 <listitem><para>Extra features are appended to the top-level feature description.
91 is a description of all the branches, tags, patches and configuration that 88 These features can come from the KERNEL_FEATURES variable in recipes.</para></listitem>
92 need to be applied to the base git repository to completely create the
93 "bsp_name-kernel_type".</para></listitem>
94 89
95 <listitem><para>the base repository is cloned, and the actions 90 <listitem><para>Each extra feature is located, compiled and appended to the script from
96 listed in the meta-series are applied to the tree.</para></listitem> 91 step #3</para></listitem>
97 92
98 <listitem><para>the git repository is left with the desired branch checked out and any 93 <listitem><para>The script is executed, and a meta-series is produced.
99 required branching, patching and tagging has been performed.</para></listitem> 94 The meta-series is a description of all the branches, tags, patches and configuration that
100</orderedlist> 95 needs to be applied to the base git repository to completely create the
101</para> 96 "bsp_name-kernel_type".</para></listitem>
102 97
103<para> 98 <listitem><para>The base repository is cloned, and the actions
104The tree is now ready for configuration and compilation. Those two topics will 99 listed in the meta-series are applied to the tree.</para></listitem>
105be covered below.
106</para>
107 100
108<note><para>The end user generated meta-series adds to the kernel as shipped with 101 <listitem><para>The git repository is left with the desired branch checked out and any
109 the Yocto Project release. Any add-ons and configuration data are applied 102 required branching, patching and tagging has been performed.</para></listitem>
110 to the end of an existing branch. The full repository generation that 103 </orderedlist>
111 is found in the linux-2.6-windriver.git is the combination of all 104 </para>
112 supported boards and configurations.
113</para></note>
114 105
115<para> 106 <para>
116This technique is flexible and allows the seamless blending of an immutable 107 The tree is now ready for configuration and compilation.
117history with additional deployment specific patches. Any additions to the 108 </para>
118kernel become an integrated part of the branches. 109
119</para> 110 <note><para>The end-user generated meta-series adds to the kernel as shipped with
111 the Yocto Project release.
112 Any add-ons and configuration data are applied to the end of an existing branch.
113 The full repository generation that is found in the
114 <filename>linux-2.6-windriver.git</filename> is the combination of all
115 supported boards and configurations.</para>
116
117 <para>This technique is flexible and allows the seamless blending of an immutable
118 history with additional deployment specific patches.
119 Any additions to the kernel become an integrated part of the branches.
120 </para></note>
120 121
121<!-- <note><para>It is key that feature descriptions indicate if any branches are 122<!-- <note><para>It is key that feature descriptions indicate if any branches are
122 required, since the build system cannot automatically decide where a 123 required, since the build system cannot automatically decide where a
@@ -132,7 +133,7 @@ kernel become an integrated part of the branches.
132 </para> 133 </para>
133</note> --> 134</note> -->
134 135
135<para> 136<!-- <para>
136A summary of end user tree construction activities follow: 137A summary of end user tree construction activities follow:
137<itemizedlist> 138<itemizedlist>
138 <listitem><para>compile and link a full top-down kernel description from feature descriptions</para></listitem> 139 <listitem><para>compile and link a full top-down kernel description from feature descriptions</para></listitem>
@@ -142,54 +143,66 @@ A summary of end user tree construction activities follow:
142 <listitem><para>migrate configuration fragments and configure the kernel</para></listitem> 143 <listitem><para>migrate configuration fragments and configure the kernel</para></listitem>
143 <listitem><para>checkout the BSP branch and build</para></listitem> 144 <listitem><para>checkout the BSP branch and build</para></listitem>
144</itemizedlist> 145</itemizedlist>
145</para> 146</para> -->
146 </section> 147 </section>
147 148
148 <section id='build-strategy'> 149 <section id='build-strategy'>
149 <title>Build Strategy</title> 150 <title>Build Strategy</title>
150<para> 151 <para>
151There are some prerequisites that must be met before starting the compilation 152 There are some prerequisites that must be met before starting the compilation
152phase of the kernel build system: 153 phase of the kernel build system:
153</para> 154 </para>
154<itemizedlist>
155 <listitem><para>There must be a kernel git repository indicated in the SRC_URI.</para></listitem>
156 <listitem><para>There must be a branch &lt;bsp name&gt;-&lt;kernel type&gt;.</para></listitem>
157</itemizedlist>
158 155
159<para> 156 <itemizedlist>
160These are typically met by running tree construction/patching phase of the 157 <listitem><para>There must be a kernel git repository indicated in the SRC_URI.</para></listitem>
161build system, but can be achieved by other means. Examples of alternate work 158 <listitem><para>There must be a branch &lt;bsp name&gt;-&lt;kernel type&gt;.</para></listitem>
162flows such as bootstrapping a BSP are provided below. 159 </itemizedlist>
163</para> 160
164<para> 161 <para>
165Before building a kernel it is configured by processing all of the 162 You can typically meet these prerequisites by running the tree construction/patching phase
166configuration "fragments" specified by the scc feature descriptions. As the 163 of the build system.
167features are compiled, associated kernel configuration fragments are noted 164 However, other means do exist.
168and recorded in the meta-series in their compilation order. The 165 For examples of alternate workflows such as bootstrapping a BSP, see
169fragments are migrated, pre-processed and passed to the Linux Kernel 166 the<link linkend='workflow-examples'> Workflow Examples</link> section in this manual.
170Configuration subsystem (lkc) as raw input in the form of a .config file. 167 </para>
171The lkc uses its own internal dependency constraints to do the final 168
172processing of that information and generates the final .config that will 169 <para>
173be used during compilation. 170 Before building a kernel it is configured by processing all of the
174</para> 171 configuration "fragments" specified by the scc feature descriptions.
175<para> 172 As the features are compiled, associated kernel configuration fragments are noted
176Kernel compilation is started, using the board's architecture and other 173 and recorded in the meta-series in their compilation order.
177relevant values from the board template, and a kernel image is produced. 174 The fragments are migrated, pre-processed and passed to the Linux Kernel
178</para> 175 Configuration subsystem (lkc) as raw input in the form of a <filename>.config</filename> file.
179<para> 176 The lkc uses its own internal dependency constraints to do the final
180The other thing that you will first see once you configure a kernel is that 177 processing of that information and generates the final <filename>.config</filename> file
181it will generate a build tree that is separate from your git source tree. 178 that is used during compilation.
182This build dir will be called "linux-&lt;BSPname&gt;-&lt;kerntype&gt;-build" where 179 </para>
183kerntype is one of standard kernel types. This functionality is done by making 180
184use of the existing support that is within the kernel.org tree by default. 181 <para>
185</para> 182 Using the board's architecture and other relevant values from the board's template
186<para> 183 the Kernel compilation is started and a kernel image is produced.
187What this means, is that all the generated files (that includes the final 184 </para>
188".config" itself, all ".o" and ".a" etc) are now in this directory. Since 185
189the git source tree can contain any number of BSPs, all on their own branch, 186 <para>The other thing that you will first see once you configure a kernel is that
190you now can easily switch between builds of BSPs as well, since each one also 187 it will generate a build tree that is separate from your git source tree.
191has their own separate build directory. 188 This build tree has the name using the following form:
192</para> 189 <literallayout class='monospaced'>
190 linux-&lt;BSPname&gt;-&lt;kerntype&gt;-build
191 </literallayout>
192 "kerntype" is one of the standard kernel types.
193 </para>
194
195 <para>
196 The existing support in the kernel.org tree achieves this default functionality.
197 </para>
198
199 <para>
200 What this means, is that all the generated files for a particular BSP are now in this directory.
201 The files include the final <filename>.config</filename>, all the <filename>.o</filename>
202 files, the <filename>.a</filename> files, and so forth.
203 Since each BSP has its own separate build directory in its own separate branch
204 of the git tree you can easily switch between different BSP builds.
205 </para>
193 </section> 206 </section>
194 207
195<!-- <section id='scc'> 208<!-- <section id='scc'>
@@ -355,51 +368,69 @@ repository.
355 <title>Workflow Examples</title> 368 <title>Workflow Examples</title>
356 369
357 <para> 370 <para>
358As previously noted, the Yocto Project kernel has built in git/guilt 371 As previously noted, the Yocto Project kernel has built in git/guilt
359integration, but these utilities are not the only way to work with the kernel 372 integration.
360repository. Yocto Project has not made changes to git, or other tools that 373 However, these utilities are not the only way to work with the kernel repository.
361invalidate alternate workflows. Additionally, the way the kernel repository 374 Yocto Project has not made changes to git or to other tools that
362is constructed uses only core git functionality allowing any number of tools 375 would invalidate alternate workflows.
363or front ends to use the resulting tree.</para> 376 Additionally, the way the kernel repository is constructed results in using
364<para> 377 only core git functionality thus allowing any number of tools or front ends to use the
365This section contains several workflow examples. 378 resulting tree.
366</para> 379 </para>
380
381 <para>
382 This section contains several workflow examples.
383 </para>
367 384
368 <section id='change-inspection-kernel-changes-commits'> 385 <section id='change-inspection-kernel-changes-commits'>
369 <title>Change Inspection: Kernel Changes/Commits</title> 386 <title>Change Inspection: Kernel Changes/Commits</title>
370<para> 387
371A common question when working with a BSP/kernel is: "What changes have been applied to this tree?" 388 <para>
372</para> 389 A common question when working with a BSP or kernel is:
373<para> 390 "What changes have been applied to this tree?"
374In some projects, where a collection of directories that 391 </para>
375contained patches to the kernel, those patches could be inspected, grep'd or 392
376otherwise used to get a general feeling for changes. This sort of patch 393 <para>
377inspection is not an efficient way to determine what has been done to the 394 In projects that have a collection of directories that
378kernel, since there are many optional patches that are selected based on the 395 contain patches to the kernel it is possible to inspect or "grep" the contents
379kernel type and feature description, not to mention patches that are actually 396 of the directories to get a general feel for the changes.
380in directories that are not being searched. 397 This sort of patch inspection is not an efficient way to determine what has been done to the
381</para> 398 kernel.
382<para> 399 The reason it is inefficient is because there are many optional patches that are
383A more effective way to determine what has changed in the kernel is to use 400 selected based on the kernel type and the feature description.
384git and inspect / search the kernel tree. This is a full view of not only the 401 Additionally, patches could exist in directories that are not included in the search.
385source code modifications, but the reasoning behind the changes. 402 </para>
386</para> 403
404 <para>
405 A more efficient way to determine what has changed in the kernel is to use
406 git and inspect or search the kernel tree.
407 This method gives you a full view of not only the source code modifications,
408 but also provides the reasons for the changes.
409 </para>
410
387 <section id='what-changed-in-a-bsp'> 411 <section id='what-changed-in-a-bsp'>
388 <title>What Changed in a BSP?</title> 412 <title>What Changed in a BSP?</title>
389<para> 413
390These examples could continue for some time, since the Yocto Project git 414 <para>
391repository doesn't break existing git functionality and there are nearly 415 Following are a few examples that show how to use git to examine changes.
392endless permutations of those commands. Also note that unless a commit range 416 Note that because the Yocto Project git repository does not break existing git
393is given (&lt;kernel type&gt;..&lt;bsp&gt;-&lt;kernel type&gt;), kernel.org history is blended 417 functionality and because there exists many permutations of these types of
394with Yocto Project changes 418 commands there are many more methods to discover changes.
395</para> 419 </para>
396<literallayout class='monospaced'> 420
421 <note><para>
422 Unless you provide a commit range
423 (&lt;kernel-type&gt;..&lt;bsp&gt;-&lt;kernel-type&gt;), kernel.org history
424 is blended with Yocto Project changes.
425 </para></note>
426
427 <literallayout class='monospaced'>
397 # full description of the changes 428 # full description of the changes
398 &gt; git whatchanged &lt;kernel type&gt;..&lt;bsp&gt;-&lt;kernel type&gt; 429 &gt; git whatchanged &lt;kernel type&gt;..&lt;bsp&gt;-&lt;kernel type&gt;
399 &gt; eg: git whatchanged standard..common_pc-standard 430 &gt; eg: git whatchanged standard..common_pc-standard
400 431
401 # summary of the changes 432 # summary of the changes
402 &gt; git log &dash;&dash;pretty=oneline &dash;&dash;abbrev-commit &lt;kernel type&gt;..&lt;bsp&gt;-&lt;kernel type&gt; 433 &gt; git log --pretty=oneline --;abbrev-commit &lt;kernel type&gt;..&lt;bsp&gt;-&lt;kernel type&gt;
403 434
404 # source code changes (one combined diff) 435 # source code changes (one combined diff)
405 &gt; git diff &lt;kernel type&gt;..&lt;bsp&gt;-&lt;kernel type&gt; 436 &gt; git diff &lt;kernel type&gt;..&lt;bsp&gt;-&lt;kernel type&gt;
@@ -413,86 +444,105 @@ with Yocto Project changes
413 444
414 # determine the commits which touch each line in a file 445 # determine the commits which touch each line in a file
415 &gt; git blame &lt;path to file&gt; 446 &gt; git blame &lt;path to file&gt;
416</literallayout> 447 </literallayout>
417 </section> 448 </section>
418 449
419 <section id='show-a-particular-feature-or-branch-change'> 450 <section id='show-a-particular-feature-or-branch-change'>
420 <title>Show a Particular Feature or Branch Change</title> 451 <title>Show a Particular Feature or Branch Change</title>
421<para> 452
422Significant features or branches are tagged in the Yocto Project tree to divide 453 <para>
423changes. Remember to first determine (or add) the tag of interest. Note: 454 Significant features or branches are tagged in the Yocto Project tree to divide
424there will be many tags, since each BSP branch is tagged, kernel.org tags and 455 changes.
425feature tags are all present. 456 Remember to first determine (or add) the tag of interest.
426</para> 457 </para>
427<literallayout class='monospaced'> 458
459 <note><para>
460 Because BSP branch, kernel.org, and feature tags are all present, there are many tags.
461 </para></note>
462
463 <literallayout class='monospaced'>
428 # show the changes tagged by a feature 464 # show the changes tagged by a feature
429 &gt; git show &lt;tag&gt; 465 &gt; git show &lt;tag&gt;
430 &gt; eg: git show yaffs2 466 &gt; eg: git show yaffs2
431 467
432 # determine which branches contain a feature 468 # determine which branches contain a feature
433 &gt; git branch &dash;&dash;contains &lt;tag&gt; 469 &gt; git branch --contains &lt;tag&gt;
434 470
435 # show the changes in a kernel type 471 # show the changes in a kernel type
436 &gt; git whatchanged wrs_base..&lt;kernel type&gt; 472 &gt; git whatchanged wrs_base..&lt;kernel type&gt;
437 &gt; eg: git whatchanged wrs_base..standard 473 &gt; eg: git whatchanged wrs_base..standard
438</literallayout> 474 </literallayout>
439<para> 475
440Many other comparisons can be done to isolate BSP changes, such as comparing 476 <para>
441to kernel.org tags (v2.6.27.18, etc), per subsystem comparisons (git 477 You can use many other comparisons to isolate BSP changes.
442whatchanged mm) or many other types of checks. 478 For example, you can compare against kernel.org tags (e.g. v2.6.27.18, etc), or
443</para> 479 you can compare agains subsystems (e.g. git whatchanged mm).
480 </para>
444 </section> 481 </section>
445 </section> 482 </section>
446 483
447 <section id='development-saving-kernel-modifications'> 484 <section id='development-saving-kernel-modifications'>
448 <title>Development: Saving Kernel Modifications</title> 485 <title>Development: Saving Kernel Modifications</title>
449<para> 486
450Another common operation is to build a Yocto Project supplied BSP, make some 487 <para>
451changes, rebuild and test. Those local changes often need to be exported, 488 Another common operation is to build a BSP supplied by Yocto Project, make some
452shared or otherwise maintained. 489 changes, rebuild and then test.
453</para> 490 Those local changes often need to be exported, shared or otherwise maintained.
454<para> 491 </para>
455Since the Yocto Project kernel source tree is backed by git, this activity is 492
456greatly simplified and is much easier than in previous releases. git tracks 493 <para>
457file modifications, additions and deletions, which allows the developer to 494 Since the Yocto Project kernel source tree is backed by git, this activity is
458modify the code and later realize that the changes should be saved, and 495 much easier as compared to with previous releases.
459easily determine what was changed. It also provides many tools to commit, 496 Because git tracks file modifications, additions and deletions, it is easy
460undo and export those modifications. 497 to modify the code and later realize that the changes should be saved.
461</para> 498 It is also easy to determine what has changed.
462<para> 499 This method also provides many tools to commit, undo and export those modifications.
463There are many ways to perform this action, and the technique employed 500 </para>
464depends on the destination for the patches, which could be any of: 501
465<itemizedlist> 502 <para>
466 <listitem><para>bulk storage</para></listitem> 503 There are many ways to save kernel modifications.
467 <listitem><para>internal sharing either through patches or using git</para></listitem> 504 The technique employed
468 <listitem><para>external submission</para></listitem> 505 depends on the destination for the patches:
469 <listitem><para>export for integration into another SCM</para></listitem> 506
470</itemizedlist> 507 <itemizedlist>
471</para> 508 <listitem><para>Bulk storage</para></listitem>
472<para> 509 <listitem><para>Internal sharing either through patches or by using git</para></listitem>
473The destination of the patches also incluences the method of gathering them 510 <listitem><para>External submissions</para></listitem>
474due to issues such as: 511 <listitem><para>Exporting for integration into another SCM</para></listitem>
475<itemizedlist> 512 </itemizedlist>
476 <listitem><para>bisectability</para></listitem> 513 </para>
477 <listitem><para>commit headers</para></listitem> 514
478 <listitem><para>division of subsystems for separate submission / review</para></listitem> 515 <para>
479</itemizedlist> 516 Because of the following list of issues, the destination of the patches also influences
480</para> 517 the method for gathering them:
518
519 <itemizedlist>
520 <listitem><para>Bisectability</para></listitem>
521 <listitem><para>Commit headers</para></listitem>
522 <listitem><para>Division of subsystems for separate submission or review</para></listitem>
523 </itemizedlist>
524 </para>
481 525
482 <section id='bulk-export'> 526 <section id='bulk-export'>
483 <title>Bulk Export</title> 527 <title>Bulk Export</title>
484<para> 528
485If patches are simply being stored outside of the kernel source repository, 529 <para>
486either permanently or temporarily, then there are several methods that can be 530 This section describes how you can export in "bulk" changes that have not
487used. 531 been separated or divided.
488</para> 532 This situation works well when you are simply storing patches outside of the kernel
489<para> 533 source repository, either permanently or temporarily, and you are not committing
490Note the "bulk" in this discussion, these techniques are not appropriate for 534 incremental changes during development.
491full integration of upstream submission, since they do not properly divide 535 </para>
492changes or provide an avenue for per-change commit messages. This example 536
493assumes that changes have not been committed incrementally during development 537 <note><para>
494and simply must be gathered and exported. 538 This technique is not appropriate for full integration of upstream submission
495<literallayout class='monospaced'> 539 because changes are not properly divided and do not provide an avenue for per-change
540 commit messages.
541 Therefore, this example assumes that changes have not been committed incrementally
542 during development and that you simply must gather and export them.
543 </para></note>
544
545 <literallayout class='monospaced'>
496 # bulk export of ALL modifications without separation or division 546 # bulk export of ALL modifications without separation or division
497 # of the changes 547 # of the changes
498 548
@@ -500,32 +550,39 @@ and simply must be gathered and exported.
500 &gt; git commit -s -a -m &gt;commit message&lt; 550 &gt; git commit -s -a -m &gt;commit message&lt;
501 or 551 or
502 &gt; git commit -s -a # and interact with $EDITOR 552 &gt; git commit -s -a # and interact with $EDITOR
503</literallayout> 553 </literallayout>
504</para> 554
505<para> 555 <para>
506These operations have captured all the local changes in the project source 556 The previous operations capture all the local changes in the project source
507tree in a single git commit, and that commit is also stored in the project's 557 tree in a single git commit.
508source tree. 558 And, that commit is also stored in the project's source tree.
509</para> 559 </para>
510<para> 560
511Once exported, those changes can then be restored manually, via a template or 561 <para>
512through integration with the default_kernel. Those topics are covered in 562 Once the changes are exported, you can restore them manually using a template
513future sections. 563 or through integration with the <filename>default_kernel</filename>.
514</para> 564 </para>
565
515 </section> 566 </section>
516 567
517 <section id='incremental-planned-sharing'> 568 <section id='incremental-planned-sharing'>
518 <title>Incremental/Planned Sharing</title> 569 <title>Incremental/Planned Sharing</title>
519<para> 570
520Note: unlike the previous "bulk" section, the following examples assume that 571 <para>
521changes have been incrementally committed to the tree during development and 572 This section describes how to save modifications when you are making incremental
522now are being exported. 573 commits or practicing planned sharing.
523</para> 574 The examples in this section assume that changes have been incrementally committed
524<para> 575 to the tree during development and now need to be exported. The sections that follow
525During development the following commands will be of interest, but for full 576 describe how you can export your changes internally through either patches or by
526git documentation refer to the git man pages or an online resource such as 577 using git commands.
527http://github.com 578 </para>
528<literallayout class='monospaced'> 579
580 <para>
581 During development the following commands are of interest.
582 For full git documentation, refer to the git man pages or to an online resource such
583 as <ulink url='http://github.com'></ulink>.
584
585 <literallayout class='monospaced'>
529 # edit a file 586 # edit a file
530 &gt; vi &gt;path&lt;/file 587 &gt; vi &gt;path&lt;/file
531 # stage the change 588 # stage the change
@@ -538,129 +595,169 @@ http://github.com
538 &gt; git commit -s 595 &gt; git commit -s
539 596
540 ... etc. 597 ... etc.
541</literallayout> 598 </literallayout>
542</para> 599 </para>
543<para> 600
544Distributed development with git is possible by having a universally agreed 601 <para>
545upon unique commit identifier (set by the creator of the commit) mapping to a 602 Distributed development with git is possible when you use a universally
546specific changeset with a specific parent. This ID is created for you when 603 agreed-upon unique commit identifier (set by the creator of the commit) that maps to a
547you create a commit, and will be re-created when you amend/alter or re-apply 604 specific changeset with a specific parent.
548a commit. As an individual in isolation, this is of no interest, but if you 605 This identifier is created for you when
549intend to share your tree with normal git push/pull operations for 606 you create a commit, and is re-created when you amend, alter or re-apply
550distributed development, you should consider the ramifications of changing a 607 a commit.
551commit that you've already shared with others. 608 As an individual in isolation, this is of no interest.
552</para> 609 However, if you
553<para> 610 intend to share your tree with normal git push and pull operations for
554Assuming that the changes have *not* been pushed upstream, or pulled into 611 distributed development, you should consider the ramifications of changing a
555another repository, both the commit content and commit messages associated 612 commit that you have already shared with others.
556with development can be update via: 613 </para>
557<literallayout class='monospaced'> 614
615 <para>
616 Assuming that the changes have not been pushed upstream, or pulled into
617 another repository, you can update both the commit content and commit messages
618 associated with development by using the following commands:
619
620 <literallayout class='monospaced'>
558 &gt; git add &gt;path&lt;/file 621 &gt; git add &gt;path&lt;/file
559 &gt; git commit &dash;&dash;amend 622 &gt; git commit --amend
560 &gt; git rebase or git rebase -i 623 &gt; git rebase or git rebase -i
561</literallayout> 624 </literallayout>
562</para> 625 </para>
563<para> 626
564Again, assuming that the changes have *not* been pushed upstream, and that 627 <para>
565there are no pending works in progress (use "git status" to check) then 628 Again, assuming that the changes have not been pushed upstream, and that
566commits can be reverted (undone) via: 629 no pending works-in-progress exist (use "git status" to check) then
567<literallayout class='monospaced'> 630 you can revert (undo) commits by using the following commands:
631
632 <literallayout class='monospaced'>
568 # remove the commit, update working tree and remove all 633 # remove the commit, update working tree and remove all
569 # traces of the change 634 # traces of the change
570 &gt; git reset &dash;&dash;hard HEAD^ 635 &gt; git reset --hard HEAD^
571 # remove the commit, but leave the files changed and staged for re-commit 636 # remove the commit, but leave the files changed and staged for re-commit
572 &gt; git reset &dash;&dash;soft HEAD^ 637 &gt; git reset --soft HEAD^
573 # remove the commit, leave file change, but not staged for commit 638 # remove the commit, leave file change, but not staged for commit
574 &gt; git reset &dash;&dash;mixed HEAD^ 639 &gt; git reset --mixed HEAD^
575</literallayout> 640 </literallayout>
576</para> 641 </para>
577<para> 642
578Branches can be created, changes cherry-picked or any number of git 643 <para>
579operations performed until the commits are in good order for pushing upstream 644 You can create branches, "cherry-pick" changes or perform any number of git
580or pull requests. After a push or pull, commits are normally considered 645 operations until the commits are in good order for pushing upstream
581'permanent' and should not be modified, only incrementally changed in new 646 or for pull requests.
582commits. This is standard "git" workflow and Yocto Project recommends the 647 After a push or pull, commits are normally considered
583kernel.org best practices. 648 "permanent" and you should not modify them.
584</para> 649 If they need to be changed you can incrementally do so with new commits.
585<note><para>It is recommend to tag or branch before adding changes to a Yocto Project 650 These practices follow the standard "git" workflow and the kernel.org best
586 BSP (or creating a new one), since the branch or tag provides a 651 practices, which Yocto Project recommends.
587 reference point to facilitate locating and exporting local changes. 652 </para>
588</para></note> 653
654 <note><para>
655 It is recommend to tag or branch before adding changes to a Yocto Project
656 BSP or before creating a new one.
657 The reason for this recommendation is because the branch or tag provides a
658 reference point to facilitate locating and exporting local changes.
659 </para></note>
589 660
590 <section id='export-internally-via-patches'> 661 <section id='export-internally-via-patches'>
591 <title>Export Internally Via Patches</title> 662 <title>Exporting Changes Internally by Using Patches</title>
592<para> 663
593Committed changes can be extracted from a working directory by exporting them 664 <para>
594as patches. Those patches can be used for upstream submission, placed in a 665 This section describes how you can extract committed changes from a working directory
595Yocto Project template for automatic kernel patching or many other common uses. 666 by exporting them as patches.
596 667 Once extracted, you can use the patches for upstream submission,
597<literallayout class='monospaced'> 668 place them in a Yocto Project template for automatic kernel patching,
598 # &gt;first commit&gt; can be a tag if one was created before development 669 or apply them in many other common uses.
670 </para>
671
672 <para>
673 This example shows how to create a directory with sequentially numbered patches.
674 Once the directory is created, you can apply it to a repository using the
675 <filename>git am</filename> command to reproduce the original commit and all
676 the related information such as author, date, commit log, and so forth.
677 </para>
678
679 <note><para>
680 The new commit identifiers (ID) will be generated upon re-application.
681 This action reflects that the commit is now applied to an underlying commit
682 with a different ID.
683 </para></note>
684
685 <para>
686 <literallayout class='monospaced'>
687 # &lt;first-commit&gt; can be a tag if one was created before development
599 # began. It can also be the parent branch if a branch was created 688 # began. It can also be the parent branch if a branch was created
600 # before development began. 689 # before development began.
601 690
602 &gt; git format-patch -o &lt;dir&gt; &lt;first commit&gt;..&lt;last commit&gt; 691 &gt; git format-patch -o &lt;dir&gt; &lt;first commit&gt;..&lt;last commit&gt;
603</literallayout> 692 </literallayout>
604</para> 693 </para>
605 694
606<para> 695 <para>
607 In other words: 696 In other words:
608<literallayout class='monospaced'> 697 <literallayout class='monospaced'>
609 # identify commits of interest. 698 # Identify commits of interest.
610 699
611 # if the tree was tagged before development 700 # If the tree was tagged before development
612 &gt; git format-patch -o &lt;save dir&gt; &lt;tag&gt; 701 &gt; git format-patch -o &lt;save dir&gt; &lt;tag&gt;
613 702
614 # if no tags are available 703 # If no tags are available
615 &gt; git format-patch -o &lt;save dir&gt; HEAD^ # last commit 704 &gt; git format-patch -o &lt;save dir&gt; HEAD^ # last commit
616 &gt; git format-patch -o &lt;save dir&gt; HEAD^^ # last 2 commits 705 &gt; git format-patch -o &lt;save dir&gt; HEAD^^ # last 2 commits
617 &gt; git whatchanged # identify last commit 706 &gt; git whatchanged # identify last commit
618 &gt; git format-patch -o &lt;save dir&gt; &lt;commit id&gt; 707 &gt; git format-patch -o &lt;save dir&gt; &lt;commit id&gt;
619 &gt; git format-patch -o &lt;save dir&gt; &lt;rev-list&gt; 708 &gt; git format-patch -o &lt;save dir&gt; &lt;rev-list&gt;
620</literallayout> 709 </literallayout>
621</para> 710 </para>
622 711
623<para> 712 <!--<para>
624The result is a directory with sequentially numbered patches, that when 713 See the "template patching" example for how to use the patches to
625applied to a repository using "git am", will reproduce the original commit 714 automatically apply to a new kernel build.
626and all related information (author, date, commit log, etc) will be 715 </para>-->
627preserved. Note that new commit IDs will be generated upon reapplication, 716 </section>
628reflecting that the commit is now applied to an underlying commit with a
629different ID.
630</para>
631<!--<para>
632See the "template patching" example for how to use the patches to
633automatically apply to a new kernel build.
634</para> -->
635 </section>
636 717
637 <section id='export-internally-via-git'> 718 <section id='export-internally-via-git'>
638 <title>Export Internally Via git</title> 719 <title>Exporting Changes Internally by Using git</title>
639<para> 720
640Committed changes can also be exported from a working directory by pushing 721 <para>
641(or by making a pull request) the changes into a master repository. Those 722 This section describes how you can export changes from a working directory
642same change can then be pulled into a new kernel build at a later time using this command form: 723 by pushing the changes into a master repository or by making a pull request.
643<literallayout class='monospaced'> 724 Once you have pushed the changes in the master repository you can then
725 pull those same changes into a new kernel build at a later time.
726 </para>
727
728 <para>
729 Use this command form to push the changes:
730 <literallayout class='monospaced'>
644 git push ssh://&lt;master server&gt;/&lt;path to repo&gt; &lt;local branch&gt;:&lt;remote branch&gt; 731 git push ssh://&lt;master server&gt;/&lt;path to repo&gt; &lt;local branch&gt;:&lt;remote branch&gt;
645</literallayout> 732 </literallayout>
646For example: 733 </para>
647<literallayout class='monospaced'> 734
735 <para>
736 For example, the following command pushes the changes from your local branch
737 <filename>common_pc-standard</filename> to the remote branch with the same name
738 in the master repository <filename>//git.mycompany.com/pub/git/kernel-2.6.27</filename>.
739 <literallayout class='monospaced'>
648 &gt; push ssh://git.mycompany.com/pub/git/kernel-2.6.27 common_pc-standard:common_pc-standard 740 &gt; push ssh://git.mycompany.com/pub/git/kernel-2.6.27 common_pc-standard:common_pc-standard
649</literallayout> 741 </literallayout>
650A pull request entails using "git request-pull" to compose an email to the 742 </para>
651maintainer requesting that a branch be pulled into the master repository, see 743
652http://github.com/guides/pull-requests for an example. 744 <para>
653</para> 745 A pull request entails using "git request-pull" to compose an email to the
654<para> 746 maintainer requesting that a branch be pulled into the master repository, see
655Other commands such as 'git stash' or branching can also be used to save 747 <ulink url='http://github.com/guides/pull-requests'></ulink> for an example.
656changes, but are not covered in this document. 748 </para>
657</para> 749
658<para> 750 <note><para>
659See the section "importing from another SCM" for how a git push to the 751 Other commands such as 'git stash' or branching can also be used to save
660default_kernel, can be used to automatically update the builds of all users 752 changes, but are not covered in this document.
661of a central git repository. 753 </para></note>
662</para> 754
663 </section> 755 <!--<para>
756 See the section "importing from another SCM" for how a git push to the
757 default_kernel, can be used to automatically update the builds of all users
758 of a central git repository.
759 </para>-->
760 </section>
664 </section> 761 </section>
665 762
666 <section id='export-for-external-upstream-submission'> 763 <section id='export-for-external-upstream-submission'>
@@ -699,10 +796,10 @@ induced patch damage.
699An example of dumping patches for external submission follows: 796An example of dumping patches for external submission follows:
700<literallayout class='monospaced'> 797<literallayout class='monospaced'>
701 # dump the last 4 commits 798 # dump the last 4 commits
702 &gt; git format-patch &dash;&dash;thread -n -o ~/rr/ HEAD^^^^ 799 &gt; git format-patch --thread -n -o ~/rr/ HEAD^^^^
703 &gt; git send-email &dash;&dash;compose &dash;&dash;subject '[RFC 0/N] &lt;patch series summary&gt;' \ 800 &gt; git send-email --compose --subject '[RFC 0/N] &lt;patch series summary&gt;' \
704 &dash;&dash;to foo@yoctoproject.org &dash;&dash;to bar@yoctoproject.org \ 801 --to foo@yoctoproject.org --to bar@yoctoproject.org \
705 &dash;&dash;cc list@yoctoproject.org ~/rr 802 --cc list@yoctoproject.org ~/rr
706 # the editor is invoked for the 0/N patch, and when complete the entire 803 # the editor is invoked for the 0/N patch, and when complete the entire
707 # series is sent via email for review 804 # series is sent via email for review
708</literallayout> 805</literallayout>
@@ -934,7 +1031,7 @@ That's it. Configure and build.
934 So first create a bare clone of the Yocto Project git repository, and then create a 1031 So first create a bare clone of the Yocto Project git repository, and then create a
935 local clone of that: 1032 local clone of that:
936 <literallayout class='monospaced'> 1033 <literallayout class='monospaced'>
937 $ git clone &dash;&dash;bare git://git.pokylinux.org/linux-2.6-windriver.git 1034 $ git clone --bare git://git.pokylinux.org/linux-2.6-windriver.git
938 linux-2.6-windriver.git 1035 linux-2.6-windriver.git
939 $ git clone linux-2.6-windriver.git linux-2.6-windriver 1036 $ git clone linux-2.6-windriver.git linux-2.6-windriver
940 </literallayout> 1037 </literallayout>
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-05-01 08:11:20 +0000