# README: Installation instruction for bibparse-1.04

## Table of contents

- Jump start
- Introduction
- Installation
- Bug reports
- UNIX Systems
- IBM PC DOS
- Test suite
- Sample build output for UNIX
- Implementation Notes

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

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

## Introduction

This directory contains `bibparse`, `biblex`, `bibunlex`, and `bibdup`, a suite of programs for support of BibTeX bibliography files. They are described in the following paper:

    @String{TUGboat = "TUGboat"}

    @Article{Beebe:TB14-4-395,
    author =       "Nelson Beebe",
    title =        "{{Bibliography prettyprinting and syntax checking}}",
    journal =      TUGboat,
    year =         "1993",
    volume =       "14",
    number =       "4",
    pages =        "395--419",
    month =        Dec,
    }

The complete text of the TUGboat article is included with bibclean 2.08 and later versions.

You can find distributions of `bibclean` in a variety of formats in the same place that you found the `bibparse` (et al) distribution. The master location is `ftp://ftp.math.utah.edu/pub/tex/bib`. Via electronic mail, a message with the body

    	help
    	send index from tex/bib

to `tuglib@math.utah.edu` will get you started.

Three files, `biblex.c`, `bibparse.c`, and `bibunlex.c`, are generated by `lex` (or `flex`), and `yacc` (or `bison`). Copies of these files from the author's site are preserved in the `save` subdirectory for manual bootstrapping, but on UNIX systems, they should be generated automatically as part of the installation process.

## Installation

Starting with version 1.03, `bibparse` 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` , `bibdup.sh` from `bibdup.sin`, and `config.h` from `config.hin`. The `configure` script is a large (2900+ lines) automatically-generated 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
    	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, plus the files `biblex.c` and `bibunlex.c` generated by `lex`, and the file `bibparse.c` generated by `yacc`. This will allow recovery from a lost or damaged `configure` file, and support manual bootstrapping on systems that lack lex/flex and yacc/bison support, or have broken implementations of those programs.

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/autoconf-`x.y`.tar.gz`), (`x.y` = 2.13 at the time of writing this), you might try augmenting `configure.in` instead, then run `autoheader`, `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 for the `make` variable, `prefix`, 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` and `Makefile` for the next build.

## Bug reports

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

## UNIX Systems

The code can be compiled with either C (K&R or ISO/ANSI Standard C) or C++ compilers, although whether C++ can be used for the `lex`/`flex`- and `yacc`/`bison`-generated code depends on how modern their versions are. 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 variables that you are likely to need to override on the `make` command line are the `Makefile` settings of `CC` and `OPT`, and if you wish to do make install, the setting of `prefix`.

If you are installing `bibparse` 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 built, tested, and validated with two independent lexers (`flex` and `lex`), and three independent parser generators (`bison`, `byacc`, and `yacc`), using all available C and C++ compilers on these 11 UNIX systems for the 1.04 release: 413 successful builds, and 49 failures. Because some compilers are stored in two different directories, or under two separate names, the actual number of independent builds is somewhat less.

While the large number of successful builds is gratifying, the failures are potentially even more important if they can be traced to deficiencies in my code. Close examination of the build logs shows that they are not: they are entirely due to one of the following:

