[commit]: Documentation for initial Ada support in GDB

[Paul Hilfinger <hilfingr at gnat dot com>]

Committed the Ada documentation.  This differs slightly from the 
approved versions in that sections describing features we have not
yet incorporated have been removed.  It's probably less confusing to
those relying on the documentation to avoid describing stuff that's
not there.

2004-10-03  Paul N. Hilfinger  <hilfinger@gnat.com>

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


Index: gdb/doc/gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.215
diff -u -p -r1.215 gdb.texinfo
--- gdb/doc/gdb.texinfo	27 Sep 2004 19:23:25 -0000	1.215
+++ gdb/doc/gdb.texinfo	3 Oct 2004 10:02:02 -0000
@@ -7717,6 +7717,11 @@ If a source file name ends in one of the
 @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, 
 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 
 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