[8/8] Add Rust documentation
Commit Message
This patch adds documentation for the new Rust support in gdb.
2016-04-26 Tom Tromey <tom@tromey.com>
* NEWS: Add Rust item.
2016-04-26 Tom Tromey <tom@tromey.com>
* gdb.texinfo (Supported Languages): Mention Rust. Update menu.
(Rust): New node.
---
gdb/ChangeLog | 4 +++
gdb/NEWS | 5 +++
gdb/doc/ChangeLog | 5 +++
gdb/doc/gdb.texinfo | 96 ++++++++++++++++++++++++++++++++++++++++++++++++++++-
4 files changed, 109 insertions(+), 1 deletion(-)
Comments
> From: Tom Tromey <tom@tromey.com>
> Cc: Tom Tromey <tom@tromey.com>
> Date: Tue, 26 Apr 2016 20:49:31 -0600
>
> This patch adds documentation for the new Rust support in gdb.
Thanks. This patch is good to go, with a few minor comments below
fixed.
> +@itemize @bullet
> +@item
> +Linespecs 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.
Please add here a cross-reference to where linespecs are described in
the manual.
> +@value{GDBN} does not implment type inference for generics. In order
^^^^^^^^
A typo.
> +@item
> +As of this writing, the Rust compiler has a few holes in the debugging
> +information it generates. These holes prevent certain features from
It might be a good idea to state here the version of the Rust compiler
for which the following description is true.
@@ -1,4 +1,8 @@
2016-04-26 Tom Tromey <tom@tromey.com>
+
+ * NEWS: Add Rust item.
+
+2016-04-26 Tom Tromey <tom@tromey.com>
Manish Goregaokar <manishsmail@gmail.com>
* symtab.c (symbol_find_demangled_name): Handle Rust.
@@ -27,6 +27,11 @@
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
@@ -1,5 +1,10 @@
2016-04-26 Tom Tromey <tom@tromey.com>
+ * gdb.texinfo (Supported Languages): Mention Rust. Update menu.
+ (Rust): New node.
+
+2016-04-26 Tom Tromey <tom@tromey.com>
+
* gdb.texinfo (Maintenance Commands): Document "maint selftest".
2016-04-13 Antoine Tremblay <antoine.tremblay@ericsson.com>
@@ -14398,7 +14398,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,
@@ -14422,6 +14422,7 @@ language reference or tutorial.
* OpenCL C:: OpenCL C
* Fortran:: Fortran
* Pascal:: Pascal
+* Rust:: Rust
* Modula-2:: Modula-2
* Ada:: Ada
@end menu
@@ -15227,6 +15228,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 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 implment 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 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