diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/writing.docbook | 57 |
1 files changed, 57 insertions, 0 deletions
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. </para> +<para> +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. +</para> + +<variablelist> + <varlistentry> + <term>patch_targets</term> + <listitem> + + <para> + 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. + </para> + + <para> + 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. + </para> + + </listitem> + </varlistentry> + + <varlistentry> + <term>patch_required</term> + <listitem> + + <para> + 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. + </para> + + <para> + 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. + </para> + </listitem> + </varlistentry> +</variablelist> + </sect1> </chapter> |