* gdb.texinfo (Filenames): Add Ada suffixes.

(Ada) New section.

2 files changed, 348 insertions, 2 deletions

diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog
index e810045..8307f25 100644
--- a/gdb/doc/ChangeLog
+++ b/gdb/doc/ChangeLog
@@ -1,3 +1,8 @@
+2004-10-03  Paul N. Hilfinger  <hilfinger@gnat.com>
+
+	* gdb.texinfo (Filenames): Add Ada suffixes.
+	(Ada) New section.
+
 2004-09-27  Andrew Cagney  <cagney@gnu.org>
 	    Robert Picco  <Robert.Picco@hp.com>
 
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 858e0a6..abc8790 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -7717,6 +7717,11 @@ If a source file name ends in one of the following extensions, then
 @value{GDBN} infers that its language is the one indicated.
 
 @table @file
+@item .ada
+@itemx .ads
+@itemx .adb
+@itemx .a
+Ada source file.
 
 @item .c
 C source file
@@ -8005,7 +8010,7 @@ being set automatically by @value{GDBN}.
 @node Support
 @section Supported languages
 
-@value{GDBN} supports C, C@t{++}, Objective-C, Fortran, Java, assembly, and Modula-2.
+@value{GDBN} supports C, C@t{++}, Objective-C, Fortran, Java, assembly, Modula-2, and Ada.
 @c This is false ...
 Some @value{GDBN} features may be used in expressions regardless of the
 language you use: the @value{GDBN} @code{@@} and @code{::} operators,
@@ -8025,6 +8030,7 @@ language reference or tutorial.
 * C::                           C and C@t{++}
 * Objective-C::                 Objective-C
 * Modula-2::                    Modula-2
+* Ada::                         Ada
 @end menu
 
 @node C
@@ -8640,7 +8646,7 @@ the description of an object.  However, this command may only work
 with certain Objective-C libraries that have a particular hook
 function, @code{_NSPrintForDebugger}, defined.
 
-@node Modula-2,  , Objective-C, Support
+@node Modula-2, Ada, Objective-C, Support
 @subsection Modula-2
 
 @cindex Modula-2, @value{GDBN} support
