summaryrefslogtreecommitdiff
path: root/gcc/ada/lib-writ.ads
blob: ef5f23a9ee38108b2344bd656103328d10689ac3 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
------------------------------------------------------------------------------
--                                                                          --
--                         GNAT COMPILER COMPONENTS                         --
--                                                                          --
--                             L I B . W R I T                              --
--                                                                          --
--                                 S p e c                                  --
--                                                                          --
--          Copyright (C) 1992-2010, Free Software Foundation, Inc.         --
--                                                                          --
-- GNAT is free software;  you can  redistribute it  and/or modify it under --
-- terms of the  GNU General Public License as published  by the Free Soft- --
-- ware  Foundation;  either version 3,  or (at your option) any later ver- --
-- sion.  GNAT is distributed in the hope that it will be useful, but WITH- --
-- OUT ANY WARRANTY;  without even the  implied warranty of MERCHANTABILITY --
-- or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License --
-- for  more details.  You should have  received  a copy of the GNU General --
-- Public License  distributed with GNAT; see file COPYING3.  If not, go to --
-- http://www.gnu.org/licenses for a complete copy of the license.          --
--                                                                          --
-- GNAT was originally developed  by the GNAT team at  New York University. --
-- Extensive contributions were provided by Ada Core Technologies Inc.      --
--                                                                          --
------------------------------------------------------------------------------

--  This package contains the routines for writing the library information

