README: Installation instruction for chkdelim-3.3

Table of contents

• Jump start
• Introduction
• Installation
• UNIX Systems
• IBM PC DOS
• test suite
• Sample build output for UNIX

Jump start

As with most GNUware, you can build, test, and install this program on most UNIX systems by these simple steps

csh et amici:
        setenv CC ...your favorite C or C++ compiler...
        ./configure && make all check install

sh et amici:
        CC=...your favorite C or C++ compiler...
        export CC
        ./configure && make all check install

Or in one line, if you have env (most modern UNIX systems do):

        env CC=... ./configure && make all check install

If you don't set the CC environment variable, then gcc (or cc, if gcc is not available) will be assumed.

If you wish to undo a make install, just do make uninstall; this will remove any files in system directories put there by make install.

On many systems, you can do it manually without using configure, like this

        touch config.h
        cc -o chkdelim chkdelim.c

See below for further details, and for instructions for non-UNIX systems.

Introduction

Please report all problems, suggestions, and comments to the author:

Installation

Starting with version 3.2, chkdelim has been adapted to use the GNU autoconf automatic configuration system for UNIX installations.

GNU autoconf is run at the author's site to produce the configure script from configure.in.

The configure script is run at each installer's UNIX site to produce Makefile from Makefile.in , and config.h from config.hin. The configure script is a large (2650+ lines) Bourne shell program that investigates various aspects of the local C implementation, and records its conclusions in config.h.

