--- /dev/null
+
+Lustre requires changes to the core kernel before it can be compiled against
+hte core kernel source tree. We use Andrew Morton's 'patch-scripts' utilties
+to keep the complexity of managing changes across multiple kernel targets down.
+They handle the ordering metadata, application, refreshing, and removal of
+patches for us. Please read scripts/docco.txt for a more thorough explanation
+of what 'patch-scripts' do.
+
+We create a thin wrapper around patchscripts with our ./prepare_tree.sh. It
+exports two environment variables. PATCHSCRIPTS is a relative path from the
+kernel source tree to the checked-out patchscripts repository. It is requires
+for patchscripts to operate on data outside the kernel source tree. It also
+puts the absolute path to the scripts/ directory at the front of PATH.
+Finally, it creates a 'series' link from the kernel tree back to the proper
+series file for that kernel tree. More on that below.
+
+prepare_tree.sh and the patch-scripts commands are the only interface we should
+use on a daily basis. We should never have to manage the patches by hand.
+This will save us heart-ache once we're good with the tools. I promise.
+
+Data to be aware of:
+
+patches/
+ contains all the patch files themselves. We should have a patch per
+ functional change.
+
+series/
+ the text files that patch-utils use to define the ordering of patches
+ that are applied to a tree. We have a series file for each kernel
+ tree variant that requires wildly different patches. (architecture
+ differences, stock vs. redhat, etc)
+
+pc/
+ control files for patch-utils. These are per tree and should never
+ be in cvs.
+
+txt/
+ text descriptions of the patches. Nice, but not functionally required.
+
+First, before anything happens, you need to prep a tree for use with
+patch-utils. This means putting a series link in the file and setting the
+environment variable:
+
+ $ eval `./prepare_tree.sh -t /tmp/kernels/linux-2.4.18 -r stock-2.4`
+
+prepare-tree.sh is careful to output variable assignments to stdout and
+everything else to stderr so the eval won't go awry. It also is clever about
+resolving the series name, so tab-completed relative paths to the series files
+can be used with -r. (it assumes that series/ is under where prepare_tree.sh
+was executed from). The series link that is created from the tree back into
+the cvs repository is created by force. Don't re-run the command with a
+different role. (this should probably be fixed)
+
+With this in place, the shell that did the eval is ready to wield patch-utils.
+
+] To apply all the patches to a given tree:
+
+ $ eval `./prepare_tree.sh -t /tmp/kernels/linux-2.4.18 -r stock-2.4`
+ $ cd /tmp/kernels/linux-2.4.18
+ $ pushpatch 100000
+ ( the huge number just serves to iterate through the patches )
+
+] To refresh the patches against a newer kernel that the series applies to.
+
+Say the series file 'rh-8.0-dev' corresponds to a CFS policy of tracking the
+most recent red hat 8.0 distro kernel. It used to be 2.4.18-14, say, and RH
+has now released RH 2.4.18-17.8.0 and CFS has decided to move to it. We
+want to update the patches in cvs HEAD to be against 2.4.18-17.8.0
+
+ $ eval `./prepare_tree.sh -t /tmp/linux-2.4.18-17.8.0 -r rh-8.0-dev`
+ $ cd /tmp/linux-2.4.18-17.8.0
+ $ for a in $NUM_PATCHES_HAVE ; do
+ pushpatch;
+ refpatch;
+ done
+
+] To add a new series
+
+Simply add a new empty file to the series/ directory, choosing a descriptive
+name for the series.
+
+] To add a patch into a series
+
+Ideally a patch can be added to the end of the series. This is most easily
+done with patch-utils import_patch. After the patch is imported it still needs
+to be applied and refreshed with 'pushpatch' and 'refpatch'. ___remember to
+cvs add the patch with -ko___ so that tags in the context of the diff aren't
+change by CVS, rendering the patch unusable.
+
+It is considered valuable to have a common HEAD which can be checked out to
+patch a kernel and build lustre across lots of targets. This creates some
+friction in the desire to keep a single canonical set of patches in CVS. We
+solve this with the patch-utils scripts by having well-named patches that are
+bound to the different series. Say alpha and ia64 kernel trees both need a
+common lustre patch. Ideally they'd both have our-funcionality.patch in their
+series, but perhaps the code path we want to alter is different in the trees
+and not in the architecture-dependant part of the kernel. For this we'd want
+our-functionality-ia64.patch in the ia64 series file, and
+our-functionality-alpha.patch in the alpha. This split becomes irritating to
+manage as shared changes want to be pushed to all the patches. This will be a
+pain as long as the kernel's we're receiving don't share revision control
+somehow. At least the patch utils make it relatively painless to 'pushpatch'
+the source patch, clean up rejects, test, and 'refpatch' to generate the new
+patch for that series.
git://git.whamcloud.com / fs / lustre-release.git / blobdiff