Y From:	CRDGW2::CRDGW2::MRGATE::"SMTP::PREP.AI.MIT.EDU::INFO-GCC-REQUEST" 19-JUN-1989 22:29  To:	MRGATE::"ARISIA::EVERHART"+ Subj:	PROTOIZE 1.00 - now available for FTP   R Received: by life.ai.mit.edu (4.0/AI-4.10) id AA04472; Mon, 19 Jun 89 19:03:50 EDT# Return-Path: <@mcc.com:rfg@mcc.com> _ Received: from MCC.COM by life.ai.mit.edu (4.0/AI-4.10) id AA04371; Mon, 19 Jun 89 18:57:13 EDT T Received: from pink.aca.mcc.com by MCC.COM with TCP/SMTP; Mon 19 Jun 89 16:54:40-CDT! Date: Mon, 19 Jun 89 16:54:23 CDT ! From: rfg@mcc.com (Ron Guilmette) ( Posted-Date: Mon, 19 Jun 89 16:54:23 CDT1 Message-Id: <8906192154.AA11286@pink.aca.mcc.com> - Received: by pink.aca.mcc.com (3.2/ACAv4.0i)  ( 	id AA11286; Mon, 19 Jun 89 16:54:23 CDT6 To: info-g++@prep.ai.mit.edu, info-gcc@prep.ai.mit.edu. Subject: PROTOIZE 1.00 - now available for FTP    2 PROTOIZE 1.00  --  now available for anonymous FTP  9 Many people have noted the need for tools to automate the 8 conversion of old C code (in non-prototyped form) to new: ANSI C and C++ prototype form.  Well, I noted it too and I! decided to do something about it.   9 I would like to announce the availability of an automated = prototyping assistant tool.  This tool can automate much (but ? definitely not all) of the otherwise tedious work of converting ; a large system of source files to ANSI-C (or C++) prototype > format.  This assistant can convert most of the obvious cases,; leaving you to do only the occasional tricky case manually.   < This prototyping assistant tool comes in two separate parts.= The first part is an tool to gather up prototype information, D and the second part is a tool to automatically edit this informationC into the proper places (i.e. function declarations and definitions) B within a set of existing source files (both base files and include files).   > The information gathering tool is really a modified version of? the GNU Project C compiler (GCC) Version 1.35 (or thereabouts). = This was the most expedient base for an information gatherer, A because it already had a whole (debugged) parser for full ANSI C.   > The other half of the automatic protyping "system" is the tool= that actually munges the prototypes back into the source code ? at the right places.  This is called "protoize".  It is written A in (reasonably portable) C.  It is about as intelligent as it can ? be, given the limitations of its input.  For instance, it knows B the difference between static and extern functions, and about many other subtle points.  @ The current "man page" for protoize is given below.  To read it,: run it through nroff or troff while using the -man option.  E Since the protoize program must be used with GCC, the current version D (1.00) is being distributed as a set of patches against the (virgin)B GCC 1.35 sources.  These patches add several files to the GCC 1.35 sources, specifically:    	protoize.c	the protoize program 	protoize.1	the man page& 	proto-gen.c	new addition to GCC (cc1)' 	std.c		prototypes for system functions   @ You may obtain the current version of protoize via anonymous FTPD from yahi.stanford.edu (36.83.0.92).  The compressed set of GCC 1.35 patches is in:   	~ftp/pub/protoize-1.00.Z   H This software is distributed with the same terms and conditions as otherH GNU software distributed by the Free Software Foundation.  Specifically,G if while using it, your source files vanish (perhaps because you didn't H bother to read the documentation first) and if you were too dumb to haveE regular backups made, you cannot hold me, my employer, FSF, or anyone I else liable for direct, incidental, or consequential damages, or for loss K of revenue, teeth, hair, or other vital or disposable organs or appendages.   @         ****** MAKE BACKUPS ******  **** YOU'VE BEEN WARNED ****  H P.S.  If you like this program, or if you use it for any big conversion,@ I'd like to hear from you.  Drop me a line at the address below.  = // Ron Guilmette  -  MCC  -  Experimental Systems Kit Project H // 3500 West Balcones Center Drive,  Austin, TX  78759  -  (512)338-3740 // ARPA: rfg@mcc.comA // UUCP: {rutgers,uunet,gatech,ames,pyramid}!cs.utexas.edu!pp!rfg     $ man page - "protoize.1"  -  cut hereJ --------------------------------------------------------------------------  .TH PROTOIZE 1 "10 June 1989" "" .SH NAMEL protoize \- convert old style (K&R) C source code to ANSI C prototype format .SH SYNOPSIS .B protoize  [  .B -C  ] [  .B -v  ] [  .B -d  ] [  .B -s<func-name>	 \&... ] [  .I prototypes-file \&... ]  .SH DESCRIPTION  .I Protoize  aids in the conversion of 0 old style (K&R) C source code files to new style2 C source code files with ANSI function prototypes.5 This conversion is useful for eliciting more complete / interface checking from ANSI C compilers, or as : a preliminary step in the conversion of C programs to C++. .PP  .I Protoize % is designed to be used in conjunction + with some C compiler which does preliminary  .I "information gathering"8 of prototype information from the files to be converted.: Currently, only the GNU C compiler is capable of producing the information need by  .I protoize   in a form which is acceptable to .I protoize. .PP  .I Protoize 7 actually has two primary functions.  First, It converts : existing (old style) function declarations and definitions8 to prototype form.  Second, for cases in which functions) are called before they have been declared  (i.e. points of  .I implicit  function declarations),  .I protoize 1 inserts new prototype style function declarations  into the source code. 2 For each case of an implicit function declaration, .I protoize / inserts the new (explicit) function declaration 1 at the very beginning of the block which contains  the implicit declaration. 3 The insertion of these additional explicit function  declarations assures that  .B all: function calls in the source code being converted will be 0 checked for correctness (by an ANSI C compiler). .PP  .I Protoize 4 supports the conversion of whole systems of C source& code to function prototype form.  Such .I "en-mass conversions"& may be performed in a batch mode, with .I protoize ' converting an entire system in one run.  .I Protoize : is able to convert entire systems of C source code becauseD it knows how to use information (gleaned by the C compiler) from one! source file to add prototypes for ( function definitions and declarations in other source files.  .PP * Each conversion of a system of source code2 to prototype format consists of two parts.  First, you must do  .I "information gathering"; by recompiling all of the source files that make up a given 6 executable program.  These recompilations must be done- with the GNU C compiler, and you must use the  .B -fgen-prototypes & option for each of these compilations. .PP 6 As you perform individual compilation steps (using the .B -fgen-prototypes  option)  you may notice that  a side-effect of+ these compilations is to leave files with a  .B .p . suffix in the same directory with the original .I base 
 source files.  During compilation with  .B -fgen-prototypes, one such .B .p  file is created for  each .I base * source file compiled.  These files contain" function prototype information and1 additional coded information which can be used by  .I protoize  to convert your source code  to function prototype format.  .PP  After all of the .B .p ! files corresponding to all of the  .B .c  files for the source code  have been created,8 you may perform the actual prototype conversion step for* the entire source code system by using the .I protoize  program.8 To perform the actual conversion step, you simply invoke .I protoize  and supply it with the list of .B .p % files for the system to be converted. 0 Usually, this list can be automatically expanded2 by your shell, and you may simply use the notation .B *.p as the command line argument to  .I protoize. .PP  Execution of the .I protoize 9 program causes your original source files to be converted : so that they contain ANSI C style function prototypes both7 for function declarations and for function definitions.G2 After the conversion of your system, you should be; left with a set of equivalent (but prototyped) source files + with the same names as your original files. 2 Before it writes each converted file back to disk, .I protoizeJ7 deletes the original file and creates a new output file 8 with the same name.  This insures that any copies of theA input files which are really just hard links to the same original.4 files will not be altered by the conversion process. .PPa .B WARNING.u9 It is strongly recommended that you make backup copies oft" all files that may be converted by .I protoize  (including both8 .I basea	 files and 
 .I include files) before you execute the .I protoize8 program. It is also recommended that you+ .B never runu .I protoizee when logged in as user .B root.4 Doing this may cause your system include files to be undesirably scrambled. .PP 4 After conversion of your entire set of source files,4 it is recommended that you check the changes made by .I protoize.2 There are two ways to do this.  First, you can run
 .I diff(1)5 and look at the differences between the converted andeE unconverted (backup) versions of each of your source files (includingo then
 .I include files).  Second,A it is recommended that you fully recompile and re-link all of they converted programs& (using some ANSI compatible C compiler= such as the GNU C compiler) immediately following conversion. " This will quickly alert you to any$ anomalies in the conversion process. .SH OPTIONS  .I Protoizes! recognizes the following options:n .TP  .BI \-s<func-name> Suppress option.) This option gives the user the ability tol force  .I protoizeiG to ignore a given function (or several functions) during the conversion  process.= When this option is used, no prototyping (for either function)F definitions or declarations) will take place for the function named by .B <func-name>.oB This option is useful for avoiding conversion of certain functionsA which use old fashioned mechanisms to accept a variable number ofw+ arguments.  Such functions are often calledh
 .I varargs: functions.  It is generally inappropriate to convert these
 .I varargs0 functions to prototype form via automated means.* Rather, you should convert these functions
 .I by hand0 (and possibly convert them to use the new ANSI C	 .I stdargi conventions at the same time). Note that you may invoke .I protoize  with as many .B \-s= options as you like, thereby suppressing the conversion of asi$ many different function as you like. .TP  .BI \-Cb C++ conversion mode.	 Normally,h .I protoizefC writes its (converted) output files back to files of the same namesuF as the original (unconverted) input files (but only after deleting the original input files).5 In C++ conversion mode, the same things happen exceptf' that after each output file is written,l5 a check is made to see if the given output file has a  .B .ceC suffix.  If it does, then the given file is renamed, and its suffixe
 is changed to  .B .C. This makes the output fileA acceptable as a C++ input file for either the GNU C++ compiler or  for the AT&T Cfront translator.a .TP  .BI \-v # Verbose mode.  For each output filefC created, print the file's name and, as the conversion for that file @ proceeds, print out the (original file) line number at which the current item conversion is! taking place.  These messages aree
 printed on
 .I stderr. This option is useful if .I protoizeuM gets confused by your source code for any reason (which happens only rarely).FB In such cases, using this option can help you find the approximate* source line for the offending source code. .TPo .BI \-diF Debug mode.  This option is to be used only by those doing maintenance on the .I protoizeEF program itself.  It causes additional messages concerning the internal state of .I protoize  to be written to
 .I stderr. .SH EXAMPLES Assume that you have a directory with- all of the files for your system in it.  Also3' assume that your system consists of twoT- executable programs, one built from the filesm .B s1.c, s2.c, andu .B s3.c," and the other built from the files .B s4.c  and- .B s5.c.G Finally, assume that these source files share some include files called- .B s1.h- and- .B s2.hR in the same directory. .PPS; In order to properly convert such a system of programs, youAJ would need to perform the following steps in exactly the order shown below& (after making backup files of course). .sp 1 	 .in +0.5io .ft Bi* gcc -fgen-protoize -o prog1 s1.c s2.c s3.c .brs% gcc -fgen-protoize -o prog2 s4.c s5.c  .brr protoize *.p .brw rm *.p .sp 1e .ft Ri	 .in -0.5iS .PPc- In the example above, the first invocation of  .I gcc causes three .B .pe files to be created. These are called .B s1.c.p, s2.c.p, andi
 .B s3.c.p.+ These files contain prototyping information  .I bothg for their correspondingt .B .ci/ files and for any and all related include filesn which are used by thesep .I basei .B .ci files. .PPi7 After the compilation of all of the files which make upi	 .I prog1,f0 you would compile all of the files which make up .I prog21 in a similar fashion (i.e. remembering to use theo .B -fgen-prototypest option again). This step would create two morei .B .p  files called	 .B s4.c.po andd
 .B s5.c.p. .PPp# Finally, after all of the necessaryw .B .pn/ files have been generated, you would invoke the  .I protoizes, program, and give it the names of all of the .B .po files needed for conversion. .I Protoized< will then proceed to read in all of the information from the .B .pn4 files and then convert all of the source files (both .I basen	 files andr
 .I include( files) which form a part of your system. .PP  Note that the only
 .I include files which are converted arex3 ones for which the current user has write access to # the containing directory.  Thus, non .I "system include" B files are ever converted (unless the user also has write access to$ the directories which contain them). .PPo9 After the protoization of your entire source code system,m- you will probably want to delete all leftovero .B .ph
 files via the  .I rm(1) command.9 In the example above, this is accomplished simply via ther .I "rm *.p"C command./ This completes the entire protoization process.n .SH CAVEATSo Ther .I protoizeo2 program doesn't just get information from your own .I \.p files.  Every time .I protoizes( executes, it also reads the file std.c.p) from some standard installation directory E (if it exists) to obtain a pre-written set of function prototypes foriM various standard system-supplied functions.  These prototypes are effectivelyr% added to the set of prototypes which U .I protoizea@ can use to perform prototype substitutions on your source files.C For this reason, if the source code for your own system of programsu% contains its own function definitions H for functions with the same names as standard system-supplied functions, .I protoize @ will issue warning messages about multiple function definitions.F In such cases, it is suggested that you universally change the name of .I your 9 function(s) to prevent any further conflicts or confusion  with system-supplied functions.o .PPe Normally, the information whichd .I protoizew# uses to perform its work comes fromo the GNU C compiler via the .B -fgen-prototypes = option.  When this option is used, full ANSI-C style functionoB prototypes are generated, but all type specifications within theseC prototypes (for both parameter types and function return types) aree .I "full expanded,"y4 that is to say that symbolic type names, created via
 .B typedef statements are .B not: used in the prototypes which GCC emits by default when the .B -fgen-prototypes  option is used.s .PP,@ If you wish to create more readable (but still fully prototyped) programs, you should use the .B -fproto-typedefsl option in addition to thez .B -fgen-prototypesf: option when you initially compile your programs (with GCC)' in preparation for protoization.  UsingA .B -fproto-typedefsp/ causes GCC to write function prototypes to your  .B .pn/ files such that symbolic type names declared ine
 .B typedef/ statements are used (where possible) to specifye9 formal parameter types and return types for all function.s .PPe If you decide to use the .B -fproto-typedefs, option, you should be awarerB that this option can have undesirable side effects.  Specifically,$ it may force you to move around your
 .B typedefL statements in the converted code (before you can successfully recompile it).I If you simply want to do temporary testing of your code (with prototypes)t! it is strongly suggested that you  .B not use the  .B -fproto-typedefso= option to GCC when compiling in preparation for protoization.) .PPo/ Note also that even when you request the use of 
 .B typedef names in your prototypes (via  .B -fproto-typedefsg ) " you will not always get all of the
 .B typedef+ names that you might expect.  Specifically,b
 .B typedef' names which are defined in terms of theu .B const and/or .B volatileh type modifiers3 may sometimes cause trouble.  This is due partly to 8 the complicated semantics of these modifiers, and partly2 to limitation of GCC's handling of them.  Problems0 with these modifiers should be rare in practice. .PPn( As noted above in the description of the .B -so option, so-calledl
 .I varargs? function do not map well to prototyped form.  Usually, the bestm
 way to handlel
 .I varargs functions will be to. suppress the conversion of these functions via thel .B -s  (suppress) option. .PPc
 If you use .I protoizeP% to convert a system which consists ofl> multiple programs, and if these programs share some non-system" include files, conflicts may arise when .I protoizeoF attempts to convert function declarations in the common include files. .PPo* For instance, in the example above, if the .B .ci	 files forh	 .I prog1,) and the  .B .cd file for .I prog2+ both contained function definitions for then function named
 .I foobar, and if there is a function .I declaration for the function	 .I foobare within one of the common
 .I include files which are shared between .I prog1 andh	 .I prog2,s then .I protoize B cannot know which of the two parameter lists from the two function .I definitions should be used to convert the  .I declaration of f	 .I foobarI
 in the commonp
 .I include file.m7 If the two formal parameter lists for the two differentm function .I definitions in the two programs 6 both have exactly the same number, order, and types of4 parameters, then it does not matter which of the two formal parameter lists .I protoizeo( chooses to perform the conversion of the .I declaration of	 .I foobari in the include file.= If, however, these two parameter lists differ (even slightly)o) then there is an irreconcilable conflict.s In such cases, the .I protoizeaF program issues a warning, picks one formal parameter list arbitrarily,H performs the conversion, and moves on.  The user is advised to heed such4 warnings, and (if possible) to rename one of the two conflicting functions in oneI of the two programs (so that conflicts will not arise) and to begin again+  on the whole conversion process. .PPn; Finally, note that it is naive to assume that conversion tof; prototype format will make old style C code into legitimateh: ANSI C code (or legitimate C++ code for that matter).  The3 automatic protoization of your source files via thea .I protoizes3 program is only one step (albeit a big one) towardse4 full conversion.  A full conversion may also require lots of editing "by hand". .SH WARNINGS> There are several possible warning and/or error messages which .I protoizer9 will issue for strange circumstances (e. g. missing inputu0 files, etc).  These are mostly self-explanatory. .PPm	 Note that  .I protoizeo- will refuse to convert anything if any of thee inputc .B .pn9 files are older that any of the files it thinks should beI* considered for conversion (i.e. all of the .I baset andi
 .I include> files which were used to build the program(s) being converted. This insures that allt .B .po. prototype files used to guide the operation of .I protoize.= are up-to-date (relative to the input files being converted).. If .I protoize - complains about the last modification time ofs .B .p-N files (or the files to be converted) this indicates that you need to recompileF some or all of the files for the program(s) being converted (using the .B -fgen-prototypest+ option), and thereby insure that all of thel	 necessarye .B .p  files are up-to-date. 	 .SH FILESr .ta 2.0i! /usr/local/bin/gcc	GNU C compilere .brt, /usr/local/bin/protoize	the protoize program .br 6 /usr/local/lib/std.c.p	standard system prototypes file .SH "SEE ALSO" gcc(1), g++(1) .SH BUGS There are many cases in whichb .I protoizeh can be hopelessly confused by. source code which hash6 comments, preprocessor commands, or macro-calls in the. vicinity of something which it has to convert.- Fortunately, these cases seem to be very raredO in practice.  All of the source files for GCC itself (with the exception of thei .I hard-params.c file) have been successfully, protoized without any special modifications. Keep in mind that( .I protoizei9 knows nothing about preprocessor commands or macro-calls,s0 and it knows very little about C style comments. .PP.0 Because the information written to the prototype5 files by GCC is derived from the original source codeu .I afterC it has been preprocessed, there are certain problems resulting from D the uses of macro-calls in function definitions and/or declarations.& These problems are a permanent part of .I protoizei+ and there is no use complaining about them.( .PP E Bugs (and requests for reasonable enhancements) should be reported toe> rfg@mcc.com.  Bugs may actually be fixed if they can be easily4 reproduced, so it is in your interest to report them( in such a way that reproduction is easy. .SH COPYINGt1 Copyright (c) 1989 Free Software Foundation, Inc.u .brl? Permission is granted to make and distribute verbatim copies ofoD this manual provided the copyright notice and this permission notice are preserved on all copies. .breF Permission is granted to copy and distribute modified versions of thisC manual under the conditions for verbatim copying, provided that thelA entire resulting derived work is distributed under the terms of ao( permission notice identical to this one. .br A Permission is granted to copy and distribute translations of thissE manual into another language, under the above conditions for modifiedi? versions, except that this permission notice may be included inoC translations approved by the Free Software Foundation instead of in  the original English.t .SH AUTHORStH Written by Ron Guilmette at the Microelectronics and Computer Technology Corporation. (rfg@mcc.com) .sp 1o5 See the GNU CC Manual for the contributors to GNU CC. 