-- --
-- S p e c --
-- --
--- Copyright (C) 1992-2011, Free Software Foundation, Inc. --
+-- Copyright (C) 1992-2012, 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- --
-- DB Detect_Blocking pragma is in effect for all units in this
-- file.
--
+ -- Ex A valid Partition_Elaboration_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 Concurrent).
+ --
-- 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).
-- -- R Restrictions --
-- ---------------------
+ -- There are two forms for R lines, positional and named. The positional
+ -- notation is now considered obsolescent, it is not generated by the most
+ -- recent versions of the compiler except under control of the debug switch
+ -- -gnatdR, but is still recognized by the binder.
+
+ -- The recognition by the binder is to ease the transition, and better deal
+ -- with some cases of inconsistent builds using incompatible versions of
+ -- the compiler and binder. The named notation is the current preferred
+ -- approach.
+
+ -- Note that R lines are generated using the information in unit Rident,
+ -- and intepreted by the binder using the information in System.Rident.
+ -- Normally these two units should be effectively identical. However in
+ -- some cases of inconsistent builds, they may be different. This may lead
+ -- to binder diagnostics, which can be suppressed using the -C switch for
+ -- the binder, which results in ignoring unrecognized restrictions in the
+ -- ali files.
+
+ -- ---------------------------------------
+ -- -- R Restrictions (Positional Form) --
+ -- ---------------------------------------
+
-- 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.
-- signal a fatal error if it is missing. This means that future
-- changes to the ALI file format must retain the R line.
+ -- ----------------------------------
+ -- -- R Restrictions (Named Form) --
+ -- ----------------------------------
+
+ -- The first R line for named form announces that named notation will be
+ -- used, and also assures that there is at least one R line present, which
+ -- makes parsing of ali files simpler. A blank line preceds the RN line.
+
+ -- RN
+
+ -- In named notation, the restrictions are given as a series of lines, one
+ -- per retrictions that is specified or violated (no information is present
+ -- for restrictions that are not specified or violated). In the following
+ -- name is the name of the restriction in all upper case.
+
+ -- For boolean restrictions, we have only two possibilities. A restrictions
+ -- pragma is present, or a violation is detected:
+
+ -- RR name
+
+ -- A restriction pragma is present for the named boolean restriction.
+ -- No violations were detected by the compiler (or the unit in question
+ -- would have been found to be illegal).
+
+ -- RV name
+
+ -- No restriction pragma is present for the named boolean restriction.
+ -- However, the compiler did detect one or more violations of this
+ -- restriction, which may require a binder consistency check.
+
+ -- For the case of restrictions that take a parameter, we need both the
+ -- information from pragma if present, and the actual information about
+ -- what possible violations occur. 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.
+
+ -- RR name=N
+
+ -- A restriction pragma is present for the named restriction which is
+ -- one of the restrictions taking a parameter. The value N (a decimal
+ -- integer) is the value given in the restriction pragma.
+
+ -- RV name=N
+
+ -- A restriction pragma may or may not be present for the restriction
+ -- given by name (one of the restrictions taking a parameter). But in
+ -- either case, the compiler detected possible violations. N (a decimal
+ -- integer) is the maximum or total count of violations (depending
+ -- on the checking type) in all the units represented by the ali file).
+ -- The value here is known to be exact by the compiler and is in the
+ -- range of Natural. Note that if an RR line is present for the same
+ -- restriction, then the value in the RV line cannot exceed the value
+ -- in the RR line (since otherwise the compiler would have detected a
+ -- violation of the restriction).
+
+ -- RV name=N+
+
+ -- Similar to the above, but the compiler cannot determine the exact
+ -- count of violations, but it is at least N.
+
+ -- -------------------------------------------------
+ -- -- R Restrictions (No_Dependence Information) --
+ -- -------------------------------------------------
+
-- 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:
--
-- The attributes may appear in any order, separated by spaces.
- -- ---------------------
- -- -- W Withed Units --
- -- ---------------------
+ -- -----------------------------
+ -- -- W, Y and Z 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
+ -- or
+ -- Y unit-name [source-name lib-name] [E] [EA] [ED] [AD]
+ -- or
+ -- Z unit-name [source-name lib-name] [E] [EA] [ED] [AD]
+ --
+ -- One W line is present for each unit that is mentioned in an explicit
+ -- non-limited with clause by the current unit. One Y line is present
+ -- for each unit that is mentioned in an explicit limited with clause
+ -- by the current unit. One Z line is present for each unit that is
+ -- only implicitly withed 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
-- 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 --
-- -----------------------
--------------------------
-- The cross-reference data follows the dependency lines. See the spec of
- -- Lib.Xref for details on the format of this data.
+ -- Lib.Xref in file lib-xref.ads 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.
+ -- reference data. See the spec of Par_SCO in file par_sco.ads for full
+ -- details of the format.
----------------------
-- Alfa Information --
----------------------
-- The Alfa information follows the SCO information. See the spec of Alfa
- -- for full details of the format.
+ -- in file alfa.ads for full details of the format.
+
+ -------------------------------------
+ -- T Target Dependent Information --
+ -------------------------------------
+
+ -- This section is present if the option to generate target dependent
+ -- information is present (this flag is set by the -gnatT switch). The
+ -- format of T lines is:
+
+ -- T key val
+
+ -- There is one line for each constant declared in the Ttypes package
+
+ -- key is the four letter code (which can be found as a comment on each
+ -- of the constant declarations in Ttypes).
+
+ -- val is the value of the constant, which is either a non-negative
+ -- decimal constant, or TRUE or FALSE for a Boolean value.
----------------------
-- Global Variables --