diff options
Diffstat (limited to 'unproto/README')
-rw-r--r-- | unproto/README | 184 |
1 files changed, 107 insertions, 77 deletions
diff --git a/unproto/README b/unproto/README index 6856d3a..1074874 100644 --- a/unproto/README +++ b/unproto/README @@ -1,76 +1,79 @@ -@(#) README 1.3 91/12/01 12:37:55 +@(#) README 1.6 93/06/18 22:29:34 -unproto - ANSI C to old C converter +unproto - Compile ANSI C with traditional UNIX C compiler -Purpose: +Description: +------------ -This is a filter that sits in between the C preprocessor and the next C -compiler stage, and that on the fly rewrites ANSI C to old C. Its -primary application is to compile ANSI C software in UNIX environments -that do not (yet) have an ANSI C compiler and that cannot run GCC -because of technical or political problems. +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. Line number information is preserved so that compiler +diagnostics still make sense. It runs at roughly the same speed as +/lib/cpp, so it has negligible impact on compilation time. -The filter leaves old-style C alone, and de-ANSI-fies function -headings, function pointer type declarations (and casts), function type -declarations, and combinations thereof. Many freely-distributable -unprotoizers have problems with the latter because they are based on a -non-recursive algorithm or even make assumptions about code layout. +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 unprototyper has support for systems that require special tricks -for variadic functions (fortunately, many don't). A sample `stdarg.h' -file is provided with support for sparc, mc68k, 80x86, vax and others. +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). -The program has been tested on a Sun SLC running SunOS 4.1.1 and on a -80286 PC clone running Microport's version of System V Release 2. It -runs at about the same speed as /lib/cpp, so it should have negigible -impact on compilation times. +Besides the rewriting of argument lists, the program does the following +transformations: string concatenation, conversion of \a and \x escape +sequences to their octal equivalents, translation of the __TIME__ and +__DATE__ macros, optional mapping of `void *' to `char *', and optional +mapping of plain `void' to `int'. -Problems solved with this release: +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. -Minor: the program was originally intended for the compilation of -already tested ANSI C source, so that diagnostics from the native C -compiler would be sufficient. The present release produces better -diagnostics, so that it can also be used for program development. - -Major: the template Makefile suggested that all #pragma directives be -filtered out. This turns out to be a bad idea because some non-ANSI -compilers (SunOS) rely on #pragmas to correctly handle the unusual flow -control caused by vfork(2), setjmp(3) etcetera. A warning to this -effect has been added to the Makefile. - -No changes were made to the actual filter logic; output should be -identical to that of the previous release. +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: +------------- -Other ANSI-isms are just passed on without modification, such as -trigraphs, token pasting (##), #pragmas, stringizing (#text) and -string concatenation ("string1" "string2"). +A description of restrictions and workarounds can be found in the +unproto.1 manual page. -The unprototyper does not understand declarations of (object). The -result (the object disappears) will be a syntax error so this should -not go by unnoticed. +Problems fixed with this release: +--------------------------------- -Some C programmers rely on ANSI-style prototypes for the automatic type -conversion of function arguments. The unprototyper, however, does not -generate casts. The lack of automatic conversion between integral -and/or pointer argument types should not be a problem in environments -where sizeof(int) == sizeof(long) == sizeof(pointer). A more serious -problem is the lack of automatic type conversions beteen integral and -floating-point function argument types. Let lint(1) be your friend. +Prototypes and definitions of functions returning pointer to function +were not rewritten to old style. Operation: +---------- -This package implements an non-default C preprocessor (the output from +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 an non-default preprocessor program is +one tells the C compiler to use a non-default preprocessor program is somewhat compiler-dependent: - SunOS 4.x: cc -Qpath directory_with_non-default_cpp ... + 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 ... + +Examples of these, and others, can be found in the acc.sh shell script +that emulates an ANSI C compiler. Your C compiler manual page should +provide the necessary information. - SysV Rel2: cc -Bdirectory_with_non-default_cpp/ -tp ... +A more portable, but less efficient, approach relies on the observation +that almost every UNIX C compiler supports the -E (write preprocessor +output to stdout) and -P options (preprocess file.c into file.i). Just +add the following lines to your Makefiles: -Your C compiler manual should provide the necessary information. + .c.o: + $(CC) $(CFLAGS) -E $*.c | unproto >$*.i # simulate -P option + $(CC) $(CFLAGS) -c $*.i + rm -f $*.i 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 @@ -82,49 +85,76 @@ 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. It should be included by C source file -that implements ANSI-style variadic functions. It is also used to -configure the `unproto' program so that it emits the proper magic for -the `...' construct. +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 implements +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 contains definitions for the sparc architecture and -for architectures that pass arguments via the stack (usually OK for -80*86, mc68k and vax C compilers). Risc processors often need special -tricks. These are usually found in the file `/usr/include/varargs.h'. +The `stdarg.h' file has support for sparc, mips, and for compilers that +pass arguments via the stack (typical for 80*86, mc68k and vax). It +gives general hints for other compilers. -The file `varargs.c' provided with this package can be used to verify -that the `stdarg.h' file has been set up correctly. +The other sample header files (stddef.h and stdlib.h) are not required +to build the unprototyper. -For maximal flexibility, you can use the `cpp' shell script provided -with this package to set up the pipe between the default C preprocessor -and the unprototyper command. The script assumes that the unprototyper -binary is called `unproto'. See the cpp.sh script and the Makefile for -details. +The `varargs.c' file provided with this package can be used to verify +that the `stdarg.h' file has been set up correctly. -The overhead of shell-script interpretation can be avoided by having -the unprototyper itself open the pipe to the C preprocessor. In this -case, the `unproto.c' source file should be compiled with the -`PIPE_THROUGH_CPP' macro defined as the pathname of the C preprocessor -(usually `/lib/cpp'), and the unprototyper binary should be called -`cpp'. See the Makefile for details. +If your C compiler has no hooks for an alternate preprocessor (the +unprototyper will be used as: `cc cflags -E file.c | unproto >file.i'), +build the `unproto' executable without the `PIPE_THROUGH_CPP' feature. +Details are given in the Makefile. + +Otherwise, 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', and +that it was compiled without the `PIPE_THROUGH_CPP' feature. 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. The same goes for +the sample stddef.h and stdlib.h files; make sure that the definitions +in there apply to your environment. Most or all of the latter files are +already part of Ultrix 4.x and SunOS 4.1.1. + +The ANSI float.h and limits.h files can be generated with the config +program by Steve Pemberton (comp.sources.misc volume 10, issue 62, +available from ftp.uu.net as comp.sources.misc/volume10/config42.Z). -Install the `stdarg.h' include file and the `unproto.1' manual page in -suitable places. +If you run the unprototyper with "cc -E" just install the `unproto' +binary; the `cpp' and `acc' shell scripts will not be needed. 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. +shell script in a suitable place. Edit the `acc' shell script and +install it in a suitable place. From now on, type `acc' instead of +`cc'. 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. +install the `cpp' unprototyper binary in a suitable place. Edit the +`acc' shell script and install it in a suitable place. From now on, +type `acc' instead of `cc'. Wietse Venema wietse@wzv.win.tue.nl + Mathematics and Computing Science Eindhoven University of Technology The Netherlands |