@end direntry
@copying
-Copyright @copyright{} 1995-2007, 2008 Free Software Foundation
+Copyright @copyright{} 1995-2007, 2008 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2
type of the expression is either @code{Standard.Boolean}, or any type derived
from this standard type.
-If assertions are disabled (switch @code{-gnata} not used), then there
+If assertions are disabled (switch @option{-gnata} not used), then there
is no run-time effect (and in particular, any side effects from the
expression will not occur at run time). (The expression is still
analyzed at compile time, and may cause types to be frozen if they are
corresponding to the argument with a terminating semicolon. Pragmas are
permitted in sequences of declarations, so you can use pragma @code{Debug} to
intersperse calls to debug procedures in the middle of declarations. Debug
-pragmas can be enabled either by use of the command line switch @code{-gnata}
+pragmas can be enabled either by use of the command line switch @option{-gnata}
or by use of the configuration pragma @code{Debug_Policy}.
@node Pragma Debug_Policy
@noindent
If the argument is @code{CHECK}, then pragma @code{DEBUG} is enabled.
If the argument is @code{IGNORE}, then pragma @code{DEBUG} is ignored.
-This pragma overrides the effect of the @code{-gnata} switch on the
+This pragma overrides the effect of the @option{-gnata} switch on the
command line.
@node Pragma Detect_Blocking
pragma. If the parameter is @code{Dynamic},
then the dynamic elaboration
model described in the Ada Reference Manual is used, as though
-the @code{-gnatE} switch had been specified on the command
+the @option{-gnatE} switch had been specified on the command
line. If the parameter is @code{Static}, then the default GNAT static
model is used. This configuration pragma overrides the setting
of the command line. For full details on the elaboration models
Note that pragma @code{Initialize_Scalars} is particularly useful in
conjunction with the enhanced validity checking that is now provided
in GNAT, which checks for invalid values under more conditions.
-Using this feature (see description of the @code{-gnatV} flag in the
+Using this feature (see description of the @option{-gnatV} flag in the
users guide) in conjunction with pragma @code{Initialize_Scalars}
provides a powerful new tool to assist in the detection of problems
caused by uninitialized variables.
@noindent
Similar to pragma @code{Inline} except that inlining is not subject to
-the use of option @code{-gnatn} and the inlining happens regardless of
+the use of option @option{-gnatn} and the inlining happens regardless of
whether this option is used.
@node Pragma Inline_Generic
@code{Poll} in this file makes a call to the appropriate runtime routine
to test for an abort condition.
-Note that polling can also be enabled by use of the @code{-gnatP} switch. See
+Note that polling can also be enabled by use of the @option{-gnatP} switch. See
the @cite{GNAT User's Guide} for details.
@node Pragma Profile (Ravenscar)
information). @var{string_literal} is a static string constant that
specifies the file name to be used in error messages and debugging
information. This is most notably used for the output of @code{gnatchop}
-with the @code{-r} switch, to make sure that the original unchopped
+with the @option{-r} switch, to make sure that the original unchopped
source file is the one referred to.
The second argument must be a string literal, it cannot be a static
The form with a string literal specifies which style options are to be
activated. These are additive, so they apply in addition to any previously
set style check options. The codes for the options are the same as those
-used in the @code{-gnaty} switch to @code{gcc} or @code{gnatmake}.
+used in the @option{-gnaty} switch to @command{gcc} or @command{gnatmake}.
For example the following two methods can be used to enable
layout checking:
activated. The validity checks are first set to include only the default
reference manual settings, and then a string of letters in the string
specifies the exact set of options required. The form of this string
-is exactly as described for the @code{-gnatVx} compiler switch (see the
+is exactly as described for the @option{-gnatVx} compiler switch (see the
GNAT users guide for details). For example the following two methods
can be used to enable validity checking for mode @code{in} and
@code{in out} subprogram parameters:
@end cartouche
@noindent
A compilation is represented by a sequence of files presented to the
-compiler in a single invocation of the @code{gcc} command.
+compiler in a single invocation of the @command{gcc} command.
@sp 1
@cartouche
If the partition contains no main program, or if the main program is in
a language other than Ada, then GNAT
-provides the binder options @code{-z} and @code{-n} respectively, and in
+provides the binder options @option{-z} and @option{-n} respectively, and in
this case a list of units can be explicitly supplied to the binder for
inclusion in the partition (all units needed by these units will also
be included automatically). For full details on the use of these
@noindent
The metrics information for GNAT depends on the performance of the
underlying operating system. The sources of the run-time for tasking
-implementation, together with the output from @code{-gnatG} can be
+implementation, together with the output from @option{-gnatG} can be
used to determine the exact sequence of operating systems calls made
to implement various tasking constructs. Together with appropriate
information on the performance of the underlying operating system,
modified as required. Any tasks requiring stack sizes different from the
default can have an appropriate alternative reference in the pragma.
-You can also use the @code{-d} binder switch to modify the default stack
+You can also use the @option{-d} binder switch to modify the default stack
size.
For access types, the @code{Storage_Size} clause specifies the maximum
@node Determining the Representations chosen by GNAT
@section Determining the Representations chosen by GNAT
@cindex Representation, determination of
-@cindex @code{-gnatR} switch
+@cindex @option{-gnatR} switch
@noindent
Although the descriptions in this section are intended to be complete, it is
used to answer the second question, but it is often easier to just see
what the compiler does.
-For this purpose, GNAT provides the option @code{-gnatR}. If you compile
+For this purpose, GNAT provides the option @option{-gnatR}. If you compile
with this option, then the compiler will output information on the actual
representations chosen, in a format similar to source representation
clauses. For example, if we compile the package:
@end smallexample
@noindent
-using the switch @code{-gnatR} we obtain the following output:
+using the switch @option{-gnatR} we obtain the following output:
@smallexample
Representation information for unit q
@c %**end of header
@copying
-Copyright @copyright{} 1995-2005, 2006, 2007, 2008 Free Software Foundation
+Copyright @copyright{} 1995-2005, 2006, 2007, 2008 Free Software Foundation,
+Inc.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2
source file name pragma. However, if the file name specified has an
extension other than @file{.ads} or @file{.adb} it is necessary to use
a special syntax when compiling the file. The name in this case must be
-preceded by the special sequence @code{-x} followed by a space and the name
+preceded by the special sequence @option{-x} followed by a space and the name
of the language, here @code{ada}, as in:
@smallexample
@command{gnatmake} handles non-standard file names in the usual manner (the
non-standard file name for the main program is simply used as the
argument to gnatmake). Note that if the extension is also non-standard,
-then it must be included in the gnatmake command, it may not be omitted.
+then it must be included in the @command{gnatmake} command, it may not
+be omitted.
@node Alternative File Naming Schemes
@section Alternative File Naming Schemes
@noindent
Interfacing can be done at 3 levels: simple data, subprograms, and
-classes. In the first two cases, GNAT offers a specific @var{Convention
-C_Plus_Plus} (or @var{CPP}) that behaves exactly like @var{Convention C}.
+classes. In the first two cases, GNAT offers a specific @code{Convention
+C_Plus_Plus} (or @code{CPP}) that behaves exactly like @code{Convention C}.
Usually, C++ mangles the names of subprograms, and currently, GNAT does
not provide any help to solve the demangling problem. This problem can be
addressed in two ways:
improperly if set during invocation of the wrong compiler. It is also
very important that the linker uses the proper @file{libgcc.a} GCC
library -- that is, the one from the C++ compiler installation. The
-implicit link command as suggested in the gnatmake command from the
-former example can be replaced by an explicit link command with the
-full-verbosity option in order to verify which library is used:
+implicit link command as suggested in the @command{gnatmake} command
+from the former example can be replaced by an explicit link command with
+the full-verbosity option in order to verify which library is used:
@smallexample
$ gnatbind ada_unit
$ gnatlink -v -v ada_unit file1.o file2.o --LINK=c++
@item -^gnatl^OUTPUT_FILE^=file
@cindex @option{^-gnatl^OUTPUT_FILE^=fname} (@command{gcc})
-This has the same effect as @code{-gnatl} except that the output is
+This has the same effect as @option{-gnatl} except that the output is
written to a file instead of to standard output. If the given name
@file{fname} does not start with a period, then it is the full name
of the file to be written. If @file{fname} is an extension, it is
so @option{-gnatR} with no parameter has the same effect), size and alignment
information is listed for declared array and record types. For
@option{-gnatR2}, size and alignment information is listed for all
-declared types and objects. Finally @code{-gnatR3} includes symbolic
+declared types and objects. Finally @option{-gnatR3} includes symbolic
expressions for values that are computed at run time for
variant records. These symbolic expressions have a mostly obvious
format with #n being used to represent the value of the n'th
@var{linker options} is an optional list of linker specific
switches.
-The default linker called by gnatlink is @var{gcc} which in
+The default linker called by gnatlink is @command{gcc} which in
turn calls the appropriate system linker.
Standard options for the linker such as @option{-lmy_lib} or
@option{-Ldir} can be added as is.
For options that are not recognized by
-@var{gcc} as linker options, use the @var{gcc} switches @option{-Xlinker} or
-@option{-Wl,}.
+@command{gcc} as linker options, use the @command{gcc} switches
+@option{-Xlinker} or @option{-Wl,}.
Refer to the GCC documentation for
details. Here is an example showing how to generate a linker map:
modifications to a source file consist in adding/removing comments,
empty lines, spaces or tabs. This means that if you have changed the
comments in a source file or have simply reformatted it, using this
-switch will tell gnatmake not to recompile files that depend on it
+switch will tell @command{gnatmake} not to recompile files that depend on it
(provided other sources on which these files depend have undergone no
semantic modifications). Note that the debugging information may be
out of date with respect to the sources if the @option{-m} switch causes
@subsection Other Optimization Switches
@cindex Optimization Switches
-Since @code{GNAT} uses the @code{gcc} back end, all the specialized
-@code{gcc} optimization switches are potentially usable. These switches
+Since @code{GNAT} uses the @command{gcc} back end, all the specialized
+@command{gcc} optimization switches are potentially usable. These switches
have not been extensively tested with GNAT but can generally be expected
to work. Examples of switches in this category are
@option{-funroll-loops} and
the various target-specific @option{-m} options (in particular, it has been
observed that @option{-march=pentium4} can significantly improve performance
on appropriate machines). For full details of these switches, see the
-@code{gcc} manual.
+@command{gcc} manual.
@node Optimization and Strict Aliasing
@subsection Optimization and Strict Aliasing
@end smallexample
@noindent
-This program prints out 0 in @code{-O0} or @code{-O1}
-mode, but it prints out 1 in @code{-O2} mode. That's
+This program prints out 0 in @option{-O0} or @option{-O1}
+mode, but it prints out 1 in @option{-O2} mode. That's
because in strict aliasing mode, the compiler can and
does assume that the assignment to @code{v2.all} could not
affect the value of @code{v1.all}, since different types
As implied by the warning message, there are approaches you can use to
avoid the unwanted strict aliasing optimization in a case like this.
-One possibility is to simply avoid the use of @code{-O2}, but
+One possibility is to simply avoid the use of @option{-O2}, but
that is a bit drastic, since it throws away a number of useful
optimizations that do not involve strict aliasing assumptions.
A less drastic approach is to compile the program using the
-option @code{-fno-strict-aliasing}. Actually it is only the
+option @option{-fno-strict-aliasing}. Actually it is only the
unit containing the dereferencing of the suspicious pointer
that needs to be compiled. So in this case, if we compile
unit @code{m} with this switch, then we get the expected
value of zero printed. Analyzing which units might need
the switch can be painful, so a more reasonable approach
-is to compile the entire program with options @code{-O2}
-and @code{-fno-strict-aliasing}. If the performance is
+is to compile the entire program with options @option{-O2}
+and @option{-fno-strict-aliasing}. If the performance is
satisfactory with this combination of options, then the
advantage is that the entire issue of possible "wrong"
optimization due to strict aliasing is avoided.
Once the objects and static libraries are created with these options, the
linker can perform the dead code elimination. You can do this by setting
the @option{-Wl,--gc-sections} option to gcc command or in the
-@option{-largs} section of gnatmake. This will perform a garbage collection of
-code and data never referenced.
+@option{-largs} section of @command{gnatmake}. This will perform a
+garbage collection of code and data never referenced.
If the linker performs a partial link (@option{-r} ld linker option), then you
will need to provide one or several entry point using the
@end smallexample
@noindent
-The attribute @var{Object_Dir} has a string value, the path name of the object
+The attribute @code{Object_Dir} has a string value, the path name of the object
directory. The path name may be absolute or relative to the directory of the
project file. This directory must already exist, and be readable and writable.
@end smallexample
@noindent
-The attribute @var{Exec_Dir} has a string value, the path name of the exec
+The attribute @code{Exec_Dir} has a string value, the path name of the exec
directory. The path name may be absolute or relative to the directory of the
project file. This directory must already exist, and be writable.
@table @code
-@item @var{Casing}
+@item @code{Casing}
This must be a string with one of the three values @code{"lowercase"},
@code{"uppercase"} or @code{"mixedcase"}; these strings are case insensitive.
@noindent
-If @var{Casing} is not specified, then the default is @code{"lowercase"}.
+If @code{Casing} is not specified, then the default is @code{"lowercase"}.
-@item @var{Dot_Replacement}
+@item @code{Dot_Replacement}
This must be a string whose value satisfies the following conditions:
@itemize @bullet
@noindent
If @code{Dot_Replacement} is not specified, then the default is @code{"-"}.
-@item @var{Spec_Suffix}
+@item @code{Spec_Suffix}
This is an associative array (indexed by the programming language name, case
insensitive) whose value is a string that must satisfy the following
conditions:
If @code{Spec_Suffix ("Ada")} is not specified, then the default is
@code{"^.ads^.ADS^"}.
-@item @var{Body_Suffix}
+@item @code{Body_Suffix}
This is an associative array (indexed by the programming language name, case
insensitive) whose value is a string that must satisfy the following
conditions:
If @code{Body_Suffix ("Ada")} is not specified, then the default is
@code{"^.adb^.ADB^"}.
-@item @var{Separate_Suffix}
+@item @code{Separate_Suffix}
This must be a string whose value satisfies the same conditions as
@code{Body_Suffix}. The same "longest suffix" rules apply.
If @code{Separate_Suffix ("Ada")} is not specified, then it defaults to same
value as @code{Body_Suffix ("Ada")}.
-@item @var{Spec}
+@item @code{Spec}
@noindent
You can use the associative array attribute @code{Spec} to define
the source file name for an individual Ada compilation unit's spec. The array
for Spec ("MyPack.MyChild") use "mypack.mychild.spec";
@end smallexample
-@item @var{Body}
+@item @code{Body}
You can use the associative array attribute @code{Body} to
define the source file name for an individual Ada compilation unit's body
@code{^gnatmetric^gnatmetric^}),
and @code{^gnatpp^gnatpp^})
on a set of project units thanks to the combination of the switches
-@code{-P}, @code{-U} and possibly the main unit when one is interested
+@option{-P}, @option{-U} and possibly the main unit when one is interested
in its closure. For instance,
@smallexample
gnat metric -Pproj
(@pxref{The GNAT Make Program gnatmake}).
All the examples in this section are specific to the GNU version of
-make. Although @code{make} is a standard utility, and the basic language
+make. Although @command{make} is a standard utility, and the basic language
is the same, these examples use some advanced features found only in
@code{GNU make}.
The example below presents two methods. The first one, although less
general, gives you more control over the list. It involves wildcard
-characters, that are automatically expanded by @code{make}. Its
+characters, that are automatically expanded by @command{make}. Its
shortcoming is that you need to explicitly specify some of the
organization of your project, such as for instance the directory tree
depth, whether some directories are found in a separate tree,...
The second method is the most general one. It requires an external
-program, called @code{find}, which is standard on all Unix systems. All
+program, called @command{find}, which is standard on all Unix systems. All
the directories found under a given root directory will be added to the
list.
Gnatmem must be supplied with the @file{gmem.out} file and the executable to
examine. If the location of @file{gmem.out} file was not explicitly supplied by
-@code{-i} switch, gnatmem will assume that this file can be found in the
+@option{-i} switch, gnatmem will assume that this file can be found in the
current directory. For example, after you have executed @file{my_program},
@file{gmem.out} can be analyzed by @code{gnatmem} using the command:
It is not always convenient to output the stack usage when the program
is still running. Hence, it is possible to delay this output until program
termination. for a given number of tasks specified as the argument of the
-@code{-u} option. For instance:
+@option{-u} option. For instance:
@smallexample
$ gnatbind -u100 file
larger, but it does not add to the size of the actual executable that
will be loaded into memory, and has no impact on run-time performance. The
generation of debug information is triggered by the use of the
-^-g^/DEBUG^ switch in the gcc or gnatmake command used to carry out
-the compilations. It is important to emphasize that the use of these
-options does not change the generated code.
+^-g^/DEBUG^ switch in the @command{gcc} or @command{gnatmake} command
+used to carry out the compilations. It is important to emphasize that
+the use of these options does not change the generated code.
The debugging information is written in standard system formats that
are used by many tools, including debuggers and profilers. The format
@end ifset
includes extensive documentation on the use
of these commands, together with examples of their use. Furthermore,
-the command @var{help} invoked from within @code{GDB} activates a simple help
+the command @command{help} invoked from within GDB activates a simple help
facility which summarizes the available commands and their options.
In this section we summarize a few of the most commonly
used commands to give an idea of what @code{GDB} is about. You should create
some routines in the DLL have the @code{Stdcall} convention
(@pxref{Windows Calling Conventions}) with stripped @code{@@}@i{nn}
suffix then you'll have to edit @file{api.def} to add it, and specify
-@code{-k} to @code{gnatdll} when creating the import library.
+@option{-k} to @command{gnatdll} when creating the import library.
@noindent
Here are some hints to find the right @code{@@}@i{nn} suffix.
@item building the DLL
-To build the DLL you must use @command{gcc}'s @code{-shared}
+To build the DLL you must use @command{gcc}'s @option{-shared}
option. It is quite simple to use this method:
@smallexample
At this point it is possible to use the DLL by directly linking
against it. Note that you must use the GNAT shared runtime when using
-GNAT shared libraries. This is achieved by using @code{-shared} binder's
+GNAT shared libraries. This is achieved by using @option{-shared} binder's
option.
@smallexample
@item -b @var{address}
@cindex @option{-b} (@code{gnatdll})
Set the relocatable DLL base address. By default the address is
-@var{0x11000000}.
+@code{0x11000000}.
@item -bargs @var{opts}
@cindex @option{-bargs} (@code{gnatdll})
projects / gcc.git / commitdiff