1 04/03/84  cross_reference, cref
  2 
  3 Syntax:  cref library_descriptions {-control_args}
  4 
  5 
  6 Function:  creates a cross-reference listing of any number of object
  7 programs.  The listing contains information about each object module
  8 encountered, including the location of each program, its entry points
  9 and definitions, any synonyms, and which other modules encountered
 10 reference each entry point or definition.  It also optionally supplies
 11 a cross-reference listing of include files used by the modules
 12 encountered.
 13 
 14 
 15 Arguments:
 16 library_descriptions
 17    can be chosen from the following:
 18    paths
 19       are the pathnames of segments to be examined and
 20       cross-referenced.  The star convention is allowed.
 21    -library library_name {-all} paths, -lb library_name {-a} paths
 22       specifies that all modules represented by paths are treated by
 23       the cross-referencer as if they were in a common library of that
 24       name.  The library_name argument can be any identifier you
 25       choose.  If -all (-a) is specified, all the module names
 26       encountered are considered external (see "Resolving references.")
 27       This control argument is generally used only for cross-references
 28       of the Multics hardcore libraries.
 29 
 30 
 31 Control arguments:
 32 -brief, -bf
 33    suppresses nonfatal error messages.  It does not affect the
 34    reporting of error messages to the output file.
 35 -first
 36    specifies, with -input_file, that once any instance of a particular
 37    module has been located, the cross-referencer need not search the
 38    remaining directories for other instances of modules with the same
 39    name.  If omitted, the cross-referencer searches all libraries in
 40    the search list for each module name supplied.
 41 -include_files, -icf
 42    cross-references include files used by all modules examined.
 43 
 44 
 45 -input_file path, -if path
 46    uses a control file describing the modules to be cross-referenced
 47    instead of the library descriptions.  If the crl suffix is not part
 48    of the supplied filename, it is assumed.  If -input_file is given,
 49    no library descriptions are allowed.
 50 -line_length N, -ll N
 51    formats lines in the output file to the given line length.  The
 52    default is 132.
 53 
 54 
 55 -output_file path, -of path
 56    creates the cross-reference list in a segment of the specified name.
 57    If the cross-reference suffix is not part of the supplied filename,
 58    it is assumed.  If -output_file is not selected, but -input_file is,
 59    the output file takes its name from the input file, with the suffix
 60    ".crossref" replacing the suffix ".crl"; otherwise, the output file
 61    is named "crossref.crossref".
 62 -short, -sh
 63    does not include in the output referenced modules that are not
 64    included in the scope of any library_descriptions.  With -short, the
 65    output reflects only the interrelationships among the modules in the
 66    libraries specified.
 67 
 68 
 69 Notes on module examination: Module examination is performed in two
 70 passes--the first defines all the segment names, synonyms, and
 71 definitions; the second examines external references and attempts to
 72 resolve them with existing definitions.
 73 
 74 Segments encountered fall into four classes--nonobject, bound
 75 segments, stand-alone modules, and archives.
 76 
 77 When a nonobject segment is encountered, a warning message is printed
 78 and the segment is included in the results of the cross-reference.
 79 
 80 
 81 When a bound segment is found, a warning message is printed and the
 82 segment is ignored.  Bound segments are useless to the
 83 cross-referencer, since information necessary to determine which
 84 components use which external reference links is no longer available
 85 due to the binding process.  Use instead the object archive from which
 86 it was bound.
 87 
 88 When a stand-alone segment is met, it is analyzed for entry points,
 89 definitions, and external references.  All additional names on the
 90 segment are entered as synonyms for the module.  This information is
 91 then included in the results of the cross-reference.
 92 
 93 
 94 When an archive is encountered, each component is analyzed for entry
 95 points, definitions, and external references.  If a bindfile exists,
 96 synonyms for each component are derived from "synonym" statements in
 97 the bindfile, when they exist.  This information is then included in
 98 the results of the cross-reference.
 99 
100 Modules are also identified by the segment in which they are found
101 (either themselves, for a stand-alone segment, or the containing
102 archive, for an archive) and by the library_name of the directory in
103 which they are found.  If the directory is given without a
104 library_name, the pathname of the directory is used as the
105 library_name.  This allows having multiple occurrences of segments with
106 the same name, as long as they differ by at least one of these
107 identification criteria.
108 
109 
110 Notes on resolving references: When a module is examined by the
111 cross-referencer, its name and synonyms are classified as "internal"
112 or "external" by the following criteria--
113    1. If the module is stand alone, its name and synonyms are external.
114    2. If the module is archived and the library description contained
115       -all , its name and all its synonyms are considered external.
116    3. If the module is archived and the library description did not
117       contain -all, its name and each of its synonyms are external only
118       if they appear in the "Addname:" statement of the bindfile.  If
119       no bindfile exists, the name and synonyms are considered
120       internal.
121 
122 
123 The cross-referencer tries to resolve external references on a
124 best-match basis by using the following criteria:
125    1. If the reference can be satisfied by a definition in the same
126       module, that definition is used.
127    2. If the referencing module is part of a bound segment and can be
128       satisfied by a definition in the same bound segment, that
129       definition is used.
130    3. If the reference can be satisfied by an external definition in
131       the same library_name, that definition is used.
132    4. Otherwise, the first external definition found that satisfies the
133       reference is used.  If more than one such definition exists, a
134       warning message is printed.
135 
136 
137 Notes on format of a driving file: If -input_file is given, the
138 cross-referencer takes its input from a special file.
139 
140 The first lines of the file must contain the names of one or more
141 directories to be searched.  They are specified in the following
142 manner:
143       -library:      (OR  -library -all:)
144       pathname_1          library_name_a
145       pathname_2          library_name_b
146          ....                ....
147       pathname_N          library_name_z;
148 
149 
150 Each pathname_i specifies a directory to be searched.  When present, a
151 library name (which can contain spaces) is used to describe the
152 preceding directory name.  (See "Module examination" above.)  The
153 tokens "-wd" or semicolon ends the search list.
154 
155 The next information in the file is a list of the segments to be
156 examined.  They must appear one to a line.
157 
158 If you wish to define explicitly synonyms for any modules that would
159 not otherwise be generated (e.g., a nonapparent reference name by which
160 a segment is sometimes initiated), they can be included in this section
161 with one or more lines of the form
162 
163    modulename syn1 syn2 ... synN
164 
165 
166 These lines do not by themselves cause the cross-referencer to search
167 for the module "modulename", since it may not be a freestanding
168 segment.  Any synonyms defined in this manner are considered external.
169 
170 
171 Notes on special cases: Segments with unique names and with
172 single-digit last components are ignored, since these are conventions
173 used by the system library tools to denote segments to be deleted
174 shortly.
175 
176 Archives whose names are identical with the exception of a different
177 numeric next-to-last component are considered the same archive.
178 
179 Definitions or entry points in archive components that masquerade as
180 segment names by an added name on the bound segment, without being
181 defined as a synonym for their containing component, are not
182 cross-referenced satisfactorily.
183 
184 
185 Notes on include files: The cross-reference listing of include files,
186 when requested, is appended to the regular output of the
187 cross-referencer.  Each include file met is classified by its
188 entryname and its date/time modified.  This ensures that modules that
189 use different versions of the same include file are apparent.