From 44fd22d44f7118c3bd6d92f23da222bae856def5 Mon Sep 17 00:00:00 2001 From: Diego Elio Pettenò Date: Sun, 31 Dec 2006 01:13:10 +0000 Subject: Start documenting the functions in the patchset's script. svn path=/trunk/; revision=32 --- doc/writing.docbook | 57 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 57 insertions(+) (limited to 'doc') diff --git a/doc/writing.docbook b/doc/writing.docbook index f33b293..70e09d9 100644 --- a/doc/writing.docbook +++ b/doc/writing.docbook @@ -19,6 +19,63 @@ the files to patch, what kind of patchset it is, and whether to fail or not if the patching is not completed as intended. + +To facilitate writing new patchsets, the names of the functions that +are defined into the patchset's script are standardised, so that the +parameters they get and the result they echo out can be relied upon +and used by autoepatch safely. + + + + + patch_targets + + + + This function is the basis to start writing a new patchset, it is + used to identify where the patches are gonna be applied. The + results are simply returned on the standard output, one per + line. This function is supposed to check if the patch should or + should not be applied over a file or a directory, by grepping, if + needed, for key phrases that would show if the patch is needed or + not. + + + + This function is not supposed to check for the applicability of + the patch on the current system. The reason for this is that it's + way simpler to test all patchsets every time, so that if errors + are added to the patchset, they can be fixed immediately. + + + + + + + patch_required + + + + This function is called in the case the patchset failed to apply + entirely; it is supposed to return 0 (truth value) if the patch is + important, and autoepatch has to fail if it's not applied (and + thus stop the merge process), or 1 (untruth value) if the patch is + optional and/or it's not of first important for the current setup. + + + + The reason to have this function is that some patches might be only + needed on some targets (for instance Gentoo/FreeBSD, or uClibc or + Darwin systems), or only in some situations (newer autotools, + newer glibc or linux-headers), and for the rest of the cases, it's + just an assurance and a testing purpose to apply the patch on + every use. So the failure on autoepatch, when a patchset fails to + apply, is entirely decided by the value returned by this function. + + + + + -- cgit v1.2.3-65-gdbad