The gcc command accepts numerous switches to control the compilation process, which are fully described in this section.
Compile. Always use this switch when compiling Ada programs.
Note that you may not use gcc without a -c switch to compile and link in one step. This is because the binder must be run, and currently gcc cannot be used to run the XGC Ada binder.
Generate debugging information. This information is stored in the object file and copied from there to the final executable file by the linker, where it can be read by the debugger. You must use the -g switch if you plan on using the debugger or simulator.
Direct XGC Ada to search the dir directory for source files needed by the current compilation (see Section 1.3).
Do not look for source files in the directory containing the source file named in the command line (see Section 1.3).
This switch is used in gcc to redirect the generated object file and its associated ALI file. Beware of this switch with XGC Ada, because it may cause the object file and ALI file to have different names which in turn may confuse the binder and the linker.
n controls the optimization level.
No optimization
Normal optimization, the default if you specify -O without an operand.
Extensive optimization, the default
Extensive optimization with automatic inlining. This applies only to inlining within a unit. See Section 1.2.10 for details on control of inter-unit inlining.
Used in place of -c to cause the assembler source file to be generated, using .s as the extension, instead of the object file. This may be useful if you need to examine the generated assembly code.
Show commands generated by the gcc driver. Normally used only for debugging purposes or if you need to be sure what version of the compiler you are executing.
Execute ver version of the compiler. This is the gcc version, not the XGC Ada version.
Generate warnings for uninitialized variables. You must also specify the -O switch (in other words, This switch works only if optimization is turned on).
Assertions enabled. Pragma Assert and pragma Debug to be activated.
Generate brief messages to stderr even if verbose mode set.
Check syntax and semantics only (no code generation attempted).
Error messages generated immediately, not saved up till end.
Full dynamic elaboration checks.
Full errors. Multiple errors per line, all undefined references.
Ada style checks enabled.
Identifier char set (c=1/2/3/4/8/p/f/n/w).
Wide character encoding method (e=n/h/u/s/e).
Limit file names to n (1-999) characters (k = krunch).
Output full source listing with embedded error messages.
Limit number of detected errors to n (1-999).
Activate inlining across unit boundaries for subprograms for which pragma inline is specified.
Activate inlining across unit boundaries for all subprograms (not just those for which pragma inline is specified. This is equivalent to using -gnatn and adding a pragma inline for every subprogram in the program.
Suppresses all inlining, even if other optimization or inlining switches are set.
Enable other checks, not normally enabled by default, including numeric overflow checking, and access before elaboration checks.
Suppress all checks.
Don't quit; try semantics, even if parse errors.
Reference manual column layout required.
Syntax check only.
Tree output file to be generated.
List units for this compilation.
Verbose mode. Full error output with source lines to stdout.
Warning mode (m=s,e,l for suppress, treat as error, elaboration warnings).
Distribution stub generation (m=r/s for receiver/sender stubs).
Enforce Ada 83 restrictions.
Standard Ada 95 mode
You may combine a sequence of XGC Ada switches into a single switch. For example, the specifying the switch
is equivalent to specifying the following sequence of switches:
The standard default format for error messages is called "brief format". Brief format messages are written to stdout (the standard output file) and have the following form:
The first integer after the file name is the line number and the second integer is the column number. emacs can parse the error messages and point to the referenced character. The following switches allow control over the error message format:
The v stands for verbose. The effect is to write long-format error messages to stdout. 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.
The l stands for list. This switch causes a full listing of the file to be generated. The output is as follows:
1. procedure E is
2. V : Integer;
3. funcion X (Q : Integer)
|
>>> incorrect spelling of keyword "function"
4. return Integer;
|
>>> ";" should be "is"
5. begin
6. return Q + Q;
7. end;
8. begin
9. V := X + X;
10. end E;
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.
The b stands for brief. This switch causes XGC Ada to generate the brief format error messages to stdout as well as the verbose format message or full listing.
The m stands for maximum. n is a decimal integer in the range of 1 to 999 and limits the number of error messages to be generated. For example, using -gnatm2 might yield
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. One particular effect is for the case of references to undefined variables. If a given variable is referenced several times, the normal format of messages is
where the parenthetical comment warns that there are additional references to the variable V. Compiling the same program with the -gnatf switch yields
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 XGC Ada 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.
Normally, the compiler saves up error messages and generates them at the end of compilation in proper sequence. This switch (the "e" stands for error) causes error messages to be generated as soon as they are detected. The use of -gnate usually causes error messages to be generated out of sequence. Use this switch when the compiler terminates abnormally because of an internal error. In this case, the error messages may be lost. Sometimes abnormal terminations are the result of mis-handled error messages, so you may want to run with the -gnate switch to determine whether any error messages were generated before the crash.
In addition to error messages, corresponding to illegalities as defined in the reference manual, the compiler detects two kinds of warning situations.
First, the compiler considers some constructs suspicious and generates a warning message to alert you to a possible error. Second, if the compiler detects a situation that is sure to raise an exception at run time, it generates a warning message. The following shows an example of warning messages:
e.adb:4:24: warning: creation of object may raise Storage_Error e.adb:10:17: warning: static value out of range e.adb:10:17: warning: "Constraint_Error" will be raised at run time
XGC Ada detects a large number of situations which it considers appropriate for the generation of warning messages. As always, warnings are not definite indications of errors. For example, if you do an out of range assignment with the deliberate intention of raising a Constraint_Error exception, then the warning that may be issued does not indicate an error. Some of the situations that XGC Ada issues warnings for (at least some of the time) are:
Possible infinitely recursive calls
Out of range values being assigned
Possible order of elaboration problems
Unreachable code
Variables that are never assigned a value
Variables that are referenced before being initialized
Task entries that are never accepted
Duplicate accepts for the same task entry in a select
Objects that take too much storage
Unchecked conversion with differing sizes
Missing return statements in a function
Incorrect pragmas
Incorrect external names
Allocation from empty storage pool
Potentially blocking operations in protected types
Suspicious parenthesization of expressions
Mismatching bounds in an aggregate
Attempt to return local value by reference
Unrecognized pragmas
Premature instantiation of generic body
Attempt to pack aliased components
Out of bounds array subscript
Wrong length on string assignment
Three switches are available to control the handling of warning messages:
This switch causes warning messages to be generated for entities that are defined but not referenced, and for units that are with'ed and not referenced. In the case of packages, a warning is also generated if no entities in the package are referenced. This means that if the package is referenced but the only references are in use clauses or renames declarations, a warning is still generated. A warning is also generated for a generic package that is with'ed but never instantiated.
This switch causes warning messages to be treated as errors. The warning string still appears, but the warning messages are counted as errors, and prevent the generation of an object file.
The "s" stands for suppress. This switch completely suppresses the output of all warning messages.
This switch causes the generation of additional warning messages relating to elaboration issues. See the separate chapter on elaboration order handling for full details of the use of this switch.
Normally the compiler generates full cross-referencing information in the .ali file. This information is used by a number of tools, including gnatfind and gnatxref. The -gnatx switch suppresses this information. This saves some space and may slightly speed up compilation, but means that these tools cannot be used.
The pragmas Assert and Debug normally have no effect and are ignored. This switch, where "a" stands for assert, causes Assert and Debug pragmas to be activated.
The pragmas have the form:
The Assert pragma causes Boolean-expression to be tested. If the result is True, the pragma has no effect (other than possible side effects from evaluating the expression). If the result is False, the exception Assert_Error declared in the package System.Assertions is raised (passing static-string-expression, if present, as the message associated with the exception). If no string expression is given the default is a string giving the file name and line number of the pragma.
The Debug pragma causes procedure to be called. Note that pragma Debug may appear within a declaration sequence, allowing debugging procedures to be called between declarations.
If you compile with the default options, XGC Ada will insert many run-time checks into the compiled code, including code that performs range checking against constraints, but not arithmetic overflow checking for integer operations (including division by zero) or checks for access before elaboration on subprogram calls. All other run-time checks, as required by the Ada 95 Reference Manual, are generated by default. The following gcc switches refine this default behavior:
Suppress all run-time checks as though you have pragma Suppress (all_checks) in your source. Use this switch to improve the performance of the code at the expense of safety in the presence of invalid data or program bugs.
Enables overflow checking for integer operations. This causes XGC Ada to generate slower and larger executable programs by adding code to check for both overflow and division by zero (resulting in raising Constraint_Error as required by Ada semantics). Note that the -gnato switch does not affect the code generated for any floating-point operations; it applies only to integer operations. For floating-point, XGC Ada has the Machine_Overflows attribute set to False and the normal mode of operation is to generate IEEE NaN and infinite values on overflow or invalid operations (such as dividing 0.0 by 0.0).
Enables dynamic checks for access before elaboration on subprogram calls and generic instantiations. For full details of the effect and use of this switch, see Chapter 1.
The setting of these switches only controls the default setting of the checks. You may modify them using either Suppress (to remove checks) or Unsuppress (to add back suppressed checks) pragmas in the program source.
The s stands for syntax. Run XGC Ada in syntax checking only mode. For example, the command
compiles file x.adb in syntax-check-only mode. You can check a series of files in a single command, and can use wild cards to specify such a group of files. Note that you must specify the -c (compile only) flag in addition to the -gnats flag.
You may use other switches in conjunction with -gnats. In particular, -gnatl and -gnatv are useful to control the format of any generated error messages.
The output is simply the error messages, if any. No object file or ALI file is generated by a syntax-only compilation. Also, no units other than the one specified are accessed. For example, if a unit X with's a unit Y, compiling unit X in syntax check only mode does not access the source file containing unit Y.
Normally, XGC Ada allows only a single unit in a source file. However, this restriction does not apply in syntax-check-only mode, and it is possible to check a file containing multiple compilation units concatenated together. This is primarily used by the gnatchop utility (see Chapter 5).
The c stands for check. Cause the compiler to operate in semantic check mode, with full checking for all illegalities specified in the reference manual, but without generation of any source code (no object or ALI file generated).
Because dependent files must be accessed, you must follow the XGC Ada semantic restrictions on file structuring to operate in this mode:
The needed source files must be accessible (see Section 1.3).
Each file must contain only one compilation unit.
The file name and unit name must match (see Section A.3).
The output consists of error messages as appropriate. No object file or ALI file is generated. The checking corresponds exactly to the notion of legality in the Ada reference manual.
Any unit can be compiled in semantics-checking-only mode, including units that would not normally be compiled (generic library units, subunits, and specifications where a separate body is present).
Although XGC Ada is primarily an Ada 95 compiler, it accepts this switch to specify that an Ada 83 mode program is being compiled. If you specify this switch, XGC Ada rejects Ada 95 extensions and applies Ada 83 semantics. It is not possible to guarantee this switch does a perfect job; for example, some subtle tests of pathological cases, such as are found in ACVC tests that have been removed from the ACVC suite for Ada 95, may not compile correctly. However for practical purposes, using this switch should ensure that programs that compile correctly under the -gnat83 switch can be ported reasonably easily to an Ada 83 compiler. This is the main use of the switch.
With few exceptions (most notably the need to use <> on unconstrained generic formal parameters), it is not necessary to use the -gnat83 switch when compiling Ada 83 programs, because, with rare and obscure exceptions, Ada 95 is upwardly compatible with Ada 83. This means that a correct Ada 83 program is usually also a correct Ada 95 program.
This switch specifies normal Ada 95 mode, and cancels the effect of any previously given -gnat83 switch.
Normally, XGC Ada permits any code layout consistent with the reference manual requirements. This switch ("r" is for "reference manual") enforces the layout conventions suggested by the examples and syntax rules of the Ada Language Reference Manual. For example, an else must line up with an if and code in the then and else parts must be indented. The compile considers violations of the layout rules a syntax error if you specify this switch.
Enforces a set of style conventions that correspond to the style used in the XGC Ada source code. All compiler units are always compiled with the -gnatg switch specified.
You can find the full documentation for the style conventions imposed by -gnatg in the body of the package Style in the compiler sources (in the file style.adb).
You should not normally use the -gnatg switch. However, you must use -gnatg for compiling any language-defined unit, or for adding children to any language-defined unit other than Standard.
Normally XGC Ada recognizes the Latin-1 character set in source program identifiers, as described in the reference manual. This switch causes XGC Ada to recognize alternate character sets in identifiers. c is a single character indicating the character set, as follows:
Latin-1 identifiers
Latin-2 letters allowed in identifiers
Latin-3 letters allowed in identifiers
Latin-4 letters allowed in identifiers
IBM PC letters (code page 437) allowed in identifiers
IBM PC letters (code page 850) allowed in identifiers
Full upper-half codes allowed in identifiers
No upper-half codes allowed in identifiers
Wide-character codes allowed in identifiers
See Section A.2, for full details on the implementation of these character sets.
Specify the method of encoding for wide characters. e is one of the following:
No wide characters allowed (default setting)
Hex encoding
Upper half encoding
Shift/JIS encoding
EUC encoding
See Section A.2.3 for full details on the these encoding methods.
Activates file name "crunching". n, a decimal integer in the range 1-999, indicates the maximum allowable length of a file name (not including the .ads or .adb extension). The default is not to enable file name crunching.
For the source file naming rules, see Section A.3.
The n here is intended to suggest the first syllable of the word "inline". XGC Ada recognizes and processes Inline pragmas. However, for the inlining to actually occur, optimization must be enabled. To enable inlining across unit boundaries, this is, inlining a call in one unit of a subprogram declared in a with'ed unit, you must also specify this switch. In the absence of this switch, XGC Ada does not attempt inlining across units and does not need to access the bodies of subprograms for which pragma Inline is specified if they are not in the current unit.
If you specify this the compiler will access these bodies, creating an extra source dependency for the resulting object file, and where possible, the call will be in-lined. See Section D.3 for further details on when inlining is possible.
This switch enforces a more extreme form of inlining across unit boundaries. It causes the compiler to proceed as though the normal (pragma) inlining switch was set, and to assume that there is a pragma Inline for every subprogram referenced by the compiled unit.
Cause XGC Ada to write the internal tree for a unit to a file (with the extension .atb for a body or .ats for a spec). This is not normally required, but is used by separate analysis tools. Typically these tools do the necessary compilations automatically, so you should never have to specify this switch in normal operation.
Print a list of units required by this compilation on stdout. The listing includes all units on which the unit being compiled depends either directly or indirectly.
Activate internal debugging switches. x is a letter or digit, or string of letters or digits, which specifies the type of debugging outputs desired. Normally these are used only for internal development or system debugging purposes. You can find full documentation for these switches in the body of the Debug unit in the compiler source file debug.adb.
One switch you may wish to use is -gnatdg, which causes a listing of the generated code in Ada source form. For example, all tasking constructs are reduced to appropriate run-time library calls. The syntax of this listing is close to normal Ada with the following additions:
Shows the storage pool being used for an allocator.
Shows the finalization (cleanup) procedure for a scope.
Conditional expression equivalent to the x?y:z construction in C.
A conversion with floating-point truncation instead of rounding.
A conversion that bypasses normal Ada semantic checking. In particular enumeration types and fixed-point types are treated simply as integers.
Combines the above two cases.
A division or multiplication of fixed-point values which are treated as integers without any kind of scaling.
Shows the storage pool associated with a free statement.
Shows the point at which typename is frozen, with possible associated actions to be performed at the freeze point.
Reference (and hence definition) to internal type itype.
Intrinsic function call.
Declaration of label labelname.
A multiple concatenation (same effect as expr & expr & expr, but handled more efficiently).
Raise the Constraint_Error exception.
A pointer to the result of evaluating expression.
An unchecked conversion of source-expression to target-type.
Used to represent internal real literals (that) have no exact representation in base 2-16 (for example, the result of compile time evaluation of the expression 1.0/27.0).