forked from drh/cii
-
Notifications
You must be signed in to change notification settings - Fork 0
/
install.html
340 lines (311 loc) · 16.4 KB
/
install.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<link HREF="http://www.drhanson.net/" REV="made" TITLE="David R. Hanson">
<title>CII Installation Guide</title>
</head>
<body>
<h1>CII Installation Guide</h1>
<p ALIGN="LEFT"><strong><a HREF="http://drh.home.dyndns.org/">David R. Hanson</a>,
Google</strong></p>
<h2>Contents</h2>
<dir>
<li><a HREF="#intro">Introduction</a></li>
<li><a HREF="#unix">Installation on UNIX</a></li>
<li><a HREF="#win32">Installation on Windows 95/NT</a></li>
<li><a HREF="#bugs">Reporting Bugs</a></li>
</dir>
<h2><a NAME="intro">Introduction</a></h2>
<p>This page describes how to install the software from my book <cite><a
HREF="http://www.awl.com/cseng/titles/0-201-49841-3/">C Interfaces and Implementations:
Techniques for Creating Reusable Software</a></cite> (<a
HREF="http://cseng.aw.com/seriesdetail.qry?SeriesID=4">Addison-Wesley Professional
Computing Series</a>, 1997, ISBN 0-201-49841-3). A CII distribution includes the following
files and directories.</p>
<table BORDER="0" CELLPADDING="0" CELLSPACING="2">
<tr>
<td><code><a HREF="README">README</a></code></td>
<td></td>
<td>distribution identification</td>
</tr>
<tr>
<td><code><a HREF="install.html">install.html</a></code></td>
<td></td>
<td>this file</td>
</tr>
<tr>
<td><code><a HREF="makefile">makefile</a></code></td>
<td></td>
<td>UNIX makefile</td>
</tr>
<tr>
<td><code><a HREF="makefile.nt">makefile.nt</a></code></td>
<td></td>
<td>Windows 95/NT makefile</td>
</tr>
<tr>
<td><code><a HREF="include">include</a>/</code></td>
<td></td>
<td>interfaces (<code>.h</code> files) for the CII library</td>
</tr>
<tr>
<td><code><a HREF="src">src</a>/</code></td>
<td></td>
<td>implementations (<code>.c</code> files) for the CII library</td>
</tr>
<tr>
<td><code><a HREF="examples">examples</a>/</code></td>
<td></td>
<td>example clients, including those from the book</td>
</tr>
<tr>
<td><code><a HREF="misc">misc</a>/</code></td>
<td></td>
<td>miscellaneous tools, e.g., <a href="misc/maxalign.c"><code>maxalign.c</code></a></td>
</tr>
</table>
<p>The CII distributions are numbered <em>X.Y</em> where <em>X</em> is the major release
number and <em>Y</em> is the minor release number. Starting with major release 1, minor
releases fix bugs and perhaps make improvements, but do <strong>not</strong> change
interfaces. The interfaces and the compiled library are compatible with earlier and later
minor releases; for example, a program compiled with the 1.3 release is compatible with
release 1.8 and vice versa. Major releases occur when one or more interfaces are changed
or extended, or when new interfaces are added.</p>
<p>It's usually best to follow a similar naming scheme when installing CII so that
programs compiled with one major release can be recompiled even after a subsequent major
release has been installed. The minor release number can be omitted. On UNIX, for example,
this convention can be accomplished by installing the interfaces in, say, <code>/usr/local/lib/cii/</code><em>X</em><code>/include</code>,
where <em>X</em> is the major release number, and installing the library, <code>libcii.a</code>,
in <code>/usr/local/lib/cii/</code><em>X</em><code>/libcii.a</code>.</p>
<p>At UNIX sites with multiple platforms (architectures and OSes) and a single <code>/usr/local</code>
hierarchy, the library can be installed in a platform-specific location below <code>/usr/local/cii/</code><em>X</em>,
e.g., <code>/usr/local/lib/cii/</code><em>X</em><code>/alpha-osf/libcii.a</code>. The
interfaces are machine independent and thus don't need platform-specific locations.
Similar conventions can be used on Windows 95/NT.</p>
<p>Following this scheme permits the actual installation locations to be confined to
specifying prefixes, like <code>/usr/local/lib/cii/</code><em>X</em><code>/include</code>
and <code>/usr/local/lib/cii/</code><em>X</em><code>/</code>, in makefiles; programs can
include interfaces by giving just the names of their header files.</p>
<p>On UNIX systems, it's also useful to plant release-independent symbol link to the
latest CII release, e.g., make <code>/usr/local/include/cii</code> point to <code>/usr/local/lib/cii/</code><em>X</em><code>/include</code>
and <code>/usr/local/lib/libcii.a</code> point to <code>/usr/local/lib/cii/</code><em>X</em><code>/libcii.a</code>.</p>
<p><strong>NB</strong>: If you use several compilers, you may need compiler-specific
variants of <code>libcii.a</code>, and thus use platform names that denote a specific
architecture, OS, <strong>and</strong> compiler. For example, the Text interface uses
small structures and passes them by value, and, on some platforms, one C compiler might
generate code for <code>src/text.c</code> that is incompatible with another compiler. This
problem is not specific to CII; it can occur with any library.</p>
<p>The installation makefile is designed so that CII can be installed from a read-only
file system or directory, which is common in networked environments, so the distribution
can be unloaded on a central file server. If you're installing CII on a UNIX system,
continue with the next section. If you're installing CII on a Windows NT 4.0 or Windows 95
system, read the next section first, then follow the <a HREF="#win32">Windows NT/95
instructions</a>.</p>
<h2><a NAME="unix">Installation on UNIX</a></h2>
<p>The CII components (include files and the library) are installed in a single <em>build
directory</em>. On multi-platform systems supported by a central file server, it's common
to store the build directory in a location specific to the platform and to the version of
CII, as suggested above. For example, installation on a UNIX system involves the following
steps. Below, the build directory is referred to as <code>BUILDDIR</code>, and the
commands shown assume the distribution directory is the current working directory.
If you want to build in the distribution directory, leave <code>BUILDDIR</code>
undefined and start at step 3.
<ol>
<li>Create the build directory, using a version- and platform-specific naming convention as
suggested above, and record the name of this directory in the <code>BUILDDIR</code>
environment variable:<blockquote>
<pre>% setenv BUILDDIR /usr/local/lib/cii/1/alpha-osf/
% mkdir -p $BUILDDIR</pre>
</blockquote>
<p>The trailing slash is required, because <code>BUILDDIR</code> is concatenated
with file names in the <code>makefile</code>, e.g., <code>$(BUILDDIR)atom$O</code>.
Here and below, commands assume the C shell. Also, you'll need a version of <code>mkdir</code>
that supports the <code>-p</code> option, which creates intermediate directories as
necessary, or create them with individual <code>mkdir</code> commands.</p>
</li>
<li>Create the include directory in the build directory, and copy the include files:<blockquote>
<pre>% mkdir ${BUILDDIR}include
% cp -p include/*.h ${BUILDDIR}include</pre>
</blockquote>
<p>Some users create a symbolic link to the include directory in the distribution instead
of making repeated copies of the include files. For example, at Princeton, the
distributions are stored under <code>/proj/pkg/cii</code>, so the include files are
"installed" by creating one symbolic link:</p>
<blockquote>
<pre>% ln -s /proj/pkg/cii/1.1/include ${BUILDDIR}include</pre>
</blockquote>
</li>
<li>Build everything using the appropriate make command for your environment:<blockquote>
<table BORDER="0" WIDTH="100%" CELLPADDING="0" CELLSPACING="2">
<tr>
<td>ALPHA OSF/1 V3.2A</td>
<td><code>% make CC='cc -std1 -Dalpha' AS='as -Dalpha'</code></td>
</tr>
<tr>
<td>MIPS IRIX 6.2</td>
<td><code>% make</code></td>
</tr>
<tr>
<td>MIPS Ultrix 4.3</td>
<td><code>% gmake CC=gcc LD=gcc</code></td>
</tr>
<tr>
<td>SPARC SunOS 5.5.1 (Solaris)</td>
<td><code>% make -k CC='cc -DMAXALIGN=8' THREADS=</code></td>
</tr>
<tr>
<td>X86_32 Linux</td>
<td><code>% make CC='cc -DMAXALIGN=4' AS='cc -c -x assembler-with-cpp -traditional'</code></td>
</tr>
<tr>
<td>X86_64 Linux, Apple Intel Mac OS X 10.5.x</td>
<td><code>% make -k THREADS=</code></td>
</tr>
</table>
</blockquote>
<p>This command builds, in <code>BUILDDIR</code>, <code>libcii.a</code>, <code>memchk.o</code>,
and the examples. There may be some warnings on some platforms. The assignment <code>THREADS=</code>
appears on those platforms for which there is no Thread implementation. On these
platforms, examples that use Thread won't link correctly, so use the <code>-k</code>
option so make keeps going.</p>
<p><a name="maxalign">On most platforms</a>, <code>malloc</code> returns pointers to
blocks that are aligned on addresses that are multiples of the size of the largest basic
data type. Some CII functions use a union to determine this multiple (cf. <code>union</code> <code>align</code>
on p. 80). Alignments are less restrictive on some platforms and, for these, <code>MAXALIGN</code>
must be defined as the alignment required as shown above. <a
href="misc/maxalign.c"><code>maxalign.c</code></a>
is a C program that attempts to determine the correct value for <code>MAXALIGN</code>, if
one is necessary, and echo the appropriate <code>-D</code> option. The
method used relies on the C compiler using the same alignments as <code>malloc</code>,
which is not required. <code>malloc</code> is the final authority: If it returns addresses
that are multiples of <code>sizeof</code> <code>(union</code> <code>align)</code>,
then <code>MAXALIGN</code> is unnecessary; otherwise, <code>MAXALIGN</code> must provide
the alignment.
So, <code>maxalign.c</code> calls <code>malloc(1)</code> to determine if the address it returns
has an alignment less strict than that used by the C compiler.</p>
<p>The command <code>make maxalign</code>
compiles and executes <code>maxalign.c</code>; the output shows the appropriate <code>-D</code> option,
if one is needed.
Incorrect values of <code>MAXALIGN</code> can cause crashes and assertion
failures.</p>
<p><code>src/{memcmp,memmove,strncmp}.c</code> are implementations of the similarly named
ANSI library functions. These are included in the distribution because some of them are
implemented incorrectly on some UNIX platforms. The corresponding object files are
assigned to <code>EXTRAS</code>; if some of these functions are implemented correctly on
your system, you can omit the CII versions by either editing <code>libcii.a</code>, or
including the appropriate assignment to <code>EXTRAS</code>, e.g.,</p>
<blockquote>
<pre>% make EXTRAS=${BUILDDIR}memcmp.o</pre>
</blockquote>
</li>
<li>The <a HREF="makefile"><code>makefile</code></a> includes the file named by the <code>CUSTOM</code>
macro; the default is <code>custom.mk</code>, and an empty <code>custom.mk</code> is
included in the distribution. If desired, prepare a site-specific customization file and
define <code>CUSTOM</code> to the path of that file when invoking make in the previous
step. For example, on the ALPHA, I use <code>osf.mk</code>:<blockquote>
<pre>% cat osf.mk
BUILDDIR=/usr/local/lib/cii/1/alpha-osf/
CC=cc -std1 -Dalpha
AS=as -Dalpha
% make CUSTOM=osf.mk</pre>
</blockquote>
</li>
<li>Run a few of the test programs, e.g., <blockquote>
<pre>% ${BUILDDIR}wf <makefile
% ${BUILDDIR}cref src/fmt.c src/str.c</pre>
</blockquote>
<p>and then clean up:</p>
<blockquote>
<pre>% make clean</pre>
</blockquote>
<p>This command removes everything except <code>include</code> and <code>libcii.a</code>.
If you want to leave <code>memchk.o</code> installed, rebuild it, e.g.,</p>
<blockquote>
<pre>% make ${BUILDDIR}memchk.o</pre>
</blockquote>
<p><code>memchk.c</code> uses <code>MAXALIGN</code>, so if you defined <code>MAXALIGN</code>
when building <code>libcii.a</code>, include it when rebuilding <code>memchk.o</code>,
e.g.,</p>
<blockquote>
<pre>% make CC='cc -DMAXALIGN=8' ${BUILDDIR}memchk.o</pre>
</blockquote>
<p><code>make clobber</code> removes everything from <code>BUILDDIR</code>.</p>
</li>
<li>If desired, plant release-independent symbolic links to the include directory and to the
installed library, e.g., <blockquote>
<pre>% ln -s ${BUILDDIR}include /usr/local/include/cii
% ln -s ${BUILDDIR}libcii.a /usr/local/lib/libcii.a</pre>
</blockquote>
</li>
</ol>
<h2><a NAME="win32">Installation on Windows 95/NT</a></h2>
<p>On Windows NT or Windows 95, you can use a directory organization similar to the one
described above for UNIX as follows. The commands below assume the distribution is rooted
at <code>C:\dist</code> and that the C compiler is Microsoft Visual C/C++ 5.0.
<ol>
<li>Create the build directory and set <code>BUILDDIR</code>:<blockquote>
<pre>C:\dist>set BUILDDIR=\lib\cii\1
C:\dist>mkdir %BUILDDIR%</pre>
</blockquote>
<p>Change the assignment to <code>BUILDDIR</code> to suit your local conventions.
On Windows, <code>BUILDDIR</code> must <em>not</em> include the trailing backslash.</p>
</li>
<li>Create the include directory in the build directory, and copy the include files:<blockquote>
<pre>C:\dist>mkdir %BUILDDIR%\include
C:\dist>copy include\*.h %BUILDDIR%\include</pre>
</blockquote>
</li>
<li>Build everything using <code>nmake</code>:<blockquote>
<pre>C:\dist>nmake -f makefile.nt BUILDDIR=%BUILDDIR%</pre>
</blockquote>
<p>This command builds, in <code>BUILDDIR</code>, <code>libcii.lib</code>, <code>libcii.pdb</code>,
<code>memchk.obj</code>, and the examples. The default <code>BUILDDIR</code> is <code>\lib\cii\1</code>,
so the assignment to <code>BUILDDIR</code> above can be omitted if you use this default.</p>
</li>
<li>Run a few of the test programs, e.g., <blockquote>
<pre>C:\dist>%BUILDDIR%\wf <makefile
C:\dist>%BUILDDIR%\sieve</pre>
</blockquote>
<p>and then clean up:</p>
<blockquote>
<pre>C:\dist>nmake -f makefile.nt BUILDDIR=%BUILDDIR% clean</pre>
</blockquote>
<p>This command removes everything except <code>include</code>, <code>libcii.a</code>, and
<code>libcii.pdb</code>. If you want to leave <code>memchk.obj</code> installed, rebuild
it, e.g., </p>
<blockquote>
<pre>C:\dist>nmake -f makefile.nt BUILDDIR=%BUILDDIR% %BUILDDIR%\memchk.obj</pre>
</blockquote>
<p><code>make clobber</code> removes everything from <code>BUILDDIR</code></p>
</li>
<li><code>src\libcii.def</code> is a module definition file for the CII library. To create a
DLL instead of a statically linked library, execute <blockquote>
<pre>C:\dist>nmake -f makefile.nt BUILDDIR=%BUILDDIR% libcii.dll</pre>
</blockquote>
<p>This command creates <code>%BUILDDIR%\libcii.dll</code>, <strong>overwrites</strong> <code>%BUILDDIR%\libcii.lib</code>
with the import library, and creates the export library <code>%BUILDDIR%\libcii.exp</code>.
If you use <code>libcii.dll</code>, you'll need to move it to a directory on your <code>PATH</code>.</p>
</li>
</ol>
<p>Some users copy the include and library files into their Visual C/C++ 5.0 distribution,
e.g.,</p>
<blockquote>
<pre>C:\dist>mkdir "\Program Files\DevStudio\VC\include\cii"
C:\dist>copy include\*.h "\Program Files\DevStudio\VC\include\cii"
C:\dist>copy %BUILDDIR%\libcii.* "\Program Files\DevStudio\VC\lib"</pre>
</blockquote>
<h2><a NAME="bugs">Reporting Bugs</a></h2>
<p>Devise the shortest possible example program that elicits the bug. Prune your example
until it can be pruned no more without sending the error into hiding. I prune most error
demonstrations to only a few lines. Annotate your example with C comments that describe
the bug and your suggested fix, if you have one. If the example crashes, please report the
last part of the call chain if you can.</p>
<p>Send your example by electronic mail to me (see below).
Please send only valid C programs; put all remarks in C comments so that I can process
reports semi-automatically.</p>
<hr>
<address>
<a HREF="http://drh.home.dyndns.org/">David Hanson</a>
</address>
</body>
</html>