diff options
Diffstat (limited to 'gcc/ada/lib-writ.ads')
| -rw-r--r-- | gcc/ada/lib-writ.ads | 89 |
1 files changed, 70 insertions, 19 deletions
diff --git a/gcc/ada/lib-writ.ads b/gcc/ada/lib-writ.ads index 6aa8dcf..e21112c 100644 --- a/gcc/ada/lib-writ.ads +++ b/gcc/ada/lib-writ.ads @@ -32,10 +32,6 @@ package Lib.Writ is -- Format of Library Information -- ----------------------------------- - -- Note: the contents of the ali file are summarized in the GNAT - -- user's guide, so if any non-trivial changes are made to this - -- section, they should be reflected in the user's guide. - -- 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 @@ -50,6 +46,48 @@ package Lib.Writ is -- 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 suchy 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 -- ------------------ @@ -72,6 +110,10 @@ package Lib.Writ is -- 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 -- -- --------------------- @@ -201,21 +243,26 @@ package Lib.Writ is -- 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 -- -- --------------------- - -- Two lines are generated to record the status of restrictions that can - -- be specified by pragma Restrictions. The first of these lines refers - -- to Restriction_Id values: + -- The 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>> + -- R <<restriction-characters>> space <<restriction-param-id-entries>> - -- This line records information regarding restrictions that do - -- not take parameter values. Here "restriction-characters is a - -- string of characters, one for each value (in order) defined - -- in Restrict.All_Boolean_Restrictions. There are three possible - -- settings for each restriction: + -- 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 @@ -236,9 +283,8 @@ package Lib.Writ is -- has "v", which is not permitted, since these restrictions -- are partition-wide. - -- The second R line refers to parameter restrictions: - - -- R <<restriction-parameter-id-entries>> + -- Following a space, the second parameter refers to restriction + -- 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 @@ -284,9 +330,14 @@ package Lib.Writ is -- vN+ A violation was detected. The compiler cannot determine -- the exact count of violations, but it is at least N. - -- There are no spaces in the line, so the entry for the example - -- in the header of this section for Max_Tasks would appear as - -- the string r4v3. + -- 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. -- ------------------------ -- -- I Interrupt States -- |