@@ -9083,6 +9089,341 @@ address can be specified by an integral constant, the construct
 In @value{GDBN} scripts, the Modula-2 inequality operator @code{#} is
 interpreted as the beginning of a comment.  Use @code{<>} instead.
 
+@node Ada
+@subsection Ada
+@cindex Ada
+
+The extensions made to @value{GDBN} for Ada only support
+output from the @sc{gnu} Ada (GNAT) compiler.
+Other Ada compilers are not currently supported, and
+attempting to debug executables produced by them is most likely
+to be difficult.
+
+
+@cindex expressions in Ada
+@menu
+* Ada Mode Intro::              General remarks on the Ada syntax 
+                                   and semantics supported by Ada mode 
+                                   in @value{GDBN}.
+* Omissions from Ada::          Restrictions on the Ada expression syntax.
+* Additions to Ada::            Extensions of the Ada expression syntax.
+* Stopping Before Main Program:: Debugging the program during elaboration.
+* Ada Glitches::                Known peculiarities of Ada mode.
+@end menu
+
+@node Ada Mode Intro
+@subsubsection Introduction
+@cindex Ada mode, general
+
+The Ada mode of @value{GDBN} supports a fairly large subset of Ada expression 
+syntax, with some extensions.
+The philosophy behind the design of this subset is 
+
+@itemize @bullet
+@item
+That @value{GDBN} should provide basic literals and access to operations for 
+arithmetic, dereferencing, field selection, indexing, and subprogram calls, 
+leaving more sophisticated computations to subprograms written into the
+program (which therefore may be called from @value{GDBN}).
+
+@item 
+That type safety and strict adherence to Ada language restrictions
+are not particularly important to the @value{GDBN} user.
+
+@item 
+That brevity is important to the @value{GDBN} user.
+@end itemize
+
+Thus, for brevity, the debugger acts as if there were 
+implicit @code{with} and @code{use} clauses in effect for all user-written 
+packages, making it unnecessary to fully qualify most names with 
+their packages, regardless of context.  Where this causes ambiguity, 
+@value{GDBN} asks the user's intent.
+
+The debugger will start in Ada mode if it detects an Ada main program. 
+As for other languages, it will enter Ada mode when stopped in a program that
+was translated from an Ada source file.
+
+While in Ada mode, you may use `@t{--}' for comments.  This is useful 
+mostly for documenting command files.  The standard @value{GDBN} comment 
+(@samp{#}) still works at the beginning of a line in Ada mode, but not in the 
+middle (to allow based literals).
+
+The debugger supports limited overloading.  Given a subprogram call in which
+the function symbol has multiple definitions, it will use the number of 
+actual parameters and some information about their types to attempt to narrow
+the set of definitions.  It also makes very limited use of context, preferring
+procedures to functions in the context of the @code{call} command, and
+functions to procedures elsewhere. 
+
+@node Omissions from Ada
+@subsubsection Omissions from Ada
+@cindex Ada, omissions from
+
+Here are the notable omissions from the subset:
+
+@itemize @bullet
+@item
+Only a subset of the attributes are supported:
+
+@itemize @minus
+@item
+@t{'First}, @t{'Last}, and @t{'Length}
+ on array objects (not on types and subtypes).
+
+@item
+@t{'Min} and @t{'Max}.  
+
+@item 
+@t{'Pos} and @t{'Val}. 
+
+@item
+@t{'Tag}.
+
+@item
+@t{'Range} on array objects (not subtypes), but only as the right
+operand of the membership (@code{in}) operator.
+
+@item 
+@t{'Access}, @t{'Unchecked_Access}, and 
+@t{'Unrestricted_Access} (a GNAT extension).
+
+@item
+@t{'Address}.
+@end itemize
+
+@item
+The names in
+@code{Characters.Latin_1} are not available and
+concatenation is not implemented.  Thus, escape characters in strings are 
+not currently available.
+
+@item
+Equality tests (@samp{=} and @samp{/=}) on arrays test for bitwise
+equality of representations.  They will generally work correctly
+for strings and arrays whose elements have integer or enumeration types.
+They may not work correctly for arrays whose element
+types have user-defined equality, for arrays of real values 
+(in particular, IEEE-conformant floating point, because of negative
+zeroes and NaNs), and for arrays whose elements contain unused bits with
+indeterminate values.  
+
+@item
+The other component-by-component array operations (@code{and}, @code{or}, 
+@code{xor}, @code{not}, and relational tests other than equality)
+are not implemented. 
+
+@item 
+There are no record or array aggregates.
+
+@item
+Calls to dispatching subprograms are not implemented.
+
+@item
+The overloading algorithm is much more limited (i.e., less selective)
+than that of real Ada.  It makes only limited use of the context in which a subexpression
+appears to resolve its meaning, and it is much looser in its rules for allowing
+type matches.  As a result, some function calls will be ambiguous, and the user
+will be asked to choose the proper resolution.
+
+@item
+The @code{new} operator is not implemented.
+
+@item
+Entry calls are not implemented.
+
+@item 
+Aside from printing, arithmetic operations on the native VAX floating-point 
+formats are not supported.
+
+@item
+It is not possible to slice a packed array.
+@end itemize
+
+@node Additions to Ada
+@subsubsection Additions to Ada
+@cindex Ada, deviations from 
+
+As it does for other languages, @value{GDBN} makes certain generic
+extensions to Ada (@pxref{Expressions}):
+
+@itemize @bullet
+@item
+If the expression @var{E} is a variable residing in memory 
+(typically a local variable or array element) and @var{N} is 
+a positive integer, then @code{@var{E}@@@var{N}} displays the values of
+@var{E} and the @var{N}-1 adjacent variables following it in memory as an array.  
+In Ada, this operator is generally not necessary, since its prime use
+is in displaying parts of an array, and slicing will usually do this in Ada.
+However, there are occasional uses when debugging programs
+in which certain debugging information has been optimized away.
+
+@item
+@code{@var{B}::@var{var}} means ``the variable named @var{var} that appears
+in function or file @var{B}.''  When @var{B} is a file name, you must typically
+surround it in single quotes.
+
+@item 
+The expression @code{@{@var{type}@} @var{addr}} means ``the variable of type
+@var{type} that appears at address @var{addr}.''
+
+@item
+A name starting with @samp{$} is a convenience variable 
+(@pxref{Convenience Vars}) or a machine register (@pxref{Registers}).
+@end itemize
+
+In addition, @value{GDBN} provides a few other shortcuts and outright additions specific 
+to Ada:
+
+@itemize @bullet
+@item 
+The assignment statement is allowed as an expression, returning
+its right-hand operand as its value.  Thus, you may enter
+
+@smallexample
+set x := y + 3
+print A(tmp := y + 1)
+@end smallexample
+
+@item 
+The semicolon is allowed as an ``operator,''  returning as its value 
+the value of its right-hand operand.
+This allows, for example,
+complex conditional breaks:
+
+@smallexample
+break f
+condition 1 (report(i); k += 1; A(k) > 100)
+@end smallexample
+
+@item 
+Rather than use catenation and symbolic character names to introduce special 
+characters into strings, one may instead use a special bracket notation, 
+which is also used to print strings.  A sequence of characters of the form 
+@samp{["@var{XX}"]} within a string or character literal denotes the 
+(single) character whose numeric encoding is @var{XX} in hexadecimal.  The
+sequence of characters @samp{["""]} also denotes a single quotation mark 
+in strings.   For example,
+@smallexample
+   "One line.["0a"]Next line.["0a"]"
+@end smallexample
+@noindent
+contains an ASCII newline character (@code{Ada.Characters.Latin_1.LF}) after each
+period.
+
+@item
+The subtype used as a prefix for the attributes @t{'Pos}, @t{'Min}, and
+@t{'Max} is optional (and is ignored in any case).  For example, it is valid
+to write
+
+@smallexample
+print 'max(x, y)
+@end smallexample
+
+@item
+When printing arrays, @value{GDBN} uses positional notation when the 
+array has a lower bound of 1, and uses a modified named notation otherwise.
+For example, a one-dimensional array of three integers with a lower bound of 3 might print as
+
+@smallexample
+(3 => 10, 17, 1)
+@end smallexample
+
+@noindent
+That is, in contrast to valid Ada, only the first component has a @code{=>} 
+clause.
+
+@item
+You may abbreviate attributes in expressions with any unique,
+multi-character subsequence of 
+their names (an exact match gets preference).
+For example, you may use @t{a'len}, @t{a'gth}, or @t{a'lh}
+in place of  @t{a'length}.
+
+@item
+@cindex quoting Ada internal identifiers
+Since Ada is case-insensitive, the debugger normally maps identifiers you type 
+to lower case.  The GNAT compiler uses upper-case characters for 
+some of its internal identifiers, which are normally of no interest to users.
+For the rare occasions when you actually have to look at them,
+enclose them in angle brackets to avoid the lower-case mapping. 
+For example,
+@smallexample
+@value{GDBP} print <JMPBUF_SAVE>[0]
+@end smallexample
+
+@item
+Printing an object of class-wide type or dereferencing an 
+access-to-class-wide value will display all the components of the object's
+specific type (as indicated by its run-time tag).  Likewise, component
+selection on such a value will operate on the specific type of the
+object.
+
+@end itemize
+
+@node Stopping Before Main Program
+@subsubsection Stopping at the Very Beginning
+
+@cindex breakpointing Ada elaboration code
+It is sometimes necessary to debug the program during elaboration, and
+before reaching the main procedure.
+As defined in the Ada Reference
+Manual, the elaboration code is invoked from a procedure called
+@code{adainit}.  To run your program up to the beginning of
+elaboration, simply use the following two commands:
+@code{tbreak adainit} and @code{run}.
+
+@node Ada Glitches
+@subsubsection Known Peculiarities of Ada Mode
+@cindex Ada, problems
+
+Besides the omissions listed previously (@pxref{Omissions from Ada}),
+we know of several problems with and limitations of Ada mode in
+@value{GDBN},
+some of which will be fixed with planned future releases of the debugger 
+and the GNU Ada compiler.
+
+@itemize @bullet
+@item
+Currently, the debugger 
+has insufficient information to determine whether certain pointers represent
+pointers to objects or the objects themselves.
+Thus, the user may have to tack an extra @code{.all} after an expression
+to get it printed properly.
+
+@item 
+Static constants that the compiler chooses not to materialize as objects in 
+storage are invisible to the debugger.
+
+@item
+Named parameter associations in function argument lists are ignored (the
+argument lists are treated as positional).
+
+@item
+Many useful library packages are currently invisible to the debugger.
+
+@item
+Fixed-point arithmetic, conversions, input, and output is carried out using 
+floating-point arithmetic, and may give results that only approximate those on 
+the host machine.
+
+@item
+The type of the @t{'Address} attribute may not be @code{System.Address}.
+
+@item
+The GNAT compiler never generates the prefix @code{Standard} for any of 
+the standard symbols defined by the Ada language.  @value{GDBN} knows about 
+this: it will strip the prefix from names when you use it, and will never
+look for a name you have so qualified among local symbols, nor match against
+symbols in other packages or subprograms.  If you have 
+defined entities anywhere in your program other than parameters and 
+local variables whose simple names match names in @code{Standard}, 
+GNAT's lack of qualification here can cause confusion.  When this happens,
+you can usually resolve the confusion 
+by qualifying the problematic names with package
+@code{Standard} explicitly.  
+@end itemize
+
 @node Unsupported languages
 @section Unsupported languages