home *** CD-ROM | disk | FTP | other *** search
/ QBasic & Borland Pascal & C / Delphi5.iso / Pascal / BPASCAL.700 / D12 / TADOC.ZIP / TCREF.TSM < prev   
Encoding:
Text File  |  1992-10-01  |  4.8 KB  |  136 lines
  1.           TCREF: THE SOURCE MODULE CROSS-REFERENCE UTILITY
  2.           ================================================
  3.  
  4. TABLE OF CONTENTS
  5. -----------------
  6. 1. What is TCREF?
  7. 2. How to Use TCREF
  8. 3. Compatibility with TLINK
  9. 4. TCREF Options
  10. 5. TCREF Reports
  11.  
  12.  
  13. 1. WHAT IS TCREF?
  14. -----------------
  15.  
  16.   TCREF is designed to produce two reports: a cross-reference list of where 
  17.   all global symbols are used and defined, and a list of individual modules 
  18.   and the symbols used within them.
  19.  
  20.  
  21. 2. HOW TO USE TCREF
  22. -------------------
  23.  
  24.   TCREF accepts as input a group of .XRF files produced by TASM. These files 
  25.   contain cross-reference information for individual modules. From these input 
  26.   files, a single .REF file is produced that contains one or more reports in 
  27.   ASCII text. The command format follows:
  28.  
  29.     TCREF <XRF files separated by '+' characters> ','
  30.        <REF filename> <switches>
  31.  
  32.   For example, the following would take the FOO1.XRF, FOO2.XRF, and FOO3.XRF 
  33.   as input files and produce FOO.REF:
  34.  
  35.     TCREF foo1+foo2+foo3,foo
  36.  
  37.   Response files
  38.   ---------------
  39.   TCREF also accepts ASCII files as command strings. Simply precede the file 
  40.   name with an @@ sign to include a file in the command string. For example,
  41.  
  42.     TCREF @@dofoo
  43.  
  44.   where DOFOO contains
  45.  
  46.     foo1+foo2+foo3,foo
  47.  
  48.   will do the same thing as the previous example.
  49.  
  50.  
  51. 3. COMPATIBILITY WITH TLINK
  52. ---------------------------
  53.  
  54.   TCREF accepts command strings that TLINK accepts. TCREF ignores any 
  55.   irrelevant switches and fields, such as any libraries or MAP files, or
  56.   switches that pertain only to the linker function. Similarly, if an .XRF 
  57.   file cannot be located, TCREF will simply ignore it.
  58.  
  59.   Beware! When using a TLINK response file, don't explicitly specify file 
  60.   extensions, since doing so will override TCREF's internal defaults and 
  61.   possibly result in disaster. For example, if the response file reads aS
  62.  
  63.     foo1+foo2+foo3,foo.exe
  64.  
  65.   you should not use this file without modification with TCREF because the 
  66.   .REF file it creates will be named FOO.EXE, presumably overwriting your 
  67.   program.
  68.  
  69.  
  70. 4. TCREF OPTIONS
  71. ----------------
  72.  
  73.   TCREF accepts all the switches present in TLINK, but most of them are 
  74.   discarded. TCREF only uses these options:
  75.  
  76.     /c makes GLOBAL report case-sensitive.
  77.  
  78.     /r generates LOCAL reports for all the specified modules.
  79.  
  80.     /p# sets report page length to # lines.
  81.  
  82.     /w# sets report page width to # columns.
  83.  
  84.  
  85. 5. TCREF REPORTS
  86. ----------------
  87.  
  88.   TCREF takes great care to make semantic sense of symbols. Cross-reference
  89.   information is useless when symbols with the same name but different
  90.   meanings are lumped together. TCREF therefore takes into account the
  91.   SCOPE of a symbol when producing its reports. Cross-reference information
  92.   is always listed for the source file and source line number.
  93.  
  94.   Global (or linker-scope) report
  95.   -------------------------------
  96.  
  97.   TCREF's global report lists cross-reference information for global symbols 
  98.   as they appear to the linker. Use the /c switch if you want to produce 
  99.   case-sensitive reports.
  100.  
  101.   In this report, global symbols appear alphabetically in the left column.
  102.   References, organized by source file, are listed in the right column.
  103.   Wherever #'s appear indicates that definition occurs at that line.
  104.  
  105.   Here's an example symbol printout:
  106.  
  107.     Global Symbols       Cref  #  = definition
  108.     BAR                  TEST.ASM:  1  3  6  9  12  15  18 +
  109.                                                 21  23  29
  110.                                           #  TEST2.ASM:  2  4  6  #8
  111.  
  112.   What does this tell you? The leading # sign before the TEST2.ASM indicates 
  113.   that BAR was defined somewhere in that module. For each source file, the 
  114.   source line at which the reference occurred is listed. This list can occupy
  115.   more than one line, as in the case of the lines for TEST.ASM. The + 
  116.   character indicates that wrap has occurred. Finally, the # sign before the 
  117.   8 indicates that a definition of BAR occurred in TEST2.ASM on line 8.
  118.  
  119.   The local (or module-scope) report
  120.   ----------------------------------
  121.  
  122.   If you specify /r on the command line, a local report will be made for
  123.   each module. It will contain all the symbols used in that module, listed 
  124.   in alphabetical order. The /c switch will have no effect on these reports, 
  125.   since the appropriate case-sensitivity has already been determined at 
  126.   assembly time.
  127.  
  128.   Like global reports, references are organized by source file in the right 
  129.   column. A sample printout looks like this:
  130.  
  131.     Module TEST.ASM Symbols        Cref  # = definition
  132.     UGH                            TEST.ASM:  1  3  6  9  12  15  18 +
  133.                                                           21  23  29
  134.                                                    #  UGH.INC:  #2
  135.  
  136.