Skip to content

Commit

Permalink
gccrs: Add base documentation for using the Rust frontend.
Browse files Browse the repository at this point in the history
gcc/rust/ChangeLog:

	* Make-lang.in: Add documentation targets.
	* gccrs.texi: New file.
  • Loading branch information
CohenArthur committed Apr 23, 2024
1 parent fa86c37 commit d38ac92
Show file tree
Hide file tree
Showing 2 changed files with 239 additions and 7 deletions.
25 changes: 18 additions & 7 deletions gcc/rust/Make-lang.in
Original file line number Diff line number Diff line change
Expand Up @@ -279,27 +279,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.

Expand Down
221 changes: 221 additions & 0 deletions gcc/rust/gccrs.texi
Original file line number Diff line number Diff line change
@@ -0,0 +1,221 @@
\input texinfo @c -*-texinfo-*-
@setfilename gccgo.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

@comment @ignore
@comment @c man begin SYNOPSIS gccrs
@comment gccgo [@option{-c}|@option{-S}]
@comment [@option{-g}] [@option{-pg}] [@option{-O}@var{level}]
@comment [@option{-I}@var{dir}@dots{}] [@option{-L}@var{dir}@dots{}]
@comment [@option{-o} @var{outfile}] @var{infile}@dots{}

@comment Only the most useful options are listed here; see below for the
@comment remainder.
@comment @c man end
@comment @c man begin SEEALSO
@comment gpl(7), gfdl(7), fsf-funding(7), gcc(1)
@comment and the Info entries for @file{gccrs} and @file{gcc}.
@comment @c man end
@comment @end ignore

@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}.

The @command{gccgo} command may be used to compile Go source code into
an object file, link a collection of object files together, or do both
in sequence.

@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.

@end table

@bye

0 comments on commit d38ac92

Please sign in to comment.