[PATCH 14.2 1/3] gccrs: Add base documentation for using the Rust frontend.

[Arthur Cohen <arthur.cohen@embecosm.com>]

gcc/rust/ChangeLog:

	* Make-lang.in: Add documentation targets.
	* gccrs.texi: New file.
---
 gcc/rust/Make-lang.in |  25 +++--
 gcc/rust/gccrs.texi   | 207 ++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 225 insertions(+), 7 deletions(-)
 create mode 100644 gcc/rust/gccrs.texi

diff --git a/gcc/rust/Make-lang.in b/gcc/rust/Make-lang.in
index dd94c9b5eab..f0fc582bd26 100644
--- a/gcc/rust/Make-lang.in
+++ b/gcc/rust/Make-lang.in
@@ -283,27 +283,38 @@ rust.tags: force
 
 # Build documentation hooks.
 
+RUST_TEXI = \
+	rust/rust.texi
+
 # Build info documentation for the front end, in the build directory. This target is only called by
 # ‘make bootstrap’ if a suitable version of makeinfo is available, so does not need to check for this,
 # and should fail if an error occurs.
 rust.info:
+	if [ x$(BUILD_INFO) = xinfo ]; then \
+	  $(MAKEINFO) $(MAKEINFOFLAGS) -I $(abs_docdir) -I $(abs_docdir)/include -o $@ $<; \
+	else \
+		true; \
+	fi
 
 rust.srcinfo:
 
 # Build DVI documentation for the front end, in the build directory. This should be done using
 # $(TEXI2DVI), with appropriate -I arguments pointing to directories of included files.
-rust.dvi:
+rust.dvi: $(RUST_TEXI)
+	$(TEXI2DVI) -I $(abs_docdir) -I $(abs_docdir)/include -o $@ $<
 
 # Build PDF documentation for the front end, in the build directory. This should be done using
 # $(TEXI2PDF), with appropriate -I arguments pointing to directories of included files.
-rust.pdf:
-
-doc/rust.info:
-doc/rust.dvi:
-doc/rust.pdf:
+rust.pdf: $(RUST_TEXI)
+	$(TEXI2PDF) -I $(abs_docdir) -I $(abs_docdir)/include -o $@ $<
 
 # Build HTML documentation for the front end, in the build directory.
-rust.html:
+rust.html: $(RUST_TEXI)
+	$(TEXI2HTML) -I $(abs_docdir) -I $(abs_docdir)/include -o $@ $<
+
+doc/rust.info: rust.info
+doc/rust.dvi: rust.dvi
+doc/rust.pdf: rust.pdf
 
 # Install hooks.
 