Should you do a make maintainer-clean [not recommended, except at the author's site], the configure script will be deleted, and you will need recent versions of both GNU m4 and autoconf correctly installed to reconstruct things, which can be done this way:

        autoheader      # Regenerate config.hin
        autoconf        # Regenerate unedited configure
        ./configure     # Regenerate config.h and Makefile
        rm configure    # delete configure
        make configure  # Regenerate edited configure
        make configure.time-stamp       # To fix configure script

For convenience and safety, the distribution includes a subdirectory named save that contains read-only copies of the files Makefile, config.h, and configure created by autoconf and make configure. This will allow recovery from a lost or damaged configure file.

Suitable hand-crafted config.h files are provided for non-UNIX systems, and in the unlikely event of a failure of the configure script on a UNIX system, config.h can be manually produced from a copy of config.hin with a few seconds of editing work. If you do this, remember to save a copy of your config.h under a different name, because running configure will destroy it. If you have GNU autoconf installed (the installation is very simple and source code is available from ftp://prep.ai.mit.edu/pub/gnu/autoconf-x.y.tar.gz), you might try augmenting config.hin instead, then run autoconf and configure.

Thus, on UNIX, installation normally consists of just two steps (assuming a csh -compatible shell):

        setenv CC ...your favorite C or C++ compiler...
        ./configure && make all check install

If you like, add OPT='your favorite optimization flags' to the make command; by default, no optimization flags are set.

The GNU standard installation directories /usr/local/bin for binaries, and /usr/local/man/man1 for manual pages are assumed. The prefix /usr/local can be overridden by providing an alternate definition on the command line:

        make prefix=/some/other/path install

After installation, you can do

        make distclean

to restore the directories to their distribution state. You should also do this between builds for different architectures from the same source tree; neglecting to do so will almost certainly lead to failure, because the config.cache file created by configure will lead to an incorrect config.h for the next build.

UNIX Systems

The code can be compiled with either C (K&R or ISO/ANSI Standard C) or C++ compilers. With some C++ compilers, it may be necessary to supply additional switches for force the compiler to stay in C++ mode, rather than reverting to C mode (e.g., on DEC Alpha OSF/1, you must do setenv CC "cxx -x cxx" ).

On UNIX systems, the only changes that you are likely to need in the Makefile are the settings of CC and CFLAGS, and possibly, DEFINES, and if you wish to do make install, the settings of bindir, MANDIR, and MANEXT.

If you are installing chkdelim on a new system, you should definitely run make check before installing it on your system. Sample output of make check from a UNIX system is given below.

These programs have been successfully built and tested with C and C++ compilers and tested on these systems for the 3.3 release (66 builds):

IBM PC DOS

The ibmpc/dos/README file contains details of the builds and tests of chkdelim under several IBM PC DOS C and C++ compilers, and instructions for building and testing chkdelim with other compilers.

Since chkdelim uses no floating-point arithmetic, and PC DOS has no shared libraries, I expect that the executables will run on any version of DOS greater than 4.0. They may also run on earlier versions. At the time of writing, MS-DOS 6.22 is current, and the chkdelim executables work fine on it.

Test suite

The chkdelim distribution includes an extensive test suite, including the reduced text of three books, and several other large files. It is run by

        make check

The text reduction is accomplished by a UNIX filter similar to

        tr -s A-Za-z x | tr -s 0-9 0

to reduce runs of letters to a single letter, x, and runs of digits to a single digit, 0. This preserves the original delimiters while both reducing the file size, and eliminating any copyright restrictions.

Each test consists of up to 4 files, named check nnn ( nnn = 001, 002, ...), with these extensions:

The make check job loops over the list of test files, and executes either

    ../chkdelim checknnn.in > checknnn.out 2> checknnn.err

    ../chkdelim `cat checknnn.opt` checknnn.in > checknnn.out 2> checknnn.err

depending on whether a .opt file is available or not. The resulting .out and .err files are then compared with the expected output in the .ok and .eok files.

For use on other operating systems, the test/check.bat file for PC DOS may serve as a useful starting point for preparing a script to run the tests.

Please do run the validation suite at your site before installing the program. Compilers are complex software systems that also have bugs, so the fact that the program runs correctly somewhere else does not mean that it will do so on a different system. In the UNIX validations listed earlier, at least one failing case turned up, and that compiler was eliminated from the list of successes.

Sample build output for UNIX

Here is a log of a successful build on Sun Solaris 2.6 using the native C++ compiler, CC:

% env CC=CC ./configure && make OPT=-xO5 all check install
creating cache ./config.cache
checking for gcc... CC
checking whether the C compiler (CC  ) works... yes
checking whether the C compiler (CC  ) is a cross-compiler... no
checking whether we are using GNU C... no
checking whether CC accepts -g... yes
checking for c++... c++
checking whether the C++ compiler (c++  ) works... yes
checking whether the C++ compiler (c++  ) is a cross-compiler... no
checking whether we are using GNU C++... yes
checking whether c++ accepts -g... yes
checking how to run the C preprocessor... CC -E
checking for stdlib.h... yes
checking for mawk... /usr/local/bin/mawk
checking for cat... cat
checking for chmod... chmod
checking for cmp... cmp
checking for col... col -b
checking for gzip... /usr/local/bin/gzip
checking for scp... scp -p
checking for rcp... (cached) scp -p
checking for cp... (cached) scp -p
checking for deroff... /bin/deroff
checking for diff... diff
checking for distill... /usr/local/bin/distill
checking for dw... /usr/local/bin/dw
checking for expand... /usr/local/bin/expand
checking for ispell... ispell
checking for jar... jar
checking for lint... /opt/SUNWspro/bin/lint
checking for ln... /usr/local/bin/ln
checking for ls... /usr/local/bin/ls
checking for man2html... /usr/local/bin/man2html
checking for mv... /usr/local/bin/mv
checking for nroff... /bin/nroff
checking for rm... rm
checking for sed... sed
checking for shar... /usr/local/bin/shar
checking for sh... /bin/sh
checking for sort... sort
checking for spell... spell
checking for gnutar... no
checking for tar... tar
checking for touch... touch
checking for unzip... /usr/local/bin/unzip
checking for zip... /usr/local/bin/zip
checking for zoo... /usr/local/bin/zoo
checking if short names are needed... no
checking for C++ bool type... yes
updating cache ./config.cache
creating ./config.status
creating Makefile
creating config.h
CC  -I. -xO5   -c -o chkdelim.o chkdelim.c
CC  -I. -xO5 -o chkdelim chkdelim.o
The following checks should produce no output other than their names...
check001
check002
check003
check004
check005
check006
check007
check008
check009
check010
check011
check012
check013
check014
check015
check016
check017
check018
check019
check020
check021
check022
check023
check024
check025
check026
check027
check028
check029
check030
check031
check032
check033
check034
check035
rm -f /usr/local/bin/chkdelim
rm -f /usr/local/bin/chkdelim-`/usr/local/bin/mawk '/^[ \t]*version *= *"[0-9.]+", *$/ { gsub(/[^0-9.]/,"",$3); print $3 }' chkdelim.c`
rm -f /usr/local/man/cat1/chkdelim-`/usr/local/bin/mawk '/^[ \t]*version *= *"[0-9.]+", *$/ { gsub(/[^0-9.]/,"",$3); print $3 }' chkdelim.c`.1
rm -f /usr/local/man/cat1/chkdelim.1
rm -f /usr/local/man/man1/chkdelim-`/usr/local/bin/mawk '/^[ \t]*version *= *"[0-9.]+", *$/ { gsub(/[^0-9.]/,"",$3); print $3 }' chkdelim.c`.1
rm -f /usr/local/man/man1/chkdelim.1
scp -p chkdelim /usr/local/bin/chkdelim

chmod 775 /usr/local/bin/chkdelim
/usr/local/bin/ln /usr/local/bin/chkdelim /usr/local/bin/chkdelim-`/usr/local/bin/mawk '/^[ \t]*version *= *"[0-9.]+", *$/ { gsub(/[^0-9.]/,"",$3); print $3 }' chkdelim.c`
scp -p chkdelim.man /usr/local/man/man1/chkdelim.1

chmod 664 /usr/local/man/man1/chkdelim.1
/usr/local/bin/ln  /usr/local/man/man1/chkdelim.1 \
 /usr/local/man/man1/chkdelim-`/usr/local/bin/mawk '/^[ \t]*version *= *"[0-9.]+", *$/ { gsub(/[^0-9.]/,"",$3); print $3 }' chkdelim.c`.1

Installed files...
-rwxrwxr-x   2 beebe    staff       40744 Oct 25 09:33 /usr/local/bin/chkdelim
-rwxrwxr-x   2 beebe    staff       40744 Oct 25 09:33 /usr/local/bin/chkdelim-3.3
-rw-rw-r--   2 beebe    staff       16331 Oct 25 07:56 /usr/local/man/man1/chkdelim-3.3.1
-rw-rw-r--   2 beebe    staff       16331 Oct 25 07:56 /usr/local/man/man1/chkdelim.1