home *** CD-ROM | disk | FTP | other *** search
/ Usenet 1994 January / usenetsourcesnewsgroupsinfomagicjanuary1994.iso / sources / misc / volume26 / unproto / part01 / README < prev    next >
Encoding:
Text File  |  1991-12-07  |  5.5 KB  |  131 lines
  1. @(#) README 1.3 91/12/01 12:37:55
  2.  
  3. unproto - ANSI C to old C converter
  4.  
  5. Purpose:
  6.  
  7. This is a filter that sits in between the C preprocessor and the next C
  8. compiler stage, and that on the fly rewrites ANSI C to old C. Its
  9. primary application is to compile ANSI C software in UNIX environments
  10. that do not (yet) have an ANSI C compiler and that cannot run GCC
  11. because of technical or political problems.
  12.  
  13. The filter leaves old-style C alone, and de-ANSI-fies function
  14. headings, function pointer type declarations (and casts), function type
  15. declarations, and combinations thereof. Many freely-distributable
  16. unprotoizers have problems with the latter because they are based on a
  17. non-recursive algorithm or even make assumptions about code layout.
  18.  
  19. The unprototyper has support for systems that require special tricks
  20. for variadic functions (fortunately, many don't). A sample `stdarg.h'
  21. file is provided with support for sparc, mc68k, 80x86, vax and others.
  22.  
  23. The program has been tested on a Sun SLC running SunOS 4.1.1 and on a
  24. 80286 PC clone running Microport's version of System V Release 2. It
  25. runs at about the same speed as /lib/cpp, so it should have negigible
  26. impact on compilation times.
  27.  
  28. Problems solved with this release:
  29.  
  30. Minor: the program was originally intended for the compilation of
  31. already tested ANSI C source, so that diagnostics from the native C
  32. compiler would be sufficient. The present release produces better
  33. diagnostics, so that it can also be used for program development.
  34.  
  35. Major: the template Makefile suggested that all #pragma directives be
  36. filtered out. This turns out to be a bad idea because some non-ANSI
  37. compilers (SunOS) rely on #pragmas to correctly handle the unusual flow
  38. control caused by vfork(2), setjmp(3) etcetera. A warning to this
  39. effect has been added to the Makefile.
  40.  
  41. No changes were made to the actual filter logic; output should be
  42. identical to that of the previous release.
  43.  
  44. Restrictions:
  45.  
  46. Other ANSI-isms are just passed on without modification, such as
  47. trigraphs, token pasting (##), #pragmas, stringizing (#text) and
  48. string concatenation ("string1" "string2").
  49.  
  50. The unprototyper does not understand declarations of (object). The
  51. result (the object disappears) will be a syntax error so this should
  52. not go by unnoticed.
  53.  
  54. Some C programmers rely on ANSI-style prototypes for the automatic type
  55. conversion of function arguments.  The unprototyper, however, does not
  56. generate casts. The lack of automatic conversion between integral
  57. and/or pointer argument types should not be a problem in environments
  58. where sizeof(int) == sizeof(long) == sizeof(pointer).  A more serious
  59. problem is the lack of automatic type conversions beteen integral and
  60. floating-point function argument types.  Let lint(1) be your friend.
  61.  
  62. Operation:
  63.  
  64. This package implements an non-default C preprocessor (the output from
  65. the default C preprocessor being piped through the unprototyper).  How
  66. one tells the C compiler to use an non-default preprocessor program is
  67. somewhat compiler-dependent:
  68.  
  69.     SunOS 4.x:  cc -Qpath directory_with_non-default_cpp ...
  70.  
  71.     SysV Rel2:  cc -Bdirectory_with_non-default_cpp/ -tp ...
  72.  
  73. Your C compiler manual should provide the necessary information.
  74.  
  75. On some systems the lint(1) command is just a shell script, and writing
  76. a version that uses the unprototyper should not be too hard. With SunOS
  77. 4.x, /usr/bin/lint is not a shell script, but it does accept the same
  78. syntax as the cc(1) command for the specification of a non-default
  79. compiler pass. 
  80.  
  81. You may have to do some research on the lint command provided with your
  82. own machine.
  83.  
  84. Configuration:
  85.  
  86. Check the contents of the `stdarg.h' file provided with this package.
  87. This file serves a dual purpose. It should be included by C source file
  88. that implements ANSI-style variadic functions. It is also used to
  89. configure the `unproto' program so that it emits the proper magic for
  90. the `...' construct.
  91.  
  92. The `stdarg.h' file contains definitions for the sparc architecture and
  93. for architectures that pass arguments via the stack (usually OK for
  94. 80*86, mc68k and vax C compilers).  Risc processors often need special
  95. tricks.  These are usually found in the file `/usr/include/varargs.h'.
  96.  
  97. The file `varargs.c' provided with this package can be used to verify
  98. that the `stdarg.h' file has been set up correctly.
  99.  
  100. For maximal flexibility, you can use the `cpp' shell script provided
  101. with this package to set up the pipe between the default C preprocessor
  102. and the unprototyper command. The script assumes that the unprototyper
  103. binary is called `unproto'. See the cpp.sh script and the Makefile for
  104. details.
  105.  
  106. The overhead of shell-script interpretation can be avoided by having
  107. the unprototyper itself open the pipe to the C preprocessor.  In this
  108. case, the `unproto.c' source file should be compiled with the
  109. `PIPE_THROUGH_CPP' macro defined as the pathname of the C preprocessor
  110. (usually `/lib/cpp'), and the unprototyper binary should be called
  111. `cpp'.  See the Makefile for details.
  112.  
  113. Installation:
  114.  
  115. Install the `stdarg.h' include file and the `unproto.1' manual page in
  116. suitable places.
  117.  
  118. If you use the `cpp' shell script to pipe the preprocessor output
  119. through the unprototyper program, install the `unproto' binary in a
  120. place where the `cpp' shell script can find it, and install the `cpp'
  121. shell script in a suitable place.
  122.  
  123. If the unprototyper itself opens the pipe to the C preprocessor (i.e.
  124. the unprototyper was built with the `PIPE_THROUGH_CPP' macro defined),
  125. install the `cpp' unprototyper binary in a suitable place.
  126.  
  127.     Wietse Venema
  128.     wietse@wzv.win.tue.nl
  129.     Eindhoven University of Technology
  130.     The Netherlands
  131.