Add Rust documentation
authorTom Tromey <tom@tromey.com>
Wed, 27 Apr 2016 01:38:56 +0000 (19:38 -0600)
committerTom Tromey <tom@tromey.com>
Tue, 17 May 2016 18:02:02 +0000 (12:02 -0600)
This patch adds documentation for the new Rust support in gdb.

2016-05-17  Tom Tromey  <tom@tromey.com>

* NEWS: Add Rust item.

2016-05-17  Tom Tromey  <tom@tromey.com>

* gdb.texinfo (Supported Languages): Mention Rust.  Update menu.
(Rust): New node.

gdb/ChangeLog
gdb/NEWS
gdb/doc/ChangeLog
gdb/doc/gdb.texinfo

index 793c5eba6bcb0df39901ba9c882b52104215b20d..3b4b9d362ab8bb00216766bc424f060c56c3f160 100644 (file)
@@ -1,3 +1,7 @@
+2016-05-17  Tom Tromey  <tom@tromey.com>
+
+       * NEWS: Add Rust item.
+
 2016-05-17  Tom Tromey  <tom@tromey.com>
            Manish Goregaokar <manishsmail@gmail.com>
 
index 77dfc0cbb43c95d66dd6aaddeb82a01935ef7d6a..3e8e7a1bd30b5575a8f67668d276aec6fed76bae 100644 (file)
--- a/gdb/NEWS
+++ b/gdb/NEWS
    Bounds: [lower = 0x7fffffffc390, upper = 0x7fffffffc3a3]
    0x0000000000400d7c in upper () at i386-mpx-sigsegv.c:68
 
+* Rust language support.
+  GDB now supports debugging programs written in the Rust programming
+  language.  See https://www.rust-lang.org/ for more information about
+  Rust.
+
 * New commands
 
 skip -file file
index 2db9be20adf5637d822f485db530d080066ef9aa..fe2e3be090759d3d6fbc298c6a965f4320963cad 100644 (file)
@@ -1,3 +1,8 @@
+2016-05-17  Tom Tromey  <tom@tromey.com>
+
+       * gdb.texinfo (Supported Languages): Mention Rust.  Update menu.
+       (Rust): New node.
+
 2016-05-17  Tom Tromey  <tom@tromey.com>
 
        * gdb.texinfo (Maintenance Commands): Document "maint selftest".
index f91a609f8ead328f6fbc4eb64630e638515a361e..42d1a63542e0d63b2dcddd01fd9b91b458114fda 100644 (file)
@@ -14399,7 +14399,7 @@ being set automatically by @value{GDBN}.
 @section Supported Languages
 
 @value{GDBN} supports C, C@t{++}, D, Go, Objective-C, Fortran, Java,
-OpenCL C, Pascal, assembly, Modula-2, and Ada.
+OpenCL C, Pascal, Rust, 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,
@@ -14423,6 +14423,7 @@ language reference or tutorial.
 * OpenCL C::                    OpenCL C
 * Fortran::                     Fortran
 * Pascal::                      Pascal
+* Rust::                        Rust
 * Modula-2::                    Modula-2
 * Ada::                         Ada
 @end menu
@@ -15228,6 +15229,99 @@ The Pascal-specific command @code{set print pascal_static-members}
 controls whether static members of Pascal objects are displayed.
 @xref{Print Settings, pascal_static-members}.
 
+@node Rust
+@subsection Rust
+
+@value{GDBN} supports the @url{https://www.rust-lang.org/, Rust
+Programming Language}.  Type- and value-printing, and expression
+parsing, are reasonably complete.  However, there are a few
+peculiarities and holes to be aware of.
+
+@itemize @bullet
+@item
+Linespecs (@pxref{Specify Location}) are never relative to the current
+crate.  Instead, they act as if there were a global namespace of
+crates, somewhat similar to the way @code{extern crate} behaves.
+
+That is, if @value{GDBN} is stopped at a breakpoint in a function in
+crate @samp{A}, module @samp{B}, then @code{break B::f} will attempt
+to set a breakpoint in a function named @samp{f} in a crate named
+@samp{B}.
+
+As a consequence of this approach, linespecs also cannot refer to
+items using @samp{self::} or @samp{super::}.
+
+@item
+Because @value{GDBN} implements Rust name-lookup semantics in
+expressions, it will sometimes prepend the current crate to a name.
+For example, if @value{GDBN} is stopped at a breakpoint in the crate
+@samp{K}, then @code{print ::x::y} will try to find the symbol
+@samp{K::x::y}.
+
+However, since it is useful to be able to refer to other crates when
+debugging, @value{GDBN} provides the @code{extern} extension to
+circumvent this.  To use the extension, just put @code{extern} before
+a path expression to refer to the otherwise unavailable ``global''
+scope.
+
+In the above example, if you wanted to refer to the symbol @samp{y} in
+the crate @samp{x}, you would use @code{print extern x::y}.
+
+@item
+The Rust expression evaluator does not support ``statement-like''
+expressions such as @code{if} or @code{match}, or lambda expressions.
+
+@item
+Tuple expressions are not implemented.
+
+@item
+The Rust expression evaluator does not currently implement the
+@code{Drop} trait.  Objects that may be created by the evaluator will
+never be destroyed.
+
+@item
+@value{GDBN} does not implement type inference for generics.  In order
+to call generic functions or otherwise refer to generic items, you
+will have to specify the type parameters manually.
+
+@item
+@value{GDBN} currently uses the C@t{++} demangler for Rust.  In most
+cases this does not cause any problems.  However, in an expression
+context, completing a generic function name will give syntactically
+invalid results.  This happens because Rust requires the @samp{::}
+operator between the function name and its generic arguments.  For
+example, @value{GDBN} might provide a completion like
+@code{crate::f<u32>}, where the parser would require
+@code{crate::f::<u32>}.
+
+@item
+As of this writing, the Rust compiler (version 1.8) has a few holes in
+the debugging information it generates.  These holes prevent certain
+features from being implemented by @value{GDBN}:
+@itemize @bullet
+
+@item
+Method calls cannot be made via traits.
+
+@item
+Trait objects cannot be created or inspected.
+
+@item
+Operator overloading is not implemented.
+
+@item
+When debugging in a monomorphized function, you cannot use the generic
+type names.
+
+@item
+The type @code{Self} is not available.
+
+@item
+@code{use} statements are not available, so some names may not be
+available in the crate.
+@end itemize
+@end itemize
+
 @node Modula-2
 @subsection Modula-2