/[autoepatch]/trunk/doc/howitworks.docbook
Gentoo

Contents of /trunk/doc/howitworks.docbook

Parent Directory Parent Directory | Revision Log Revision Log


Revision 29 - (show annotations) (download)
Sat Dec 30 08:39:25 2006 UTC (7 years, 7 months ago) by flameeyes
File size: 7722 byte(s)
Add some documentation about whitespaces in autoepatch.
1 <chapter id="howitworks">
2 <title>How it works</title>
3
4 <para>
5 In this chapter, we'll try to explain how autoepatch works, and how to
6 extend it to patch and fix new problems. The reason to provide a
7 throughout documentation about this is to make the maintainership of
8 autoepatch simpler, so that if the developers currently involved in
9 its writing would not be available, newcomers won't have to read all
10 the code to find how it actually works.
11 </para>
12
13 <sect1 id="requirements">
14 <title>Requirements</title>
15
16 <para>
17 Being a package that is going to be in the system set, and used by
18 every user as a Portage component, autoepatch needs to have the
19 minimum impact over the dependencies of that set. For this reason, the
20 script is a bash script. As the targets for Gentoo software are less
21 wide than the general GNU or Open Source targets, there's no need to
22 use a portable subset of sh (as we already consider bash present), and
23 it can depend on a few GNU tools, or at least tools that can support
24 an acceptable subset of GNU parameters.
25 </para>
26
27 <para>
28 There are basically two Gentoo specific softwares that are needed for
29 autoepatch: the first is baselayout, as autoepatch loads
30 /sbin/functions.sh to get functions like ebegin and eend, and
31 similar; the other is Portage, as autoepatch uses the portageq
32 command, and allows to the patchsets to use it.
33 </para>
34
35 <para>
36 First of all, as most of the patchsets are expected to be actual patch
37 files, the patch(1) command is supposed to be coming from GNU
38 project. While FreeBSD uses Larry Wall's patch(1) command, that
39 supports most of the options that GNU patch supports, there are some
40 tricky behaviours on fuzzyness of patches. If patch(1) is not a
41 GNU-compatible implementation, you can provide a GNU patch command
42 named <emphasis>gpatch</emphasis> that will be prioritised over the
43 normal patch(1).
44 </para>
45
46 <para>
47 Another command on which behaviour the script relies more than just a
48 bit is find(1). Considering the frequency of execution of the script
49 itself, and thus of the targetting logic, the script tries to reduce
50 as much as possible the processes spawn, so instead of using xargs(1)
51 command to transform the find(1) output to input arguments to other
52 commands, autoepatch relies on find(1) to support the <emphasis>-exec
53 cmd {} +</emphasis> syntax.
54 </para>
55
56 <para>
57 Luckily not only GNU findutils, but also FreeBSD, Darwin and NetBSD find(1)
58 implementations support that syntax. OpenBSD on the other hand does
59 not, so to allow autoepatch to work on that operating system, a
60 special handling for the find command was written: by replacing the
61 string <emphasis>@findcmd@</emphasis> with the path, or the name, of a
62 compatible find implementation (most likely GNU find), you can tell
63 autoepatch to run an alternative command.
64 </para>
65
66 <para>
67 As there is often the need to get a temporary file, either for log or
68 debugging purposes, or to store intermediate results, the mktemp
69 utility is also required. Unfortunately, the mktemp utility found on
70 most Linux implementations (Gentoo Linux included) comes from
71 debianutils package, and has a syntax incompatible with the original
72 BSD mktemp utility. As the autoepatch script does not get the USERLAND
73 variable from Portage, and tries to be entirely transparent to that
74 matter, the choice between the two implementations is done at runtime
75 by checking the outcome of calling <emphasis>mktemp -V</emphasis>; on
76 Debian implementation, this reports the version of the command itself,
77 while it simply fails on BSD implementation. The emktemp wrapper is
78 picked up from eutils.eclass.
79 </para>
80
81 </sect1>
82
83 <sect1 id="concepts">
84 <title>Concepts</title>
85
86 <para>
87 There aren't many concepts to describe on autoepatch because it is,
88 basically, a simple set of scripts. The definitions that will be given
89 here are not even proper "concepts" but this section is intented to
90 clear up the terminology used, so that there can't be misunderstanding
91 in the next sections and chapters.
92 </para>
93
94 <variablelist>
95 <varlistentry>
96 <term>patchset</term>
97 <listitem>
98
99 <para>
100 With this term, the documentation will refer to a set of scripts
101 and actual patches, the base element handled by autoepatch itself.
102 Despite the name used seem to limit a patchset to just patches,
103 it's well possible that a patchset has no actual ".patch" file,
104 and instead consist of a single shell script that describes the
105 changes to apply to targets.
106 </para>
107
108 <para>
109 The patchsets can be found in the repository inside the patches
110 directory, or for the installed copy in
111 /usr/share/autoepatch/patches
112 <footnote><para>
113 For alternative prefixes support, see <xref
114 linkend="prefixsupport" />.
115 </para></footnote>
116 </para>
117
118 </listitem>
119 </varlistentry>
120
121 <varlistentry>
122 <term>target</term>
123 <listitem>
124
125 <para>
126 Under this name we consider a file, or a directory, on which the
127 patchset applies. When the target is a directory, ad the patchset
128 contains actual patches, the paths inside the patches should refer
129 to the direct name of the files starting from the target directory
130 (-p0 option to gpatch); when the target is a file instead, the
131 patch will apply directly over the file. When instead the patchset
132 consist of a function (or a series of functions), the target is
133 passed as parameter, whichever the type it is.
134 </para>
135
136 <para>
137 For more informations about target, look at <xref
138 linkend="writingpatchsets" />.
139 </para>
140
141 </listitem>
142 </varlistentry>
143 </variablelist>
144
145 </sect1>
146
147 <sect1 id="whitespaces">
148 <title>Whitespaces handling and safety</title>
149
150 <para>
151 While there are currently some limitations in ebuilds and in Portage
152 code that disallow using paths with spaces for important directories
153 like the merge root, the temporary directory and the portage tree
154 directory, autoepatch was supposed not to break even if all of them had
155 all kind of special characters. Unfortunately this is not always
156 possible, because of limitations in the tools and the language used.
157 </para>
158
159 <para>
160 The biggest limitation is provided by bash itself: variables cannot
161 contain the NULL character, which means that the targets cannot be
162 passed with the output of find -print0 or grep -Z, so the targets
163 have to be separated by the \n sequence (new line).
164 </para>
165
166 <para>
167 To try minimising the possibility of problems during piping throught
168 different commands (find, grep and so on), it is suggested to use the
169 option <emphasis>find $dir -exec cmd {} +</emphasis> rather than using
170 -print and xargs (this also avoids one process spawn), and if you need
171 to pass the result of grep -l, also add the --null parameter.
172 </para>
173
174 <warning>
175 <para>
176 For reasons far from our understanding, FreeBSD people decided to
177 use the -Z option to GNU grep to support running grep over
178 gzip-compressed files. For compatibility and portability, rather
179 than using the -Z option, you should use the --null option in
180 autoepatch patchsets, which would behave consistently on both Linux
181 and non-Linux systems.
182 </para>
183 </warning>
184
185 </sect1>
186
187 <sect1 id="prefixsupport">
188 <title>Alternative prefixes support</title>
189
190 <para>
191 Although Portage, at the time of writing, it's limited to work as a
192 primary package manager and does not support officially a way to
193 install packages on an alternate prefix (like /usr/local or something
194 else), autoepatch is designed to support being installed in an
195 arbitrary prefix from day one.
196 </para>
197
198 <para>
199 To install autoepatch on a different prefix, you should just replace
200 the string <emphasis>@PREFIX@</emphasis> with the prefix the package
201 is installed in the file autoepatch.sh.
202 </para>
203
204 </sect1>
205
206 </chapter>

  ViewVC Help
Powered by ViewVC 1.1.20