@(#) README 1.4 92/01/15 21:52:54

unproto - Compile ANSI C with traditional UNIX C compiler

Description:
------------

This is a filter that sits in between the UNIX C preprocessor and the
next UNIX C compiler stage, on the fly transforming ANSI C syntax to
old C syntax.  It runs at roughly the same speed as /lib/cpp, so it 
has negligible impact on compilation time.

Typically, the program is invoked by the native UNIX C compiler as an
alternate preprocessor. The unprototyper in turn invokes the native C
preprocessor and massages its output.  Similar tricks can be used with
the lint(1) command. Details are given below.

The filter rewrites ANSI-style function headings, function pointer
types and type casts, function prototypes, and combinations thereof.
Unlike some other unprototypers, this one is fully recursive and does
not depend on source file layout (see the example.c file).

New and improved functionality provided by the present version: string
concatenation, conversion of \a and \x escape sequences to their octal
equivalents, translation of __TIME__ and __DATE__, optional mapping of
`void *' to `char *', optional mapping of plain `void' to `int', faster
execution, and better conservation of program layout.

The unprototyper provides hooks for compilers that require special
tricks for variadic functions (fortunately, many don't). <stdarg.h>
support is provided for sparc, mips, mc68k, 80x86, vax, and others.

The program has been tested with SunOS 4.1.1 (sparc), Ultrix 4.0 and
4.2 (mips), and Microport System V Release 2 (80286). It should work
with almost every PCC-based UNIX C compiler.

Restrictions:
-------------

A description of restrictions and workarounds can be found in the
unproto.1 manual page.

Problems fixed with this release:
---------------------------------

Some multi-line statements could end up on a single output line, so
that compiler diagnostics with respect to those statements could point
to the wrong source-file position (other compiler diagnostics would not
have this problem).  The token input/output routines were completely
rewritten to eliminate these inconsistencies.

Backslashes within comments were not given special treatment.  Since
the C preprocessor by default removes all comments this would almost
never have caused a problem.

A backslash in front of any token except newline was not given special
treatment. I have never seen any C code where this would have caused a
problem.

The program now returns a non-zero status if it detected any problems.

A couple of simple heuristics have been added so that the program may
now even be useful for the conversion of unpreprocessed source.

Operation:
----------

This package implements a non-default C preprocessor (the output from
the default C preprocessor being piped through the unprototyper).  How
one tells the C compiler to use a non-default preprocessor program is
somewhat compiler-dependent:

    SunOS 4.x:  cc -Qpath directory_with_alternate_cpp ...

    Ultrix 4.x: cc -tp -hdirectory_with_alternate_cpp -B ...

    System V.2: cc -Bdirectory_with_alternate_cpp/ -tp ...

Your C compiler manual page should provide the necessary information.

On some systems the lint(1) command is just a shell script, and writing
a version that uses the unprototyper should not be too hard. With SunOS
4.x, /usr/bin/lint is not a shell script, but it does accept the same
syntax as the cc(1) command for the specification of a non-default
compiler pass. 

You may have to do some research on the lint command provided with your
own machine.

Configuration:
--------------

Check the contents of the `stdarg.h' file provided with this package.
This file serves a dual purpose: (1) on systems that do not provide a
stdarg.h file, it should be included by C source files that implement
ANSI-style variadic functions; (2) it is also used to configure the
unprototyper so that it emits the proper magic when it sees `...'.

The `stdarg.h' file has support for sparc, mips, and for compilers that
pass arguments via the stack (old-style UNIX compilers for 80*86, mc68k
and vax). It gives general hints for other compilers.

The `varargs.c' file provided with this package can be used to verify
that the `stdarg.h' file has been set up correctly.

For maximal flexibility, the `cpp.sh' shell script can be used to set
up the pipe between the native C preprocessor and the unprototyper
command.  The script assumes that the unprototyper binary is called
`unproto'.  See the Makefile and the `cpp.sh' script for details and
for a description of possible problems with this approach.

The overhead and problems of shell-script interpretation can be avoided
by letting the unprototyper itself pipe its standard input through the
C preprocessor.  For this mode of operation, the unprototyper binary
should be called `cpp', and the `unproto.c' source file should be
compiled with the `PIPE_THROUGH_CPP' macro defined as the absolute
pathname of the native C preprocessor (usually `/lib/cpp').  See the
Makefile for details.

Installation:
-------------

Install the `unproto.1' manual page in a suitable place. If your system
does not provide a `stdarg.h' file, find a suitable place for the one
provided with the unprototyper and install it there.

If you use the `cpp' shell script to pipe the preprocessor output
through the unprototyper program, install the `unproto' binary in a
place where the `cpp' shell script can find it, and install the `cpp'
shell script in a suitable place.

If the unprototyper itself opens the pipe to the C preprocessor (i.e.
the unprototyper was built with the `PIPE_THROUGH_CPP' macro defined),
install the `cpp' unprototyper binary in a suitable place.

	Wietse Venema
	wietse@wzv.win.tue.nl
	Mathematics and Computing Science
	Eindhoven University of Technology
	The Netherlands