diff --git a/gcc/rust/gccrs.texi b/gcc/rust/gccrs.texi
new file mode 100644
index 00000000000..52f055eaad8
--- /dev/null
+++ b/gcc/rust/gccrs.texi
@@ -0,0 +1,207 @@
+\input texinfo @c -*-texinfo-*-
+@setfilename gccrs.info
+@settitle The GNU Rust Compiler
+
+@c Merge the standard indexes into a single one.
+@syncodeindex fn cp
+@syncodeindex vr cp
+@syncodeindex ky cp
+@syncodeindex pg cp
+@syncodeindex tp cp
+
+@include gcc-common.texi
+
+@c Copyright years for this manual.
+@set copyrights-gccrs 2024
+
+@copying
+@c man begin COPYRIGHT
+Copyright @copyright{} @value{copyrights-gccrs} Free Software Foundation, Inc.
+
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.3 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, the Front-Cover Texts being (a) (see below), and
+with the Back-Cover Texts being (b) (see below).
+A copy of the license is included in the
+@c man end
+section entitled ``GNU Free Documentation License''.
+@ignore
+@c man begin COPYRIGHT
+man page gfdl(7).
+@c man end
+@end ignore
+
+@c man begin COPYRIGHT
+
+(a) The FSF's Front-Cover Text is:
+
+     A GNU Manual
+
+(b) The FSF's Back-Cover Text is:
+
+     You have freedom to copy and modify this GNU Manual, like GNU
+     software.  Copies published by the Free Software Foundation raise
+     funds for GNU development.
+@c man end
+@end copying
+
+@ifinfo
+@format
+@dircategory Software development
+@direntry
+* gccrs: (gccrs).           A GCC-based compiler for the Rust programming language
+@end direntry
+@end format
+
+@insertcopying
+@end ifinfo
+
+@titlepage
+@title The GNU Rust Compiler
+@versionsubtitle
+@author The gccrs team
+
+@page
+@vskip 0pt plus 1filll
+Published by the Free Software Foundation @*
+51 Franklin Street, Fifth Floor@*
+Boston, MA 02110-1301, USA@*
+@sp 1
+@insertcopying
+@end titlepage
+@contents
+@page
+
+@node Top
+@top Introduction
+
+This manual describes how to use @command{gccrs}, the GNU compiler for
+the Rust programming language.  This manual is specifically about
+@command{gccrs}.  For more information about the Rust programming
+language, see @uref{https//rust-lang.org}.
+
+@menu
+* Copying::                     The GNU General Public License.
+* GNU Free Documentation License::
+                                How you can share and copy this manual.
+* Invoking gccrs::              How to run gccrs.
+* Index::                       Index.
+@end menu
+
+
+@include gpl_v3.texi
+
+@include fdl.texi
+
+@node Invoking gccrs
+@chapter Invoking gccrs
+
+@c man title gccrs A GCC-based compiler for the Rust programming language
+
+@c man begin DESCRIPTION gccrs
+
+The @command{gccrs} command is a frontend to @command{gcc} and
+supports many of the same options, @xref{Option Summary, , Option
+Summary, gcc, Using the GNU Compiler Collection (GCC)}, as well
+as some @command{gccrs} specific ones. This manual only documents
+the options that are specific to @command{gccrs}.
+
+@c man end
+
+@c man begin OPTIONS gccrust
+
+@table @gcctabopt
+
+@cindex @option{-frust-incomplete-and-experimental-compiler-do-not-use}
+@item -frust-incomplete-and-experimental-compiler-do-not-use
+This flag enables the compilation of Rust code with the GCC Rust compiler.
+It is used to indicate the unstability of the compiler, and reminds the user
+about the expected incoming breakage. @command{gccrs} is not yet able to
+compile real Rust code, or to report valid errors when seeing incorrect Rust.
+It also does not compile and link to the Rust standard library, meaning you
+are not able to access most existing Rust types, macros and functions.
+
+@cindex @option{-frust-mini-std}
+@item -frust-mini-std
+Add the @code{mini_std} module to the crate you are currently compiling. This miniature
+standard library is experimental, and does not represent a strict subset of Rust's
+standard library. It is there so that you can have access to basic Rust functionality,
+such as common arithmetic operations on natural numbers or printing basic strings to
+the standard output streams.
+
+@cindex @option{-frust-borrowcheck}
+@item -frust-borrowcheck
+Enable the experimental borrow-checking pass in the @command{gccrs} pipeline. This pass
+feeds information to @command{polonius}, a next-generation borrow-checking algorithm for
+Rust. It is incomplete and cannot be used to safely analyze Rust borrowing rules with
+@command{gccrs} yet.
+
+@cindex @option{-frust-cfg}
+@item -frust-cfg=@var{input}
+Specify a @code{#[cfg]} directive for the Rust compiler. This is used in Rust code
+to perform conditional compilation. The input can be of the form @code{key} or @code{key=value}.
+
+@cindex @option{-frust-compile-until}
+@item -frust-compile-until=@var{step}
+Stop the compilation at a certain stage in the @command{gccrs} pipeline. The available steps are:
+@code{ast}, @code{attributecheck}, @code{expansion}, @code{astvalidation}, @code{featuregating}, @code{nameresolution}, @code{lowering}, @code{typecheck}, @code{privacy}, @code{unsafety}, @code{const}, @code{borrowcheck}, @code{compilation}, @code{end}.
+
+@cindex @option{-frust-crate-type}
+@item -frust-crate-type=@var{type}
+What type of crate to produce using @command{gccrs}. While the official Rust compiler supports
+multiple options such as @code{staticlib} or @code{rlib}, the Rust compiler for GCC does not.
+The complete list of accepted @code{type}s is as follows: @code{bin}, @code{lib}, @code{rlib}, @code{dylib}, @code{cdylib}, @code{staticlib}, @code{proc_macro}.
+The list of supported @code{type}s is: @code{bin}, @code{proc_macro}.
+
+@cindex @option{-frust-crate}
+@item -frust-crate=@var{name}
+Specify the name to use for the crate we are producing.
+
+@cindex @option{-frust-edition}
+@item -frust-edition=@var{year}
+Rust edition to use when compiling the code. Available editions are @code{2015}, @code{2018} and @code{2021}.
+
+@cindex @option{-frust-embed-metadata}
+@item -frust-embed-metadata
+Enable embedding metadata directly into object files.
+
+@cindex @option{-frust-metadata-output}
+@item -frust-metadata-output=@var{path}
+Path where crate metadata should be written.
+
+@cindex @option{-frust-extern}
+@item -frust-extern=@var{path}
+Specify a path from which an external crate should be loaded.
+
+@cindex @option{-frust-mangling}
+@item -frust-mangling=@var{version}
+Mangling algorithm to use: @code{legacy} or @code{v0}.
+
+@cindex @option{-frust-max-recursion-depth}
+@item -frust-max-recursion-depth=@var{max_value}
+Set the maximum recursion depth for macro expansion. The default is 128.
+
+@cindex @option{-frust-name-resolution-2.0}
+@item -frust-name-resolution-2.0
+Switch to the experimental name resolution algorithm which is currently being rewritten.
+
+@cindex @option{-frust-debug}
+@item -frust-debug
+Turn on debug printing from the Rust compiler frontend. This does not turn on debug
+information for the produced binaries, and will create a lot of noise on the output.
+This option is aimed for the developers of @command{gccrs}.
+
+@cindex @option{-frust-dump-}
+@item -frust-dump-@var{to_dump}
+Create debug dump files from various passes of the @command{gccrs} pipeline.
+Available dumps are: @code{lex}, @code{ast-pretty}, @code{register_plugins}, @code{injection}, @code{expansion}, @code{resolution}, @code{target_options}, @code{hir}, @code{hir-pretty}, @code{all}
+
+@end table
+
+@node Index
+@unnumbered Index
+
+@printindex cp
+
+@bye
-- 
2.42.0