gccrs: Add "Using gccrs" section to gccrs.texi

gcc/rust/ChangeLog:

	* gccrs.texi: Add section about compiling Rust code with gccrs.

gcc/rust/gccrs.texi

@@ -85,7 +85,8 @@ language, see @uref{https//rust-lang.org}.
 * Copying::                     The GNU General Public License.
 * GNU Free Documentation License::
                                 How you can share and copy this manual.
-* Invoking gccrs::              How to run gccrs.
+* Invoking @code{gccrs}::       How to run @code{gccrs}.
+* Using @code{gccrs}::          Compiling Rust code with @code{gccrs}.
 * Index::                       Index.
 @end menu
 
@@ -94,8 +95,8 @@ language, see @uref{https//rust-lang.org}.
 
 @include fdl.texi
 
-@node Invoking gccrs
-@chapter Invoking gccrs
+@node Invoking @code{gccrs}
+@chapter Invoking @code{gccrs}
 
 @c man title gccrs A GCC-based compiler for the Rust programming language
 
@@ -199,6 +200,43 @@ Available dumps are: @code{lex}, @code{ast-pretty}, @code{register_plugins}, @co
 
 @end table
 
+@node Using @code{gccrs}
+@chapter Using @code{gccrs}
+
+@code{gccrs} is not yet able to compile "real" Rust code, but it is progressing fast. A lot of the language's functionality resides in its runtime, the @code{core} library, which exposes interfaces intrinsic to the language that the compiler has to implement as built-in. These interfaces are so important to the Rust programming language that basic functionality, like adding two numbers together, is not even possible without part of the @code{core} library. Similarly, it is not possible to create closures, or to index into an array without @code{core}.
+
+And while @code{gccrs} is able to compile a large part of the @code{core} library, it is not yet able to compile all of it, or to provide all of the functionality it expects. As a result, we are not yet able to compile and distribute the runtime libraries for you to use when compiling Rust code.
+
+This means that most of the Rust code you will attempt to write will not compile out of the box without extensive modifications, and without delving into the compiler's internals.
+
+Furthermore, a lot of Rust code will make extensive use of the language's standard library. The standard library includes @code{core}, but also another Rust crate named @code{alloc}: @code{alloc} makes use of dynamic memory allocation in order to provide abstractions for vector types, hashmaps, or mutexes. @code{gccrs} is not yet able to make use of a global memory allocator for Rust, so all of the dynamically allocated types that the standard library provides are not usable.
+
+Likewise, format strings and their printing on standard output requires dynamic memory buffers as well as a mutex type - we are thus not able to offer proper formatting and printing with @code{gccrs}.
+
+You can however make use of a lot of Rust abstractions and experiment with them - and obviously, report bugs if the implementation comes up short. For example, you are able to define Rust @code{enum}s, @code{struct}s, and do rudimentary pattern matching on them. You can use this to experiment with @code{Result} and @code{Option}, two abstractions often used in Rust for error handling. Likewise, you are able to define and use traits, Rust's equivalent of abstract classes, which allow shared behavior between types.
+
+If you try and use functionality which depends on a @code{core} interface, @code{gccrs} should warn you about the missing interface and ask you to define it. You can then have a look for that interface in our testsuite, in @code{core}'s code, or directly ask the @code{gccrs} team about it on IRC, Zulip or on our mailing-list.
+
+For string formatting and printing to @code{stdout}, you are able to use the C @code{printf} family of functions, or any other C function as a matter of fact, since @code{gccrs} support linking your Rust code to your system's C library.
+
+For example, a simple addition and printing of the result may look like this:
+
+@example
+extern "C" @{
+    fn printf(s: *const i8, ...) -> i32;
+@}
+
+fn main() @{
+    let a = 15 + 14;
+
+    unsafe @{ printf("%d\n\0" as *const str as *const i8, a) @}
+@}
+@end example
+
+When compiled and linked as you would any other program with @code{gcc}, running the resulting binary should display @code{29}. You might see a non-zero exit code in your shell, which is due to the lack of @code{main} shim in @code{gccrs}. You can circumvent this by creating a C-like @code{main} function, which returns an integer as a result. Note that this is not valid Rust code and will be rejected in the near future!
+
+Despite all these limitations, we encourage you to try out our compiler and to please report back any issues you find with it. The frontend is extremely experimental, and will break on valid Rust code - if you see an error, it is most probably because of the @code{gccrs} team rather than the code you are trying to compile. Please do not direct bug reports to the authors of this Rust code, but rather to us.
+
 @node Index
 @unnumbered Index