home *** CD-ROM | disk | FTP | other *** search
/ Liren Large Software Subsidy 7 / 07.iso / c / c017 / 34.ddi / CXREF2TC.ZIP / CXREF.DOC < prev    next >
Encoding:
Text File  |  1990-05-15  |  8.1 KB  |  188 lines

  1.           CXREF 2.00TC - (See end of Doc for information)
  2.  
  3.            CXREF - C Program Cross Reference Generator
  4.                   Version: 2.00     June 24, 1986
  5.  
  6.  
  7.     CXREF produces a cross-reference listing for a C program  and 
  8. optional  graphical  representation of the block structure of the 
  9. program.  Occurrences only are listed.  No  distinction  is  made 
  10. between  definitions  and  references.  Version 2.00 of CXREF has 
  11. been converted from Turbo Pascal source  into  C  source.  The  C 
  12. compiler  used  was  Datalight's small model compiler however the 
  13. source appears to be reasonably standard and little effort should 
  14. be required to convert it to any other C.  
  15.  
  16.  
  17. USAGE:
  18.  
  19.     The command line for CXREF has the following format:
  20.  
  21.         CXREF input_file_name [output_file_name] [options]
  22.  
  23.     Both the input_file_name and the output_file_name may be full 
  24. PC/MS-DOS path names.  The output_file_name is  optional.  If  is 
  25. is  not  supplied,  the output file will be created with the same 
  26. name as the input file but  with  an  extension  of  LST.  If  no 
  27. extension  is  specified  for the input file,  an extension of .C 
  28. will be assumed.  If an output file name is specified but without 
  29. an extension, an extension of LST will be assumed.  
  30.  
  31.     The current version of CXREF supports three flag options and 
  32. two options that require an additional parameter.
  33.  
  34.     Flag Options:
  35.  
  36.         -NL  - Suppress  the  graphical  representation  of   the 
  37.                program  and  the  line  numbered  listing  of the 
  38.                program.  
  39.  
  40.         -NS  - Suppress cross-referencing of C keywords.
  41.  
  42.         -NI  - Suppress analysis of #include files.
  43.  
  44.     Value Options:
  45.  
  46.         -I <path>  - Supplies the path for  #include  <file_name> 
  47.                      files.  Must be followed by the pathname.
  48.                      **See note below RB**
  49.  
  50.         -T <n>     - Sets  the  tab stop value for tab expansion.  
  51.                      The default value is 4.  
  52.  
  53.     The  default  condition  is  to  produce  the  line  numbered 
  54. listing,   including  all  #include  files,   showing  the  block 
  55. structure and to cross-reference all symbols.  
  56.  
  57.     If executed with  no  command  line  parameters,  CXREF  will 
  58. display a brief summary of its usage.  
  59.  
  60.  
  61. INCLUDE FILES:
  62.  
  63.     This version of CXREF will process single level include files 
  64. of  either  the  quote  delimited  or the angle bracket ['<','>'] 
  65. forms.  Quote delimited include files are  located  in  the  same 
  66. directory  as  the  input  program  and  angle  bracket delimited 
  67. include   files   are   located   in   a   "system"    directory.  
  68. Unfortunately,  there  is  no  standard  "system" directory under 
  69. PC/MS-DOS and the various C compilers use a number  of  different 
  70. mechanisms  to  provide  a  "system"  directory.  To  handle  the 
  71. different "system" directories, CXREF provides the "-I" option on 
  72. the command line,  allowing the user to provide a  path  for  all 
  73. angle bracket delimited include files.  
  74.  
  75.     CXREF can handle up to 26 include files, distinguished by the 
  76. letters  A  through  Z  following  the  line  numbers in both the 
  77. listing and the cross-reference.  The line numbers shown, both on 
  78. the listing and in the cross-reference,  are  true  line  numbers 
  79. within  the  file  making the cross-reference without the listing 
  80. useful.  
  81.  
  82.  
  83.  
  84. HISTORY OF DEVELOPMENT:
  85.  
  86.     This program has  had  a  long  history.  It  was  originally 
  87. written  for  Pascal  programs  by N.  Wirth using the "quadratic 
  88. quotient" hash method.  It was adapted for UCSD Pascal (1.4 - the 
  89. public  domain  version)  by  Shawn   Fanning   (in   1978)   and 
  90. subsequently  adapted  for  Pascal/MT+  by Mike Lehman (in 1981).  
  91. This version was then modified by Warren A.  Smith to try to  get 
  92. back  to ISO standard Pascal and to add the additional feature of 
  93. mapping out the compound statements.  It was modified  for  Turbo 
  94. Pascal  by  Ron  Finger in July,  1984.  This last version of the 
  95. program, at least, was named XLIST.  
  96.  
  97.     Further modifications were made by Larry Dodson in September, 
  98. 1985.   These  include  the  ability  to  handle  Include  files, 
  99. expansion   of   the   identifier  field  from  eight  to  twelve 
  100. characters,  optional  suppression  of  the  output  of  standard 
  101. identifiers,  a margin on the left of the output to provide space 
  102. to punch holes for a three-ring binder, and a compile time option 
  103. of 66 or 88 lines per page.  In addition,  several comments  were 
  104. added,  blocking  (for  readability)  was improved,  the name was 
  105. changed from XLIST  to  XREF,  and  several  other  less  evident 
  106. corrections  and  modifications were incorporated.  These changes 
  107. were made and tested using Turbo Pascal (Version 2.0 for CP/M 80) 
  108. on a Kaypro II with an Okidata 82 printer.  
  109.  
  110.     NXREF was then produced by  Don  Williams  as  practically  a 
  111. complete  rewrite  of  XREF.  Binary  trees  were  used  for  the 
  112. references rather than the 'quadratic quotient' used by XREF (the 
  113. binary tree routines used,  however,  are simple  adaptations  of 
  114. those  presented  by  N.  Wirth  in  his  excellent  book,  "Data 
  115. Structures + Algorithms = Programs".) The program was modified to 
  116. take advantage of the Turbo Pascal  3.0  Command  Line  parameter 
  117. features.  The  case  structure  of  the  first  occurrence of an 
  118. identifier  was  preserved  (XREF   and   XLIST   converted   all 
  119. identifiers to upper case in the cross-reference.  
  120.  
  121.     Use  of  the  binary  tree  routines  and  dynamic allocation 
  122. allowed the maximum length of an identifier to be increased to 29 
  123. bytes.  In NXREF,  this length  is  determined  by  the  printout 
  124. format rather than the structure that holds the references.  
  125.  
  126.     Upon realizing that a similar facility would be useful for C 
  127. programs, I modified NXREF into CXREF.  Since, from the viewpoint 
  128. of structure and cross-reference, the differences between Pascal 
  129. and C are slight, it was a relatively simple modification.
  130.  
  131.     CXREF200 and beyond have been converted to  C  with  CXREF200 
  132. being  in Datalight C.  Future releases of this program may be in 
  133. some other C source.  
  134.  
  135.  
  136.  
  137.                 CXREF Version 2.00TC  May -1990
  138.  
  139. This version of the CXREF program was witten to compile under the Turbo
  140. C 2.0x compiler.  It has all the same features of the version written
  141. for the Datalight C compiler documented above.  One bug was corrected
  142. involving nested include files and is explained in comments in the
  143. source code included.
  144.  
  145. Since the person who ported this program to Datalight C does not
  146. identify him/her self it is difficult to give credit for the hours of
  147. work that person put into porting CXREF from Turbo Pascal to C.  None
  148. the less the work has been appreciated by many including me.
  149.  
  150. I modified this to compile under Turbo C since I wanted the ability to
  151. send control strings to the printer and change some of the defaults in
  152. the .LST file.  I am NOT distributing that version, but rather the
  153. direct port of the original CXREF modified simply to get it to compile
  154. and run using Turbo C.  My guess is that it should compile under
  155. MicroSoft C as well, but I have not tried.
  156.  
  157. CXREF 2.00TC (for Turbo C) in .EXE format is the LARGE MEMORY MODEL.
  158. The program will compile and work correctly in the SMALL memory model if
  159. the user does not attempt to create .LST files on large source files.
  160. The program does little if any error checking on its cross reference or
  161. file building - so the large memory model assures more reliable
  162. operation on large source files.  All you need to compile the code is:
  163.  
  164.                 tcc -ml cxref.c
  165.  
  166. assuming, of course, that you have the lib/include files specified in
  167. the TCCONFIG.CFG file.  See the source code comments for more
  168. information.
  169.  
  170.  
  171. **NOTE: The "value options" discussed in the original documentation need
  172. to have a space between the parameter and the value, i.e.:
  173.  
  174. -I C:\TC\INCLUDE
  175.  
  176. instead of,
  177.  
  178. -IC:\TC\INCLUDE
  179.  
  180. I thought about changing this, but I decided to do as direct a port as
  181. possible.
  182.  
  183.  
  184. Now it is up to you to modify to your heat's content.
  185.  
  186. Modified May 1990 -- Roland M. Brown III
  187.  
  188.