Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

gccrs: Add base documentation for using the Rust frontend. #2966

Open
wants to merge 3 commits into
base: master
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 37 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 Expand Up @@ -359,6 +370,25 @@ 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: $(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.
Expand Down
207 changes: 207 additions & 0 deletions gcc/rust/gccrs.texi
Original file line number Diff line number Diff line change
@@ -0,0 +1,207 @@
\input texinfo @c -*-texinfo-*-
@setfilename gccrs.info
@settitle The GNU Rust Compiler
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just to be sure, is that the "blessed" name, wrt the Rust® ?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

good question :) I think we can leave it like this for now, and be open to changing it


@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.
Comment on lines +125 to +131
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should probably not be mentioned.

Suggested change
@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.
CohenArthur marked this conversation as resolved.
Show resolved Hide resolved
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
Loading