| blob | 5c7a08696d68e022805547f8e4431bcf1f0e70e1 |
1 ------------------------------------------------------------------------------
2 -- --
3 -- GNAT COMPILER COMPONENTS --
4 -- --
5 -- L I B . X R E F --
6 -- --
7 -- S p e c --
8 -- --
9 -- Copyright (C) 1998-2018, Free Software Foundation, Inc. --
10 -- --
11 -- GNAT is free software; you can redistribute it and/or modify it under --
12 -- terms of the GNU General Public License as published by the Free Soft- --
13 -- ware Foundation; either version 3, or (at your option) any later ver- --
14 -- sion. GNAT is distributed in the hope that it will be useful, but WITH- --
15 -- OUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY --
16 -- or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License --
17 -- for more details. You should have received a copy of the GNU General --
18 -- Public License distributed with GNAT; see file COPYING3. If not, go to --
19 -- http://www.gnu.org/licenses for a complete copy of the license. --
20 -- --
21 -- GNAT was originally developed by the GNAT team at New York University. --
22 -- Extensive contributions were provided by Ada Core Technologies Inc. --
23 -- --
24 ------------------------------------------------------------------------------
26 -- This package contains for collecting and outputting cross-reference
27 -- information.
34 -------------------------------------------------------
35 -- Format of Cross-Reference Information in ALI File --
36 -------------------------------------------------------
38 -- Cross-reference sections follow the dependency section (D lines) in
39 -- an ALI file, so that they need not be read by gnatbind, gnatmake etc.
41 -- A cross reference section has a header of the form
43 -- X dependency-number filename
45 -- This header precedes xref information (entities/references from
46 -- the unit), identified by dependency number and file name. The
47 -- dependency number is the index into the generated D lines and
48 -- is ones origin (e.g. 2 = reference to second generated D line).
50 -- Note that the filename here will reflect the original name if
51 -- a Source_Reference pragma was encountered (since all line number
52 -- references will be with respect to the original file).
54 -- The lines following the header look like
56 -- line type col level entity renameref instref typeref overref ref ref
58 -- line is the line number of the referenced entity. The name of
59 -- the entity starts in column col. Columns are numbered from one,
60 -- and if horizontal tab characters are present, the column number
61 -- is computed assuming standard 1,9,17,.. tab stops. For example,
62 -- if the entity is the first token on the line, and is preceded
63 -- by space-HT-space, then the column would be column 10.
65 -- type is a single letter identifying the type of the entity. See
66 -- next section (Cross-Reference Entity Identifiers) for a full list
67 -- of the characters used).
69 -- col is the column number of the referenced entity
71 -- level is a single character that separates the col and entity
72 -- fields. It is an asterisk (*) for a top level library entity that
73 -- is publicly visible, as well for an entity declared in the visible
74 -- part of a generic package, the plus sign (+) for a C/C++ static
75 -- entity, and space otherwise.
77 -- entity is the name of the referenced entity, with casing in
78 -- the canonical casing for the source file where it is defined.
80 -- renameref provides information on renaming. If the entity is
81 -- a package, object or overloadable entity which is declared by
82 -- a renaming declaration, and the renaming refers to an entity
83 -- with a simple identifier or expanded name, then renameref has
84 -- the form:
86 -- =line:col
88 -- Here line:col give the reference to the identifier that appears
89 -- in the renaming declaration. Note that we never need a file entry,
90 -- since this identifier is always in the current file in which the
91 -- entity is declared. Currently, renameref appears only for the
92 -- simple renaming case. If the renaming reference is a complex
93 -- expressions, then renameref is omitted. Here line/col give
94 -- line/column as defined above.
96 -- instref is only present for package and subprogram instances. The
97 -- information in instref is the location of the point of declaration
98 -- of the generic parent unit. This part has the form:
100 -- [file|line]
102 -- without column information, on the reasonable assumption that
103 -- there is only one unit per line (the same assumption is made in
104 -- references to entities declared within instances, see below).
106 -- typeref is the reference for a related type. This part is
107 -- optional. It is present for the following cases:
109 -- derived types (points to the parent type) LR=<>
110 -- access types (points to designated type) LR=()
111 -- array types (points to component type) LR=()
112 -- subtypes (points to ancestor type) LR={}
113 -- functions (points to result type) LR={}
114 -- enumeration literals (points to enum type) LR={}
115 -- objects and components (points to type) LR={}
117 -- For a type that implements multiple interfaces, there is an
118 -- entry of the form LR=<> for each of the interfaces appearing
119 -- in the type declaration. In the data structures of ali.ads,
120 -- the type that the entity extends (or the first interface if
121 -- there is no such type) is stored in Xref_Entity_Record.Tref*,
122 -- additional interfaces are stored in the list of references
123 -- with a special type of Interface_Reference.
125 -- For an array type, there is an entry of the form LR=<> for each
126 -- of the index types appearing in the type declaration. The index
127 -- types follow the entry for the component type. In the data
128 -- structures of ali.ads, however, the list of index types are
129 -- output in the list of references with a special Rtype set to
130 -- Array_Index_Reference.
132 -- In the above list LR shows the brackets used in the output which
133 -- has one of the two following forms:
135 -- L file | line type col R user entity
136 -- L name-in-lower-case R standard entity
138 -- For the form for a user entity, file is the dependency number
139 -- of the file containing the declaration of the related type.
140 -- This number and the following vertical bar are omitted if the
141 -- relevant type is defined in the same file as the current entity.
142 -- The line, type, col are defined as previously described, and
143 -- specify the location of the relevant type declaration in the
144 -- referenced file. For the standard entity form, the name between
145 -- the brackets is the normal name of the entity in lower case.
147 -- overref is present for overriding operations (procedures and
148 -- functions), and provides information on the operation that it
149 -- overrides. This information has the format:
151 -- '<' file | line 'o' col '>'
153 -- file is the dependency number of the file containing the
154 -- declaration of the overridden operation. It and the following
155 -- vertical bar are omitted if the file is the same as that of
156 -- the overriding operation.
158 -- There may be zero or more ref entries on each line
160 -- file | line type col [...]
162 -- file is the dependency number of the file with the reference.
163 -- It and the following vertical bar are omitted if the file is
164 -- the same as the previous ref, and the refs for the current
165 -- file are first (and do not need a bar).
167 -- line is the line number of the reference
169 -- col is the column number of the reference, as defined above
171 -- type is one of
172 -- b = body entity
173 -- c = completion of private or incomplete type
174 -- d = discriminant of type
175 -- D = object definition
176 -- e = end of spec
177 -- E = first private entity
178 -- H = abstract type
179 -- i = implicit reference
180 -- k = implicit reference to parent unit in child unit
181 -- l = label on END line
182 -- m = modification
183 -- o = own variable reference (SPARK only)
184 -- p = primitive operation
185 -- P = overriding primitive operation
186 -- r = reference
187 -- R = subprogram reference in dispatching call
188 -- s = subprogram reference in a static call
189 -- t = end of body
190 -- w = WITH line
191 -- x = type extension
192 -- z = generic formal parameter
193 -- > = subprogram IN parameter
194 -- = = subprogram IN OUT parameter
195 -- < = subprogram OUT parameter
196 -- ^ = subprogram ACCESS parameter
198 -- b is used for spec entities that are repeated in a body,
199 -- including the unit (subprogram, package, task, protected body,
200 -- protected entry) name itself, and in the case of a subprogram,
201 -- the formals. This letter is also used for the occurrence of
202 -- entry names in accept statements. Such entities are not
203 -- considered to be definitions for cross-referencing purposes,
204 -- but rather are considered to be references to the corresponding
205 -- spec entities, marked with this special type.
207 -- c is similar to b but is used to mark the completion of a
208 -- private or incomplete type. As with b, the completion is not
209 -- regarded as a separate definition, but rather a reference to
210 -- the initial declaration, marked with this special type.
212 -- d is used to identify a discriminant of a type. If this is
213 -- an incomplete or private type with discriminants, the entry
214 -- denotes the occurrence of the discriminant in the partial view
215 -- which is also the point of definition of the discriminant. The
216 -- occurrence of the same discriminant in the full view is a
217 -- regular reference to it.
219 -- e is used to identify the end of a construct in the following
220 -- cases:
222 -- Block Statement end [block_IDENTIFIER];
223 -- Loop Statement end loop [loop_IDENTIFIER];
224 -- Package Specification end [[PARENT_UNIT_NAME .] IDENTIFIER];
225 -- Task Definition end [task_IDENTIFIER];
226 -- Protected Definition end [protected_IDENTIFIER];
227 -- Record Definition end record;
228 -- Enumeration Definition );
230 -- Note that 'e' entries are special in that they appear even
231 -- in referencing units (normally xref entries appear only for
232 -- references in the extended main source unit (see Lib) to which
233 -- the ali applies. But 'e' entries are really structural and
234 -- simply indicate where packages end. This information can be
235 -- used to reconstruct scope information for any entities
236 -- referenced from within the package. The line/column values
237 -- for these entries point to the semicolon ending the construct.
239 -- i is used to identify a reference to the entity in a generic
240 -- actual or in a default in a call. The node that denotes the
241 -- entity does not come from source, but it has the Sloc of the
242 -- source node that generates the implicit reference, and it is
243 -- useful to record this one.
245 -- k is another non-standard reference type, used to record a
246 -- reference from a child unit to its parent. For various cross-
247 -- referencing tools, we need a pointer from the xref entries for
248 -- the child to the parent. This is the opposite way round from
249 -- normal xref entries, since the reference is *from* the child
250 -- unit *to* the parent unit, yet appears in the xref entries for
251 -- the child. Consider this example:
252 --
253 -- package q is
254 -- end;
255 -- package q.r is
256 -- end q.r;
257 --
258 -- The ali file for q-r.ads has these entries
259 --
260 -- D q.ads
261 -- D q-r.ads
262 -- D system.ads
263 -- X 1 q.ads
264 -- 1K9*q 2e4 2|1r9 2r5
265 -- X 2 q-r.ads
266 -- 1K11*r 1|1k9 2|2l7 2e8
267 --
268 -- Here the 2|1r9 entry appearing in the section for the parent
269 -- is the normal reference from the child to the parent. The 1k9
270 -- entry in the section for the child duplicates this information
271 -- but appears in the child rather than the parent.
273 -- l is used to identify the occurrence in the source of the name
274 -- on an end line. This is just a syntactic reference which can be
275 -- ignored for semantic purposes (e.g. a call graph construction).
276 -- Again, in the case of an accept there can be multiple l lines.
278 -- o is used for variables referenced from a SPARK 'own'
279 -- definition. In the SPARK language, it is allowed to use a
280 -- variable before its actual declaration.
282 -- p is used to mark a primitive operation of the given entity.
283 -- For example, if we have a type Tx, and a primitive operation
284 -- Pq of this type, then an entry in the list of references to
285 -- Tx will point to the declaration of Pq. Note that this entry
286 -- type is unusual because it an implicit rather than explicit,
287 -- and the name of the reference does not match the name of the
288 -- entity for which a reference is generated. These entries are
289 -- generated only for entities declared in the extended main
290 -- source unit (main unit itself, its separate spec (if any).
291 -- and all subunits (considered recursively).
293 -- If the primitive operation overrides an inherited primitive
294 -- operation of the parent type, the letter 'P' is used in the
295 -- corresponding entry.
297 -- R is used to mark a dispatching call. The reference is to
298 -- the specification of the primitive operation of the root
299 -- type when the call has a controlling argument in its class.
301 -- s is used to mark a static subprogram call. The reference is
302 -- to the specification of the subprogram being called.
304 -- t is similar to e. It identifies the end of a corresponding
305 -- body (such a reference always links up with a b reference)
307 -- Subprogram Body end [DESIGNATOR];
308 -- Package Body end [[PARENT_UNIT_NAME .] IDENTIFIER];
309 -- Task Body end [task_IDENTIFIER];
310 -- Entry Body end [entry_IDENTIFIER];
311 -- Protected Body end [protected_IDENTIFIER]
312 -- Accept Statement end [entry_IDENTIFIER]];
314 -- Note that in the case of accept statements, there can
315 -- be multiple b and t entries for the same entity.
317 -- x is used to identify the reference as the entity from which a
318 -- tagged type is extended. This allows immediate access to the
319 -- parent of a tagged type.
321 -- z is used on the cross-reference line for a generic unit,
322 -- to mark the definition of a generic formal of the unit. This
323 -- entry type is similar to 'k' and 'p' in that it is an implicit
324 -- reference for an entity with a different name.
326 -- The characters >, <. =, and ^ are used on the cross-reference
327 -- line for a subprogram, to denote formal parameters and their
328 -- modes. As with the 'z' and 'p' entries, each such entry is
329 -- an implicit reference to an entity with a different name.
331 -- [..] is used for generic instantiation references. These
332 -- references are present only if the entity in question is
333 -- a generic entity, and in that case the [..] contains the
334 -- reference for the instantiation. In the case of nested
335 -- instantiations, this can be nested [...[...[...]]] etc. The
336 -- reference is of the form [file|line] no column is present since
337 -- it is assumed that only one instantiation appears on a single
338 -- source line. Note that the appearance of file numbers in such
339 -- references follows the normal rules (present only if needed,
340 -- and resets the current file for subsequent references).
342 -- Examples:
344 -- 44B5*Flag_Type{boolean} 5r23 6m45 3|9r35 11r56
346 -- This line gives references for the publicly visible Boolean
347 -- type Flag_Type declared on line 44, column 5. There are four
348 -- references
350 -- a reference on line 5, column 23 of the current file
352 -- a modification on line 6, column 45 of the current file
354 -- a reference on line 9, column 35 of unit number 3
356 -- a reference on line 11, column 56 of unit number 3
358 -- 2U13 p3=2:35 5b13 8r4 12r13 12t15
360 -- This line gives references for the non-publicly visible
361 -- procedure p3 declared on line 2, column 13. This procedure
362 -- renames the procedure whose identifier reference is at
363 -- line 2 column 35. There are four references:
365 -- the corresponding body entity at line 5, column 13,
366 -- of the current file.
368 -- a reference (e.g. a call) at line 8 column 4 of the
369 -- current file.
371 -- the END line of the body has an explicit reference to
372 -- the name of the procedure at line 12, column 13.
374 -- the body ends at line 12, column 15, just past this label
376 -- 16I9*My_Type<2|4I9> 18r8
378 -- This line gives references for the publicly visible Integer
379 -- derived type My_Type declared on line 16, column 9. It also
380 -- gives references to the parent type declared in the unit
381 -- number 2 on line 4, column 9. There is one reference:
383 -- a reference (e.g. a variable declaration) at line 18 column
384 -- 4 of the current file.
386 -- 10I3*Genv{integer} 3|4I10[6|12]
388 -- This line gives a reference for the entity Genv in a generic
389 -- package. The reference in file 3, line 4, col 10, refers to an
390 -- instance of the generic where the instantiation can be found in
391 -- file 6 at line 12.
393 -- Continuation lines are used if the reference list gets too long,
394 -- a continuation line starts with a period, and then has references
395 -- continuing from the previous line. The references are sorted first
396 -- by unit, then by position in the source.
398 -- Note on handling of generic entities. The cross-reference is oriented
399 -- towards source references, so the entities in a generic instantiation
400 -- are not considered distinct from the entities in the template. All
401 -- definitions and references from generic instantiations are suppressed,
402 -- since they will be generated from the template. Any references to
403 -- entities in a generic instantiation from outside the instantiation
404 -- are considered to be references to the original template entity.
406 ----------------------------------------
407 -- Cross-Reference Entity Identifiers --
408 ----------------------------------------
410 -- In the cross-reference section of the ali file, entity types are
411 -- identified by a single letter, indicating the entity type. The following
412 -- table indicates the letter. A space for an entry is used for entities
413 -- that do not appear in the cross-reference table.
415 -- For objects, the character * appears in this table. In the xref listing,
416 -- this character is replaced by the lower case letter that corresponds to
417 -- the type of the object. For example, if a variable is of a Float type,
418 -- then, since the type is represented by an upper case F, the object would
419 -- be represented by a lower case f.
421 -- A special exception is the case of booleans, whose entities are normal
422 -- E_Enumeration_Type or E_Enumeration_Subtype entities, but which appear
423 -- as B/b in the xref lines, rather than E/e.
425 -- For private types, the character + appears in the table. In this case
426 -- the kind of the underlying type is used, if available, to determine the
427 -- character to use in the xref listing. The listing will still include a
428 -- '+' for a generic private type, for example, but will retain the '*' for
429 -- an object or formal parameter of such a type.
431 -- For subprograms, the characters 'U' and 'V' appear in the table,
432 -- indicating procedures and functions. If the operation is abstract,
433 -- these letters are replaced in the xref by 'x' and 'y' respectively.
510 -- The following entities are not ones to which we gather the cross-
511 -- references, since it does not make sense to do so (e.g. references
512 -- to a package are to the spec, not the body). Indeed the occurrence of
513 -- the body entity is considered to be a reference to the spec entity.
521 -- The following table is for information purposes. It shows the use of
522 -- each character appearing as an entity type.
524 -- letter lower case usage UPPER CASE USAGE
526 -- a array object (except string) array type (except string)
527 -- b Boolean object Boolean type
528 -- c class-wide object class-wide type
529 -- d decimal fixed-point object decimal fixed-point type
530 -- e non-Boolean enumeration object non_Boolean enumeration type
531 -- f floating-point object floating-point type
532 -- g C/C++ macro C/C++ fun-like macro
533 -- h Interface (Ada 2005) Abstract type
534 -- i signed integer object signed integer type
535 -- j C++ class object C++ class
536 -- k generic package package
537 -- l label on loop label on statement
538 -- m modular integer object modular integer type
539 -- n enumeration literal named number
540 -- o ordinary fixed-point object ordinary fixed-point type
541 -- p access object access type
542 -- q label on block C/C++ include file
543 -- r record object record type
544 -- s string object string type
545 -- t task object task type
546 -- u generic procedure procedure
547 -- v generic function or operator function or operator
548 -- w protected object protected type
549 -- x abstract procedure exception
550 -- y abstract function entry or entry family
551 -- z generic formal parameter (unused)
553 ---------------------------------------------------
554 -- Handling of Imported and Exported Subprograms --
555 ---------------------------------------------------
557 -- If a pragma Import or Interface applies to a subprogram, the pragma is
558 -- the completion of the subprogram. This is noted in the ALI file by
559 -- making the occurrence of the subprogram in the pragma into a body
560 -- reference ('b') and by including the external name of the subprogram and
561 -- its language, bracketed by '<' and '>' in that reference. For example:
563 -- 3U13*imported_proc 4b<c,there>21
565 -- indicates that procedure imported_proc, declared at line 3, has a pragma
566 -- Import at line 4, that its body is in C, and that the link name as given
567 -- in the pragma is "there".
569 -- If a pragma Export applies to a subprogram exported to a foreign
570 -- language (ie. the pragma has convention different from Ada), then the
571 -- pragma is annotated in the ALI file by making the occurrence of the
572 -- subprogram in the pragma into an implicit reference ('i') and by
573 -- including the external name of the subprogram and its language,
574 -- bracketed by '<' and '>' in that reference. For example:
576 -- 3U13*exported_proc 4i<c,here>21
578 -- indicates that procedure exported_proc, declared at line 3, has a pragma
579 -- Export at line 4, that its body is exported to C, and that the link name
580 -- as given in the pragma is "here".
582 -------------------------
583 -- Deferred_References --
584 -------------------------
586 -- Normally we generate references as we go along, but as discussed in
587 -- Sem_Util.Is_LHS, and Sem_Ch8.Find_Direct_Name/Find_Selected_Component,
588 -- we have one case where that is tricky, which is when we have something
589 -- like X.A := 3, where we don't know until we know the type of X whether
590 -- this is a reference (if X is an access type, so what we really have is
591 -- X.all.A := 3) or a modification, where X is not an access type.
593 -- What we do in such cases is to gather nodes, where we would have liked
594 -- to call Generate_Reference but we couldn't because we didn't know enough
595 -- into this table, Then we deal with generating references later on when
596 -- we have sufficient information to do it right.
602 -- One entry, E, N are as required for Generate_Reference call
613 -- This procedure is called from Frontend to process these table entries.
614 -- It is also called from Sem_Warn.
617 -- Determine whether arbitrary entity Ent has a pending reference in order
618 -- to suppress premature warnings about useless assignments. See comments
619 -- in Analyze_Assignment in sem_ch5.adb.
621 -----------------------------
622 -- SPARK Xrefs Information --
623 -----------------------------
625 -- This package defines procedures for collecting SPARK cross-reference
626 -- information and printing in ALI files.
630 function Enclosing_Subprogram_Or_Library_Package
632 -- Return the closest enclosing subprogram or library-level package.
633 -- This ensures that GNATprove can distinguish local variables from
634 -- global variables.
636 procedure Generate_Dereference
639 -- This procedure is called to record a dereference. N is the location
640 -- of the dereference.
642 generic
643 with procedure Process
647 -- Call Process on cross-references relevant to the SPARK backend with
648 -- parameter Xref holding the relevant subset of the xref entry and
649 -- Index holding the position in the original tables with references
650 -- (if positive) or dereferences (if negative).
654 -----------------
655 -- Subprograms --
656 -----------------
659 -- Records the definition of an entity
661 procedure Generate_Operator_Reference
664 -- Node N is an operator node, whose entity has been set. If this entity
665 -- is a user defined operator (i.e. an operator not defined in package
666 -- Standard), then a reference to the operator is recorded at node N.
667 -- T is the operand type of the operator. A reference to the operator is an
668 -- implicit reference to the type, and that needs to be recorded to avoid
669 -- spurious warnings on unused entities, when the operator is a renaming of
670 -- a predefined operator.
672 procedure Generate_Reference
678 -- This procedure is called to record a reference. N is the location of the
679 -- reference and E is the referenced entity. Typ is one of:
680 --
681 -- a character already described in the description of ref entries above
682 -- ' ' for dummy reference (see below)
683 --
684 -- Note: all references to incomplete or private types are to the original
685 -- (incomplete or private type) declaration. The full declaration is
686 -- treated as a reference with type 'c'.
687 --
688 -- Note: all references to packages or subprograms are to the entity for
689 -- the spec. The entity in the body is treated as a reference with type
690 -- 'b'. Similar handling for references to subprogram formals.
691 --
692 -- The call has no effect if N is not in the extended main source unit.
693 -- This check is omitted for type 'e' references (where it is useful to
694 -- have structural scoping information for other than the main source),
695 -- and for 'p' (since we want to pick up inherited primitive operations
696 -- that are defined in other packages).
697 --
698 -- The call also has no effect if any of the following conditions hold:
699 --
700 -- cross-reference collection is disabled
701 -- entity does not come from source (and Force is False)
702 -- reference does not come from source (and Force is False)
703 -- the entity is not one for which xrefs are appropriate
704 -- the type letter is blank
705 -- the node N is not an identifier, defining identifier, or expanded name
706 -- the type is 'p' and the entity is not in the extended main source
707 --
708 -- If all these conditions are met, then the Is_Referenced flag of E is set
709 -- (unless Set_Ref is False) and a cross-reference entry is recorded for
710 -- later output when Output_References is called.
711 --
712 -- Note: the dummy space entry is for the convenience of some callers,
713 -- who find it easier to pass a space to suppress the entry than to do
714 -- a specific test. The call has no effect if the type is a space.
715 --
716 -- The parameter Set_Ref is normally True, and indicates that in addition
717 -- to generating a cross-reference, the Referenced flag of the specified
718 -- entity should be set. If this parameter is False, then setting of the
719 -- Referenced flag is inhibited.
720 --
721 -- The parameter Force is set to True to force a reference to be generated
722 -- even if Comes_From_Source is false. This is used for certain implicit
723 -- references, and also for end label references.
726 -- Add a reference to the definition of each formal on the line for
727 -- a subprogram or an access_to_subprogram type.
730 -- Add a reference to the definition of each generic formal on the line
731 -- for a generic unit.
734 -- Output references to the current ali file
737 -- Initialize internal tables