summaryrefslogtreecommitdiff
blob: afe0b8bb2eb123736866eebb5884edca84d27f62 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
<chapter id="writingpatchsets">
<title>Writing Patchsets</title>

<para>
This chapter will try to cover all the needed knowledge to write a new
patchset for autoepatch, as well as to maintain the ones already
present in the distribution.
</para>

<sect1 id="writingthescript">
<title>The patchset's script</title>

<para>
An autoepatch patchset consists at least of two atoms: a directory,
whose name is also the name of the patchset, and a bash script, inside
that directory, named the same way with ".sh" extension. That script
is the core of the patchset, as it will tell autoepatch where to find
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 going to 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 importance 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>

  <varlistentry>
    <term>patch_trigger_action</term>
    <listitem>

    <para>
    This function is the core of those patchsets without actual patch
    files to apply. It is called once per target to execute some
    commands on the given parameter. It is useful to run a sed
    command, or to parse the file in some complex way, and produce
    either a new output or changing the target file.
    </para>

    <para>
    Another likely usage of this ind of patchsets is to operate on a
    given directory, where you have to change the files according to
    some other file, for example if you're gonna change some gettext
    support.
    </para>

    </listitem>
  </varlistentry>
</variablelist>

</sect1>

</chapter>