- Code from `lex/flex` and/or `bison/byacc/yacc` which is not C++-compatible; there is no excuse for such vendor sloppiness, but it exists. C has had an ANSI/ISO Standard since December 1989, and the draft standard was stable at least two years before that, so the target language has been publicly defined for about a dozen years. All C-Standard-conforming code should compile without problems under C++ (barring use of C++ reserved words).
- Lack of compiler support for the non-standard stack memory allocator, `alloca()`, used in `bison`-generated code.
- Internal compiler errors (e.g., `lcc` on NeXT and SGI IRIX 6.x systems).
- Broken vendor-provided `yacc` (SGI IRIX 5.3).
- Broken vendor-provided header file, `alloca.h` (pgCC). A bug report about this to the vendor, The Portland Group (http://www.pgroup.com), produced a prompt response with the following patch:

      #ifdef __cplusplus
      extern "C" char * __builtin_alloca (int);
      #endif

      *** /usr/pgi/linux86/include/alloca.h   Thu Apr 22 18:57:51 1999
      --- ./alloca.h  Tue May 11 11:52:01 1999
      ***************
      *** 36,41 ****
      --- 36,44 ----

        # define __alloca(size)       __builtin_alloca (size)
        # define alloca(size) __alloca (size)
      + #ifdef __cplusplus
      + extern "C" char * __builtin_alloca (int);
      + #endif

        __END_DECLS

### Successes

#### flex + bison (70 compilers)

Machine and model | O/S | Compilers
DEC Alpha 2100-5/250 | OSF/1 3.2 | /usr/bin/c89 /usr/bin/cc /bin/cc /bin/c89 /bin/cxx -x cxx /usr/ucb/cc /usr/ccs/bin/cc /usr/ccs/bin/c89 /usr/local/bin/gcc /usr/local/bin/g++
HP 9000/735 | HP-UX 10.01 | /usr/bin/c89 /usr/ccs/bin/cc /usr/bin/cc /usr/local/bin/gcc /usr/local/bin/g++ /bin/c89 /bin/cc
IBM PowerPC 43P | AIX 4.2 | /bin/xlC /usr/local/bin/gcc /usr/local/bin/g++ /usr/bin/c89 /usr/bin/cc /bin/cc /bin/c89
Intel Pentium II 450MHz | GNU/Linux 2.1.132 | /usr/bin/cc /usr/pgi/linux86/bin/pgcc /usr/bin/gcc /usr/bin/g++ /usr/local/bin/gcc /usr/local/bin/g++
Intel Pentium II MMX | GNU/Linux 2.0.35 | /usr/bin/gcc /usr/bin/g++ /usr/bin/cc /usr/local/bin/lcc -A -A /usr/local/bin/gcc /usr/local/bin/g++
NeXT Turbostation | Mach 3.3 | /bin/cc /usr/local/bin/gcc /usr/local/bin/g++
SGI Challenge L | IRIX 5.3 | /bin/cc /usr/bin/CC /usr/bin/cc /usr/local/bin/gcc /usr/local/bin/g++ /bin/CC
SGI Origin/200-4 | IRIX 6.4 | /bin/CC /usr/bin/cc /bin/cc /bin/c89 /usr/bin/c89 /usr/local/bin/gcc /usr/local/bin/g++ /usr/bin/CC
Sun SPARC 10/412 | GNU/Linux 2.0.35 | /usr/bin/cc /usr/bin/gcc /usr/bin/g++
Sun SPARC LX | Solaris 2.5 | /opt/SUNWspro/bin/c89 /usr/ucb/cc /opt/SUNWspro/bin/CC /opt/SUNWspro/bin/cc /usr/local/bin/gcc /usr/local/bin/g++ /usr/local/bin/lcc -A -A
Sun Ultra Enterprise 5500 | Solaris 2.6 | /usr/local/bin/gcc /usr/local/bin/g++ /usr/local/bin/lcc -A -A /opt/SUNWspro/bin/CC /opt/SUNWspro/bin/c89 /opt/SUNWspro/bin/cc /usr/ucb/cc

#### flex + byacc (75 compilers)

Machine and model | O/S | Compilers
DEC Alpha 2100-5/250 | OSF/1 3.2 | /usr/bin/c89 /bin/c89 /bin/cc /usr/ccs/bin/c89 /usr/ucb/cc /usr/local/bin/gcc /usr/local/bin/g++ /bin/cxx -x cxx /usr/local/bin/lcc -A -A /usr/ccs/bin/cc /usr/bin/cc
HP 9000/735 | HP-UX 10.01 | /usr/bin/cc /bin/cc /usr/ccs/bin/cc /usr/bin/c89 /usr/local/bin/gcc /usr/local/bin/g++ /bin/c89 /usr/bin/CC /bin/CC
IBM PowerPC 43P | AIX 4.2 | /bin/xlC /usr/bin/c89 /bin/cc /usr/local/bin/gcc /usr/local/bin/g++ /bin/c89 /usr/bin/cc
Intel Pentium II 450MHz | GNU/Linux 2.1.132 | /usr/bin/cc /usr/pgi/linux86/bin/pgCC /usr/local/bin/gcc /usr/local/bin/g++ /usr/pgi/linux86/bin/pgcc /usr/bin/gcc /usr/bin/g++
Intel Pentium II MMX | GNU/Linux 2.0.35 | /usr/local/bin/lcc -A -A /usr/bin/gcc /usr/bin/g++ /usr/local/bin/gcc /usr/local/bin/g++ /usr/bin/cc
NeXT Turbostation | Mach 3.3 | /bin/cc /usr/local/bin/gcc /usr/local/bin/g++
SGI Challenge L | IRIX 5.3 | /bin/cc /usr/local/bin/gcc /usr/local/bin/lcc -A -A /usr/local/bin/g++ /usr/bin/CC /usr/bin/cc /bin/CC
SGI Origin/200-4 | IRIX 6.4 | /bin/CC /usr/bin/CC /usr/bin/c89 /bin/cc /usr/bin/cc /usr/local/bin/gcc /usr/local/bin/g++ /bin/c89
Sun SPARC 10/412 | GNU/Linux 2.0.35 | /usr/bin/gcc /usr/bin/g++ /usr/bin/cc
Sun SPARC LX | Solaris 2.5 | /usr/ucb/cc /opt/SUNWspro/bin/c89 /usr/local/bin/lcc -A -A /opt/SUNWspro/bin/CC /opt/SUNWspro/bin/cc /usr/local/bin/gcc /usr/local/bin/g++
Sun Ultra Enterprise 5500 | Solaris 2.6 | /usr/local/bin/lcc -A -A /usr/local/bin/gcc /usr/local/bin/g++ /opt/SUNWspro/bin/CC /opt/SUNWspro/bin/cc /opt/SUNWspro/bin/c89 /usr/ucb/cc

#### flex + yacc (66 compilers)

Machine and model | O/S | Compilers
DEC Alpha 2100-5/250 | OSF/1 3.2 | /usr/bin/c89 /usr/local/bin/gcc /usr/local/bin/g++ /bin/c89 /usr/ucb/cc /bin/cxx -x cxx /usr/ccs/bin/c89 /usr/bin/cc /usr/ccs/bin/cc /usr/local/bin/lcc -A -A /bin/cc
HP 9000/735 | HP-UX 10.01 | /bin/CC /usr/ccs/bin/cc /usr/bin/CC /bin/cc /usr/bin/cc /bin/c89 /usr/bin/c89 /usr/local/bin/gcc /usr/local/bin/g++
IBM PowerPC 43P | AIX 4.2 | /usr/bin/cc /bin/cc /bin/c89 /bin/xlC /usr/bin/c89 /usr/local/bin/gcc
Intel Pentium II 450MHz | GNU/Linux 2.1.132 | /usr/bin/gcc /usr/bin/g++ /usr/pgi/linux86/bin/pgCC /usr/pgi/linux86/bin/pgcc /usr/bin/cc /usr/local/bin/gcc /usr/local/bin/g++
Intel Pentium II MMX | GNU/Linux 2.0.35 | /usr/bin/cc /usr/local/bin/gcc /usr/local/bin/g++ /usr/bin/gcc /usr/bin/g++ /usr/local/bin/lcc -A -A
NeXT Turbostation | Mach 3.3 | /bin/cc /usr/local/bin/gcc /usr/local/bin/g++
SGI Origin/200-4 | IRIX 6.4 | /usr/local/bin/gcc /usr/local/bin/g++ /usr/bin/CC /bin/CC /usr/bin/cc /bin/cc /bin/c89 /usr/bin/c89
Sun SPARC 10/412 | GNU/Linux 2.0.35 | /usr/bin/cc /usr/bin/gcc /usr/bin/g++
Sun SPARC LX | Solaris 2.5 | /usr/local/bin/gcc /usr/local/bin/g++ /opt/SUNWspro/bin/cc /usr/ucb/cc /opt/SUNWspro/bin/c89 /opt/SUNWspro/bin/CC
Sun Ultra Enterprise 5500 | Solaris 2.6 | /opt/SUNWspro/bin/c89 /usr/ucb/cc /usr/local/bin/gcc /usr/local/bin/g++ /usr/local/bin/lcc -A -A /opt/SUNWspro/bin/CC /opt/SUNWspro/bin/cc

#### lex + bison (67 compilers)

Machine and model | O/S | Compilers
DEC Alpha 2100-5/250 | OSF/1 3.2 | /usr/ccs/bin/cc /usr/bin/c89 /usr/ucb/cc /usr/local/bin/gcc /usr/ccs/bin/c89 /bin/cc /bin/c89 /usr/bin/cc
HP 9000/735 | HP-UX 10.01 | /usr/bin/cc /usr/ccs/bin/cc /bin/c89 /usr/local/bin/gcc /usr/local/bin/g++ /bin/cc /usr/bin/c89
IBM PowerPC 43P | AIX 4.2 | /usr/local/bin/gcc /usr/local/bin/g++ /usr/bin/c89 /bin/c89 /bin/xlC /bin/cc /usr/bin/cc
Intel Pentium II 450MHz | GNU/Linux 2.1.132 | /usr/bin/gcc /usr/bin/g++ /usr/bin/cc /usr/pgi/linux86/bin/pgcc /usr/local/bin/gcc /usr/local/bin/g++
Intel Pentium II MMX | GNU/Linux 2.0.35 | /usr/bin/cc /usr/bin/gcc /usr/bin/g++ /usr/local/bin/gcc /usr/local/bin/lcc -A -A /usr/local/bin/g++
NeXT Turbostation | Mach 3.3 | /usr/local/bin/gcc /bin/cc
SGI Challenge L | IRIX 5.3 | /bin/CC /usr/bin/CC /bin/cc /usr/bin/cc /usr/local/bin/gcc /usr/local/bin/g++
SGI Origin/200-4 | IRIX 6.4 | /usr/bin/cc /usr/bin/c89 /usr/local/bin/gcc /usr/local/bin/g++ /bin/CC /bin/cc /usr/bin/CC /bin/c89
Sun SPARC 10/412 | GNU/Linux 2.0.35 | /usr/bin/cc /usr/bin/gcc /usr/bin/g++
Sun SPARC LX | Solaris 2.5 | /usr/local/bin/gcc /usr/local/bin/g++ /opt/SUNWspro/bin/CC /opt/SUNWspro/bin/cc /usr/ucb/cc /usr/local/bin/lcc -A -A /opt/SUNWspro/bin/c89
Sun Ultra Enterprise 5500 | Solaris 2.6 | /opt/SUNWspro/bin/c89 /usr/local/bin/gcc /usr/local/bin/g++ /opt/SUNWspro/bin/CC /usr/ucb/cc /opt/SUNWspro/bin/cc /usr/local/bin/lcc -A -A

#### lex + byacc (72 compilers)

Machine and model | O/S | Compilers
DEC Alpha 2100-5/250 | OSF/1 3.2 | /bin/cc /usr/local/bin/gcc /usr/local/bin/lcc -A -A /usr/ccs/bin/cc /usr/ucb/cc /usr/bin/c89 /usr/ccs/bin/c89 /usr/bin/cc /bin/c89
HP 9000/735 | HP-UX 10.01 | /bin/CC /bin/cc /usr/ccs/bin/cc /bin/c89 /usr/bin/CC /usr/local/bin/gcc /usr/bin/cc /usr/local/bin/g++ /usr/bin/c89
IBM PowerPC 43P | AIX 4.2 | /usr/bin/cc /usr/bin/c89 /bin/c89 /bin/cc /bin/xlC /usr/local/bin/gcc /usr/local/bin/g++
Intel Pentium II 450MHz | GNU/Linux 2.1.132 | /usr/bin/gcc /usr/bin/g++ /usr/bin/cc /usr/pgi/linux86/bin/pgCC /usr/local/bin/gcc /usr/local/bin/g++ /usr/pgi/linux86/bin/pgcc
Intel Pentium II MMX | GNU/Linux 2.0.35 | /usr/local/bin/lcc -A -A /usr/bin/gcc /usr/bin/g++ /usr/bin/cc /usr/local/bin/gcc /usr/local/bin/g++
NeXT Turbostation | Mach 3.3 | /usr/local/bin/gcc /bin/cc
SGI Challenge L | IRIX 5.3 | /usr/bin/cc /usr/local/bin/lcc -A -A /bin/CC /bin/cc /usr/local/bin/gcc /usr/bin/CC /usr/local/bin/g++
SGI Origin/200-4 | IRIX 6.4 | /usr/bin/c89 /usr/bin/CC /usr/bin/cc /bin/c89 /usr/local/bin/gcc /usr/local/bin/g++ /bin/CC /bin/cc
Sun SPARC 10/412 | GNU/Linux 2.0.35 | /usr/bin/gcc /usr/bin/g++ /usr/bin/cc
Sun SPARC LX | Solaris 2.5 | /usr/local/bin/lcc -A -A /opt/SUNWspro/bin/CC /usr/local/bin/gcc /usr/local/bin/g++ /opt/SUNWspro/bin/cc /usr/ucb/cc /opt/SUNWspro/bin/c89
Sun Ultra Enterprise 5500 | Solaris 2.6 | /usr/local/bin/lcc -A -A /opt/SUNWspro/bin/c89 /usr/ucb/cc /usr/local/bin/gcc /usr/local/bin/g++ /opt/SUNWspro/bin/CC /opt/SUNWspro/bin/cc

#### lex + yacc (63 compilers)

Machine and model | O/S | Compilers
DEC Alpha 2100-5/250 | OSF/1 3.2 | /usr/ccs/bin/c89 /usr/bin/c89 /bin/c89 /usr/ccs/bin/cc /usr/local/bin/gcc /usr/ucb/cc /usr/local/bin/lcc -A -A /bin/cc /usr/bin/cc
HP 9000/735 | HP-UX 10.01 | /usr/ccs/bin/cc /usr/bin/c89 /usr/bin/CC /bin/c89 /usr/bin/cc /bin/CC /usr/local/bin/gcc /usr/local/bin/g++ /bin/cc
IBM PowerPC 43P | AIX 4.2 | /usr/bin/c89 /usr/local/bin/gcc /bin/cc /bin/c89 /bin/xlC /usr/bin/cc
Intel Pentium II 450MHz | GNU/Linux 2.1.132 | /usr/pgi/linux86/bin/pgcc /usr/bin/gcc /usr/local/bin/gcc /usr/bin/g++ /usr/local/bin/g++ /usr/bin/cc /usr/pgi/linux86/bin/pgCC
Intel Pentium II MMX | GNU/Linux 2.0.35 | /usr/local/bin/gcc /usr/local/bin/g++ /usr/bin/gcc /usr/bin/g++ /usr/bin/cc /usr/local/bin/lcc -A -A
NeXT Turbostation | Mach 3.3 | /bin/cc /usr/local/bin/gcc
SGI Origin/200-4 | IRIX 6.4 | /bin/cc /usr/bin/c89 /usr/bin/cc /usr/local/bin/gcc /usr/local/bin/g++ /bin/c89 /bin/CC /usr/bin/CC
Sun SPARC 10/412 | GNU/Linux 2.0.35 | /usr/bin/cc /usr/bin/gcc /usr/bin/g++
Sun SPARC LX | Solaris 2.5 | /usr/local/bin/gcc /usr/local/bin/g++ /usr/ucb/cc /opt/SUNWspro/bin/CC /opt/SUNWspro/bin/c89 /opt/SUNWspro/bin/cc
Sun Ultra Enterprise 5500 | Solaris 2.6 | /usr/ucb/cc /opt/SUNWspro/bin/CC /opt/SUNWspro/bin/cc /usr/local/bin/gcc /usr/local/bin/g++ /opt/SUNWspro/bin/c89 /usr/local/bin/lcc -A -A

### Failures

#### flex + bison (7 compilers)

Machine and model | O/S | Compilers
DEC Alpha 2100-5/250 | OSF/1 3.2 | /usr/local/bin/lcc -A -A
HP 9000/735 | HP-UX 10.01 | /usr/bin/CC /bin/CC
Intel Pentium II 450MHz | GNU/Linux 2.1.132 | /usr/pgi/linux86/bin/pgCC
NeXT Turbostation | Mach 3.3 | /usr/local/bin/lcc -A -A
SGI Challenge L | IRIX 5.3 | /usr/local/bin/lcc -A -A
SGI Origin/200-4 | IRIX 6.4 | /usr/local/bin/lcc -A -A

#### flex + byacc (2 compilers)

Machine and model | O/S | Compilers
NeXT Turbostation | Mach 3.3 | /usr/local/bin/lcc -A -A
SGI Origin/200-4 | IRIX 6.4 | /usr/local/bin/lcc -A -A

#### flex + yacc (11 compilers)

Machine and model | O/S | Compilers
IBM PowerPC 43P | AIX 4.2 | /usr/local/bin/g++
NeXT Turbostation | Mach 3.3 | /usr/local/bin/lcc -A -A
SGI Challenge L | IRIX 5.3 | /usr/local/bin/lcc -A -A /usr/local/bin/gcc /bin/cc /bin/CC /usr/bin/cc /usr/bin/CC /usr/local/bin/g++
SGI Origin/200-4 | IRIX 6.4 | /usr/local/bin/lcc -A -A
Sun SPARC LX | Solaris 2.5 | /usr/local/bin/lcc -A -A

#### lex + bison (10 compilers)

Machine and model | O/S | Compilers
DEC Alpha 2100-5/250 | OSF/1 3.2 | /usr/local/bin/g++ /usr/local/bin/lcc -A -A /bin/cxx -x cxx
HP 9000/735 | HP-UX 10.01 | /bin/CC /usr/bin/CC
Intel Pentium II 450MHz | GNU/Linux 2.1.132 | /usr/pgi/linux86/bin/pgCC
NeXT Turbostation | Mach 3.3 | /usr/local/bin/lcc -A -A /usr/local/bin/g++
SGI Challenge L | IRIX 5.3 | /usr/local/bin/lcc -A -A
SGI Origin/200-4 | IRIX 6.4 | /usr/local/bin/lcc -A -A

#### lex + byacc (5 compilers)

Machine and model | O/S | Compilers
DEC Alpha 2100-5/250 | OSF/1 3.2 | /bin/cxx -x cxx /usr/local/bin/g++
NeXT Turbostation | Mach 3.3 | /usr/local/bin/lcc -A -A /usr/local/bin/g++
SGI Origin/200-4 | IRIX 6.4 | /usr/local/bin/lcc -A -A

#### lex + yacc (14 compilers)

Machine and model | O/S | Compilers
DEC Alpha 2100-5/250 | OSF/1 3.2 | /bin/cxx -x cxx /usr/local/bin/g++
IBM PowerPC 43P | AIX 4.2 | /usr/local/bin/g++
NeXT Turbostation | Mach 3.3 | /usr/local/bin/lcc -A -A /usr/local/bin/g++
SGI Challenge L | IRIX 5.3 | /usr/local/bin/gcc /usr/local/bin/g++ /bin/cc /bin/CC /usr/local/bin/lcc -A -A /usr/bin/cc /usr/bin/CC
SGI Origin/200-4 | IRIX 6.4 | /usr/local/bin/lcc -A -A
Sun SPARC LX | Solaris 2.5 | /usr/local/bin/lcc -A -A

## IBM PC DOS

Of all the compilers that I have available on the IBM PC under Microsoft DOS and Windows (two versions of Turbo C, four of Microsoft C, and two of Watcom C), none support 32-bit int data. This prevents the use of the `yacc` version of `bibparse.c`, because it requires an integer type that can hold values as large as -10000000. Had all such data been given a type defined by a `typedef`, a one-line change from `int` to `long` would permit the transfer of the code to an environment with 32-bit `long` support. Sadly, such is not the case. Perhaps the commercial Mortice-Kern MKS Tools package of UNIX tools on DOS addresses this issue, but I do not yet have it.

Another problem is that the parser tables are too big for the obnoxious 64KB-segment limit of the Intel x86 architecture, and none of the compilers, except for the Watcom 386 compiler, will compile the code.

Fortunately, the solution is simply to use `bison` instead of `yacc`. It has been designed to work with integers as small as 16 bits, and its parser tables are more compact.

The three programs can be built standalone in this environment, without the need for `lex`, `flex`, or `yacc` libraries, provided that the symbol `HAVE_IBMPC` is defined in the `config.h` file, and the symbol `HAVE_FILENO` is undefined there. This will enable a simple version of the `yywrap()` function, and also reduce the memory requirements to fit in the 64KB-segment limit.

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

Since `bibparse` 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 `bibparse` executables work fine on it. They also work on Caldera OpenDOS 7.01, the version supplied by Sun under Solaris 2.6 for the SunPC emulator, and on the Windows version of DOS under Windows 95.

## Test suite

The `bibparse` distribution includes a comprehensive test suite which is run by

    	make check

For use on other operating systems, the `ibmpc/dos/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.

## 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=/opt/SUNWspro/bin/CC ./configure && make
    creating cache ./config.cache
    checking for gcc... /opt/SUNWspro/bin/CC
    checking whether the C compiler (/opt/SUNWspro/bin/CC   ) works... yes
    checking whether the C compiler (/opt/SUNWspro/bin/CC   ) is a cross-compiler... no
    checking whether we are using GNU C... no
    checking whether /opt/SUNWspro/bin/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 for compiler language... C++
    checking how to run the C preprocessor... /opt/SUNWspro/bin/CC  -E
    checking for alloca.h... yes
    checking for stdlib.h... yes
    checking for nawk... nawk
    checking for chmod... chmod
    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... deroff
    checking for diff... diff
    checking for distill... /usr/local/bin/distill
    checking for ditroff... no
    checking for groff... groff
    checking for etags... etags
    checking for expand... expand
    checking for jar... jar
    checking for lex... lex
    checking for flex... (cached) lex
    checking for ln... ln
    checking for ls... ls
    checking for man2html... /usr/local/bin/man2html
    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 shar... shar
    checking for spell... spell
    checking for tar... tar
    checking for touch... touch
    checking for unzip... unzip
    checking for yacc... yacc
    checking for zip... zip
    checking for zoo... zoo
    checking for fileno... no
    checking for alloca in -lPW... no
    checking for lex/flex library... -ll
    checking for yacc library... -ly
    checking for bison flags...
    checking for preprocessor symbols needed on Sun Solaris...  -D__EXTERN_C__
    updating cache ./config.cache
    creating ./config.status
    creating Makefile
    creating bibdup.sh
    creating config.h
    yacc -v  bibparse.y

    conflicts: 6 shift/reduce
    sed -e 's/char *yytext *\[YYLMAX\]/char yytext[40960]/' -e '/static void __yy__unused() { main(); }/d' -e 's/#[         ]*define[       ]*YYLMAX.*$/#define YYLMAX BIBYYLMAX/' -e '/extern[     ]*char[         ]*[*]getenv[    ]*[(][  ]*[)]/d' < y.tab.c > bibparse.c
    rm -f y.tab.c
    /opt/SUNWspro/bin/CC  -D__EXTERN_C__ -DBIBYYLMAX=40960 -I.  -c bibparse.c
    lex -t biblex.l | sed -e 's/char *yytext *\[YYLMAX\]/char yytext[40960]/' -e '/static void __yy__unused() { main(); }/d' -e 's/#[       ]*define[       ]*YYLMAX.*$/#define YYLMAX BIBYYLMAX/' -e '/extern[     ]*char[         ]*[*]getenv[    ]*[(][  ]*[)]/d' > biblex.c
    136/1000 nodes(%e), 311/2500 positions(%p), 50/500 (%n), 3095 transitions,
    188/10000 packed char classes(%k),  230/3000 packed transitions(%a),  265/6000 output slots(%o)
    /opt/SUNWspro/bin/CC  -D__EXTERN_C__ -DBIBYYLMAX=40960 -I.  -Dyylex=xxlex -o bibparse bibparse.o biblex.c  -ll -ly
    /opt/SUNWspro/bin/CC  -D__EXTERN_C__ -DBIBYYLMAX=40960 -I.  -o biblex lexmain.c biblex.c  -ll -ly
    lexmain.c:
    biblex.c:
    lex -t bibunlex.l | sed -e 's/char *yytext *\[YYLMAX\]/char yytext[40960]/' -e '/static void __yy__unused() { main(); }/d' -e 's/#[     ]*define[       ]*YYLMAX.*$/#define YYLMAX BIBYYLMAX/' -e '/extern[     ]*char[         ]*[*]getenv[    ]*[(][  ]*[)]/d' > bibunlex.c
    /opt/SUNWspro/bin/CC  -D__EXTERN_C__ -DBIBYYLMAX=40960 -I.  -o bibunlex bibunlex.c  -ll -ly

    The following checks should produce no output, other than their names
    lex001
    lex002
    lex003
    lex004
    lex005

    The following checks should produce no output, other than their names
    parse001
    parse002
    parse003
    parse004
    parse005
    parse006
    parse007
    parse008
    parse009
    parse010
    parse011
    parse012
    parse013
    parse014
    parse015

    The following checks should produce no output, other than their names
    unlex001
    unlex002
    unlex003
    unlex004
    unlex005

## Implementation Notes

While the GNU `autoconfigure` system is a great boon for end users, it is a painful system for developers to implement for their code. Despite already having adapted several other programs to use this system, I spent two long and tedious days at `bibparse 1.03` experimenting with settings in the `configure.in` file before the tests succeeded on a large enough number of systems that I can have some confidence that the installations will go smoothly at most end-user sites.

At version 1.04, when I ported `bibparse` to even more systems, and a new parser generator, `byacc`, it took another four days of tuning the `configure.in` file to handle system peculiarities, notably on GNU/Linux.

A major problem with `autoconfigure` is that it is not sufficiently C++-aware. The simple test files that it creates for probing features of the host implementation lack correct prototypes, and compilation failures then lead to incorrect setting of values in `config.h` and `Makefile`.

On most of the test systems, the vendor-provided `lex` is not C++-aware either, so that compilation failures from missing prototypes, or inconsistent or old-style function declarations, are common.

One vendor, HP, generates a reference to an non-standard external header file, `yacc.h`, in `yacc` output, but the location of that header file is unknown to `g++`. In any event, that file is wrong anyway, because it declares `yyparse()` to have C linkage, but the version in the generated C file will be compiled with C++ linkage. This was solved by created a temporary empty `yacc.h` file in the rules for `bibparse.o` in `Makefile.in`.

The same vendor, HP, generates a call to `main()` in `lex` output which then fails to match the prototype, and causes compilation failure. This was solved by an edit step in `Makefile.in` to removed the offending line.

Another problem for C++ use is that, on some systems, the normal `lex` functions `input()` and `output()` must be renamed to avoid conflicts with uses of those names in C++ header files. On Sun Solaris 2.x, they become `lex_input()` and `lex_output()`, so `bibyydcl.h` has to handle this case specially. I don't see any good way to do this with `configure`, since it is very awkward to produce tests in languages other than C.

The GNU/Linux (Caldera Light 2.0.30) system on which I tested `bibparse` 1.03 had `yacc`, but not its library, `-ly`, so a more complex test had to be generated in `configure.in` to handle that irregularity.

The RedHat GNU/Linux systems on Intel Pentium and Sun SPARC hardware on which I tested `bibparse` 1.04 have `lex`, but not its library, `-ll`, and worse, that `lex` is really `flex`, which does not behave compatibly, unless it is invoked with the compatibility-mode flag, `-l`. However, that flag cannot be used with ordinary `lex`: on HP systems, it produces a warning; on IBM systems, it produces garbage in the output C file; on SGI systems, it causes `lex` to hang in an apparent I/O wait. It took several tries on various systems before I settled on the code finally used in `configure.in` to handle these variations.

On SGI IRIX 5.3 systems, there is a bug in `yacc` which results in a bogus complaint

    UX:yacc: ERROR: Redeclaration of precedence of TOKEN_EQUALS, line 210

Thus, on that system, either `bison` or `byacc` (Berkeley `yacc`) must be used, and neither are provided by the vendor.

You can get `bison` at the Free Software Foundation archive (or one of its several mirrors): ftp://prep.ai.mit.edu/gnu/bison/bison-1.27.tar.gz,

The most recent version of Berkeley `byacc` that I could find is at the Cygnus FTP site: ftp://ftp.cygnus.com/pub/gdb/infrastructure/byacc-940324.tar.gz That version has been make to run with an early version of GNU `autoconfig`, and has bug fixes beyond the `byacc` version 1.9 of 22-Feb-1993 that I found at the Berkeley BSD development site: ftp://ftp.cs.berkeley.edu/pub/4bsd/byacc.1.9.tar.Z Even though the Cygnus version is newer (23-Mar-1994), it produces code that did not compile under C++ until I made this patch:

    ===================================================================
    RCS file: byacc-940324/byacc/RCS/skeleton.c,v
    retrieving revision 1.1
    diff -r1.1 byacc-940324/byacc/skeleton.c
    98a99,102
    >     "#ifdef __cplusplus",
    >     "extern \"C\"",
    >     "#endif",
    >     "    extern char *getenv();",
    105,108d108
    <     "#ifdef __cplusplus",
    <     "extern \"C\"",
    <     "#endif",
    <     "    extern char *getenv();",
    ===================================================================

On Sun Solaris 2.x, the symbol `__EXTERN_C__` must be defined in order to expose certain function prototypes in the code generated by `lex` and `yacc`. `configure.in` has a special test for this system to generate the needed definition.

The linkers on some UNIX systems do not search `/usr/local/lib` by default, even though this has long been a standard location for locally-installed libraries. Consequently, the `configure.in` rules add this directory to the library search path when the `flex` library `-lfl` is required. If your site has a non-standard location for this library, where your linker cannot find it without help, then you'll have to override the `LDFLAGS` value when you run `make`, e.g.,

    make LDFLAGS='-L/my/private/lib'