package Lib.Writ is

   -----------------------------------
   -- Format of Library Information --
   -----------------------------------

   --  This section describes the format of the library information that is
   --  associated with object files. The exact method of this association is
   --  potentially implementation dependent and is described and implemented in
   --  package ali. From the point of view of the description here, all we need
   --  to know is that the information is represented as a string of characters
   --  that is somehow associated with an object file, and can be retrieved. If
   --  no library information exists for a given object file, then we take this
   --  as equivalent to the non-existence of the object file, as if source file
   --  has not been previously compiled.

   --  The library information is written as a series of lines of the form:

   --    Key_Character parameter parameter ...

   --  The following sections describe the format of these lines in detail

   --------------------------------------
   -- Making Changes to the ALI Format --
   --------------------------------------

   --  A number of tools use ali.adb to parse ali files. This means that
   --  changes to this format can cause old versions of these tools to be
   --  incompatible with new versions of the compiler. Any changes to ali file
   --  formats must be carefully evaluated to understand any such possible
   --  conflicts, and in particular, it is very undesirable to create conflicts
   --  between older versions of GPS and newer versions of the compiler.

   --  If the following guidelines are respected, downward compatibility
   --  problems (old tools reading new ali files) should be minimized:

   --    The basic key character format must be kept

   --    The V line must be the first line, this is checked by ali.adb even in
   --    Ignore_Errors mode, and is used to verify that the file at hand is
   --    indeed likely intended to be an ali file.

   --    The P line must be present, though may be modified in contents
   --    according to remaining guidelines. Again, ali.adb assumes the P
   --    line is present even in Ignore_Errors mode.

   --    New modifiers can generally be added (in particular adding new two
   --    letter modifiers to the P or U lines is always safe)

   --    Adding entirely new lines (with a new key letter) to the ali file is
   --    always safe, at any point (other than before the V line), since such
   --    lines will be ignored.

   --  Following the guidelines in this section should ensure that this problem
   --  is minimized and that old tools will be able to deal successfully with
   --  new ali formats. Note that this does not apply to the compiler itself,
   --  which always requires consistency between the ali files and the binder.
   --  That is because one of the main functions of the binder is to ensure
   --  consistency of the partition, and this can be compromised if the ali
   --  files are inconsistent.

   ------------------
   -- Header Lines --
   ------------------

   --  The initial header lines in the file give information about the
   --  compilation environment, and identify other special information such as
   --  main program parameters.

   --  ----------------
   --  -- V  Version --
   --  ----------------

   --    V "xxxxxxxxxxxxxxxx"
   --
   --      This line indicates the library output version, as defined in
   --      Gnatvsn. It ensures that separate object modules of a program are
   --      consistent. It has to be changed if anything changes which would
   --      affect successful binding of separately compiled modules. Examples
   --      of such changes are modifications in the format of the library info
   --      described in this package, or modifications to calling sequences, or
   --      to the way that data is represented.

   --    Note: the V line absolutely must be the first line, and no change
   --    to the ALI format should change this, since even in Ignore_Errors
   --    mode, Scan_ALI insists on finding a V line.

   --  ---------------------
   --  -- M  Main Program --
   --  ---------------------

   --    M type [priority] [T=time-slice] [AB] [C=cpu] W=?

   --      This line appears only if the main unit for this file is suitable
   --      for use as a main program. The parameters are:

   --        type

   --          P for a parameterless procedure
   --          F for a function returning a value of integral type
   --            (used for writing a main program returning an exit status)

   --        priority

   --          Present only if there was a valid pragma Priority in the
   --          corresponding unit to set the main task priority. It is an
   --          unsigned decimal integer.

   --        T=time-slice

   --          Present only if there was a valid pragma Time_Slice in the
   --          corresponding unit. It is an unsigned decimal integer in the
   --          range 0 .. 10**9 giving the time slice value in units of
   --          milliseconds. The actual significance of this parameter is
   --          target dependent.

   --        AB

   --          Present if there is an allocator in the body of the procedure
   --          after the BEGIN. This will be a violation of the restriction
   --          No_Allocators_After_Elaboration if it is present, and this
   --          unit is used as a main program (only the binder can find the
   --          violation, since only the binder knows the main program).

   --        C=cpu

   --          Present only if there was a valid pragma CPU in the
   --          corresponding unit to set the main task affinity. It is an
   --          unsigned decimal integer.

   --        W=?

   --          This parameter indicates the wide character encoding method used
   --          when compiling the main program file. The ? character is the
   --          single character used in the -gnatW? switch. This is used to
   --          provide the default wide-character encoding for Wide_Text_IO
   --          files.

   --  -----------------
   --  -- A  Argument --
   --  -----------------

   --    A argument

   --      One of these lines appears for each of the arguments present in the
   --      call to the gnat1 program. This can be used if it is necessary to
   --      reconstruct this call (e.g. for fix and continue).

   --  -------------------
   --  -- P  Parameters --
   --  -------------------

   --    P <<parameters>>

   --      Indicates various information that applies to the compilation of the
   --      corresponding source file. Parameters is a sequence of zero or more
   --      two letter codes that indicate configuration pragmas and other
   --      parameters that apply:
   --
   --      The arguments are as follows:
   --
   --         CE   Compilation errors. If this is present it means that the ali
   --              file resulted from a compilation with the -gnatQ switch set,
   --              and illegalities were detected. The ali file contents may
   --              not be completely reliable, but the format will be correct
   --              and complete. Note that NO is always present if CE is
   --              present.
   --
   --         DB   Detect_Blocking pragma is in effect for all units in this
   --              file.
   --
   --         FD   Configuration pragmas apply to all the units in this file
   --              specifying a possibly non-standard floating point format
   --              (VAX float with Long_Float using D_Float).
   --
   --         FG   Configuration pragmas apply to all the units in this file
   --              specifying a possibly non-standard floating point format
   --              (VAX float with Long_Float using G_Float).
   --
   --         FI   Configuration pragmas apply to all the units in this file
   --              specifying a possibly non-standard floating point format
   --              (IEEE Float).
   --
   --         Lx   A valid Locking_Policy pragma applies to all the units in
   --              this file, where x is the first character (upper case) of
   --              the policy name (e.g. 'C' for Ceiling_Locking).
   --
   --         NO   No object. This flag indicates that the units in this file
   --              were not compiled to produce an object. This can occur as a
   --              result of the use of -gnatc, or if no object can be produced
   --              (e.g. when a package spec is compiled instead of the body,
   --              or a subunit on its own).
   --
   --         NR   No_Run_Time. Indicates that a pragma No_Run_Time applies
   --              to all units in the file.
   --
   --         NS   Normalize_Scalars pragma in effect for all units in
   --              this file.
   --
   --         Qx   A valid Queueing_Policy pragma applies to all the units
   --              in this file, where x is the first character (upper case)
   --              of the policy name (e.g. 'P' for Priority_Queueing).
   --
   --         SL   Indicates that the unit is an Interface to a Standalone
   --              Library. Note that this indication is never given by the
   --              compiler, but is added by the Project Manager in gnatmake
   --              when an Interface ALI file is copied to the library
   --              directory.

   --         SS   This unit references System.Secondary_Stack (that is,
   --              the unit makes use of the secondary stack facilities).
   --
   --         Tx   A valid Task_Dispatching_Policy pragma applies to all
   --              the units in this file, where x is the first character
   --              (upper case) of the corresponding policy name (e.g. 'F'
   --              for FIFO_Within_Priorities).
   --
   --         UA  Unreserve_All_Interrupts pragma was processed in one or
   --             more units in this file
   --
   --         ZX  Units in this file use zero-cost exceptions and have
   --             generated exception tables. If ZX is not present, the
   --             longjmp/setjmp exception scheme is in use.
   --
   --      Note that language defined units never output policy (Lx, Tx, Qx)
   --      parameters. Language defined units must correctly handle all
   --      possible cases. These values are checked for consistency by the
   --      binder and then copied to the generated binder output file.

   --    Note: The P line must be present. Even in Ignore_Errors mode, Scan_ALI
   --    insists on finding a P line. So if changes are made to the ALI format,
   --    they should not include removing the P line!

   --  ---------------------
   --  -- R  Restrictions --
   --  ---------------------

   --  The first R line records the status of restrictions generated by pragma
   --  Restrictions encountered, as well as information on what the compiler
   --  has been able to determine with respect to restrictions violations.
   --  The format is:

   --    R <<restriction-characters>> <<restriction-param-id-entries>>

   --      The first parameter is a string of characters that records
   --      information regarding restrictions that do not take parameter not
   --      take parameter values. It is a string of characters, one character
   --      for each value (in order) in All_Boolean_Restrictions. There are
   --      three possible settings for each restriction:

   --        r   Restricted. Unit was compiled under control of a pragma
   --            Restrictions for the corresponding restriction. In this case
   --            the unit certainly does not violate the Restriction, since
   --            this would have been detected by the compiler.

   --        n   Not used. The unit was not compiled under control of a pragma
   --            Restrictions for the corresponding restriction, and does not
   --            make any use of the referenced feature.

   --        v   Violated. The unit was not compiled under control of a pragma
   --            Restrictions for the corresponding restriction, and it does
   --            indeed use the referenced feature.

   --      This information is used in the binder to check consistency, i.e. to
   --      detect cases where one unit has "r" and another unit has "v", which
   --      is not permitted, since these restrictions are partition-wide.

   --  The second parameter, which immediately follows the first (with no
   --  separating space) gives restriction information for identifiers for
   --  which a parameter is given.

   --      The parameter is a string of entries, one for each value in
   --      Restrict.All_Parameter_Restrictions. Each entry has two components
   --      in sequence, the first indicating whether or not there is a
   --      restriction, and the second indicating whether or not the compiler
   --      detected violations. In the boolean case it is not necessary to
   --      separate these, since if a restriction is set, and violated, that is
   --      an error. But in the parameter case, this is not true. For example,
   --      we can have a unit with a pragma Restrictions (Max_Tasks => 4),
   --      where the compiler can detect that there are exactly three tasks
   --      declared. Both of these pieces of information must be passed to the
   --      binder. The parameter of 4 is important in case the total number of
   --      tasks in the partition is greater than 4. The parameter of 3 is
   --      important in case some other unit has a restrictions pragma with
   --      Max_Tasks=>2.

   --      The component for the presence of restriction has one of two
   --      possible forms:

   --         n   No pragma for this restriction is present in the set of units
   --             for this ali file.

   --         rN  At least one pragma for this restriction is present in the
   --             set of units for this ali file. The value N is the minimum
   --             parameter value encountered in any such pragma. N is in the
   --             range of Integer (a value larger than N'Last causes the
   --             pragma to be ignored).

   --      The component for the violation detection has one of three
   --      possible forms:

   --         n   No violations were detected by the compiler

   --         vN  A violation was detected. N is either the maximum or total
   --             count of violations (depending on the checking type) in all
   --             the units represented by the ali file). Note that this
   --             setting is only allowed for restrictions that are in
   --             Checked_[Max|Sum]_Parameter_Restrictions. The value here is
   --             known to be exact by the compiler and is in the range of
   --             Natural.

   --         vN+ A violation was detected. The compiler cannot determine
   --             the exact count of violations, but it is at least N.

   --      There are no spaces within the parameter string, so the entry
   --      described above in the header of this section for Max_Tasks would
   --      appear as the string r4v3.

   --      Note: The restrictions line is required to be present. Even in
   --      Ignore_Errors mode, Scan_ALI expects to find an R line and will
   --      signal a fatal error if it is missing. This means that future
   --      changes to the ALI file format must retain the R line.

   --  Subsequent R lines are present only if pragma Restriction No_Dependence
   --  is used. There is one such line for each such pragma appearing in the
   --  extended main unit. The format is

   --    R unit_name

   --      Here the unit name is in all lower case. The components of the unit
   --      name are separated by periods. The names themselves are in encoded
   --      form, as documented in Namet.

   --  -------------------------
   --  -- I  Interrupt States --
   --  -------------------------

   --    I interrupt-number interrupt-state line-number

   --      This line records information from an Interrupt_State pragma. There
   --      is one line for each separate pragma, and if no such pragmas are
   --      used, then no I lines are present.

   --      The interrupt-number is an unsigned positive integer giving the
   --      value of the interrupt as defined in Ada.Interrupts.Names.

   --      The interrupt-state is one of r/s/u for Runtime/System/User

   --      The line number is an unsigned decimal integer giving the line
   --      number of the corresponding Interrupt_State pragma. This is used
   --      in consistency messages.

   --  --------------------------------------
   --  -- S  Priority Specific Dispatching --
   --  --------------------------------------

   --    S policy_identifier first_priority last_priority line-number

   --      This line records information from a Priority_Specific_Dispatching
   --      pragma. There is one line for each separate pragma, and if no such
   --      pragmas are used, then no S lines are present.

   --      The policy_identifier is the first character (upper case) of the
   --      corresponding policy name (e.g. 'F' for FIFO_Within_Priorities).

   --      The first_priority and last_priority fields define the range of
   --      priorities to which the specified dispatching policy apply.

   --      The line number is an unsigned decimal integer giving the line
   --      number of the corresponding Priority_Specific_Dispatching pragma.
   --      This is used in consistency messages.

   ----------------------------
   -- Compilation Unit Lines --
   ----------------------------

   --  Following these header lines, a set of information lines appears for
   --  each compilation unit that appears in the corresponding object file. In
   --  particular, when a package body or subprogram body is compiled, there
   --  will be two sets of information, one for the spec and one for the body,
   --  with the entry for the body appearing first. This is the only case in
   --  which a single ALI file contains more than one unit (in particular note
   --  that subunits do *not* count as compilation units for this purpose, and
   --  generate no library information, since they are inlined).

   --  --------------------
   --  -- U  Unit Header --
   --  --------------------

   --  The lines for each compilation unit have the following form

   --    U unit-name source-name version <<attributes>>
   --
   --      This line identifies the unit to which this section of the library
   --      information file applies. The first three parameters are the unit
   --      name in internal format, as described in package Uname, and the name
   --      of the source file containing the unit.
   --
   --      Version is the version given as eight hexadecimal characters with
   --      upper case letters. This value is the exclusive or of the source
   --      checksums of the unit and all its semantically dependent units.
   --
   --      The <<attributes>> are a series of two letter codes indicating
   --      information about the unit:
   --
   --         BD  Unit does not have pragma Elaborate_Body, but the elaboration
   --             circuit has determined that it would be a good idea if this
   --             pragma were present, since the body of the package contains
   --             elaboration code that modifies one or more variables in the
   --             visible part of the package. The binder will try, but does
   --             not promise, to keep the elaboration of the body close to
   --             the elaboration of the spec.
   --
   --         DE  Dynamic Elaboration. This unit was compiled with the dynamic
   --             elaboration model, as set by either the -gnatE switch or
   --             pragma Elaboration_Checks (Dynamic).
   --
   --         EB  Unit has pragma Elaborate_Body, or is a generic instance that
   --             has a body. Set for instances because RM 12.3(20) requires
   --             that the body be immediately elaborated after the spec (we
   --             would normally do that anyway, because elaborate spec and
   --             body together whenever possible, and for an instance it is
   --             always possible; however setting EB ensures that this is done
   --             even when using the -p gnatbind switch).
   --
   --         EE  Elaboration entity is present which must be set true when
   --             the unit is elaborated. The name of the elaboration entity is
   --             formed from the unit name in the usual way. If EE is present,
   --             then this boolean must be set True as part of the elaboration
   --             processing routine generated by the binder. Note that EE can
   --             be set even if NE is set. This happens when the boolean is
   --             needed solely for checking for the case of access before
   --             elaboration.
   --
   --         GE  Unit is a generic declaration, or corresponding body
   --
   --         IL  Unit source uses a style with identifiers in all lower-case
   --         IU  (IL) or all upper case (IU). If the standard mixed-case usage
   --             is detected, or the compiler cannot determine the style, then
   --             no I parameter will appear.
   --
   --         IS  Initialize_Scalars pragma applies to this unit, or else there
   --             is at least one use of the Invalid_Value attribute.
   --
   --         KM  Unit source uses a style with keywords in mixed case (KM)
   --         KU  or all upper case (KU). If the standard lower-case usage is
   --             is detected, or the compiler cannot determine the style, then
   --             no K parameter will appear.
   --
   --         NE  Unit has no elaboration routine. All subprogram bodies and
   --             specs are in this category. Package bodies and specs may or
   --             may not have NE set, depending on whether or not elaboration
   --             code is required. Set if N_Compilation_Unit node has flag
   --             Has_No_Elaboration_Code set.
   --
   --         OL   The units in this file are compiled with a local pragma
   --              Optimize_Alignment, so no consistency requirement applies
   --              to these units. All internal units have this status since
   --              they have an automatic default of Optimize_Alignment (Off).
   --
   --         OO   Optimize_Alignment (Off) is the default setting for all
   --              units in this file. All files in the partition that specify
   --              a default must specify the same default.
   --
   --         OS   Optimize_Alignment (Space) is the default setting for all
   --              units in this file. All files in the partition that specify
   --              a default must specify the same default.
   --
   --         OT   Optimize_Alignment (Time) is the default setting for all
   --              units in this file. All files in the partition that specify
   --              a default must specify the same default.
   --
   --         PK  Unit is package, rather than a subprogram
   --
   --         PU  Unit has pragma Pure
   --
   --         PR  Unit has pragma Preelaborate
   --
   --         RA  Unit declares a Remote Access to Class-Wide (RACW) type
   --
   --         RC  Unit has pragma Remote_Call_Interface
   --
   --         RT  Unit has pragma Remote_Types
   --
   --         SP  Unit has pragma Shared_Passive.
   --
   --         SU  Unit is a subprogram, rather than a package
   --
   --      The attributes may appear in any order, separated by spaces.

   --  ---------------------
   --  -- W  Withed Units --
   --  ---------------------

   --  Following each U line, is a series of lines of the form

   --    W unit-name [source-name lib-name] [E] [EA] [ED] [AD]
   --
   --      One of these lines is present for each unit that is mentioned in an
   --      explicit with clause by the current unit. The first parameter is the
   --      unit name in internal format. The second parameter is the file name
   --      of the file that must be compiled to compile this unit. It is
   --      usually the file for the body, except for packages which have no
   --      body. For units that need a body, if the source file for the body
   --      cannot be found, the file name of the spec is used instead. The
   --      third parameter is the file name of the library information file
   --      that contains the results of compiling this unit. The optional
   --      modifiers are used as follows:
   --
   --        E   pragma Elaborate applies to this unit
   --
   --        EA  pragma Elaborate_All applies to this unit
   --
   --        ED  Elaborate_Desirable set for this unit, which means that there
   --            is no Elaborate, but the analysis suggests that Program_Error
   --            may be raised if the Elaborate conditions cannot be satisfied.
   --            The binder will attempt to treat ED as E if it can.
   --
   --        AD  Elaborate_All_Desirable set for this unit, which means that
   --            there is no Elaborate_All, but the analysis suggests that
   --            Program_Error may be raised if the Elaborate_All conditions
   --            cannot be satisfied. The binder will attempt to treat AD as
   --            EA if it can.
   --
   --      The parameter source-name and lib-name are omitted for the case of a
   --      generic unit compiled with earlier versions of GNAT which did not
   --      generate object or ali files for generics.

   --  In fact W lines include implicit withs ???

   --  -----------------------
   --  -- L  Linker_Options --
   --  -----------------------

   --  Following the W lines (if any, or the U line if not), are an optional
   --  series of lines that indicates the usage of the pragma Linker_Options in
   --  the associated unit. For each appearance of a pragma Linker_Options (or
   --  Link_With) in the unit, a line is present with the form:

   --    L "string"

   --      where string is the string from the unit line enclosed in quotes.
   --      Within the quotes the following can occur:

   --        c    graphic characters in range 20-7E other than " or {
   --        ""   indicating a single " character
   --        {hh} indicating a character whose code is hex hh (0-9,A-F)
   --        {00} [ASCII.NUL] is used as a separator character
   --             to separate multiple arguments of a single
   --             Linker_Options pragma.

   --      For further details, see Stringt.Write_String_Table_Entry. Note that
   --      wide characters in the form {hhhh} cannot be produced, since pragma
   --      Linker_Option accepts only String, not Wide_String.

   --      The L lines are required to appear in the same order as the
   --      corresponding Linker_Options (or Link_With) pragmas appear in the
   --      source file, so that this order is preserved by the binder in
   --      constructing the set of linker arguments.

   --  --------------
   --  -- N  Notes --
   --  --------------

   --  The final section of unit-specific lines contains notes which record
   --  annotations inserted in source code for processing by external tools
   --  using pragmas. For each occurrence of any of these pragmas, a line is
   --  generated with the following syntax:

   --    N x<sloc> [<arg_id>:]<arg> ...

   --      x is one of:
   --        A  pragma Annotate
   --        C  pragma Comment
   --        I  pragma Ident
   --        T  pragma Title
   --        S  pragma Subtitle

   --      <sloc> is the source location of the pragma in line:col format

   --      Successive entries record the pragma_argument_associations.

   --        If a pragma argument identifier is present, the entry is prefixed
   --        with the pragma argument identifier <arg_id> followed by a colon.

   --        <arg> represents the pragma argument, and has the following
   --        conventions:

   --          - identifiers are output verbatim
   --          - static string expressions are output as literals encoded as
   --            for L lines
   --          - static integer expressions are output as decimal literals
   --          - any other expression is replaced by the placeholder "<expr>"

   ---------------------
   -- Reference Lines --
   ---------------------

   --  The reference lines contain information about references from any of the
   --  units in the compilation (including body version and version attributes,
   --  linker options pragmas and source dependencies).

   --  ------------------------------------
   --  -- E  External Version References --
   --  ------------------------------------

   --  One of these lines is present for each use of 'Body_Version or 'Version
   --  in any of the units of the compilation. These are used by the linker to
   --  determine which version symbols must be output. The format is simply:

   --    E name

   --  where name is the external name, i.e. the unit name with either a S or a
   --  B for spec or body version referenced (Body_Version always references
   --  the body, Version references the Spec, except in the case of a reference
   --  to a subprogram with no separate spec). Upper half and wide character
   --  codes are encoded using the same method as in Namet (Uhh for upper half,
   --  Whhhh for wide character, where hh are hex digits).

   --  ---------------------
   --  -- D  Dependencies --
   --  ---------------------

   --  The dependency lines indicate the source files on which the compiled
   --  units depend. This is used by the binder for consistency checking.
   --  These lines are also referenced by the cross-reference information.

   --    D source-name time-stamp checksum [subunit-name] line:file-name

   --      The time-stamp field contains the time stamp of the corresponding
   --      source file. See types.ads for details on time stamp representation.

   --      The checksum is an 8-hex digit representation of the source file
   --      checksum, with letters given in lower case.

   --      The subunit name is present only if the dependency line is for a
   --      subunit. It contains the fully qualified name of the subunit in all
   --      lower case letters.

   --      The line:file-name entry is present only if a Source_Reference
   --      pragma appeared in the source file identified by source-name. In
   --      this case, it gives the information from this pragma. Note that this
   --      allows cross-reference information to be related back to the
   --      original file. Note: the reason the line number comes first is that
   --      a leading digit immediately identifies this as a Source_Reference
   --      entry, rather than a subunit-name.

   --      A line number of zero for line: in this entry indicates that there
   --      is more than one source reference pragma. In this case, the line
   --      numbers in the cross-reference are correct, and refer to the
   --      original line number, but there is no information that allows a
   --      reader of the ALI file to determine the exact mapping of physical
   --      line numbers back to the original source.

   --      Files with a zero checksum and a non-zero time stamp are in general
   --      files on which the compilation depends but which are not Ada files
   --      with further dependencies. This includes preprocessor data files
   --      and preprocessor definition files.

   --      Note: blank lines are ignored when the library information is read,
   --      and separate sections of the file are separated by blank lines to
   --      ease readability. Blanks between fields are also ignored.

   --      For entries corresponding to files that were not present (and thus
   --      resulted in error messages), or for files that are not part of the
   --      dependency set, both the time stamp and checksum are set to all zero
   --      characters. These dummy entries are ignored by the binder in
   --      dependency checking, but must be present for proper interpretation
   --      of the cross-reference data.

   --------------------------
   -- Cross-Reference Data --
   --------------------------

   --  The cross-reference data follows the dependency lines. See the spec of
   --  Lib.Xref for details on the format of this data.

   ---------------------------------
   -- Source Coverage Obligations --
   ---------------------------------

   --  The Source Coverage Obligation (SCO) information follows the cross-
   --  reference data. See the spec of Par_SCO for full details of the format.

   ----------------------
   -- Global Variables --
   ----------------------

   --  The table defined here stores one entry for each Interrupt_State pragma
   --  encountered either in the main source or in an ancillary with'ed source.
   --  Since interrupt state values have to be consistent across all units in a
   --  partition, we detect inconsistencies at compile time when we can.

   type Interrupt_State_Entry is record
      Interrupt_Number : Pos;
      --  Interrupt number value

      Interrupt_State : Character;
      --  Set to r/s/u for Runtime/System/User

      Pragma_Loc : Source_Ptr;
      --  Location of pragma setting this value in place
   end record;

   package Interrupt_States is new Table.Table (
     Table_Component_Type => Interrupt_State_Entry,
     Table_Index_Type     => Nat,
     Table_Low_Bound      => 1,
     Table_Initial        => 30,
     Table_Increment      => 200,
     Table_Name           => "Name_Interrupt_States");

   --  The table structure defined here stores one entry for each
   --  Priority_Specific_Dispatching pragma encountered either in the main
   --  source or in an ancillary with'ed source. Since have to be consistent
   --  across all units in a partition, we may as well detect inconsistencies
   --  at compile time when we can.

   type Specific_Dispatching_Entry is record
      Dispatching_Policy : Character;
      --  First character (upper case) of the corresponding policy name

      First_Priority     : Nat;
      --  Lower bound of the priority range to which the specified dispatching
      --  policy applies.

      Last_Priority      : Nat;
      --  Upper bound of the priority range to which the specified dispatching
      --  policy applies.

      Pragma_Loc         : Source_Ptr;
      --  Location of pragma setting this value in place
   end record;

   package Specific_Dispatching is new Table.Table (
     Table_Component_Type => Specific_Dispatching_Entry,
     Table_Index_Type     => Nat,
     Table_Low_Bound      => 1,
     Table_Initial        => 10,
     Table_Increment      => 100,
     Table_Name           => "Name_Priority_Specific_Dispatching");

   -----------------
   -- Subprograms --
   -----------------

   procedure Ensure_System_Dependency;
   --  This procedure ensures that a dependency is created on system.ads. Even
   --  if there is no semantic dependency, Targparm has read the file to
   --  acquire target parameters, so we need a source dependency.

   procedure Write_ALI (Object : Boolean);
   --  This procedure writes the library information for the current main unit
   --  The Object parameter is true if an object file is created, and false
   --  otherwise.
   --
   --  Note: in the case where we are not generating code (-gnatc mode), this
   --  routine only writes an ALI file if it cannot find an existing up to
   --  date ALI file. If it *can* find an existing up to date ALI file, then
   --  it reads this file and sets the Lib.Compilation_Arguments table from
   --  the A lines in this file.

   procedure Add_Preprocessing_Dependency (S : Source_File_Index);
   --  Indicate that there is a dependency to be added on a preprocessing data
   --  file or on a preprocessing definition file.

end Lib.Writ;