git.sur5r.net Git - openldap/blob - build/unproto/README

   1 @(#) README 1.6 93/06/18 22:29:34
   2
   3 unproto - Compile ANSI C with traditional UNIX C compiler
   4
   5 Description:
   6 ------------
   7
   8 This is a filter that sits in between the UNIX C preprocessor and the
   9 next UNIX C compiler stage, on the fly transforming ANSI C syntax to
  10 old C syntax.  Line number information is preserved so that compiler
  11 diagnostics still make sense.  It runs at roughly the same speed as
  12 /lib/cpp, so it has negligible impact on compilation time.
  13
  14 Typically, the program is invoked by the native UNIX C compiler as an
  15 alternate preprocessor. The unprototyper in turn invokes the native C
  16 preprocessor and massages its output.  Similar tricks can be used with
  17 the lint(1) command. Details are given below.
  18
  19 The filter rewrites ANSI-style function headings, function pointer
  20 types and type casts, function prototypes, and combinations thereof.
  21 Unlike some other unprototypers, this one is fully recursive and does
  22 not depend on source file layout (see the example.c file).
  23
  24 Besides the rewriting of argument lists, the program does the following
  25 transformations:  string concatenation, conversion of \a and \x escape
  26 sequences to their octal equivalents, translation of the __TIME__ and
  27 __DATE__ macros, optional mapping of `void *' to `char *', and optional
  28 mapping of plain `void' to `int'.
  29
  30 The unprototyper provides hooks for compilers that require special
  31 tricks for variadic functions (fortunately, many don't). <stdarg.h>
  32 support is provided for sparc, mips, mc68k, 80x86, vax, and others.
  33
  34 The program has been tested with SunOS 4.1.1 (sparc), Ultrix 4.0 and
  35 4.2 (mips), and Microport System V Release 2 (80286). It should work
  36 with almost every PCC-based UNIX C compiler.
  37
  38 Restrictions:
  39 -------------
  40
  41 A description of restrictions and workarounds can be found in the
  42 unproto.1 manual page.
  43
  44 Problems fixed with this release:
  45 ---------------------------------
  46
  47 Prototypes and definitions of functions returning pointer to function
  48 were not rewritten to old style.
  49
  50 Operation:
  51 ----------
  52
  53 This package implements a non-default C preprocessor (the output from
  54 the default C preprocessor being piped through the unprototyper).  How
  55 one tells the C compiler to use a non-default preprocessor program is
  56 somewhat compiler-dependent:
  57
  58     SunOS 4.x:  cc -Qpath directory_with_alternate_cpp ...
  59
  60     Ultrix 4.x: cc -tp -hdirectory_with_alternate_cpp -B ...
  61
  62     System V.2: cc -Bdirectory_with_alternate_cpp/ -tp ...
  63
  64 Examples of these, and others, can be found in the acc.sh shell script
  65 that emulates an ANSI C compiler.  Your C compiler manual page should
  66 provide the necessary information.
  67
  68 A more portable, but less efficient, approach relies on the observation
  69 that almost every UNIX C compiler supports the -E (write preprocessor
  70 output to stdout) and -P options (preprocess file.c into file.i). Just
  71 add the following lines to your Makefiles:
  72
  73     .c.o:
  74             $(CC) $(CFLAGS) -E $*.c | unproto >$*.i # simulate -P option
  75             $(CC) $(CFLAGS) -c $*.i
  76             rm -f $*.i
  77
  78 On some systems the lint(1) command is just a shell script, and writing
  79 a version that uses the unprototyper should not be too hard. With SunOS
  80 4.x, /usr/bin/lint is not a shell script, but it does accept the same
  81 syntax as the cc(1) command for the specification of a non-default
  82 compiler pass.
  83
  84 You may have to do some research on the lint command provided with your
  85 own machine.
  86
  87 Configuration:
  88 --------------
  89
  90 Check the contents of the `stdarg.h' file provided with this package.
  91 This file serves a dual purpose: (1) on systems that do not provide a
  92 stdarg.h file, it should be included by C source files that implements
  93 ANSI-style variadic functions; (2) it is also used to configure the
  94 unprototyper so that it emits the proper magic when it sees `...'.
  95
  96 The `stdarg.h' file has support for sparc, mips, and for compilers that
  97 pass arguments via the stack (typical for 80*86, mc68k and vax). It
  98 gives general hints for other compilers.
  99
 100 The other sample header files (stddef.h and stdlib.h) are not required
 101 to build the unprototyper.
 102
 103 The `varargs.c' file provided with this package can be used to verify
 104 that the `stdarg.h' file has been set up correctly.
 105
 106 If your C compiler has no hooks for an alternate preprocessor (the
 107 unprototyper will be used as: `cc cflags -E file.c | unproto >file.i'),
 108 build the `unproto' executable without the `PIPE_THROUGH_CPP' feature.
 109 Details are given in the Makefile.
 110
 111 Otherwise, the `cpp.sh' shell script can be used to set up the pipe
 112 between the native C preprocessor and the unprototyper command.  The
 113 script assumes that the unprototyper binary is called `unproto', and
 114 that it was compiled without the `PIPE_THROUGH_CPP' feature.  See the
 115 Makefile and the `cpp.sh' script for details and for a description of
 116 possible problems with this approach.
 117
 118 The overhead and problems of shell-script interpretation can be avoided
 119 by letting the unprototyper itself pipe its standard input through the
 120 C preprocessor.  For this mode of operation, the unprototyper binary
 121 should be called `cpp', and the `unproto.c' source file should be
 122 compiled with the `PIPE_THROUGH_CPP' macro defined as the absolute
 123 pathname of the native C preprocessor (usually `/lib/cpp').  See the
 124 Makefile for details.
 125
 126 Installation:
 127 -------------
 128
 129 Install the `unproto.1' manual page in a suitable place. If your system
 130 does not provide a `stdarg.h' file, find a suitable place for the one
 131 provided with the unprototyper and install it there. The same goes for
 132 the sample stddef.h and stdlib.h files; make sure that the definitions
 133 in there apply to your environment. Most or all of the latter files are
 134 already part of Ultrix 4.x and SunOS 4.1.1.
 135
 136 The ANSI float.h and limits.h files can be generated with the config
 137 program by Steve Pemberton (comp.sources.misc volume 10, issue 62,
 138 available from ftp.uu.net as comp.sources.misc/volume10/config42.Z).
 139
 140 If you run the unprototyper with "cc -E" just install the `unproto'
 141 binary; the `cpp' and `acc' shell scripts will not be needed.
 142
 143 If you use the `cpp' shell script to pipe the preprocessor output
 144 through the unprototyper program, install the `unproto' binary in a
 145 place where the `cpp' shell script can find it, and install the `cpp'
 146 shell script in a suitable place. Edit the `acc' shell script and
 147 install it in a suitable place. From now on, type `acc' instead of
 148 `cc'.
 149
 150 If the unprototyper itself opens the pipe to the C preprocessor (i.e.
 151 the unprototyper was built with the `PIPE_THROUGH_CPP' macro defined),
 152 install the `cpp' unprototyper binary in a suitable place. Edit the
 153 `acc' shell script and install it in a suitable place. From now on,
 154 type `acc' instead of `cc'.
 155
 156         Wietse Venema
 157         wietse@wzv.win.tue.nl
 158         Mathematics and Computing Science
 159         Eindhoven University of Technology
 160         The Netherlands