[PATCHSET 14.2] Add documentation rules for Rust frontend

[PATCHSET 14.2] Add documentation rules for Rust frontend

[Arthur Cohen]

Hi everyone,

This is a quick and simple patchset to our Makefile in order to have proper
documentation rules for the Rust frontend. Let me know if these changes would
be accepted into 14.2, or if we should rather integrate them to trunk for 15.1
as part of our upstreaming process.

If the changes are accepted for 14.2, I will be following them up with .texi
changes to improve the documentation of the Rust frontend.

Best,

Arthur

[PATCH 14.2 1/3] gccrs: Add base documentation for using the Rust
[PATCH 14.2 2/3] rust: Add rust.install-dvi and rust.install-html
[PATCH 14.2 3/3] rust: Copy install-html rule from Ada frontend

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

[Arthur Cohen]

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

[PATCH 14.2 2/3] rust: Add rust.install-dvi and rust.install-html rules

[Arthur Cohen]

From: Christophe Lyon <christophe.lyon@linaro.org>

rust has the (empty) rust.dvi and rust.html rules, but lacks the
(empty) rust.install-dvi and rust.install-html ones.

2024-04-04  Christophe Lyon  <christophe.lyon@linaro.org>

	gcc/rust/
	* Make-lang.in (rust.install-dvi, rust.install-html): New rules.
---
 gcc/rust/Make-lang.in | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/gcc/rust/Make-lang.in b/gcc/rust/Make-lang.in
index f0fc582bd26..2395541425f 100644
--- a/gcc/rust/Make-lang.in
+++ b/gcc/rust/Make-lang.in
@@ -374,6 +374,8 @@ selftest-rust-valgrind: $(RUST_SELFTEST_DEPS)
 # should have dependencies on info files that should be installed.
 rust.install-info:
 
+rust.install-dvi:
+rust.install-html:
 rust.install-pdf:
 
 # Install man pages for the front end. This target should ignore errors.
-- 
2.42.0

[PATCH 14.2 3/3] rust: Copy install-html rule from Ada frontend

[Arthur Cohen]

gcc/rust/ChangeLog:

	* Make-lang.in: Add proper rust.install-html rule.
---
 gcc/rust/Make-lang.in | 19 ++++++++++++++++++-
 1 file changed, 18 insertions(+), 1 deletion(-)

diff --git a/gcc/rust/Make-lang.in b/gcc/rust/Make-lang.in
index 2395541425f..815a8b315c0 100644
--- a/gcc/rust/Make-lang.in
+++ b/gcc/rust/Make-lang.in
@@ -375,7 +375,24 @@ selftest-rust-valgrind: $(RUST_SELFTEST_DEPS)
 rust.install-info:
 
 rust.install-dvi:
-rust.install-html:
+
+rust.install-html: $(build_htmldir)/rust
+	@$(NORMAL_INSTALL)
+	test -z "$(htmldir)" || $(mkinstalldirs) "$(DESTDIR)$(htmldir)"
+	@for p in $(build_htmldir)/rust; do \
+	  if test -f "$$p" || test -d "$$p"; then d=""; else d="$(srcdir)/"; fi; \
+	  f=$(html__strip_dir) \
+	  if test -d "$$d$$p"; then \
+	    echo " $(mkinstalldirs) '$(DESTDIR)$(htmldir)/$$f'"; \
+	    $(mkinstalldirs) "$(DESTDIR)$(htmldir)/$$f" || exit 1; \
+	    echo " $(INSTALL_DATA) '$$d$$p'/* '$(DESTDIR)$(htmldir)/$$f'"; \
+	    $(INSTALL_DATA) "$$d$$p"/* "$(DESTDIR)$(htmldir)/$$f"; \
+	  else \
+	    echo " $(INSTALL_DATA) '$$d$$p' '$(DESTDIR)$(htmldir)/$$f'"; \
+	    $(INSTALL_DATA) "$$d$$p" "$(DESTDIR)$(htmldir)/$$f"; \
+	  fi; \
+	done
+
 rust.install-pdf:
 
 # Install man pages for the front end. This target should ignore errors.
-- 
2.42.0