/[svn]/vendor/ircservices-5.1.24/docs/tech/10.html
ViewVC logotype

Contents of /vendor/ircservices-5.1.24/docs/tech/10.html

Parent Directory Parent Directory | Revision Log Revision Log


Revision 3389 - (show annotations)
Fri Apr 25 14:12:15 2014 UTC (6 years, 2 months ago) by michael
File MIME type: application/xhtml+xml
File size: 49387 byte(s)
- Imported ircservices-5.1.24

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/>&nbsp;&nbsp;&nbsp;&nbsp;10-3-1. <a href="#s3-1">Core source files</a>
20 <br/>&nbsp;&nbsp;&nbsp;&nbsp;10-3-2. <a href="#s3-2">Modules</a>
21 <br/>&nbsp;&nbsp;&nbsp;&nbsp;10-3-3. <a href="#s3-3">Language files</a>
22 <br/>&nbsp;&nbsp;&nbsp;&nbsp;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&mdash;which is
336 probably a security issue in some cases; see also
337 <a href="11.html#s1">section 11-1</a>&mdash;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&mdash;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&mdash;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&nbsp;*</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>

svnadmin@ircd-hybrid.org
ViewVC Help
Powered by ViewVC 1.1.28