1 |
<?xml version="1.0" encoding="ISO-8859-1"?> |
2 |
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11-strict.dtd"> |
3 |
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en"> |
4 |
<head> |
5 |
<meta http-equiv="Content-Style-Type" content="text/css"/> |
6 |
<style type="text/css">@import "style.css";</style> |
7 |
<title>IRC Services Technical Reference Manual - 10. Compilation</title> |
8 |
</head> |
9 |
|
10 |
<body> |
11 |
<h1 class="title" id="top">IRC Services Technical Reference Manual</h1> |
12 |
|
13 |
<h2 class="section-title">10. Compilation</h2> |
14 |
|
15 |
<p class="section-toc"> |
16 |
10-1. <a href="#s1">Compilation overview</a> |
17 |
<br/>10-2. <a href="#s2">The <tt>configure</tt> script</a> |
18 |
<br/>10-3. <a href="#s3">The compilation process</a> |
19 |
<br/> 10-3-1. <a href="#s3-1">Core source files</a> |
20 |
<br/> 10-3-2. <a href="#s3-2">Modules</a> |
21 |
<br/> 10-3-3. <a href="#s3-3">Language files</a> |
22 |
<br/> 10-3-4. <a href="#s3-4">The <tt>tools</tt> and <tt>data</tt> directories</a> |
23 |
<br/>10-4. <a href="#s4">Installation</a> |
24 |
<br/>10-5. <a href="#s5">Assumptions</a> |
25 |
</p> |
26 |
|
27 |
<p class="backlink"><a href="9.html">Previous section: The database conversion tool</a> | |
28 |
<a href="index.html">Table of Contents</a> | |
29 |
<a href="11.html">Next section: Future work</a></p> |
30 |
|
31 |
<!------------------------------------------------------------------------> |
32 |
<hr/> |
33 |
|
34 |
<h3 class="subsection-title" id="s1">10-1. Compilation overview</h3> |
35 |
|
36 |
<p>Services uses the common <tt>configure; make; make install</tt> method |
37 |
for compilation. The <tt>configure</tt> script in the top directory tests |
38 |
the system compiler and environment to ensure Services can be compiled and |
39 |
to compensate for differences between systems, such as broken or missing |
40 |
implementations of system library functions; once it has run, the source |
41 |
files are compiled using the <tt>make</tt> tool. Once compilation is |
42 |
complete, the command <tt>make install</tt> will install the executable |
43 |
and data files to their final location on the system as specified by |
44 |
parameters to the <tt>configure</tt> script (or using the defaults from |
45 |
that script).</p> |
46 |
|
47 |
<p class="backlink"><a href="#top">Back to top</a></p> |
48 |
|
49 |
<!------------------------------------------------------------------------> |
50 |
<hr/> |
51 |
|
52 |
<h3 class="subsection-title" id="s2">10-2. The <tt>configure</tt> script</h3> |
53 |
|
54 |
<p>Before the source code can be compiled, certain features of the compiler |
55 |
and environment need to be checked, and appropriate settings made; this is |
56 |
performed by the <tt>configure</tt> script present in the top directory. |
57 |
The script performs the following operations:</p> |
58 |
|
59 |
<ul> |
60 |
|
61 |
<li class="spaced">Defines miscellaneous utility functions.</li> |
62 |
|
63 |
<li class="spaced">Creates a temporary directory, for storing files used in |
64 |
the tests. The directory name is defined to be "conf-tmp" at the top of |
65 |
the script. If the directory already exists (because a previous |
66 |
<tt>configure</tt> run was aborted, for example), that directory is |
67 |
used.</li> |
68 |
|
69 |
<li class="spaced">Initializes configuration and command-line option |
70 |
variables.</li> |
71 |
|
72 |
<li class="spaced">Parses command-line options. See |
73 |
<a href="../2.html#table2-2">table 2-2</a> in section 2 of the main |
74 |
manual for a list of all recognized options.</li> |
75 |
|
76 |
<li class="spaced">Loads the results of any previous run from the cache |
77 |
file, <tt>config.cache</tt>, unless the <tt>-ignore-cache</tt> option is |
78 |
given. If the cache was created by an earlier version of the script, |
79 |
appropriate adjustments are made to the cached results (usually clearing |
80 |
the affected variable or variables so that the modified test is run |
81 |
again). Note that the loading is done via a <tt>source</tt> command, |
82 |
executing the commands in the cache file directly, which can lead to |
83 |
security problems if the user is tricked into storing a malicious cache |
84 |
file in the Services directory.</li> |
85 |
|
86 |
<li class="spaced">Determines installation directories for executable files |
87 |
(variable <tt>BINDEST</tt>) and data files (variable <tt>DATDEST</tt>), |
88 |
either from the <tt>-prefix</tt>, <tt>-bindest</tt>, and <tt>-datdest</tt> |
89 |
options, or from the defaults included in the script, as follows: |
90 |
<ul> |
91 |
<li>If the <tt>-prefix</tt> option is given with a parameter |
92 |
<tt><i>PATH</i></tt>, then the executable directory is set to |
93 |
<tt><i>PATH</i>/sbin</tt> and the data directory is set to |
94 |
<tt><i>PATH</i>/lib/<i>PROGRAM</i></tt>, where <tt><i>PROGRAM</i></tt> is |
95 |
the program name given to the <tt>-program</tt> option (or the default of |
96 |
"<tt>ircservices</tt>" if the <tt>-program</tt> option is not given).</li> |
97 |
<li>If the <tt>-prefix</tt> option is not given and the <tt>-bindest</tt> |
98 |
option is given, then the executable directory is set to the path given by |
99 |
the <tt>-bindest</tt> option.</li> |
100 |
<li>If neither of the <tt>-prefix</tt> or <tt>-bindest</tt> options are |
101 |
given, then the executable directory is set to the cached value of the |
102 |
<tt>BINDEST</tt> variable if present; otherwise, the default of |
103 |
<tt>/usr/local/sbin</tt> is used.</li> |
104 |
<li>If the <tt>-prefix</tt> option is not given and the <tt>-datdest</tt> |
105 |
option is present, then the data directory is set to the path given by the |
106 |
<tt>-datdest</tt> option.</li> |
107 |
<li>If neither of the <tt>-prefix</tt> or <tt>-datdest</tt> options are |
108 |
given, but the <tt>-bindest</tt> option is given, then the data directory |
109 |
is set to a path derived from the executable directory, by either replacing |
110 |
a trailing <tt>/sbin</tt> or <tt>/bin</tt> with <tt>/lib/<i>PROGRAM</i></tt> |
111 |
or appending <tt>/lib</tt> if the executable directory does not end in |
112 |
<tt>/sbin</tt> or <tt>/bin</tt>.</li> |
113 |
<li>If none of the <tt>-prefix</tt>, <tt>-bindest</tt>, or <tt>-datdest</tt> |
114 |
options are given, then the data directory is set to the cached value of |
115 |
the <tt>DATDEST</tt> variable if present; otherwise, the default of |
116 |
<tt>/usr/local/lib/<i>PROGRAM</i></tt> is used.</li> |
117 |
</ul> |
118 |
Note that the current Services architecture does not allow data files to be |
119 |
stored in multiple separate locations.</li> |
120 |
|
121 |
<li class="spaced">Opens the log file (<tt>configure.log</tt>). |
122 |
Significant commands run by the script, and the results of all tests, are |
123 |
logged to this file to aid diagnosis in case of problems. Each test is |
124 |
given a distinctive name, written at the beginning of each line in the log; |
125 |
these names are given in the descriptions below.</li> |
126 |
|
127 |
<li class="spaced">(<span class="configure-test-name">check_test_nt</span>) |
128 |
Checks whether the shell's built-in <tt>test</tt> command, if any, or the |
129 |
system <tt>/bin/test</tt> or <tt>/usr/bin/test</tt> command supports the |
130 |
<tt>-nt</tt> option for testing whether one file is newer than another. |
131 |
Some shells, such as <tt>/bin/sh</tt> on at least some versions of the |
132 |
Solaris operating system, do not support the <tt>-nt</tt> test. This test |
133 |
is required for module compilation |
134 |
(see <a href="#s3-2">section 10-3-2</a>).</li> |
135 |
|
136 |
<li class="spaced">(<span class="configure-test-name">find_cc</span>) |
137 |
Determines the program to use to compile source files. This program is |
138 |
assumed to be able to link object files into an executable as well. If the |
139 |
<tt>-cc</tt> option or a cached result is available, they are used in that |
140 |
order of preference, and subsequent compiler checks are bypassed. |
141 |
Otherwise, the commands <tt>gcc</tt>, <tt>icc</tt>, and <tt>cc</tt> are |
142 |
checked in that order, and the first one that is able to compile a short |
143 |
test program is used as the C compiler. (However, if <tt>gcc</tt> is |
144 |
chosen and the version cannot be confirmed to be at least 3.2, the script |
145 |
aborts; likewise, if another compiler is chosen and it is unable to compile |
146 |
ANSI C programs, the script aborts.) Finally, the chosen compiler is |
147 |
tested to ensure that it understands variadic-argument macros and the |
148 |
<tt>va_copy</tt> function, C99 features that Services makes use of.</li> |
149 |
|
150 |
<li class="spaced">(<span class="configure-test-name">find_ccopts</span>) |
151 |
Determines the command-line options to use with the C compiler for |
152 |
compiling source code. If the <tt>-cflags</tt> option is given, the |
153 |
specified option string is used; if <tt>-cflags</tt> is not given and the |
154 |
cached result for the C compiler program name was chosen, the cached option |
155 |
string is used; otherwise, a default option string is chosen by the |
156 |
<tt>def_cc_flags</tt> function. In the latter case, the compiler is |
157 |
checked for the presence of the GCC |
158 |
<a href="http://www.research.ibm.com/trl/projects/security/ssp/">stack-protector |
159 |
extension</a> <span class="remotehost">[www.research.ibm.com]</span>; at |
160 |
least some versions of this extension have a bug which causes incorrect |
161 |
code to be generated, and if the extension is present and this bug is |
162 |
detected, <tt>-fno-stack-protector</tt> is added to the default option |
163 |
string to disable this extension. A test is made with the default flags to |
164 |
ensure that the compiler accepts them, and if the test fails, an empty |
165 |
option string is used instead. |
166 |
<br/><br/> |
167 |
Regardless of the method used to find the flags, a final test is made to |
168 |
ensure that the compilation with the selected flag set does not cause the |
169 |
stack-protector bug to appear. (This bug relates to the GCC |
170 |
<tt>__builtin_apply</tt> and <tt>__builtin_return</tt> facility for passing |
171 |
a function call through to a different function, used in Services to handle |
172 |
imported functions in the <tt>database/version4</tt> module. There have |
173 |
been other bugs in the implementation of this facility as well, so the test |
174 |
is carefully written to avoid triggering them.)</li> |
175 |
|
176 |
<li class="spaced">(<span class="configure-test-name">check_gcc_builtin</span>) |
177 |
Checks for bugs in the implementation of the GCC <tt>__builtin_apply</tt> |
178 |
and <tt>__builtin_return</tt> facility, if understood by the compiler. At |
179 |
least three bugs are present in various versions of GCC, noted in the GCC |
180 |
Bugzilla tracker as bugs |
181 |
<a href="http://gcc.gnu.org/bugzilla/show_bug.cgi?id=8028">8028</a>, |
182 |
<a href="http://gcc.gnu.org/bugzilla/show_bug.cgi?id=11151">11151</a>, and |
183 |
<a href="http://gcc.gnu.org/bugzilla/show_bug.cgi?id=20076">20076</a> |
184 |
<span class="remotehost">[gcc.gnu.org]</span>. Bug 20076 is not relevant |
185 |
to Services, but if one of the other bugs is detected, the script will |
186 |
activate assembly-language workarounds for i386, Sparc, and PowerPC CPUs, |
187 |
and abort on other processors since no workaround is available. |
188 |
</li> |
189 |
|
190 |
<li class="spaced">(<span class="configure-test-name">find_lflags</span>) |
191 |
Determines what options to use when linking executables. Uses the option |
192 |
string given with the <tt>-lflags</tt> option, the previous cached result, |
193 |
or an empty string, in that order of preference.</li> |
194 |
|
195 |
<li class="spaced">(<span class="configure-test-name">find_exe_suffix</span>) |
196 |
Checks what filename extension, if any, is appended to executable |
197 |
filenames by the compiler/linker.</li> |
198 |
|
199 |
<li class="spaced">(<span class="configure-test-name">find_libs</span>) |
200 |
Determines what additional libraries need to be specified on the link |
201 |
command line. Checks are made for <tt>-lm</tt>, <tt>-lsocket</tt>, |
202 |
<tt>-lresolv</tt>, <tt>-lnsl</tt>, and <tt>-lcrypt</tt>; if relevant |
203 |
functions from these libraries cannot be called without the corresponding |
204 |
<tt>-l</tt> option, the option is added to the library option string. If |
205 |
the <tt>-libs</tt> option is passed to the script, its parameter is |
206 |
appended to the library option string after all library checks are done.</li> |
207 |
|
208 |
<li class="spaced">(<span class="configure-test-name">check_shared</span>) |
209 |
Checks whether dynamic (shared-object) modules can be used. If the |
210 |
<tt>-use-static-modules</tt> option is given, dynamic modules are disabled; |
211 |
if not, and if a cached result is available, that result is used. |
212 |
Otherwise, a check is first made for the presence of the <tt>dlfcn.h</tt> |
213 |
header file, using the <tt>test_include</tt> function (see the |
214 |
<tt>check_stdint</tt> test below). If this file is present, the script |
215 |
proceeds to check whether <tt>-ldl</tt> is needed to access the dynamic |
216 |
loader functions and ensure that <tt>-rdynamic</tt> and <tt>-shared</tt> |
217 |
can be used with the compiler. A check is then made that attempts to open |
218 |
shared objects with unresolved symbols fail, and that shared objects with |
219 |
no unresolved symbols can in fact be used properly. If these tests |
220 |
succeed, a final check is made to determine whether symbol lookups require |
221 |
an underscore prepended to the symbol name or not. If any test fails, |
222 |
dynamic modules are disabled.</li> |
223 |
|
224 |
<li class="spaced">(<span class="configure-test-name">check_ranlib</span>) |
225 |
Checks whether the <tt>ranlib</tt> program exists on the system. If a |
226 |
cached result is not available, a dummy file is created, and the |
227 |
<tt>ar</tt> program is used to add it to a dummy archive (if <tt>ar</tt> is |
228 |
not available, the script aborts). <tt>ranlib</tt> is then run on this |
229 |
archive, and the success or failure of the command is recorded.</li> |
230 |
|
231 |
<li class="spaced">(<span class="configure-test-name">check_stdint</span>) |
232 |
Checks for the presence of the <tt>stdint.h</tt> header. This is done by |
233 |
calling the <tt>test_include</tt> function, which first checks whether the |
234 |
given file exists in /usr/include, then, if the file is not found, checks |
235 |
whether a test program that includes the file with <tt>#include</tt> can be |
236 |
compiled. The variable <tt>HAVE_<i>header_name</i></tt>, where |
237 |
<tt><i>header_name</i></tt> is the header filename converted to upper case |
238 |
with non-alphanumeric characters replaced by underscores, is then set to 1 |
239 |
or 0 if the test succeeded or failed, respectively. The return value of |
240 |
the function itself is the success or failure of the test.</li> |
241 |
|
242 |
<li class="spaced">(<span class="configure-test-name">check_strings</span>) |
243 |
Checks for the presence of the <tt>strings.h</tt> header.</li> |
244 |
|
245 |
<li class="spaced">(<span class="configure-test-name">check_sysselect</span>) |
246 |
Checks for the presence of the <tt>sys/select.h</tt> header.</li> |
247 |
|
248 |
<li class="spaced">(<span class="configure-test-name">check_sysproto</span>) |
249 |
Checks for the presence of the <tt>sys/proto.h</tt> header.</li> |
250 |
|
251 |
<li class="spaced">(<span class="configure-test-name">check_int8</span>) |
252 |
Determines what type can be used for 8-bit integers. The <tt>char</tt> |
253 |
type, and the <tt>int8_t</tt> type if the <tt>stdint.h</tt> header is |
254 |
present, are checked first, giving preference to <tt>int8_t</tt> if |
255 |
available; if neither is an 8-bit type, a <tt>byte</tt> type is checked for |
256 |
next. If that type does not exist or is not 8 bits wide, the script |
257 |
aborts. The selected type is used to declare the <tt>int8</tt> and |
258 |
<tt>uint8</tt> types. (As described in <a href="11.html#s1">section |
259 |
11-1</a>, Services development was started before <tt>stdint.h</tt> and |
260 |
the sized integer types were standardized, hence the use of nonstandard |
261 |
type names.)</li> |
262 |
|
263 |
<li class="spaced">(<span class="configure-test-name">check_int16</span>) |
264 |
Determines what type can be used for 16-bit integers, selecting among |
265 |
<tt>int16_t</tt> (if present), <tt>int</tt>, and <tt>short</tt> in that |
266 |
order. The selected type is used to declare the <tt>int16</tt> and |
267 |
<tt>uint16</tt> types.</li> |
268 |
|
269 |
<li class="spaced">(<span class="configure-test-name">check_int32</span>) |
270 |
Determines what type can be used for 32-bit integers, selecting among |
271 |
<tt>int32_t</tt> (if present), <tt>int</tt>, and <tt>long</tt> in that |
272 |
order. The selected type is used to declare the <tt>int32</tt> and |
273 |
<tt>uint32</tt> types.</li> |
274 |
|
275 |
<li class="spaced">(<span class="configure-test-name">check_int_size</span>) |
276 |
Finds the size of the <tt>int</tt> type. If the <tt>int</tt> type is less |
277 |
than 16 bits wide (a violation of the C standard), the script aborts.</li> |
278 |
|
279 |
<li class="spaced">(<span class="configure-test-name">check_long_size</span>) |
280 |
Finds the size of the <tt>long</tt> type. If the <tt>long</tt> type is less |
281 |
than 32 bits wide (a violation of the C standard), the script aborts.</li> |
282 |
|
283 |
<li class="spaced">(<span class="configure-test-name">check_ptr_size</span>) |
284 |
Finds the size of pointer types. If pointers are smaller than integers, |
285 |
the script aborts (see <a href="#s5">section 10-5</a> regarding this |
286 |
assumption).</li> |
287 |
|
288 |
<li class="spaced">(<span class="configure-test-name">check_time_t</span>) |
289 |
Finds the size of the <tt>time_t</tt> type. If the <tt>time_t</tt> type is |
290 |
less than 32 bits wide, the script aborts.</li> |
291 |
|
292 |
<li class="spaced">(<span class="configure-test-name">check_gid_t</span>) |
293 |
Checks for the presence of the <tt>gid_t</tt> type and finds its size.</li> |
294 |
|
295 |
<li class="spaced">(<span class="configure-test-name">check_socklen_t</span>) |
296 |
Checks for the presence of the <tt>socklen_t</tt> type.</li> |
297 |
|
298 |
<li class="spaced">(<span class="configure-test-name">check_aix_intNN</span>) |
299 |
Checks whether system headers define the <tt>int16</tt> and <tt>int32</tt> |
300 |
types, which clash with type names used in Services. The |
301 |
<tt>sys/systypes.h</tt> header in at least some versions of the AIX |
302 |
operating system seems to define these.</li> |
303 |
|
304 |
<li class="spaced">(<span class="configure-test-name">check_strerror</span>) |
305 |
Checks for how system error numbers can be converted to descriptive |
306 |
strings. The <tt>strerror()</tt> function is used preferentially if |
307 |
present; if not, a compatibility function in <tt>compat.c</tt> implements |
308 |
<tt>strerror()</tt>, using either the system's <tt>sys_errlist[]</tt> array |
309 |
if present, or a built-in message list if not. However, if the |
310 |
<tt>-use-local-funcs</tt> option was given, this test is skipped and the |
311 |
compatibility function (assuming no <tt>sys_errlist[]</tt>) is used.</li> |
312 |
|
313 |
<li class="spaced">(<span class="configure-test-name">check_compat</span>) |
314 |
Checks for compatibility functions that need to be enabled. At this stage, |
315 |
the <tt>-use-local-funcs</tt> option is checked and, if present, |
316 |
compatibility functions for all functions below through <tt>strsignal()</tt> |
317 |
are enabled. If not, and cached results are available for all functions, |
318 |
those results are used. If not, testing proceeds to each individual |
319 |
function test.</li> |
320 |
|
321 |
<li class="spaced">(<span class="configure-test-name">check_hstrerror</span>) |
322 |
Checks for the presence of the <tt>check_hstrerror()</tt> function. This |
323 |
is done by calling the <tt>test_function</tt> function, which attempts to |
324 |
compile a test program which calls the function (the contents of the test |
325 |
program are specified by the called). If the compilation succeeds and the |
326 |
test program returns a successful exit code (0), the function is assumed to |
327 |
exist. As with <tt>test_include</tt>, the variable |
328 |
<tt>HAVE_<i>function_name</i></tt> (where <tt><i>function_name</i></tt> is |
329 |
the function name in upper-case) and return value are set according to the |
330 |
test result.</li> |
331 |
|
332 |
<li class="spaced">(<span class="configure-test-name">check_snprintf</span>) |
333 |
Checks for the presence and behavior of the <tt>snprintf()</tt> function |
334 |
(if found, the <tt>vsnprintf()</tt> function is assumed to also exist). |
335 |
Services ignores the possibility of string truncation—which is |
336 |
probably a security issue in some cases; see also |
337 |
<a href="11.html#s1">section 11-1</a>—and expects <tt>snprintf()</tt> |
338 |
to return the number of characters actually written into the buffer. If |
339 |
<tt>snprintf()</tt> is available but uses a different return value scheme, |
340 |
a compatibility function translates the return value to what Services |
341 |
expects. If <tt>snprintf()</tt> is not available at all, the version |
342 |
included in <tt>vsnprintf.c</tt> is used.</li> |
343 |
|
344 |
<li class="spaced">(<span class="configure-test-name">check_strtok</span>) |
345 |
Checks for the presence and behavior of the <tt>strtok()</tt> function. |
346 |
Some system library implementations of <tt>strtok()</tt> have been found to |
347 |
contain bugs, which are checked for by this test.</li> |
348 |
|
349 |
<li class="spaced">(<span class="configure-test-name">check_stricmp</span>) |
350 |
Checks for the presence of the <tt>stricmp()</tt> function. This is |
351 |
equivalent to the POSIX <tt>strcasecmp()</tt> function, but has a more |
352 |
concise and clearer name (I always have to stop and remember that the |
353 |
"case" in <tt>strcasecmp</tt> means that case is <i>ignored</i> rather |
354 |
than that it is compared). If <tt>stricmp()</tt> is not available but |
355 |
<tt>strcasecmp()</tt> is available, the former is made an alias for the |
356 |
latter via <tt>#define</tt>.</li> |
357 |
|
358 |
<li class="spaced">(<span class="configure-test-name">check_strdup</span>) |
359 |
Checks for the presence of the <tt>strdup()</tt> function.</li> |
360 |
|
361 |
<li class="spaced">(<span class="configure-test-name">check_strspn</span>) |
362 |
Checks for the presence of the <tt>strspn()</tt> and <tt>strcspn()</tt> |
363 |
functions (the variable set is <tt>HAVE_STRSPN</tt>).</li> |
364 |
|
365 |
<li class="spaced">(<span class="configure-test-name">check_strsignal</span>) |
366 |
Checks for the presence of the <tt>strsignal()</tt> function.</li> |
367 |
|
368 |
<li class="spaced">(<span class="configure-test-name">check_gettimeofday</span>) |
369 |
Checks for the presence of the <tt>gettimeofday()</tt> function.</li> |
370 |
|
371 |
<li class="spaced">(<span class="configure-test-name">check_setgrent</span>) |
372 |
Checks for the presence of the <tt>setgrent()</tt> function. However, if |
373 |
the <tt>gid_t</tt> type does not exist, the test is not executed and the |
374 |
function is assumed to not exist.</li> |
375 |
|
376 |
<li class="spaced">(<span class="configure-test-name">check_setregid</span>) |
377 |
Checks for the presence of the <tt>setregid()</tt> function. However, if |
378 |
the <tt>gid_t</tt> type does not exist, the test is not executed and the |
379 |
function is assumed to not exist.</li> |
380 |
|
381 |
<li class="spaced">(<span class="configure-test-name">check_umask</span>) |
382 |
Checks for the presence of the <tt>umask()</tt> function.</li> |
383 |
|
384 |
<li class="spaced">(<span class="configure-test-name">check_fork</span>) |
385 |
Checks for the presence of the <tt>fork()</tt> function.</li> |
386 |
|
387 |
<li class="spaced">(<span class="configure-test-name">check_gethostbyname</span>) |
388 |
Checks for the presence of the <tt>gethostbyname()</tt> function.</li> |
389 |
|
390 |
<li class="spaced">(<span class="configure-test-name">check_getsetrlimit</span>) |
391 |
Checks for the presence of the <tt>getrlimit()</tt> and <tt>setrlimit()</tt> |
392 |
functions.</li> |
393 |
|
394 |
<li class="spaced">(<span class="configure-test-name">check_crypt</span>) |
395 |
Checks for the presence of the <tt>crypt()</tt> function.</li> |
396 |
|
397 |
<li class="spaced">(<span class="configure-test-name">check_install</span>) |
398 |
Checks whether a working <tt>install</tt> program exists on the system. If |
399 |
not, the <tt>install-script</tt> script included in the top source |
400 |
directory is used instead.</li> |
401 |
|
402 |
<li class="spaced">(<span class="configure-test-name">check_install-d</span>) |
403 |
Checks whether <tt>install -d</tt> can be used to create directories. If |
404 |
not, <tt>mkdir</tt> is tried as a workaround, falling back to the |
405 |
<tt>install-script</tt> script if necessary.</li> |
406 |
|
407 |
<li class="spaced">(<span class="configure-test-name">check_copy_recurse</span>) |
408 |
Determines what command should be used to copy entire directories. The |
409 |
default command is <tt>cp -dpr</tt> in Linux and Cygwin environments, and |
410 |
<tt>cp -pr</tt> in other environments. If this command does not work, the |
411 |
<tt>tar</tt> command is used as a substitute if possible (see the |
412 |
<tt>cp-recursive</tt> script in the top source directory). If <tt>tar</tt> |
413 |
cannot be used either, the script aborts.</li> |
414 |
|
415 |
<li class="spaced">Creates the file <tt>config.h</tt>, containing the |
416 |
results of configuration relevant to the source code (such as compilation |
417 |
options and required compatibility functions) as <tt>#define</tt> |
418 |
preprocessor macros. If the <tt>config.h</tt> file already exists and the |
419 |
content of the new <tt>config.h</tt> to be written is unchanged from that |
420 |
in the existing file, the existing file is left untouched, so as not to |
421 |
cause an unneeded recompile of all source files if <tt>configure</tt> is |
422 |
re-run with identical parameters.</li> |
423 |
|
424 |
<li class="spaced">Creates the file <tt>Makefile.inc</tt>, containing the |
425 |
results of configuration relevant to compilation commands (such as the |
426 |
compiler command and options and installation directories) as <tt>make</tt> |
427 |
variables. As above, if <tt>Makefile.inc</tt> already exists and its |
428 |
content has not changed, the old file is left alone.</li> |
429 |
|
430 |
<li class="spaced">Creates the cache file <tt>config.cache</tt>, saving the |
431 |
results of configuration so that a subsequent run of the <tt>configure</tt> |
432 |
script will execute faster. The file is written as a sequence of shell |
433 |
commands, so that it can simply be sourced at runtime rather than parsing |
434 |
each line individually.</li> |
435 |
|
436 |
</ul> |
437 |
|
438 |
<p>Note that a deliberate decision was made to not use the GNU |
439 |
<tt>autoconf</tt>/<tt>automake</tt>/<tt>libtool</tt> suite of tools, as |
440 |
they are overly complex for the range of systems Services is expected to be |
441 |
used on. (I have seen far too many programs where running the |
442 |
autoconf-generated <tt>configure</tt> script takes longer than compiling |
443 |
the program itself.)</p> |
444 |
|
445 |
<p class="backlink"><a href="#top">Back to top</a></p> |
446 |
|
447 |
<!------------------------------------------------------------------------> |
448 |
<hr/> |
449 |
|
450 |
<h3 class="subsection-title" id="s3">10-3. The compilation process</h3> |
451 |
|
452 |
<p>Overall compilation is controlled by the <tt>Makefile</tt> in the top |
453 |
source directory. When run with no target specified, the default target |
454 |
<tt>all</tt> is used, which first checks that the <tt>configure</tt> script |
455 |
has been run (aborting with a notice to the user if not), then proceeds to |
456 |
actual compilation with the <tt>myall</tt> target. This target compiles |
457 |
the main program (<tt>ircservices</tt> or <tt>ircservices.exe</tt>), then |
458 |
generates the language files and creates the <tt>convert-db</tt> and |
459 |
<tt>ircservices-chk</tt> tools.</p> |
460 |
|
461 |
<p>Additional targets available are: <tt>install</tt>, which installs |
462 |
program and data files to the appropriate directories (see |
463 |
<a href="#s4">section 10-4</a>); <tt>clean</tt>, which removes most |
464 |
generated files, such as object and executable files; and |
465 |
<tt>spotless</tt>, or <tt>distclean</tt> in the GNU style, which removes |
466 |
<i>all</i> generated files (including <tt>config.cache</tt>). All of these |
467 |
targets are called recursively for the <tt>modules</tt>, <tt>lang</tt>, and |
468 |
<tt>tools</tt> directories.</p> |
469 |
|
470 |
<p>The main Makefile also includes two rules, for <tt>services.h</tt> and |
471 |
<tt>language.h</tt>, which cause those files to be <tt>touch</tt>ed (the |
472 |
file timestamp updated) whenever any sub-header file changes. This is |
473 |
done because it is considered easier than ensuring that every dependency |
474 |
list stays up to date with all sub-header files.</p> |
475 |
|
476 |
<p class="backlink"><a href="#top">Back to top</a></p> |
477 |
|
478 |
|
479 |
<h4 class="subsubsection-title" id="s3-1">10-3-1. Core source files</h4> |
480 |
|
481 |
<p>Compilation of the main executable starts with compilation of the core |
482 |
source files, stored in the top source directory. The object files to be |
483 |
created are listed in alphabetical order in the <tt>$(OBJS)</tt> variable. |
484 |
The options used for compilation are <tt>-DSTATIC_MODULES</tt> if using |
485 |
static modules, followed by the options selected by the <tt>configure</tt> |
486 |
script (in the <tt>$(BASE_CFLAGS)</tt> variable), followed by the options |
487 |
in the <tt>$(MORE_CFLAGS)</tt> variable (defined at the top of the |
488 |
Makefile, intended for users to add or change extra options on the fly).</p> |
489 |
|
490 |
<p>After compiling all of the core source files, compilation proceeds to |
491 |
the modules, as described below; finally, a <tt>version.c</tt> file is |
492 |
generated by the <tt>version.sh</tt> script, containing the program version |
493 |
number and a build number (extracted from the previous contents of |
494 |
<tt>version.c</tt>) which is incremented by one each build, and this file |
495 |
is compiled and linked with the rest of the main source files, as well as |
496 |
the modules when compiling modules statically, to produce the main |
497 |
executable.</p> |
498 |
|
499 |
<p>Note that one core header file, <tt>langstrs.h</tt>, is copied from the |
500 |
language file subdirectory, where it is first generated if necessary; see |
501 |
<a href="#s3-3">section 10-3-3</a> below for details.</p> |
502 |
|
503 |
<p class="backlink"><a href="#top">Back to top</a></p> |
504 |
|
505 |
|
506 |
<h4 class="subsubsection-title" id="s3-2">10-3-2. Modules</h4> |
507 |
|
508 |
<p>Compilation of modules is handled by <tt>modules/Makefile</tt> and its |
509 |
auxiliary file, <tt>modules/Makerules</tt>. The top directory's Makefile |
510 |
calls one of two targets in <tt>modules/Makefile</tt> to compile all |
511 |
available modules: <tt>all-dynamic</tt> if dynamic linking is in use, |
512 |
<tt>all-static</tt> for static linking. Both of these targets perform the |
513 |
same basic function: search for all subdirectories of the <tt>modules</tt> |
514 |
directory that contain Makefiles, and call the <tt>all-dynamic</tt> or |
515 |
<tt>all-static</tt> target in each subdirectory's Makefile.</p> |
516 |
|
517 |
<p>Since the subdirectory search is performed at compilation time, it is |
518 |
possible to add new modules to Services by simply copying the directory |
519 |
containing the module source code and Makefile into the <tt>modules</tt> |
520 |
directory. This is in fact the recommended method for installing |
521 |
third-party modules, and the module compilation system was designed with |
522 |
this aim in mind.</p> |
523 |
|
524 |
<p>Of the two main targets in <tt>modules/Makefile</tt>, the |
525 |
<tt>all-dynamic</tt> target is the simpler of the two. It loops through |
526 |
all subdirectories, calling the <tt>all-dynamic</tt> target in each, then |
527 |
updates a dummy <tt>.stamp</tt> file if the subdirectory's <tt>.stamp</tt> |
528 |
file was updated. This file is used by the main Makefile to determine |
529 |
whether <tt>version.c</tt> should be regenerated.</p> |
530 |
|
531 |
<p>For static modules, the process is slightly more complicated, since a |
532 |
list of all modules and exported symbols must be provided to the core |
533 |
module manager. In addition to calling each subdirectory's |
534 |
<tt>all-static</tt> target, the <tt>.modext-*</tt>, <tt>.modsyms-*</tt>, |
535 |
and <tt>.modlist-*</tt> files in each subdirectory are concatenated to |
536 |
form module and symbol lists; these are then compiled into an additional |
537 |
object file, <tt>modlist.o</tt>, and an archive (<tt>modules.a</tt>) is |
538 |
created containing this file and all module object files. This archive is |
539 |
then linked into the final executable.</p> |
540 |
|
541 |
<p>The compilation of individual modules is handled by the |
542 |
<tt>modules/Makerules</tt> file, which is included by each subdirectory's |
543 |
Makefile. This file is designed so that individual module Makefiles need |
544 |
only set up some variables with lists of files to be compiled and include |
545 |
the <tt>Makerules</tt> file. However, due in part to limitations of the |
546 |
GNU <tt>make</tt> program, the actual implementation is quite complex, and |
547 |
as a side effect it takes <tt>make</tt> considerable time to process the |
548 |
module subdirectories even when no files need to be recompiled.</p> |
549 |
|
550 |
<p>The limitation in <tt>make</tt> which I found no easy way around during |
551 |
development is that there is (or was; see <a href="11.html#s1-gmake">the |
552 |
relevant note in section 11-1</a> for a method that works with newer |
553 |
versions of GNU <tt>make</tt>) no way to specify a rule in which the name |
554 |
of a variable specifying a dependency varies with the target name. For |
555 |
example, suppose a subdirectory contains two modules, <tt>module1</tt> and |
556 |
<tt>module2</tt>. If each module consists of only one source file and has |
557 |
no other dependencies, the rule is simple (assuming dynamic modules, and |
558 |
assuming the presence of a <tt>%.o: %.c</tt> compilation rule):</p> |
559 |
|
560 |
<div class="code">%.so: %.o |
561 |
$(CC_SHARED) $^ -o $@</div> |
562 |
|
563 |
<p>However, suppose that <tt>module1</tt> depends on file <tt>aux1.o</tt> |
564 |
and <tt>module2</tt> depends on files <tt>aux2.o</tt> and <tt>aux3.o</tt>. |
565 |
If these are specified in <tt>$(OBJECTS-module1.so)</tt> and |
566 |
<tt>$(OBJECTS-module2.so)</tt>, one might then be tempted to write:</p> |
567 |
|
568 |
<div class="code">%.so: %.o $(OBJECTS-%.so) |
569 |
$(CC_SHARED) $^ -o $@</div> |
570 |
|
571 |
<p>Unfortunately, this does not substitute <tt>module1</tt> or |
572 |
<tt>module2</tt> in the <tt>$(OBJECTS-%.so)</tt> reference, but uses the |
573 |
value of the variable literally named <tt>OBJECTS-%.so</tt>. Nor does it |
574 |
work to use <tt>$@</tt> instead of <tt>%.so</tt> in the variable name:</p> |
575 |
|
576 |
<div class="code">%.so: OBJECTS = $(OBJECTS-$@) |
577 |
%.so: %.o $(OBJECTS) |
578 |
$(CC_SHARED) $^ -o $@</div> |
579 |
|
580 |
<p>Here, <tt>$(OBJECTS)</tt> is only defined for commands inside the |
581 |
pattern rule, so it cannot be used in the dependency list. Likewise, |
582 |
<tt>$@</tt> is only defined for the command list, so specifying |
583 |
<tt>$(OBJECTS-$@)</tt> in the dependency list also does not work.</p> |
584 |
|
585 |
<p>The upshot of all this is that in order to have a dependency list that |
586 |
varies with the target, it is necessary to call <tt>make</tt> recursively. |
587 |
The bulk of the <tt>Makerules</tt> file is dedicated to handling this |
588 |
recursive calling and setting variables appropriately for each target.</p> |
589 |
|
590 |
<p>The Makefile for a module directory typically consists only of variable |
591 |
definitions followed by the line "<tt>include ../Makerules</tt>". Chief |
592 |
among the variables required is the <tt>$(MODULES)</tt> variable, which |
593 |
lists the modules contained in the directory; each module is specified with |
594 |
a <tt>.so</tt> extension (static modules are compiled to <tt>.a</tt> |
595 |
archives, but the filename translation is handled transparently by the |
596 |
<tt>Makerules</tt> file), and is assumed to be compiled from a source file |
597 |
of the same name with a <tt>.c</tt> extension. If any additional object |
598 |
files are required by the module, they are specified in a variable named |
599 |
<tt>$(OBJECTS-<i>module</i>.so)</tt>, where <tt><i>module</i></tt> is |
600 |
replaced by the module name. Header file dependencies can be specified |
601 |
through the <tt>$(INCLUDE)</tt> variable for dependencies common to all |
602 |
object files, and <tt>$(INCLUDE-<i>object</i>.o)</tt> for a particular |
603 |
object file. If any object requires a special rule for compilation, that |
604 |
rule can be written in the Makefile, but rules are not needed for the |
605 |
ordinary case of compiling a <tt>.c</tt> source file to a <tt>.o</tt> |
606 |
object file.</p> |
607 |
|
608 |
<p>When the subdirectory's <tt>all-dynamic</tt> or <tt>all-static</tt> rule |
609 |
is first invoked, the script first checks, via pattern rules, that no |
610 |
modules have names ending in <tt>_static</tt> (which would conflict with |
611 |
the static module compilation procedure, as described below) or beginning |
612 |
with a period (which would conflict with the temporary files created during |
613 |
compilation). Then, for each module, <tt>make</tt> is called recursively |
614 |
with the <tt>$(TARGET)</tt> variable set to the target module name (with |
615 |
no filename extension), <tt>$(OBJECTS)</tt> variable set to the contents of |
616 |
the particular module's object list (<tt>$(OBJECTS-<i>module</i>.so)</tt>), |
617 |
and <tt>$(REALLY_COMPILE)</tt>, the recursion level variable, set to 1.</p> |
618 |
|
619 |
<p>When called with <tt>$(REALLY_COMPILE)</tt> equal to 1, |
620 |
<tt>Makerules</tt> instead defines a rule for the target file, |
621 |
<tt>$(TARGET).so</tt> or <tt>$(TARGET).a</tt> For dynamic modules, this |
622 |
simply involves compiling the relevant files and linking them into a |
623 |
shared object; for static modules, however, the objects will eventually be |
624 |
archived into a single <tt>modules.a</tt> archive, so no <tt>.a</tt> file |
625 |
for the individual module is actually needed. What the rule does instead |
626 |
is to record each object file's name in the <tt>.$(DIRNAME).lst</tt> file, |
627 |
which is then used by the <tt>all-static</tt> rule to link all object files |
628 |
in the directory into a single object <tt>$(DIRNAME).o</tt> for storing in |
629 |
the <tt>modules.a</tt> archive. (A dummy <tt>$(TARGET).a</tt> file is also |
630 |
created so that <tt>make</tt> can perform its file timestamp checks.) In |
631 |
addition, since the static module manager requires a list of names and |
632 |
pointers for all variables and functions exported by each module, the |
633 |
static module compilation rule searches through all source files—each |
634 |
object file is assumed to correspond to a single source file with the same |
635 |
name and a <tt>.c</tt> extension, and no header files are checked—for |
636 |
<tt>EXPORT_VAR()</tt>, <tt>EXPORT_ARRAY()</tt>, and <tt>EXPORT_FUNC()</tt> |
637 |
macro invocations. The export information given to these macros, along |
638 |
with declarations for the implicitly exported variables |
639 |
<tt>_this_module_ptr</tt> and <tt>module_version</tt>, array |
640 |
<tt>module_config[]</tt>, and functions <tt>init_module()</tt> and |
641 |
<tt>exit_module()</tt>, are written to two temporary files: |
642 |
<tt>.modext-<i>module</i>.h</tt>, containing <tt>extern</tt> declarations, |
643 |
and <tt>.modsyms-<i>module</i>.c</tt>, containing the actual symbol |
644 |
entries. A line with the module name and symbol array pointer is also |
645 |
written to <tt>.modlist-<i>module</i>.c</tt> for later inclusion in the |
646 |
overall module list.</p> |
647 |
|
648 |
<p>For each individual object file, <tt>Makerules</tt> first (at recursion |
649 |
level 1) generates a rule for compiling the object file that calls |
650 |
<tt>make</tt> recursively, with <tt>$(TARGET)</tt> now set to the object |
651 |
file's base filename (with the <tt>.o</tt> extension stripped), |
652 |
<tt>$(INCLUDES2)</tt> set to the particular object file's dependency list |
653 |
from <tt>$(INCLUDES-<i>object</i>.o)</tt>, <tt>-DMODULE</tt> and |
654 |
<tt>-DMODULE_ID=<i>module-id</i></tt> appended to <tt>$(CFLAGS)</tt> |
655 |
(<tt><i>module-id</i></tt> is a C-style identifier derived from the |
656 |
directory and module name, used to make common module identifiers unique), |
657 |
and <tt>$(REALLY_COMPILE)</tt> set to 2. In addition, for the main file |
658 |
of a module (the source file with the same name as the module), |
659 |
<tt>-DMODULE_MAIN_FILE</tt> is also appended to <tt>$(CFLAGS)</tt>.</p> |
660 |
|
661 |
<p>In this second recursion level, the actual source file compilation is |
662 |
performed. The <tt><i>object</i>.o</tt> rule does not perform the actual |
663 |
compilation, but depends on a <tt>.compiled-<i>object</i>.o</tt> dummy file |
664 |
whose rule performs the compilation and on a dummy <tt>FRC</tt> (force) |
665 |
rule; this hack prevents <tt>make</tt> from outputting "nothing to do" |
666 |
messages for every unchanged object file. The compilation command itself |
667 |
is similar to that used for the core source code, but the command is |
668 |
prefixed by a <tt>cd</tt> to the top directory, so that the relative path |
669 |
to the source file is saved in the object file's debug information. This |
670 |
allows debuggers to easily find the proper source file, even if multiple |
671 |
module subdirectories have identically-named source files.</p> |
672 |
|
673 |
<p>For static modules, a slight change is made for the module's main source |
674 |
file: rather than compiling the source file to <tt><i>module</i>.o</tt>, |
675 |
the object file is given the filename <tt><i>module</i>_static.o</tt>, and |
676 |
the five implicitly exported variables/functions (<tt>init_module()</tt>, |
677 |
etc.) are renamed via <tt>-D</tt> options to names containing the |
678 |
<tt><i>module-id</i></tt> so that they do not cause symbol conflicts with |
679 |
other modules at link time.</p> |
680 |
|
681 |
<p class="backlink"><a href="#top">Back to top</a></p> |
682 |
|
683 |
|
684 |
<h4 class="subsubsection-title" id="s3-3">10-3-3. Language files</h4> |
685 |
|
686 |
<p>The language files, stored in the <tt>lang</tt> directory, are |
687 |
precompiled into binary format to speed the startup of Services, as |
688 |
described in <a href="2.html#s8-4">section 2-8-4</a>. This precompilation |
689 |
is performed by the <tt>langcomp</tt> program, compiled from |
690 |
<tt>langcomp.c</tt>. When called with the <tt>all</tt> target, the |
691 |
Makefile first compiles <tt>langcomp</tt>, then runs it on each language |
692 |
source file to generate the corresponding precompiled binary file. In the |
693 |
special case of the Japanese language files (<tt>ja_*.l</tt>), which |
694 |
correspond to the various encodings common on Japanese computer systems, |
695 |
the EUC file (<tt>ja_euc.l</tt>) is treated as canonical, and when it |
696 |
changes, the <tt>jconv.pl</tt> script is automatically run to regenerate |
697 |
the <tt>ja_sjis.l</tt> file before compiling it to binary format. (There |
698 |
was also a JIS-encoded file, <tt>ja_jis.l</tt>, in the past, but this was |
699 |
dropped because of extra % characters in the text causing <tt>printf()</tt> |
700 |
functions to break.)</p> |
701 |
|
702 |
<p>The list of standard language strings is taken from the English language |
703 |
file, <tt>en_us.l</tt>; a simple <tt>grep</tt> is used to extract the |
704 |
string names to the <tt>index</tt> file, and this file is then used to |
705 |
generate <tt>langstrs.h</tt>, which contains the string names both as |
706 |
preprocessor (<tt>#define</tt>) constants and as a string array, available |
707 |
if <tt>LANGSTR_ARRAY</tt> is defined. The core source file |
708 |
<tt>language.c</tt> uses this array for looking up string names when |
709 |
loading external language files at runtime.</p> |
710 |
|
711 |
<p class="backlink"><a href="#top">Back to top</a></p> |
712 |
|
713 |
|
714 |
<h4 class="subsubsection-title" id="s3-4">10-3-4. The <tt>tools</tt> and <tt>data</tt> directories</h4> |
715 |
|
716 |
<p>The <tt>tools</tt> directory contains two additional programs: |
717 |
<tt>convert-db</tt>, the database conversion tool discussed in |
718 |
<a href="9.html">section 9</a>, and <tt>ircservices-chk</tt>, a simple |
719 |
script designed to run from a periodic execution utility such as |
720 |
<tt>cron</tt> to ensure that Services is restarted if it should stop for |
721 |
any reason (such as a crash).</p> |
722 |
|
723 |
<p>In addition to the main source file <tt>convert-db</tt> and the |
724 |
<tt>convert-*.c</tt> source files that handle particular database types, |
725 |
<tt>convert-db</tt> makes use of three source files from the main source |
726 |
code: <tt>compat.c</tt>, containing compatibility functions; |
727 |
<tt>modules/database/fileutil.c</tt>, containing routines to read and write |
728 |
data in binary database files; and <tt>modules/misc/xml-export.c</tt>, |
729 |
containing routines to generate an XML file from loaded data. These three |
730 |
files are compiled using special rules, which include the |
731 |
<tt>-DCONVERT_DB</tt> compiler option to trigger special handling in the |
732 |
source files for the <tt>convert-db</tt> tool.</p> |
733 |
|
734 |
<p>The "compilation" of <tt>ircservices-chk</tt> consists of simply |
735 |
replacing the <tt>@PROGRAM@</tt>, <tt>@BINDEST@</tt> and <tt>@DATDEST@</tt> |
736 |
fields in the template file <tt>ircservices-chk.in</tt> with the actual |
737 |
file/pathnames, writing the output to the file <tt>ircservices-chk</tt> |
738 |
(more precisely, <tt>$(PROGRAM)-chk</tt>, where <tt>$(PROGRAM)</tt> is the |
739 |
value of the <tt>-program</tt> option given to the <tt>configure</tt> |
740 |
script), and marking that file executable with <tt>chmod</tt>.</p> |
741 |
|
742 |
<p>Likewise, the two sample configuration files |
743 |
(<tt>example-ircservices.conf</tt> and <tt>example-modules.conf</tt>) in |
744 |
the <tt>data</tt> subdirectory are generated from template files, replacing |
745 |
occurrences of <tt>@PROGRAM@</tt> with the actual program name to give |
746 |
appropriate defaults for various file names.</p> |
747 |
|
748 |
<p class="backlink"><a href="#top">Back to top</a></p> |
749 |
|
750 |
<!------------------------------------------------------------------------> |
751 |
<hr/> |
752 |
|
753 |
<h3 class="subsection-title" id="s4">10-4. Installation</h3> |
754 |
|
755 |
<p>The <tt>install</tt> target, which like <tt>all</tt> defers actual work |
756 |
to the <tt>myinstall</tt> target, first creates the target directories, |
757 |
<tt>$(BINDEST)</tt> and <tt>$(DATDEST)</tt>, if they do not exist; copies |
758 |
the main executable file to the <tt>$(BINDEST)</tt> directory; and calls |
759 |
the <tt>install</tt> target in the <tt>modules</tt>, <tt>lang</tt>, |
760 |
<tt>tools</tt>, and <tt>data</tt> directories. However, when static |
761 |
modules are being used, the module install is skipped (since the module |
762 |
objects are linked directly into the executable, there is nothing to |
763 |
install).</p> |
764 |
|
765 |
<p>The module installation consists of calling the <tt>install</tt> target |
766 |
in each module subdirectory; this target, declared in the |
767 |
<tt>modules/Makerules</tt> file, creates a subdirectory of the same name |
768 |
inside the <tt>modules</tt> directory under <tt>$(DATDEST)</tt>, then |
769 |
copies all module shared-object files into that directory.</p> |
770 |
|
771 |
<p>The language installation first creates a <tt>language</tt> directory |
772 |
under <tt>$(DATDEST)</tt>; the precompiled language files are then copied |
773 |
into that directory.</p> |
774 |
|
775 |
<p>The tool installation copies the <tt>ircservices-chk</tt> script to |
776 |
<tt>$(BINDEST)</tt>, and the <tt>convert-db</tt> program to |
777 |
<tt>$(DATDEST)</tt>. The latter is not copied to the executable file |
778 |
directory to avoid the possibility that the executable file name conflicts |
779 |
with another program installed on the system. (A better solution might be |
780 |
to rename the program to something like <tt>ircservices-convert</tt>.)</p> |
781 |
|
782 |
<p>The data file installation copies the example configuration files, |
783 |
<tt>example-ircservices.conf</tt> and <tt>example-modules.conf</tt>, to |
784 |
<tt>$(DATDEST)</tt>; <tt>example-ircservices.conf</tt> is renamed at this |
785 |
time to <tt>example-$(PROGRAM).conf</tt>. If the <tt>helpfiles</tt> |
786 |
directory does not exist under <tt>$(DATDEST)</tt>, it is copied from the |
787 |
<tt>helpfiles</tt> subdirectory of the <tt>data</tt> directory.</p> |
788 |
|
789 |
<p>Since the <tt>install</tt> target depends on the <tt>all</tt> (or more |
790 |
precisely, the <tt>myall</tt>) target, it is also possible to perform |
791 |
compilation and installation in one step by simply executing <tt>make |
792 |
install</tt>.</p> |
793 |
|
794 |
<p>If the variable <tt>INSTALL_PREFIX</tt> is set, its value is prepended |
795 |
to all pathnames used for installation; for example, the |
796 |
<tt>ircservices</tt> executable file is installed to |
797 |
<tt>$(INSTALL_PREFIX)$(BINDEST)/ircservices</tt>. This allows Services to |
798 |
be installed to an alternate root directory, such as when preparing a |
799 |
chroot'd environment or a distribution image. This variable is not set by |
800 |
any of the Makefiles, but can be set on the <tt>make</tt> command line. |
801 |
(Note that there is no slash after <tt>$(INSTALL_PREFIX)</tt>; inserting |
802 |
one would have the side effect of prefixing <tt>$(BINDEST)</tt> and |
803 |
<tt>$(DATDEST)</tt> with a slash when no prefix was given, which could |
804 |
potentially have undesired side effects.)</p> |
805 |
|
806 |
<p class="backlink"><a href="#top">Back to top</a></p> |
807 |
|
808 |
<!------------------------------------------------------------------------> |
809 |
<hr/> |
810 |
|
811 |
<h3 class="subsection-title" id="s5">10-5. Assumptions</h3> |
812 |
|
813 |
<p>Finally, it is worth noting a few assumptions made by the source code. |
814 |
These are all believed to hold on any system Services is likely to be used |
815 |
on, and some are double-checked by the <tt>configure</tt> script.</p> |
816 |
|
817 |
<ul> |
818 |
<li class="spaced"><b>Pointer values are at least as large as <tt>int</tt> |
819 |
values.</b> The module system uses <tt>void *</tt> as type |
820 |
placeholders for module callbacks, as described in |
821 |
<a href="4.html#s5-3">section 4-5-3</a>, and some database management |
822 |
routines, such as in the OperServ news and autokill modules (see |
823 |
<a href="7.html#s2-2-1">section 7-2-2-1</a>, for example) store integer |
824 |
values in pointer fields. While these are admittedly very crocky ways of |
825 |
doing things, they do require that pointers be at least large enough to |
826 |
hold values that may be stored in them. The <tt>configure</tt> script |
827 |
checks that pointers are at least as large as <tt>int</tt>s, and aborts if |
828 |
not.</li> |
829 |
|
830 |
<li class="spaced"><b>Character values are exactly 8 bits.</b> More |
831 |
precisely, a <tt>char</tt> variable is exactly one byte in size (whatever |
832 |
size a byte may be). This is not checked by the <tt>configure</tt> script, |
833 |
but it is mandated by the C standard and should not be a problem.</li> |
834 |
|
835 |
<li class="spaced"><b>Unprototyped routines can accept up to five arguments |
836 |
regardless of type.</b> Or to be more accurate, all of the first five |
837 |
arguments to a routine are stored in same-size locations regardless of |
838 |
type. This requirement is a side effect of the module callback calling |
839 |
method mentioned above, and holds on at least x86 (where everything except |
840 |
<tt>long long</tt> is 32 bits) and x86-64 (where the first five arguments |
841 |
are all passed in registers). Note that this is not checked by the |
842 |
<tt>configure</tt> script.</li> |
843 |
|
844 |
<li class="spaced"><b>Pointer aliasing (type-punning) is allowed.</b> The |
845 |
C standard disallows "aliasing" of pointers of different types (C99 6.5 (7)); |
846 |
in other words, if you have a pointer variable <tt>struct foostruct |
847 |
*foo</tt>, you may not assign the value of <tt>foo</tt> to <tt>struct |
848 |
barstruct *bar</tt> and then modify the contents of <tt>*bar</tt>. This |
849 |
sounds like a good idea on the surface, but it turns out to be quite |
850 |
inconvenient in practice; in particular, it prevents the use of "derived |
851 |
structures", where the first member of one structure is a second structure |
852 |
(similar to a derived class in object-oriented languages). It would in |
853 |
theory be possible, if unduly verbose, to rewrite the code to obey the |
854 |
aliasing rules; but for convenience, Services simply assumes that this sort |
855 |
of aliasing is permitted. The <tt>configure</tt> script does not check for |
856 |
this directly, since any effect would be compiler-dependent and difficult |
857 |
(if not impossible) to detect reliably, but the script does enable the |
858 |
<tt>-fno-strict-aliasing</tt> option when compiling with GCC, which |
859 |
disables optimizations that rely on this aliasing rule.</li> |
860 |
|
861 |
<li class="spaced"><b>The <tt>NULL</tt> pointer is bitwise zero for all |
862 |
pointer types.</b> For the sake of efficiency (and concise source code), |
863 |
arrays or structures containing pointers are often cleared by using |
864 |
<tt>calloc()</tt> to allocate precleared memory or <tt>memset()</tt> to |
865 |
fill the memory region with the byte value 0, and it is assumed that these |
866 |
operation are equivalent to individually assigning the <tt>NULL</tt> value |
867 |
to each pointer. The C standard does not require that <tt>NULL</tt> be |
868 |
stored in memory as the value zero, only that it compare equal to zero, but |
869 |
every system I have used so far uses bitwise zero for <tt>NULL</tt>, so I |
870 |
have not made an effort to write "correct" code. Note that the |
871 |
<tt>configure</tt> script does not check for this.</li> |
872 |
</ul> |
873 |
|
874 |
<p class="backlink"><a href="#top">Back to top</a></p> |
875 |
|
876 |
<!------------------------------------------------------------------------> |
877 |
<hr/> |
878 |
|
879 |
<p class="backlink"><a href="9.html">Previous section: The database conversion tool</a> | |
880 |
<a href="index.html">Table of Contents</a> | |
881 |
<a href="11.html">Next section: Future work</a></p> |
882 |
|
883 |
</body> |
884 |
</html> |