README: Installation instruction for biblabel-0.05

Last update: Mon Oct 30 18:31:15 2006

Table of contents

• Prerequisites
• Jump start
• Introduction
• Installation
• UNIX Systems
• Test suite
• Sample build output for UNIX

Prerequisites

This package requires bibclean, available at

http://www.math.utah.edu/pub/tex/bib/index-table-b.html#bibclean

or equivalently

ftp://ftp.math.utah.edu/pub/tex/bib/bibclean-x.y.z.*

It is desirable, but not essential, to also have the file header checksum utility, available at

http://www.math.utah.edu/pub/misc/index.html#checksum

or equivalently

ftp://ftp.math.utah.edu/pub/misc/checksum-x.y.*

It also requires an implementation of awk, available on all POSIX-compliant systems as nawk or awk, and sometimes also as gawk and mawk:

http://cm.bell-labs.com/cm/cs/awkbook/index.html
ftp://ftp.gnu.org/gnu/gawk
ftp://ftp.whidbey.net/pub/brennan/mawkx.y.z.tar.gz

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

See below for more details.

Introduction

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

Installation

biblabel 0.04 has been updated to use the GNU autoconf automatic configuration system for UNIX installations.

GNU autoconf is run at the maintainer'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 (ca. 2400 lines) Bourne shell program that investigates various aspects of the local C implementation, and records its conclusions in config.h.

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.

Should you do a make maintainer-clean [ not recommended, except at the maintainer'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:

        make -f save/Makefile reconfigure

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 don't set the CC environment variable, then gcc (or cc, if gcc is not available) will be assumed.

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

On some systems, it may be necessary to supply compiler optimization flags at configure time, in which case you should instead include them as part of the CC variable setting. They will then be permanently recorded in the Makefile.

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 at configure time like this:

        ./configure --prefix=/some/other/path

or at make time like this:

        make prefix=/some/other/path

If you are installing this software as an individual user, instead of as a system manager, and you only use one binary architecture flavor, a reasonable choice for the prefix is $HOME/local. You then need only add $HOME/local/bin to your search path.

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 Compaq/DEC Alpha OSF/1, you must set CC to "cxx -x cxx").

If you are installing biblabel 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.

This program has been successfully built and tested with C and C++ compilers on these systems for the 2.00 release (117 builds):

Test suite

The biblabel distribution includes a simple validation test. It is run by

        make check

There should be no output from that test, other than a banner line announcing that expectation.

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.

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 --prefix=/tmp/local && make  all check install
creating cache ./config.cache
checking for compiler and utilities... 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 gawk... gawk
checking for bibclean... bibclean
checking for bibsort... bibsort
checking for checksum... checksum
checking for chmod... chmod
checking for col... col
checking for gzip... gzip
checking for scp... scp -p
checking for rcp... (cached) scp -p
checking for cp... (cached) scp -p
checking for date... date
checking for etags... etags
checking for jar... jar
checking for lint... lint
checking for ln... ln
checking for mkdir... mkdir
checking for mv... mv
checking for nroff... nroff
checking for rm... rm
checking for rmdir... rmdir
checking for sed... sed
checking for time... time
checking for touch... touch
checking for unzip... unzip
checking for zip... zip
checking for zoo... zoo
checking how to run the C preprocessor... cc -E
checking for ANSI C header files... yes
checking for alloc.h... no
checking for ctype.h... yes
checking for limits.h... yes
checking for math.h... yes
checking for stdio.h... yes
checking for stdlib.h... yes
checking for string.h... yes
checking for working const... yes
checking for mode_t... yes
checking for size_t... yes
checking for ptrdiff_t... yes
updating cache ./config.cache
creating ./config.status
creating Makefile
creating config.h
config.h is unchanged
cc -g -DHOST=\"xxx.math.utah.edu\" -DUSER=\"beebe\" -I. -c -o citesub.o citesub.c
cc -g -DHOST=\"xxx.math.utah.edu\" -DUSER=\"beebe\" -I. -c -o hash.o hash.c
cc -g -DHOST=\"xxx.math.utah.edu\" -DUSER=\"beebe\" -I. -c -o strdup.o strdup.c
cc -g -DHOST=\"xxx.math.utah.edu\" -DUSER=\"beebe\" -I. -c -o stricm.o stricm.c
cc -g -DHOST=\"xxx.math.utah.edu\" -DUSER=\"beebe\" -I. -c -o xalloc.o xalloc.c
cc -g -DHOST=\"xxx.math.utah.edu\" -DUSER=\"beebe\" -I. -o citesub citesub.o hash.o \
        strdup.o stricm.o xalloc.o
This package does not yet have a validation suite
mkdir /tmp/local/lib/biblabel
/bin/cp biblabel.awk /tmp/local/lib/biblabel/biblabel.awk
chmod 644 /tmp/local/lib/biblabel/biblabel.awk
sed -e 's@^BIBLABELAWK=./biblabel.awk@BIBLABELAWK=/tmp/local/lib/biblabel/biblabel.awk@' \
        biblabel.sh | checksum >/tmp/local/bin/biblabel
chmod 755 /tmp/local/bin/biblabel
/bin/cp biblabel.man /tmp/local/man/man1/biblabel.1
rm -f /tmp/local/man/cat1/biblabel.1
chmod 644 /tmp/local/man/man1/biblabel.1
/bin/cp citesub /tmp/local/bin/citesub
chmod 755 /tmp/local/bin/citesub
/bin/cp citesub.man /tmp/local/man/man1/citesub.1
rm -f /tmp/local/man/cat1/citesub.1
chmod 644 /tmp/local/man/man1/citesub.1