home *** CD-ROM | disk | FTP | other *** search
/ Usenet 1994 October / usenetsourcesnewsgroupsinfomagicoctober1994disk2.iso / reviewed / volume01 / cextract / part00 next >
Internet Message Format  |  1991-07-08  |  6KB
  1. From: adb@cs.bu.edu (Adam Bryant)
  2. Subject: C prototyper / header file generator 
  3.  
  4. Environment: UNIX, VMS
  5.  
  6. Tested Environments: 
  7.     VAX/VMS
  8.     VAX 8700/VMS
  9.     VAX/BSD 4.3
  10.     IBM-RT/AOS 4.3
  11.     DECstation/Ultrix 3.1
  12.     IBM PS-2/AIX 1.2
  13.     MAC/AUX
  14.     Sun 4/SunOS 4.1.1
  15.     Sun 3/SunOS 4.0.3, 4.1.1
  16.     SGI/IRIX 3.3
  17.     Apollo DN10000/Domain OS 10.2.p
  18.  
  19. Dates:
  20.     Submission Received: April 15 1991
  21.     Reviews Returned: April 29 1991
  22.     Revised Submission Received: May 3 1991
  23.     Reviews Returned: May 17 1991
  24.     Revised Submission Received: May 23 1991
  25.     Reviews Returned: June 5 1991
  26.     Revised Submission Received: June 18 1991
  27.     Reviews Returned: July 2 1991
  28.     Revised Submission Received: July 5 1991
  29.     Accepted: July 6 1991
  30.  
  31. Author's Summary:
  32. -----------------
  33.  
  34. This package is cextract, version 1, patchlevel 2.  This is the first
  35. official release and is being distributed through the newsgroup
  36. comp.sources.reviewed.
  37.  
  38. The cextract/cextdoc program is copyright 1991 by Adam Bryant.
  39.  
  40. The code is freely distributable and there are no restrictions other
  41. than the fact that it not be used for monetary gain and that copyright
  42. notices must be kept intact.
  43.  
  44. The program may be used to generate proprietary source code or
  45. documentation, but its own source code may not be used as a part of any
  46. proprietary programs.
  47.  
  48. This package contains a C prototype extractor.  I know what you are
  49. thinking...  "Not another one!".  But, I found a need for one, and more
  50. importantly, a small one that could run on as many systems as possible.
  51.  
  52. Cextract is ideal for generating header files for large multi-file C
  53. programs, and will provide an automated method for generating all of the
  54. prototypes for all of the functions in such a program.
  55.  
  56. Cextract also functions as a rudimentary documentation extractor,
  57. generating a sorted list of all functions and their locations.
  58.  
  59. The main advantages that I find with this program over other prototyping
  60. programs:
  61.  
  62. - smaller.  [You can distribute it with your own packages so that other
  63. programmers can rebuild your header files.]
  64.  
  65. - fully written in C.  [You don't need a lex or yacc compiler to get
  66. this going.]
  67.  
  68. - more portable.  [As far as I know, it only requires that the system
  69. has a C preprocessor for it to work.] I have even provided support for
  70. VMS systems, although I wish the compiler on that system allowed the
  71. comments to be retained.
  72.  
  73. - reads either ANSI or K&R C code and outputs either K&R or ANSI [or
  74. both!] function definitions.
  75.  
  76. - can catch all #define statements within the parameter list and replace
  77. before output, if needed.  [such as "#define FILE struct _iobuf"] This
  78. feature is provided to account for adjustments caused by the C
  79. preprocessor.
  80.  
  81. - automatically catches and replaces FILE and varargs stuff.
  82.  
  83. - has a built in documentation extraction program.
  84.  
  85. Likely disadvantages:
  86.  
  87. - It is not a fully implemented compiler, so it might not complain if it
  88. is reading invalid C code.
  89.  
  90. - Might barf on extremely complex code.
  91.  
  92. - could probably be a little faster.  [any speed up suggestions are
  93. welcome]
  94.  
  95. - with heavily conditional (#ifdef'ed) code, it might not be able to
  96. generate a "generic" header file which would work for all possible code
  97. permutations.
  98.  
  99.  
  100. Reviewers' Comments:
  101. --------------------
  102.  
  103.   I have tested this program on a VAX running BSD 4.3, an IBM RT/PC
  104. running AOS 4.3, a DECstation running Ultrix 3.1, an IBM PS/2 running
  105. AIX 1.2, and a Mac running A/UX.  It compiles and passes its test with
  106. no problems on all of these systems.
  107.  
  108.   The package provides a fast, portable method for extracting function
  109. declarations.  The features that I find most useful include its
  110. ability to surround the declarations with #ifdef directives that
  111. control when they are used (or that prevent reuse), and its ability to
  112. produce both ANSI and non-ANSI declarations and to put in an #ifdef to
  113. cause the ANSI declarations to be used only when appropriate.
  114.  
  115.     ---------------------------------------------------------------
  116. Cextract is a nice tool, that extracts routine headers of a C program
  117. into an .h file.  Both ANSI-C and K&R C are supported.  It has many
  118. extra facilities, but unfortunately most of them require a C
  119. preprocessor which does not strip of comments like VAX-C does.  I
  120. look forward to using it.  cextract was reviewed on VAX/VMS.
  121.  
  122.     ---------------------------------------------------------------
  123.  
  124.     Cextract eases production of interface files by extracting
  125. prototypes in ANSI and non-ANSI styles.  Can extract leading comments as
  126. well, and can generate the skeleton for code documentation.
  127.  
  128.     ---------------------------------------------------------------
  129. `Cextract' is an extremely useful utility for managing software
  130. written in C.  It extracts function headings from source files
  131. and makes prototypes of them, to make a header file suitable for
  132. inclusion by other source files.  The documentation option
  133. produces output suitable for printing.  There are numerous
  134. switches for handling comments, ANSI/non-ANSI declarations,
  135. sorting of the prototypes, and so on.  The `-H' option is
  136. particularly useful in dealing with large software projects.
  137.  
  138. The program was tested on Sun, VAX, and Apollo systems, and
  139. performed as expected.  (A note for Apollo users:  the SYSFLG
  140. option in the Makefile should be set to -DBSD -U__STDC__, because
  141. the Apollo C compiler thinks that it is ANSI C - but we know
  142. better!)
  143.  
  144. I strongly recommend the use of `cextract' for any size of
  145. project!  (I particularly wish to praise the author for his
  146. speedy action in dealing with the reviewers' comments.)
  147.  
  148.  
  149. Author's Comments on the Review Process
  150. ---------------------------------------
  151.  
  152. When I first submitted cextract to comp.sources.reviewed I thought it
  153. was a bit rough, but even so, ready for the net.  I figured that it was
  154. fairly portable and that any rough edges to it or minor bugs could be
  155. ironed out when bug reports and patches started coming in.  Well, the
  156. reviewers saw through my laziness and made sure that I turned in a
  157. finished product.
  158.  
  159. Not only did they discover bugs that hadn't turned up in months of use
  160. by myself and others, they came up with excellent improvement
  161. suggestions that inspired me to redesign much of the code and greatly
  162. improve the overall quality.  Hopefully everyone will be able to
  163. recognize that the review process was able to greatly enhance this
  164. program beyond what even I had imagined it capable of.
  165.  
  166.