@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
@itemize @bullet
@item
-@code{Functions}, @code{utility program names}, @code{standard names},
+@code{Functions}, @command{utility program names}, @code{standard names},
and @code{classes}.
@item
-@samp{Option flags}
+@option{Option flags}
@item
-@file{File Names}, @file{button names}, and @file{field names}.
+@file{File names}, @samp{button names}, and @samp{field names}.
@item
-@var{Variables}.
+@code{Variables}, @env{environment variables}, and @var{metasyntactic
+variables}.
@item
@emph{Emphasis}.
@noindent
The basic character set is Latin-1. This character set is defined by ISO
standard 8859, part 1. The lower half (character codes @code{16#00#}
-... @code{16#7F#)} is identical to standard ASCII coding, but the upper half
+@dots{} @code{16#7F#)} is identical to standard ASCII coding, but the upper half
is used to represent additional characters. These include extended letters
used by European languages, such as French accents, the vowels with umlauts
used in German, and the extra letter A-ring used in Swedish.
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:
@item
Using GNAT and G++ from two different GCC installations: If both
-compilers are on the PATH, the previous method may be used. It is
-important to note that environment variables such as C_INCLUDE_PATH,
-GCC_EXEC_PREFIX, BINUTILS_ROOT, and GCC_ROOT will affect both compilers
+compilers are on the @env{PATH}, the previous method may be used. It is
+important to note that environment variables such as
+@env{C_INCLUDE_PATH}, @env{GCC_EXEC_PREFIX}, @env{BINUTILS_ROOT}, and
+@env{GCC_ROOT} will affect both compilers
at the same time and may make one of the two compilers operate
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++
@b{#include} <iostream>
@b{using namespace} std;
-void Check_Carnivore (Carnivore *obj) @{ ... @}
-void Check_Domestic (Domestic *obj) @{ ... @}
-void Check_Animal (Animal *obj) @{ ... @}
-void Check_Dog (Dog *obj) @{ ... @}
+void Check_Carnivore (Carnivore *obj) @{@dots{}@}
+void Check_Domestic (Domestic *obj) @{@dots{}@}
+void Check_Animal (Animal *obj) @{@dots{}@}
+void Check_Dog (Dog *obj) @{@dots{}@}
@b{extern} "C" @{
void adainit (void);
@cindex cannot generate code
If you attempt to compile any of these files, you will get one of the
-following error messages (where fff is the name of the file you compiled):
+following error messages (where @var{fff} is the name of the file you compiled):
@smallexample
cannot generate code for file @var{fff} (package spec)
@item -gnatA
@cindex @option{-gnatA} (@command{gcc})
-Avoid processing @file{gnat.adc}. If a gnat.adc file is present,
+Avoid processing @file{gnat.adc}. If a @file{gnat.adc} file is present,
it will be ignored.
@item -gnatb
Control level of validity checking. See separate section describing
this feature.
-@item ^-gnatw@var{xxx}^/WARNINGS=(@var{option}[,...])^
+@item ^-gnatw@var{xxx}^/WARNINGS=(@var{option}[,@dots{}])^
@cindex @option{^-gnatw^/WARNINGS^} (@command{gcc})
Warning mode where
^@var{xxx} is a string of option letters that^the list of options^ denotes
@cindex @option{-gnatx} (@command{gcc})
Suppress generation of cross-reference information.
-@item ^-gnaty^/STYLE_CHECKS=(option,option..)^
+@item ^-gnaty^/STYLE_CHECKS=(option,option@dots{})^
@cindex @option{^-gnaty^/STYLE_CHECKS^} (@command{gcc})
Enable built-in style checks (@pxref{Style Checking}).
This is the default behavior in the absence of an @option{/OPTIMIZE}
qualifier.
-@item /OPTIMIZE[=(keyword[,...])]
+@item /OPTIMIZE[=(keyword[,@dots{}])]
@cindex @option{/OPTIMIZE} (@code{GNAT COMPILE})
Selects the level of optimization for your program. The supported
keywords are as follows:
@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
@smallexample @c ada
procedure K (S : String) is
pragma Assert (S'First = 1);
- ...
+ @dots{}
@end smallexample
@item -gnatwx
and operands for attributes such as @code{Pos}. Checks are also made
on individual component values for composite comparisons, and on the
expressions in type conversions and qualified expressions. Checks are
-also made on explicit ranges using .. (e.g. slices, loops etc).
+also made on explicit ranges using @samp{..} (e.g. slices, loops etc).
@item -gnatVp
@emph{Validity checks for parameters.}
@findex Style checking
@noindent
-The @option{-gnaty^x^(option,option,...)^} switch
+The @option{-gnaty^x^(option,option,@dots{})^} switch
@cindex @option{-gnaty} (@command{gcc})
causes the compiler to
enforce specified style rules. A limited set of style rules has been used
specified style check, an appropriate warning message is given, preceded by
the character sequence ``(style)''.
@ifset vms
-@code{(option,option,...)} is a sequence of keywords
+@code{(option,option,@dots{})} is a sequence of keywords
@end ifset
@ifclear vms
The string @var{x} is a sequence of letters or digits
annotation
language (where ``@code{--#}'' is used). For the purposes of this rule, a
special character is defined as being in one of the ASCII ranges
-@code{16#21#..16#2F#} or @code{16#3A#..16#3F#}.
+@code{16#21#@dots{}16#2F#} or @code{16#3A#@dots{}16#3F#}.
Note that this usage is not permitted
in GNAT implementation units (i.e. when @option{-gnatg} is used).
X3 : Integer := Integer'Last;
X4 : Integer range 1 .. 5 := 5;
F : Float := 2.0E+20;
-...
+@dots{}
X1 := X1 + 1;
X2 := X2 + 1;
X3 := Integer (F);
(to meet the requirement of H.3.1(9) in a
convenient manner).
-@item @var{expr} && @var{expr} && @var{expr} ... && @var{expr}
+@item @var{expr} && @var{expr} && @var{expr} @dots{} && @var{expr}
A multiple concatenation (same effect as @var{expr} & @var{expr} &
@var{expr}, but handled more efficiently).
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
@item
@findex ADA_PRJ_INCLUDE_FILE
Each of the directories listed in the text file whose name is given
-by the @code{ADA_PRJ_INCLUDE_FILE} ^environment variable^logical name^.
+by the @env{ADA_PRJ_INCLUDE_FILE} ^environment variable^logical name^.
@noindent
-@code{ADA_PRJ_INCLUDE_FILE} is normally set by gnatmake or by the ^gnat^GNAT^
+@env{ADA_PRJ_INCLUDE_FILE} is normally set by gnatmake or by the ^gnat^GNAT^
driver when project files are used. It should not normally be set
by other means.
@item
@findex ADA_INCLUDE_PATH
Each of the directories listed in the value of the
-@code{ADA_INCLUDE_PATH} ^environment variable^logical name^.
+@env{ADA_INCLUDE_PATH} ^environment variable^logical name^.
@ifclear vms
Construct this value
-exactly as the @code{PATH} environment variable: a list of directory
+exactly as the @env{PATH} environment variable: a list of directory
names separated by colons (semicolons when working with the NT version).
@end ifclear
@ifset vms
In addition, you can specify @option{-Sev} to indicate that the value is
to be set at run time. In this case, the program will look for an environment
@cindex GNAT_INIT_SCALARS
-variable of the form @code{GNAT_INIT_SCALARS=xx}, where xx is one
+variable of the form @env{GNAT_INIT_SCALARS=xx}, where xx is one
of @option{in/lo/hi/xx} with the same meanings as above.
If no environment variable is found, or if it does not have a valid value,
then the default is @option{in} (invalid values).
@item
@findex ADA_PRJ_OBJECTS_FILE
Each of the directories listed in the text file whose name is given
-by the @code{ADA_PRJ_OBJECTS_FILE} ^environment variable^logical name^.
+by the @env{ADA_PRJ_OBJECTS_FILE} ^environment variable^logical name^.
@noindent
-@code{ADA_PRJ_OBJECTS_FILE} is normally set by gnatmake or by the ^gnat^GNAT^
+@env{ADA_PRJ_OBJECTS_FILE} is normally set by gnatmake or by the ^gnat^GNAT^
driver when project files are used. It should not normally be set
by other means.
@item
@findex ADA_OBJECTS_PATH
Each of the directories listed in the value of the
-@code{ADA_OBJECTS_PATH} ^environment variable^logical name^.
+@env{ADA_OBJECTS_PATH} ^environment variable^logical name^.
@ifset unw
Construct this value
-exactly as the @code{PATH} environment variable: a list of directory
+exactly as the @env{PATH} environment variable: a list of directory
names separated by colons (semicolons when working with the NT version
of GNAT).
@end ifset
@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:
@ifset vms
@command{gnatlink} accepts the following types of extra files on the command
-line: objects (.OBJ), libraries (.OLB), sharable images (.EXE), and
-options files (.OPT). These are recognized and handled according to their
-extension.
+line: objects (@file{.OBJ}), libraries (@file{.OLB}), sharable images
+(@file{.EXE}), and options files (@file{.OPT}). These are recognized and
+handled according to their extension.
@end ifset
@node Switches for gnatlink
If @var{mode_switches} are present, they must always be placed after
the last @var{file_name} and all @code{switches}.
-If you are using standard file extensions (.adb and .ads), then the
+If you are using standard file extensions (@file{.adb} and @file{.ads}), then the
extension may be omitted from the @var{file_name} arguments. However, if
you are using non-standard extensions, then it is required that the
extension be given. A relative or absolute directory path can be
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
have to be marked as non-abortable.
If you use neither the @code{abort} statement, nor asynchronous transfer
-of control (@code{select .. then abort}), then this distributed overhead
+of control (@code{select @dots{} then abort}), then this distributed overhead
is removed, which may have a general positive effect in improving
overall performance. Especially code involving frequent use of tasking
constructs and controlled types will show much improved performance.
pragma Inline (Q);
end R;
package body R is
- ...
+ @dots{}
end R;
with R;
procedure Main is
begin
- ...
+ @dots{}
R.Q;
end Main;
@end cartouche
@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
type Int2A is access Int2;
Int1V : Int1A;
Int2V : Int2A;
- ...
+ @dots{}
begin
- ...
+ @dots{}
for J in Data'Range loop
if Data (J) = Int1V.all then
Int2V.all := Int2V.all + 1;
end if;
end loop;
- ...
+ @dots{}
end R;
@end cartouche
@end smallexample
@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
The @code{gnatchop} command has the form:
@smallexample
-$ gnatchop switches @var{file name} [@var{file name} @var{file name} ...]
+$ gnatchop switches @var{file name} [@var{file name} @var{file name} @dots{}]
[@var{directory}]
@end smallexample
@noindent
will look for Ada units in all files with the @file{.ada} extension,
and will add to the list of file for project @file{prj.gpr} the C files
-with extension ".^c^C^".
+with extension @file{.^c^C^}.
@item ^-h^/HELP^
@cindex @option{^-h^/HELP^} (@code{gnatname})
@group
with GUI, Comm;
procedure App_Main is
- ...
+ @dots{}
begin
- ...
+ @dots{}
end App_Main;
@end group
@end smallexample
@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.
with "project1", "utilities.gpr";
with "/namings/apex.gpr";
project Main is
- ...
+ @dots{}
@end group
@end smallexample
sources. This can be achieved through the @emph{project extension} facility.
@smallexample @c projectfile
- project Modified_Utilities extends "/baseline/utilities.gpr" is ...
+ project Modified_Utilities extends "/baseline/utilities.gpr" is @dots{}
@end smallexample
@noindent
Create project A1 that extends A, placing modified P1 there:
@smallexample @c 0projectfile
-project A1 extends "(...)/A" is
+project A1 extends "(@dots{})/A" is
end A1;
@end smallexample
P3 there:
@smallexample @c 0projectfile
-with "(...)/A1";
-project C1 extends all "(...)/C" is
+with "(@dots{})/A1";
+project C1 extends all "(@dots{})/C" is
end C1;
@end smallexample
@end enumerate
Mode : Mode_Type := external ("MODE");
case Mode is
when "Debug" =>
- ...
+ @dots{}
@end group
@end smallexample
with "/global/apex.gpr";
project Example is
package Naming renames Apex.Naming;
- ...
+ @dots{}
end Example;
@end group
@end smallexample
@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
-- Ada source file:
with Pack;
procedure Foo_Main is
- ...
+ @dots{}
end Foo_Main;
@end group
@end smallexample
@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
@noindent
The command invocation for @code{gnatxref} is:
@smallexample
-$ gnatxref [switches] sourcefile1 [sourcefile2 ...]
+$ gnatxref [switches] sourcefile1 [sourcefile2 @dots{}]
@end smallexample
@noindent
@smallexample
$ gnatfind [switches] pattern[:sourcefile[:line[:column]]]
- [file1 file2 ...]
+ [file1 file2 @dots{}]
@end smallexample
@noindent
line of the first character of the identifier for the
entity reference. Columns are numbered from 1.
-@item file1 file2 ...
+@item file1 file2 @dots{}
The search will be restricted to these source files. If none are given, then
the search will be done for every library file in the search path.
These file must appear only after the pattern or sourcefile.
These file names are considered to be regular expressions, so for instance
-specifying 'source*.adb' is the same as giving every file in the current
-directory whose name starts with 'source' and whose extension is 'adb'.
+specifying @file{source*.adb} is the same as giving every file in the current
+directory whose name starts with @file{source} and whose extension is
+@file{adb}.
The location of the spec of the entity will always be displayed, even if it
-isn't in one of file1, file2,... The occurrences of the entity in the
-separate units of the ones given on the command line will also be displayed.
+isn't in one of @file{file1}, @file{file2},@enddots{} The occurrences
+of the entity in the separate units of the ones given on the command
+line will also be displayed.
Note that if you specify at least one file in this part, @code{gnatfind} may
-sometimes not be able to find the body of the subprograms...
+sometimes not be able to find the body of the subprograms.
@end table
@leftskip=.5cm
@end iftex
@group
-regexp ::= term @{| term@} -- alternation (term or term ...)
+regexp ::= term @{| term@} -- alternation (term or term @dots{})
term ::= item @{item@} -- concatenation (item then item)
@table @samp
@item abcde|fghi
-will match any of the two strings 'abcde' and 'fghi'.
+will match any of the two strings @samp{abcde} and @samp{fghi},
@item abc*d
-will match any string like 'abd', 'abcd', 'abccd', 'abcccd', and so on
+will match any string like @samp{abd}, @samp{abcd}, @samp{abccd},
+@samp{abcccd}, and so on,
@item [a-z]+
will match any string which has only lowercase characters in it (and at
@table @option
@item ^-M@i{nnn}^/LINE_LENGTH_MAX=@i{nnn}^
@cindex @option{^-M^/LINE_LENGTH^} (@command{gnatpp})
-Maximum line length, @i{nnn} from 32 ..256, the default value is 79
+Maximum line length, @i{nnn} from 32@dots{}256, the default value is 79
@item ^-i@i{nnn}^/INDENTATION_LEVEL=@i{nnn}^
@cindex @option{^-i^/INDENTATION_LEVEL^} (@command{gnatpp})
-Indentation level, @i{nnn} from 1 .. 9, the default value is 3
+Indentation level, @i{nnn} from 1@dots{}9, the default value is 3
@item ^-cl@i{nnn}^/CONTINUATION_INDENT=@i{nnn}^
@cindex @option{^-cl^/CONTINUATION_INDENT^} (@command{gnatpp})
Indentation level for continuation lines (relative to the line being
-continued), @i{nnn} from 1 .. 9.
+continued), @i{nnn} from 1@dots{}9.
The default
value is one less then the (normal) indentation level, unless the
indentation is set to 1 (in which case the default value for continuation
lines
#elsif @i{expression} [then]
lines
-...
+@dots{}
#else
lines
#end if;
files and libraries in the directories mentioned in the project file. For
convenience, the user's library project file should be installed in a location
that will be searched automatically by the GNAT
-builder. These are the directories referenced in the @code{ADA_PROJECT_PATH}
+builder. These are the directories referenced in the @env{ADA_PROJECT_PATH}
environment variable (@pxref{Importing Projects}), and also the default GNAT
library location that can be queried with @command{gnatls -v} and is usually of
the form $gnat_install_root/lib/gnat.
@smallexample @c projectfile
with "my_lib";
project My_Proj is
- ...
+ @dots{}
end My_Proj;
@end smallexample
@itemize @bullet
@item
@file{/dir/my_lib_src} has been added by the user to the environment
-variable @code{ADA_INCLUDE_PATH}, or by the administrator to the file
+variable @env{ADA_INCLUDE_PATH}, or by the administrator to the file
@file{ada_source_path}
@item
@file{/dir/my_lib_obj} has been added by the user to the environment
-variable @code{ADA_OBJECTS_PATH}, or by the administrator to the file
+variable @env{ADA_OBJECTS_PATH}, or by the administrator to the file
@file{ada_object_path}
@item
a pragma @code{Linker_Options} has been added to one of the sources.
(@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}.
## csc is put in the top level directory (where the Makefile is).
## toplevel_dir __ first_csc (sources) __ lib (will contain the library)
## \_ second_csc (sources) __ lib (will contain the library)
-## \_ ...
+## \_ @dots{}
## Although this Makefile is build for shared library, it is easy to modify
## to build partial link objects instead (modify the lines with -shared and
## gnatlink below)
# The following variable should give the directory containing libgnat.so
# You can get this directory through 'gnatls -v'. This is usually the last
# directory in the Object_Path.
-GLIB=...
+GLIB=@dots{}
# The directories for the libraries
# (This macro expands the list of CSC to the list of shared libraries, you
# by a new tool, gnatmlib
$@{LIB_DIR@}:
mkdir -p $@{dir $@@ @}
- cd $@{dir $@@ @}; gcc -shared -o $@{notdir $@@ @} ../*.o -L$@{GLIB@} -lgnat
- cd $@{dir $@@ @}; cp -f ../*.ali .
+ cd $@{dir $@@ @} && gcc -shared -o $@{notdir $@@ @} ../*.o -L$@{GLIB@} -lgnat
+ cd $@{dir $@@ @} && cp -f ../*.ali .
# The dependencies for the modules
# Note that we have to force the expansion of *.o, since in some cases
store it in a variable. For small projects, it is often easier to
specify each of them by hand, since you then have full control over what
is the proper order for these directories, which ones should be
-included...
+included.
However, in larger projects, which might involve hundreds of
subdirectories, it might be more convenient to generate this list
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,...
+depth, whether some directories are found in a separate tree, @enddots{}
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:
@ifclear vms
To ensure that a clean exception is signalled for stack
overflow, set the environment variable
-@code{GNAT_STACK_LIMIT} to indicate the maximum
+@env{GNAT_STACK_LIMIT} to indicate the maximum
stack area that can be used, as in:
@cindex GNAT_STACK_LIMIT
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
@smallexample @c ada
for I in 1 .. N loop
- ...
+ @dots{}
end loop;
@end smallexample
@smallexample @c ada
subtype S is Integer range 1..N;
-...
+@dots{}
for I in S loop
- ...
+ @dots{}
end loop;
@end smallexample
@item -f
@cindex @option{-f} (@code{gnathtml})
By default, gnathtml will generate html links only for global entities
-('with'ed units, global variables and types,...). If you specify
+('with'ed units, global variables and types,@dots{}). If you specify
@option{-f} on the command line, then links will be generated for local
entities too.
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
0040138B at d:/stb/stb.adb:10
0040139C at d:/stb/stb.adb:14
00401335 at d:/stb/b~stb.adb:104
-004011C4 at /build/.../crt1.c:200
-004011F1 at /build/.../crt1.c:222
+004011C4 at /build/@dots{}/crt1.c:200
+004011F1 at /build/@dots{}/crt1.c:222
77E892A4 in ?? at ??:0
@end smallexample
0040138B in stb.p2 at d:/stb/stb.adb:10
0040139C in stb at d:/stb/stb.adb:14
00401335 in main at d:/stb/b~stb.adb:104
-004011C4 in <__mingw_CRTStartup> at /build/.../crt1.c:200
-004011F1 in <mainCRTStartup> at /build/.../crt1.c:222
+004011C4 in <__mingw_CRTStartup> at /build/@dots{}/crt1.c:200
+004011F1 in <mainCRTStartup> at /build/@dots{}/crt1.c:222
@end smallexample
@noindent
@cartouche
X, Y : Integer := Init_Func;
Q : String (X .. Y) := "abc";
-...
+@dots{}
for Q'Address use Compute_Address;
@end cartouche
@end smallexample
X, Y : Integer := Init_Func;
Q_Address : constant Address := Compute_Address;
Q : String (X .. Y) := "abc";
-...
+@dots{}
for Q'Address use Q_Address;
@end cartouche
@end group
The user can alternatively specify a processor on which the program should run
to emulate a single-processor system. The multiprocessor / uniprocessor choice
is made by
-setting the environment variable @code{GNAT_PROCESSOR}
-@cindex @code{GNAT_PROCESSOR} environment variable (on Sparc Solaris)
+setting the environment variable @env{GNAT_PROCESSOR}
+@cindex @env{GNAT_PROCESSOR} environment variable (on Sparc Solaris)
to one of the following:
@table @code
@group
@cartouche
with Unit_1;
-package Unit_2 is ...
+package Unit_2 is @dots{}
@end cartouche
@end group
@end smallexample
package body Math is
function Sqrt (Arg : Float) return Float is
begin
- ...
+ @dots{}
end Sqrt;
end Math;
@end group
with Stuff;
procedure Main is
begin
- ...
+ @dots{}
end Main;
@end group
@end cartouche
@smallexample @c ada
@group
@cartouche
-package X is ...
+package X is @dots{}
-package Y is ...
+package Y is @dots{}
with X;
-package body Y is ...
+package body Y is @dots{}
with Y;
-package body X is ...
+package body X is @dots{}
@end cartouche
@end group
@end smallexample
which means you would have to
elaborate the body of @code{Y} first, but that @code{with}'s @code{X},
which means
-you have to elaborate the body of @code{X} first, but ... and we have a
+you have to elaborate the body of @code{X} first, but @dots{} and we have a
loop that cannot be broken.
It is true that the binder can in many cases guess an order of elaboration
@smallexample @c ada
@group
FP_Initialize_Required : constant Boolean := True;
-...
+@dots{}
if FP_Initialize_Required then
-...
+@dots{}
end if;
@end group
@end smallexample
package Config is
FP_Initialize_Required : constant Boolean := True;
Reset_Available : constant Boolean := False;
- ...
+ @dots{}
end Config;
@end group
@end smallexample
@smallexample @c ada
@group
-if ... then
- ... -- some statements
+if @dots{} then
+ @dots{} -- some statements
else
pragma Assert (Num_Cases < 10);
null;
declare
X : Bit_String (1 .. 10);
begin
- ...
+ @dots{}
end;
else
declare
X : Large_Bit_String (1 .. 1000);
begin
- ...
+ @dots{}
end;
end if;
@end group
@smallexample @c ada
@group
if Ada_2005 then
- ... neat Ada 2005 code
+ @dots{} neat Ada 2005 code
else
- ... not quite as neat Ada 95 code
+ @dots{} not quite as neat Ada 95 code
end if;
@end group
@end smallexample
character literals that were legal in Ada 83 are illegal in Ada 95.
For example:
@smallexample @c ada
- for Char in 'A' .. 'Z' loop ... end loop;
+ for Char in 'A' .. 'Z' loop @dots{} end loop;
@end smallexample
@noindent
@code{Character} or @code{Wide_Character}. The simplest correction
is to make the type explicit; e.g.:
@smallexample @c ada
- for Char in Character range 'A' .. 'Z' loop ... end loop;
+ for Char in Character range 'A' .. 'Z' loop @dots{} end loop;
@end smallexample
@item New reserved words
@noindent
It is possible to control where temporary files gets created by setting
-the TMP environment variable. The file will be created:
+the @env{TMP} environment variable. The file will be created:
@itemize
-@item Under the directory pointed to by the TMP environment variable if
+@item Under the directory pointed to by the @env{TMP} environment variable if
this directory exists.
-@item Under c:\temp, if the TMP environment variable is not set (or not
-pointing to a directory) and if this directory exists.
+@item Under @file{c:\temp}, if the @env{TMP} environment variable is not
+set (or not pointing to a directory) and if this directory exists.
@item Under the current working directory otherwise.
@end itemize
EXPORTS
@i{symbol1}
@i{symbol2}
- ...
+ @dots{}
@end cartouche
@end group
@end smallexample
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
-$ gcc -shared -o api.dll obj1.o obj2.o ...
+$ gcc -shared -o api.dll obj1.o obj2.o @dots{}
@end smallexample
It is important to note that in this case all symbols found in the
file, @pxref{The Definition File}. For example:
@smallexample
-$ gcc -shared -o api.dll api.def obj1.o obj2.o ...
+$ gcc -shared -o api.dll api.def obj1.o obj2.o @dots{}
@end smallexample
If you use a definition file you must export the elaboration procedures
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
return Fact;
end Factorial;
- ...
+ @dots{}
-- The remainder of this package body is unchanged.
end API;
@end cartouche
@cartouche
package API is
Count : Integer := 0;
- ...
+ @dots{}
-- Remainder of the package omitted.
end API;
@end cartouche
@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})