Output and Error Message Control - GNAT User's Guide for Native Platforms

Next: Warning Message Control, Previous: Alphabetical List of All Switches, Up: Compiler Switches

4.3.2 Output and Error Message Control

The standard default format for error messages is called 'brief format'. Brief format messages are written to stderr (the standard error file) and have the following form:

    e.adb:3:04: Incorrect spelling of keyword "function"
    e.adb:4:20: ";" should be "is"

The first integer after the file name is the line number in the file, and the second integer is the column number within the line. GPS can parse the error messages and point to the referenced character. The following switches provide control over the error message format:

-gnatv

The v stands for verbose. The effect of this setting is to write long-format error messages to stdout (the standard output file. The same program compiled with the `-gnatv' switch would generate:

         3. funcion X (Q : Integer)
            |
         >>> Incorrect spelling of keyword "function"
         4. return Integer;
                          |
         >>> ";" should be "is"

The vertical bar indicates the location of the error, and the >>> prefix can be used to search for error messages. When this switch is used the only source lines output are those with errors.

-gnatl

The l stands for list. This switch causes a full listing of the file to be generated. In the case where a body is compiled, the corresponding spec is also listed, along with any subunits. Typical output from compiling a package body p.adb might look like:

         Compiling: p.adb
         
              1. package body p is
              2.    procedure a;
              3.    procedure a is separate;
              4. begin
              5.    null
                        |
                 >>> missing ";"
         
              6. end;
         
         Compiling: p.ads
         
              1. package p is
              2.    pragma Elaborate_Body
                                         |
                 >>> missing ";"
         
              3. end p;
         
         Compiling: p-a.adb
         
              1. separate p
                         |
                 >>> missing "("
         
              2. procedure a is
              3. begin
              4.    null
                        |
                 >>> missing ";"
         
              5. end;

When you specify the `-gnatv' or `-gnatl' switches and standard output is redirected, a brief summary is written to stderr (standard error) giving the number of error messages and warning messages generated.

-gnatl=`fname': This has the same effect as `-gnatl' except that the output is written to a file instead of to standard output. If the given name fname does not start with a period, then it is the full name of the file to be written. If fname is an extension, it is appended to the name of the file being compiled. For example, if file xyz.adb is compiled with `-gnatl=.lst', then the output is written to file xyz.adb.lst.

-gnatU: This switch forces all error messages to be preceded by the unique string 'error:'. This means that error messages take a few more characters in space, but allows easy searching for and identification of error messages.

-gnatb: The b stands for brief. This switch causes GNAT to generate the brief format error messages to stderr (the standard error file) as well as the verbose format message or full listing (which as usual is written to stdout (the standard output file).

-gnatm=`n'

The m stands for maximum. n is a decimal integer in the range of 1 to 999999 and limits the number of error or warning messages to be generated. For example, using `-gnatm2' might yield

         e.adb:3:04: Incorrect spelling of keyword "function"
         e.adb:5:35: missing ".."
         fatal error: maximum number of errors detected
         compilation abandoned

The default setting if no switch is given is 9999. If the number of warnings reaches this limit, then a message is output and further warnings are suppressed, but the compilation is continued. If the number of error messages reaches this limit, then a message is output and the compilation is abandoned. A value of zero means that no limit applies.

Note that the equal sign is optional, so the switches `-gnatm2' and `-gnatm=2' are equivalent.

-gnatf

The f stands for full. Normally, the compiler suppresses error messages that are likely to be redundant. This switch causes all error messages to be generated. In particular, in the case of references to undefined variables. If a given variable is referenced several times, the normal format of messages is

         e.adb:7:07: "V" is undefined (more references follow)

where the parenthetical comment warns that there are additional references to the variable V. Compiling the same program with the `-gnatf' switch yields

         e.adb:7:07: "V" is undefined
         e.adb:8:07: "V" is undefined
         e.adb:8:12: "V" is undefined
         e.adb:8:16: "V" is undefined
         e.adb:9:07: "V" is undefined
         e.adb:9:12: "V" is undefined

The `-gnatf' switch also generates additional information for some error messages. Some examples are:

Details on possibly non-portable unchecked conversion
List possible interpretations for ambiguous calls
Additional details on incorrect parameters

-gnatjnn: In normal operation mode (or if `-gnatj0' is used), then error messages with continuation lines are treated as though the continuation lines were separate messages (and so a warning with two continuation lines counts as three warnings, and is listed as three separate messages).
If the `-gnatjnn' switch is used with a positive value for nn, then messages are output in a different manner. A message and all its continuation lines are treated as a unit, and count as only one warning or message in the statistics totals. Furthermore, the message is reformatted so that no line is longer than nn characters.

-gnatq: The q stands for quit (really 'don't quit'). In normal operation mode, the compiler first parses the program and determines if there are any syntax errors. If there are, appropriate error messages are generated and compilation is immediately terminated. This switch tells GNAT to continue with semantic analysis even if syntax errors have been found. This may enable the detection of more errors in a single run. On the other hand, the semantic analyzer is more likely to encounter some internal fatal error when given a syntactically invalid tree.

-gnatQ

In normal operation mode, the ALI file is not generated if any illegalities are detected in the program. The use of `-gnatQ' forces generation of the ALI file. This file is marked as being in error, so it cannot be used for binding purposes, but it does contain reasonably complete cross-reference information, and thus may be useful for use by tools (e.g., semantic browsing tools or integrated development environments) that are driven from the ALI file. This switch implies `-gnatq', since the semantic phase must be run to get a meaningful ALI file.

In addition, if `-gnatt' is also specified, then the tree file is generated even if there are illegalities. It may be useful in this case to also specify `-gnatq' to ensure that full semantic processing occurs. The resulting tree file can be processed by ASIS, for the purpose of providing partial information about illegal units, but if the error causes the tree to be badly malformed, then ASIS may crash during the analysis.

When `-gnatQ' is used and the generated ALI file is marked as being in error, `gnatmake' will attempt to recompile the source when it finds such an ALI file, including with switch `-gnatc'.

Note that `-gnatQ' has no effect if `-gnats' is specified, since ALI files are never generated if `-gnats' is set.