From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mail-ed1-x52f.google.com (mail-ed1-x52f.google.com [IPv6:2a00:1450:4864:20::52f]) by sourceware.org (Postfix) with ESMTPS id A4E793882646 for ; Fri, 14 Jun 2024 12:23:24 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org A4E793882646 Authentication-Results: sourceware.org; dmarc=none (p=none dis=none) header.from=embecosm.com Authentication-Results: sourceware.org; spf=pass smtp.mailfrom=embecosm.com ARC-Filter: OpenARC Filter v1.0.0 sourceware.org A4E793882646 Authentication-Results: server2.sourceware.org; arc=none smtp.remote-ip=2a00:1450:4864:20::52f ARC-Seal: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1718367807; cv=none; b=BSiV44vuloBT7doLw4ki2UZextmDHTK84peR1q2/dNrD1YSOwnhl97S51JBFeN4z0kdNT4vGLcS879Xvvy6Qm9si39Jr2/ncjb5dS57RYwJhlOcqfVPFDC0PrmQMJetAMoRLWRxwjakTNRDa566yOgiDIigKQntU5BfAb43S/mU= ARC-Message-Signature: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1718367807; c=relaxed/simple; bh=m0SA6imFAGjKj/nhIDchAKfdygv3I+4Aq3o9hUxnIvI=; h=DKIM-Signature:From:To:Subject:Date:Message-ID:MIME-Version; b=PbQsn6pprnkmixdSovNAdBrjuLS/OmT8H33TMAChdWiDThGZwnM9IgBFVTlFl7BkW1JDjbzgwg8xl5ssoVLa0eqZAxEew5NAI5bWXExSVSEI86PG6PfQvaaYTnV/cdYqU29OjQCcCZoaNpd3aZbwNOtzCA6MK02e9c/uGp6lu/c= ARC-Authentication-Results: i=1; server2.sourceware.org Received: by mail-ed1-x52f.google.com with SMTP id 4fb4d7f45d1cf-57c7681ccf3so2368905a12.2 for ; Fri, 14 Jun 2024 05:23:24 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=embecosm.com; s=google; t=1718367803; x=1718972603; darn=gcc.gnu.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=LEmWnclKolA6aeNA6MxhsjJSlOtF14/S4b7N4BCqK/k=; b=OueC0ohYuqujRM8CrGzWpznxDIG5RebpiLBtC2wc3X45QfPajlimAIvru31MYssZbr ABmKEe+DUJo7B4cMtWYcvQU6c4H/8ty+ClhGTocvT5pKH4PLCr4ZdB2zMAJ5l32m6Vt+ 3DkuONTanFTUaMTaCXrIYMibIcy7KPS1vVt6AIJaS+n4+Hx5bW1AOv5dmXSVjZRlC2qJ wZHrE3Q5x4ycV8E3VqFG9tAs6HjKS7amPhJBeprT5n2LUSpU2B/WqqNVS1gqsppDJNG3 t9kiSJCKvA7o2iiAunMQ9h+vIdmFDMFJJsY0xRjlI61lXP2K4ga7jMlrrFtdVug5O4nm pwLw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1718367803; x=1718972603; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=LEmWnclKolA6aeNA6MxhsjJSlOtF14/S4b7N4BCqK/k=; b=xNkDbHt8PouUIsW7+7pryrtw8X5KBZ7saDwPFMtcEAivIK+YD6UTa73QifJ2hlKVav ptC+79yRZv677ipiOhvmKzjtS/4mjnxR0St6XtHwxXYNdiSu1ohMOvReV7DJTzgH6U0J 6diqjC1JwdikQb/5pJvg+G5eI9KDF1H7otnY8adpycquMdFdhs0aKrG1vJrGKqubFh2P 67J/VeZUbdjDHHOdj5szRYlBy12gmfbqD8FJJ72LSqsOMjEzTUw5mJ5sLNOIfJ+6QIgz CyzPhq7KHU03KlehlmerbRLknY3dbkq736d1vrfD2GTVrqc2UT8YMnvFYUFtP8MWfp4Y vDOg== X-Gm-Message-State: AOJu0YzJlF2Qlf7dFukz8kkYpjt24L8K3XJaNAiu2ztkwr7+qiUNfVGR yggoMCaEW1ppirj8tC01JCL83RhoksHgOSNUk+hrrV1UIl6GeCM7my/jNdbLEkoRQvIq5BbVN33 fDKxT X-Google-Smtp-Source: AGHT+IGPlsYl0JUrDhCVUgiur6nAZsVNsjkYj3LKI3ICKbbqmyDasV5z2J6vA4nPw8e61mtOkHPBhw== X-Received: by 2002:a17:906:4690:b0:a6f:52e0:f1ea with SMTP id a640c23a62f3a-a6f60bcc9abmr170951966b.0.1718367802753; Fri, 14 Jun 2024 05:23:22 -0700 (PDT) Received: from localhost.localdomain ([2a04:cec2:26:2e08:be74:f961:1e88:9892]) by smtp.gmail.com with ESMTPSA id a640c23a62f3a-a6f56da3fe5sm183703866b.18.2024.06.14.05.23.22 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 14 Jun 2024 05:23:22 -0700 (PDT) From: Arthur Cohen To: gcc-patches@gcc.gnu.org Cc: gcc-rust@gcc.gnu.org, Arthur Cohen Subject: [PATCH 14.2 1/3] gccrs: Add base documentation for using the Rust frontend. Date: Fri, 14 Jun 2024 16:21:13 +0200 Message-ID: <20240614142300.31778-4-arthur.cohen@embecosm.com> X-Mailer: git-send-email 2.42.0 In-Reply-To: <20240614142300.31778-2-arthur.cohen@embecosm.com> References: <20240614142300.31778-2-arthur.cohen@embecosm.com> MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-Spam-Status: No, score=-13.4 required=5.0 tests=BAYES_00,DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,GIT_PATCH_0,RCVD_IN_DNSWL_NONE,SPF_HELO_NONE,SPF_PASS,TXREP,T_SCC_BODY_TEXT_LINE autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on server2.sourceware.org List-Id: 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