any of these three cases, the check name must be visible. A check
name is visible if it is in the configuration pragmas applying to
the current unit, or if it appears at the start of any unit that
-is part of the dependency set of the current unit (e.g. units that
-are mentioned in @code{with} clauses.
+is part of the dependency set of the current unit (e.g., units that
+are mentioned in @code{with} clauses).
@node Pragma Comment
@unnumberedsec Pragma Comment
is known at compile time, and has the value True. The set of expressions
whose values are known at compile time includes all static boolean
expressions, and also other values which the compiler can determine
-at compile time (e.g. the size of a record type set by an explicit
+at compile time (e.g., the size of a record type set by an explicit
size representation clause, or the value of a variable which was
initialized to a constant and is known not to have been modified).
If these conditions are met, an error message is generated using
is reserved for @var{LOCAL_NAME} by the assembler and it will be resolved
to the same address as @var{static_string_EXPRESSION} by the linker.
-The actual linker name for the target must be used (e.g. the fully
+The actual linker name for the target must be used (e.g.@: the fully
encoded name with qualification in Ada, or the mangled name in C++),
or it must be declared using the C convention with @code{pragma Import}
or @code{pragma Export}.
Some file formats do not support arbitrary sections so not all target
machines support this pragma. The use of this pragma may cause a program
execution to be erroneous if it is used to place an entity into an
-inappropriate section (e.g. a modified variable into the @code{.text}
+inappropriate section (e.g.@: a modified variable into the @code{.text}
section). See also @code{pragma Persistent_BSS}.
@smallexample @c ada
mode. This is primarily intended for dealing with the situations
in the predefined library where subprograms or packages
have become defined as obsolescent in Ada 2005
-(e.g. in Ada.Characters.Handling), but may be used anywhere.
+(e.g.@: in Ada.Characters.Handling), but may be used anywhere.
The following examples show typical uses of this pragma:
The argument can be an identifier or a character literal. In the identifier
case, it is one of @code{HEX}, @code{UPPER}, @code{SHIFT_JIS},
@code{EUC}, @code{UTF8}, or @code{BRACKETS}. In the character literal
-case it is correspondingly one of the characters h,u,s,e,8,b.
+case it is correspondingly one of the characters @samp{h}, @samp{u},
+@samp{s}, @samp{e}, @samp{8}, or @samp{b}.
Note that when the pragma is used within a file, it affects only the
encoding within that file, and does not affect withed units, specs,
is the hexadecimal representation of the virtual address of the corresponding
task control block. If the variable is an array of tasks, the image of each
task will have the form of an indexed component indicating the position of a
-given task in the array, eg. Group(5)_XXXXXXX. If the task is a
+given task in the array, e.g.@: Group(5)_XXXXXXX. If the task is a
component of a record, the image of the task will have the form of a selected
component. These rules are fully recursive, so that the image of a task that
is a subcomponent of a composite object corresponds to the expression that
there are no limitations on placement of such components, and they
may start and end at arbitrary bit boundaries.
-If the component size is not a power of 2 (e.g. 3 or 5), then
+If the component size is not a power of 2 (e.g.@: 3 or 5), then
an array of this type longer than 64 bits must always be placed on
on a storage unit (byte) boundary and occupy an integral number
of storage units (bytes). Any component clause that does not
streams by mixed language programs. Note though that system level buffering is
explicitly enabled at elaboration of the standard I/O packages and that can
have an impact on mixed language programs, in particular those using I/O before
-calling the Ada elaboration routine (e.g. adainit). It is recommended to call
+calling the Ada elaboration routine (e.g.@: adainit). It is recommended to call
the Ada elaboration routine before performing any I/O or when impractical,
flush the common I/O streams and in particular Standard_Output before
elaborating the Ada code.
-- If text_translation_required is true, then the following
-- functions may be used to dynamically switch a file from
-- binary to text mode or vice versa. These functions have
- -- no effect if text_translation_required is false (i.e. in
+ -- no effect if text_translation_required is false (i.e.@: in
-- normal UNIX mode). Use fileno to get a stream handle.
procedure set_binary_mode (handle : int);
procedure set_text_mode (handle : int);
@cindex pragma @code{Shared_Passive}
the purpose of designating shared passive packages.
This allows the use of passive partitions in the
-context described in the Ada Reference Manual; i.e. for communication
+context described in the Ada Reference Manual; i.e., for communication
between separate partitions of a distributed application using the
features in Annex E.
@cindex Annex E
needed. The only requirement is that the two programs have a
common shared file system. It is even possible for programs
running on different machines with different architectures
-(e.g. different endianness) to communicate via the data in
+(e.g.@: different endianness) to communicate via the data in
a passive partition.
@item Persistence between program runs
@item Communication_Protocol
This is a simple string attribute. Its value is the name of the protocol
to use to communicate with the target in a cross-compilation environment,
-e.g. @code{"wtx"} or @code{"vxworks"}.
+e.g.@: @code{"wtx"} or @code{"vxworks"}.
@item Compiler_Command
This is an associative array attribute, whose domain is a language name. Its
@item VCS_Kind
This is a simple attribute. Its value is a string used to specify the
-Version Control System (VCS) to be used for this project, e.g CVS, RCS
+Version Control System (VCS) to be used for this project, e.g.@: CVS, RCS
ClearCase or Perforce.
@item VCS_File_Check
Documentation on Emacs and other tools is available in Emacs under the
pull-down menu button: @code{Help - Info}. After selecting @code{Info},
-use the middle mouse button to select a topic (e.g. Emacs).
+use the middle mouse button to select a topic (e.g.@: Emacs).
In a character cell terminal, do @kbd{C-h i} to invoke info, and then @kbd{m}
(stands for menu) followed by the menu item desired, as in @kbd{m Emacs}, to
Select @code{Debug}, then @code{Run}. When the
@code{Program Arguments} window appears, click @code{OK}.
A console window will appear; enter some line of text,
-e.g. @code{abcde}, at the prompt.
+e.g.@: @code{abcde}, at the prompt.
The program will pause execution when it gets to the
breakpoint, and the corresponding line is highlighted.
Any character in the range 80-FF allowed in identifiers, and all are
considered distinct. In other words, there are no uppercase and lowercase
equivalences in this range. This is useful in conjunction with
-certain encoding schemes used for some foreign character sets (e.g.
+certain encoding schemes used for some foreign character sets (e.g.,
the typical method of representing Chinese characters on the PC).
@item No Upper-Half
An exception arises if the file name generated by the above rules starts
with one of the characters
@ifset vms
-A,G,I, or S,
+@samp{A}, @samp{G}, @samp{I}, or @samp{S},
@end ifset
@ifclear vms
-a,g,i, or s,
+@samp{a}, @samp{g}, @samp{i}, or @samp{s},
@end ifclear
and the second character is a
minus. In this case, the character ^tilde^dollar sign^ is used in place
the standard names for child units of the packages System, Ada,
Interfaces, and GNAT, which use the prefixes
@ifset vms
-S- A- I- and G-
+@samp{S-}, @samp{A-}, @samp{I-}, and @samp{G-},
@end ifset
@ifclear vms
-s- a- i- and g-
+@samp{s-}, @samp{a-}, @samp{i-}, and @samp{g-},
@end ifclear
respectively.
@code{Body_File_name} rule is used for subunits as well.
The separate rule for subunits can also be used to implement the rather
-unusual case of a compilation environment (e.g. a single directory) which
+unusual case of a compilation environment (e.g.@: a single directory) which
contains a subunit and a child unit with the same unit name. Although
both units cannot appear in the same partition, the Ada Reference Manual
allows (but does not require) the possibility of the two units coexisting
checking.
@item
-Categorization information (e.g. use of pragma @code{Pure}).
+Categorization information (e.g.@: use of pragma @code{Pure}).
@item
Information on all @code{with}'ed units, including presence of
Where CC is the name of the non-GNU C++ compiler.
If the @code{zero cost} exception mechanism is used, and the platform
-supports automatic registration of exception tables (e.g. Solaris or IRIX),
+supports automatic registration of exception tables (e.g.@: Solaris or IRIX),
paths to more objects are required:
@smallexample
@end smallexample
If the @code{zero cost} exception mechanism is used, and the platform
-doesn't support automatic registration of exception tables (e.g. HP-UX,
+doesn't support automatic registration of exception tables (e.g.@: HP-UX,
Tru64 or AIX), the simple approach described above will not work and
a pre-linking phase using GNAT will be necessary.
generation of the @file{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
+for use by tools (e.g., semantic browsing tools or integrated development
environments) that are driven from the @file{ALI} file. This switch
implies @option{-gnatq}, since the semantic phase must be run to get a
meaningful ALI file.
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 @samp{..} (e.g. slices, loops etc).
+also made on explicit ranges using @samp{..} (e.g.@: slices, loops etc).
@item -gnatVp
@emph{Validity checks for parameters.}
special character is defined as being in one of the ASCII ranges
@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).
+in GNAT implementation units (i.e., when @option{-gnatg} is used).
@item
A line consisting entirely of minus signs, possibly preceded by blanks, is
@emph{Check order of subprogram bodies.}
If the ^letter o^word ORDERED_SUBPROGRAMS^ appears in the string
after @option{-gnaty} then all subprogram bodies in a given scope
-(e.g. a package body) must be in alphabetical order. The ordering
+(e.g.@: a package body) must be in alphabetical order. The ordering
rule uses normal Ada rules for comparing strings, ignoring casing
of letters, except that if there is a trailing numeric suffix, then
-the value of this suffix is used in the ordering (e.g. Junk2 comes
+the value of this suffix is used in the ordering (e.g.@: Junk2 comes
before Junk10).
@item ^p^PRAGMA^
is to list this expanded code in a form very close to normal Ada source.
This is very useful in understanding the implications of various Ada
usage on the efficiency of the generated code. There are many cases in
-Ada (e.g. the use of controlled types), where simple Ada statements can
+Ada (e.g.@: the use of controlled types), where simple Ada statements can
generate a lot of run-time code. By using @option{-gnatG} you can identify
these cases, and consider whether it may be desirable to modify the coding
approach to improve efficiency.
format with #n being used to represent the value of the n'th
discriminant. See source files @file{repinfo.ads/adb} in the
@code{GNAT} sources for full details on the format of @option{-gnatR3}
-output. If the switch is followed by an s (e.g. @option{-gnatR2s}), then
+output. If the switch is followed by an s (e.g.@: @option{-gnatR2s}), then
the output is to a file with the name @file{^file.rep^file_REP^} where
file is the name of the corresponding source file.
@end ifclear
@code{GNAT} sources for full details on the format of
@option{/REPRESENTATION_INFO=SYMBOLIC} output.
If _FILE is added at the end of an option
-(e.g. @option{/REPRESENTATION_INFO=ARRAYS_FILE}),
+(e.g.@: @option{/REPRESENTATION_INFO=ARRAYS_FILE}),
then the output is to a file with the name @file{file_REP} where
file is the name of the corresponding source file.
@end ifset
The GCC technology provides a wide range of target dependent
@option{-m} switches for controlling
details of code generation with respect to different versions of
-architectures. This includes variations in instruction sets (e.g.
+architectures. This includes variations in instruction sets (e.g.@:
different members of the power pc family), and different requirements
-for optimal arrangement of instructions (e.g. different members of
+for optimal arrangement of instructions (e.g.@: different members of
the x86 family). The list of available @option{-m} switches may be
found in the GCC documentation.
@noindent
On VMS, GNAT compiled programs return POSIX-style codes by default,
-e.g. @option{/RETURN_CODES=POSIX}.
+e.g.@: @option{/RETURN_CODES=POSIX}.
To enable VMS style return codes, use GNAT BIND and LINK with the option
@option{/RETURN_CODES=VMS}. For example:
@item ``@option{^lo^LOW^}'' for the lowest possible value
@item ``@option{^hi^HIGH^}'' for the highest possible value
@item ``@option{xx}'' for a value consisting of repeated bytes with the
-value 16#xx# (i.e. xx is a string of two hexadecimal digits).
+value 16#xx# (i.e., xx is a string of two hexadecimal digits).
@end itemize
In addition, you can specify @option{-Sev} to indicate that the value is
file is out of date with respect to the source file. Note that this is the
mode that is automatically used by @command{gnatmake} because in this
case the checking against sources has already been performed by
-@command{gnatmake} in the course of compilation (i.e. before binding).
+@command{gnatmake} in the course of compilation (i.e.@: before binding).
@ifset vms
@item /READ_SOURCES=AVAILABLE
@item @command{gcc} @asis{switches}
@ifclear vms
Any uppercase or multi-character switch that is not a @command{gnatmake} switch
-is passed to @command{gcc} (e.g. @option{-O}, @option{-gnato,} etc.)
+is passed to @command{gcc} (e.g.@: @option{-O}, @option{-gnato,} etc.)
@end ifclear
@ifset vms
Any qualifier that cannot be recognized as a qualifier for @code{GNAT MAKE}
@noindent
We want to develop an application in directory @file{^/app^[APP]^} that
@code{with} the packages @code{GUI} and @code{Comm}, using the properties of
-the corresponding project files (e.g. the ^switch^switch^ settings
+the corresponding project files (e.g.@: the ^switch^switch^ settings
and object directory).
Skeletal code for a main procedure might be something like the following:
A @emph{simple string expression} is one of the following:
@itemize @bullet
-@item A literal string; e.g.@code{"comm/my_proj.gpr"}
+@item A literal string; e.g.@: @code{"comm/my_proj.gpr"}
@item A string-valued variable reference (@pxref{Variables})
@item A string-valued attribute reference (@pxref{Attributes})
@item An external reference (@pxref{External References in Project Files})
not white space nor line break immediately following the leading @code{--} of
the comment) should be without any change moved from the argument source
into reformatted source. This switch allows to preserve comments that are used
-as a special marks in the code (e.g. SPARK annotation).
+as a special marks in the code (e.g.@: SPARK annotation).
@node Construct Layout
@subsection Construct Layout
@item
If such a replacement occurs in the
second character position of a name, and the first character is
-^a, g, s, or i^A, G, S, or I^ then replace the dot by the character
-^~ (tilde)^$ (dollar sign)^
+^@samp{a}, @samp{g}, @samp{s}, or @samp{i}, ^@samp{A}, @samp{G}, @samp{S}, or @samp{I},^
+then replace the dot by the character
+^@samp{~} (tilde)^@samp{$} (dollar sign)^
instead of a minus.
@end itemize
The reason for this exception is to avoid clashes
with the standard names for children of System, Ada, Interfaces,
-and GNAT, which use the prefixes ^s- a- i- and g-^S- A- I- and G-^
+and GNAT, which use the prefixes
+^@samp{s-}, @samp{a-}, @samp{i-}, and @samp{g-},^@samp{S-}, @samp{A-}, @samp{I-}, and @samp{G-},^
respectively.
The @option{^-gnatk^/FILE_NAME_MAX_LENGTH=^@var{nn}}
@noindent
@var{name} is the uncrunched file name, derived from the name of the unit
-in the standard manner described in the previous section (i.e. in particular
+in the standard manner described in the previous section (i.e., in particular
all dots are replaced by hyphens). The file name may or may not have an
extension (defined as a suffix of the form period followed by arbitrary
characters other than period). If an extension is present then it will
using ^lowercase^uppercase^
for all letters, except that a hyphen in the second character position is
replaced by a ^tilde^dollar sign^ if the first character is
-^a, i, g, or s^A, I, G, or S^.
+^@samp{a}, @samp{i}, @samp{g}, or @samp{s}^@samp{A}, @samp{I}, @samp{G}, or @samp{S}^.
The extension is @code{.ads} for a
specification and @code{.adb} for a body.
Krunching does not affect the extension, but the file name is shortened to
Causes comments to be scanned. Normally comments are ignored by gnatprep.
If this option is specified, then comments are scanned and any $symbol
substitutions performed as in program text. This is particularly useful
-when structured comments are used (e.g. when writing programs in the
+when structured comments are used (e.g., when writing programs in the
SPARK dialect of Ada). Note that this switch is not available when
doing integrated preprocessing (it would be useless in this context
since comments are ignored by the compiler in any case).
including none at all. The @code{else} is optional, as in Ada.
The @code{#} marking the start of a preprocessor line must be the first
-non-blank character on the line, i.e. it must be preceded only by
+non-blank character on the line, i.e., it must be preceded only by
spaces or horizontal tabs.
Symbol substitution outside of preprocessor lines is obtained by using
@item
Copy the @code{ALI} files of the interface to the library directory,
add in this copy an indication that it is an interface to a SAL
-(i.e. add a word @option{SL} on the line in the @file{ALI} file that starts
+(i.e., add a word @option{SL} on the line in the @file{ALI} file that starts
with letter ``P'') and make the modified copy of the @file{ALI} file
read-only.
@end itemize
@item
General information concerning memory management, such as the total
number of allocations and deallocations, the amount of allocated
-memory and the high water mark, i.e. the largest amount of allocated
+memory and the high water mark, i.e.@: the largest amount of allocated
memory in the course of program execution.
@item
@end table
@noindent
-The environment task stack, e.g. the stack that contains the main unit, is
+The environment task stack, e.g., the stack that contains the main unit, is
only processed when the environment variable GNAT_STACK_LIMIT is set.
The effect is not quite semantically identical to incorporating
the declarations directly into package @code{System},
but most programs will not notice a difference
-unless they use prefix notation (e.g. @code{System.Integer_8})
+unless they use prefix notation (e.g.@: @code{System.Integer_8})
to reference the entities directly in package @code{System}.
For units containing such references,
the prefixes must either be removed, or the pragma @code{Extend_System}
On GNU/Linux without NPTL support (usually system with GNU C Library
older than 2.3), the signal model is not POSIX compliant, which means
that to send a signal to the process, you need to send the signal to all
-threads, e.g. by using @code{killpg()}.
+threads, e.g.@: by using @code{killpg()}.
@node AIX-Specific Considerations
@section AIX-Specific Considerations
-- pragma Import because if we try to with the unit and
-- call it Ada style, then not only do we waste time
-- recompiling it, but also, we don't really know the right
- -- switches (e.g. identifier character set) to be used
+ -- switches (e.g.@: identifier character set) to be used
-- to compile it.
procedure Ada_Main_Program;
@noindent
In some languages that involve the same kind of elaboration problems,
-e.g. Java and C++, the programmer is expected to worry about these
+e.g.@: Java and C++, the programmer is expected to worry about these
ordering problems himself, and it is common to
write a program in which an incorrect elaboration order gives
surprising results, because it references variables before they
@section Controlling Elaboration in GNAT - Internal Calls
@noindent
-In the case of internal calls, i.e. calls within a single package, the
+In the case of internal calls, i.e., calls within a single package, the
programmer has full control over the order of elaboration, and it is up
to the programmer to elaborate declarations in an appropriate order. For
example writing:
In the body of @code{Decls} a call is made from within the body of a library
task to a subprogram in the package @code{Utils}. Since this call may
occur at elaboration time (given that the task is activated at elaboration
-time), we have to assume the worst, i.e. that the
+time), we have to assume the worst, i.e., that the
call does happen at elaboration time.
@item
A significant part of the problem arises because of the use of the
single task declaration form. This means that the elaboration of
-the task type, and the elaboration of the task itself (i.e. the
+the task type, and the elaboration of the task itself (i.e.@: the
creation of the task) happen at the same time. A good rule
of style in Ada is to always create explicit task types. By
following the additional step of placing task objects in separate
compiler so this can only be used where both declarations are legal,
even though one of them will not be used.
-Another approach is to define integer constants, e.g. @code{Bits_Per_Word}, or
-Boolean constants, e.g. @code{Little_Endian}, and then write declarations
+Another approach is to define integer constants, e.g.@: @code{Bits_Per_Word}, or
+Boolean constants, e.g.@: @code{Little_Endian}, and then write declarations
that are parameterized by these constants. For example
@smallexample @c ada
@item =
output constraint
@item g
-global (i.e. can be stored anywhere)
+global (i.e.@: can be stored anywhere)
@item m
in memory
@item I
@node Legal Ada 83 programs that are illegal in Ada 95
@subsection Legal Ada 83 programs that are illegal in Ada 95
-Some legal Ada 83 programs are illegal (i.e. they will fail to compile) in
+Some legal Ada 83 programs are illegal (i.e., they will fail to compile) in
Ada 95 and thus also in Ada 2005:
@table @emph
@itemize @bullet
@item
-Modify the program to eliminate the circularities, e.g. by moving
+Modify the program to eliminate the circularities, e.g.@: by moving
elaboration-time code into explicitly-invoked procedures
@item
Constrain the elaboration order by including explicit @code{Elaborate_Body} or
@noindent
Make sure the system on which GNAT is installed is accessible from the
-current machine, i.e. the install location is shared over the network.
+current machine, i.e., the install location is shared over the network.
Shared resources are accessed on Windows by means of UNC paths, which
have the format @code{\\server\sharename\path}
If you use @command{gcc} to compile the non-Ada part of your application,
there are no Windows-specific restrictions that affect the overall
interoperability with your Ada code. If you plan to use
-Microsoft tools (e.g. Microsoft Visual C/C++), you should be aware of
+Microsoft tools (e.g.@: Microsoft Visual C/C++), you should be aware of
the following limitations:
@itemize @bullet
It is therefore not possible to exchange GNAT run-time objects between the
Ada DLL and the main Ada program. Example of GNAT run-time objects are file
-handles (e.g. @code{Text_IO.File_Type}), tasks types, protected objects
+handles (e.g.@: @code{Text_IO.File_Type}), tasks types, protected objects
types, etc.
It is completely safe to exchange plain elementary, array or record types,
@noindent
To use the services exported by the Ada DLL from another programming
-language (e.g. C), you have to translate the specs of the exported Ada
+language (e.g.@: C), you have to translate the specs of the exported Ada
entities in that language. For instance in the case of @code{API.dll},
the corresponding C header file could look like:
projects / platform / upstream / linaro-gcc.git / commitdiff