Whamcloud - gitweb
- bring in akpm's patch management scripts and a first cut at
[fs/lustre-release.git] / lustre / kernel_patches / README
1
2 Lustre requires changes to the core kernel before it can be compiled against
3 hte core kernel source tree.  We use Andrew Morton's 'patch-scripts' utilties
4 to keep the complexity of managing changes across multiple kernel targets down.
5 They handle the ordering metadata, application, refreshing, and removal of
6 patches  for us.  Please read scripts/docco.txt for a more thorough explanation
7 of what 'patch-scripts' do.
8
9 We create a thin wrapper around patchscripts with our ./prepare_tree.sh.  It
10 exports two environment variables.  PATCHSCRIPTS is a relative path from the
11 kernel source tree to the checked-out patchscripts repository.  It is requires
12 for patchscripts to operate on data outside the kernel source tree.  It also
13 puts the absolute path to the scripts/ directory at the front of PATH.
14 Finally, it creates a 'series' link from the kernel tree back to the proper
15 series file for that kernel tree.  More on that below.
16
17 prepare_tree.sh and the patch-scripts commands are the only interface we should
18 use on a daily basis.  We should never have to manage the patches by hand.
19 This will save us heart-ache once we're good with the tools.  I promise.
20
21 Data to be aware of:
22
23 patches/
24         contains all the patch files themselves.  We should have a patch per 
25         functional change.  
26
27 series/
28         the text files that patch-utils use to define the ordering of patches
29         that are applied to a tree.  We have a series file for each kernel
30         tree variant that requires wildly different patches.  (architecture
31         differences, stock vs. redhat, etc) 
32
33 pc/
34         control files for patch-utils.  These are per tree and should never
35         be in cvs.
36
37 txt/
38         text descriptions of the patches.  Nice, but not functionally required.
39
40 First, before anything happens, you need to prep a tree for use with
41 patch-utils.  This means putting a series link in the file and setting the
42 environment variable:
43
44         $ eval `./prepare_tree.sh -t /tmp/kernels/linux-2.4.18 -r stock-2.4`
45
46 prepare-tree.sh is careful to output variable assignments to stdout and
47 everything else to stderr so the eval won't go awry.  It also is clever about
48 resolving the series name, so tab-completed relative paths to the series files
49 can be used with -r.  (it assumes that series/ is under where prepare_tree.sh
50 was executed from).  The series link that is created from the tree back into
51 the cvs repository is created by force.  Don't re-run the command with a
52 different role.  (this should probably be fixed)
53
54 With this in place, the shell that did the eval is ready to wield patch-utils.
55
56 ] To apply all the patches to a given tree:
57
58         $ eval `./prepare_tree.sh -t /tmp/kernels/linux-2.4.18 -r stock-2.4`
59         $ cd /tmp/kernels/linux-2.4.18
60         $ pushpatch 100000
61                 ( the huge number just serves to iterate through the patches )
62
63 ] To refresh the patches against a newer kernel that the series applies to.
64
65 Say the series file 'rh-8.0-dev' corresponds to a CFS policy of tracking the
66 most recent red hat 8.0 distro kernel.   It used to be 2.4.18-14, say, and RH
67 has now released RH 2.4.18-17.8.0 and CFS has decided to move to it.  We
68 want to update the patches in cvs HEAD to be against 2.4.18-17.8.0
69
70         $ eval `./prepare_tree.sh -t /tmp/linux-2.4.18-17.8.0 -r rh-8.0-dev`
71         $ cd /tmp/linux-2.4.18-17.8.0
72         $ for a in $NUM_PATCHES_HAVE ; do
73                 pushpatch;
74                 refpatch;
75           done
76
77 ] To add a new series 
78
79 Simply add a new empty file to the series/ directory, choosing a descriptive
80 name for the series.
81
82 ] To add a patch into a series
83
84 Ideally a patch can be added to the end of the series.  This is most easily
85 done with patch-utils import_patch.  After the patch is imported it still needs
86 to be applied and refreshed with 'pushpatch' and 'refpatch'.  ___remember to
87 cvs add the patch with -ko___ so that tags in the context of the diff aren't
88 change by CVS, rendering the patch unusable.
89
90 It is considered valuable to have a common HEAD which can be checked out to
91 patch a kernel and build lustre across lots of targets.  This creates some
92 friction in the desire to keep a single canonical set of patches in CVS.  We
93 solve this with the patch-utils scripts by having well-named patches that are
94 bound to the different series.  Say alpha and ia64 kernel trees both need a
95 common lustre patch.  Ideally they'd both have our-funcionality.patch in their
96 series, but perhaps the code path we want to alter is different in the trees
97 and not in the architecture-dependant part of the kernel.  For this we'd want
98 our-functionality-ia64.patch in the ia64 series file, and
99 our-functionality-alpha.patch in the alpha.  This split becomes irritating to
100 manage as shared changes want to be pushed to all the patches.  This will be a
101 pain as long as the kernel's we're receiving don't share revision control
102 somehow.  At least the patch utils make it relatively painless to 'pushpatch'
103 the source patch, clean up rejects, test, and 'refpatch' to generate the new
104 patch for that series.