cii/install.html at master · drh/cii

Repository navigation

History

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

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">

<html>

<head>

<title>CII Installation Guide</title>

</head>

<body>

<h1>CII Installation Guide</h1>

<a HREF="https://drh.github.io">David R. Hanson</a>,

Google

<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>

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.

<tr>

<td><code><a HREF="README">README</a></code></td>

<td>distribution identification</td>

</tr>

<tr>

<td><code><a HREF="install.html">install.html</a></code></td>

</tr>

<tr>

<td><code><a HREF="makefile">makefile</a></code></td>

<td>UNIX makefile</td>

</tr>

<tr>

<td><code><a HREF="makefile.nt">makefile.nt</a></code></td>

<td>Windows 95/NT makefile</td>

</tr>

<tr>

<td><code><a HREF="include">include</a>/</code></td>

<td>interfaces (<code>.h</code> files) for the CII library</td>

</tr>

<tr>

<td>implementations (<code>.c</code> files) for the CII library</td>

</tr>

<tr>

<td><code><a HREF="examples">examples</a>/</code></td>

<td>example clients, including those from the book</td>

</tr>

<tr>

<td>miscellaneous tools, e.g., <a href="misc/maxalign.c"><code>maxalign.c</code></a></td>

</tr>

</table>

The CII distributions are numbered X.Y where X is the major release

number and Y is the minor release number. Starting with major release 1, minor

releases fix bugs and perhaps make improvements, but do not 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.

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>X<code>/include</code>,

where X is the major release number, and installing the library, <code>libcii.a</code>,

in <code>/usr/local/lib/cii/</code>X<code>/libcii.a</code>.

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>X,

e.g., <code>/usr/local/lib/cii/</code>X<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.

Following this scheme permits the actual installation locations to be confined to

specifying prefixes, like <code>/usr/local/lib/cii/</code>X<code>/include</code>

and <code>/usr/local/lib/cii/</code>X<code>/</code>, in makefiles; programs can

include interfaces by giving just the names of their header files.

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>X<code>/include</code>

and <code>/usr/local/lib/libcii.a</code> point to <code>/usr/local/lib/cii/</code>X<code>/libcii.a</code>.

NB: 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, and 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.

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>.

<h2><a NAME="unix">Installation on UNIX</a></h2>

The CII components (include files and the library) are installed in a single build

directory. 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>

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.

</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>

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:

<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>

<tr>

<td>ALPHA OSF/1 V3.2A</td>

<td><code>% make CC='cc -std1 -Dalpha' AS='as -Dalpha'</code></td>

</tr>

<tr>

</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>

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.

<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.

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.

<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.,

<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>

and then clean up:

<pre>% make clean</pre>

</blockquote>

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.,

<pre>% make ${BUILDDIR}memchk.o</pre>

</blockquote>

<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.,

<pre>% make CC='cc -DMAXALIGN=8' ${BUILDDIR}memchk.o</pre>

</blockquote>

<code>make clobber</code> removes everything from <code>BUILDDIR</code>.

</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>

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>

Change the assignment to <code>BUILDDIR</code> to suit your local conventions.

On Windows, <code>BUILDDIR</code> must not include the trailing backslash.

</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>

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 assignme 698E nt to <code>BUILDDIR</code> above can be omitted if you use this default.

</li>

<li>Run a few of the test programs, e.g., <blockquote>

<pre>C:\dist>%BUILDDIR%\wf <makefile

C:\dist>%BUILDDIR%\sieve</pre>

</blockquote>

and then clean up:

<pre>C:\dist>nmake -f makefile.nt BUILDDIR=%BUILDDIR% clean</pre>

</blockquote>

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.,

<pre>C:\dist>nmake -f makefile.nt BUILDDIR=%BUILDDIR% %BUILDDIR%\memchk.obj</pre>

</blockquote>

<code>make clobber</code> removes everything from <code>BUILDDIR</code>

</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>

This command creates <code>%BUILDDIR%\libcii.dll</code>, overwrites <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>.

</li>

</ol>

Some users copy the include and library files into their Visual C/C++ 5.0 distribution,

e.g.,

<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>

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.

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.

<hr>

<a HREF="https://drh.github.io">David Hanson</a>

</address>

</body>

</html>

FilesExpand file tree

install.html

Latest commit

History

install.html

File metadata and controls