From 55760f3999e43d2e49ed7f557a5f79a380dbcdb3 Mon Sep 17 00:00:00 2001 From: "A.J. Gardner" Date: Sun, 21 Jan 2018 17:34:57 -0600 Subject: [PATCH 1/3] Start documenting rustc and rustdoc --- src/SUMMARY.md | 4 ++++ src/tools.md | 14 ++++++++++++ src/tools/rustc.md | 54 ++++++++++++++++++++++++++++++++++++++++++++ src/tools/rustdoc.md | 8 +++++++ src/undocumented.md | 6 ----- 5 files changed, 80 insertions(+), 6 deletions(-) create mode 100644 src/tools.md create mode 100644 src/tools/rustc.md create mode 100644 src/tools/rustdoc.md diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 642e4b483..7e6563538 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -82,6 +82,10 @@ - [Behavior considered undefined](behavior-considered-undefined.md) - [Behavior not considered unsafe](behavior-not-considered-unsafe.md) +- [Tools](tools.md) + - [rustc](tools/rustc.md) + - [rustdoc](tools/rustdoc.md) + [Appendix: Influences](influences.md) [Appendix: As-yet-undocumented Features](undocumented.md) diff --git a/src/tools.md b/src/tools.md new file mode 100644 index 000000000..36286dc11 --- /dev/null +++ b/src/tools.md @@ -0,0 +1,14 @@ +# Tools + +The official Rust tool suite contains a variety of tools for dealing with Rust +code and associated artifacts. + +[`rustc`][rustc] is the Rust language compiler. + +[`rustdoc`][rustdoc] is the documentation tool which generates documentation from Rust +source code. + +`cargo` is the Rust package manager. + +[rustc]: tools/rustc.html +[rustdoc]: tools/rustdoc.html diff --git a/src/tools/rustc.md b/src/tools/rustc.md new file mode 100644 index 000000000..00714c883 --- /dev/null +++ b/src/tools/rustc.md @@ -0,0 +1,54 @@ +# `rustc` + +The Rust compiler has many options and can accept a wide variety of arguments, +and its behavior can vary depending on the values of several environment +variables. + +We document the compiler's command-line options, arguments, and operative +environment variables here. + +Some discussions of environment variables exists in the [Linkage](linkage.html) +chapter and the [Operator expressions](expressions/operator-expr.html#overflow) +chapter. + +## Lint options + + -W, --warn OPT Set lint warnings + -A, --allow OPT Set lint allowed + -D, --deny OPT Set lint denied + -F, --forbid OPT Set lint forbidden + --cap-lints LEVEL + Set the most restrictive lint level. More restrictive + lints are capped at this level + +## Codegen options + +`rustc` provides many options for codegen, all accessible as arguments to the +`-C` option. + +### Debug info + +To produce output with debug info use the `-C debuginfo=val` option, where +`val` may be one of `0`, `1`, or `2`. The default is `0`. + - `0` means output no debug info + - `1` means output only line tables + - `2` means output full debug info with variable and type information + +Providing the `-g` option is equivalent to `-C debuginfo=2`. If both `-g` and +`-C debuginfo` are provided, the compiler will complain. + +### Optimization + +To produce optimized output, use the `-C opt-level=val` option, where `val` +may be one of `0`, `1`, `2`, `3`. The nightly compiler will also accept `s`, +or `z`. The default is `0`. + - `0-3` direct `rustc` to optimize for execution speed with `0` meaning no + optimizations, and `3` meaning aggressive optimization. + - `s` and `z` direct `rustc` to optimize for output size, with `s` meaning + typical size optimizations and `z` meaning aggressive size optimizations. + +Providing the option `-O` is equivalent to `-C opt-level=2`. If both `-O` and +`-C opt-level` are provided, the compiler will complain. + +If `s` or `z` are provided on a non-nightly compiler, the compiler will +complain. diff --git a/src/tools/rustdoc.md b/src/tools/rustdoc.md new file mode 100644 index 000000000..fd555ec55 --- /dev/null +++ b/src/tools/rustdoc.md @@ -0,0 +1,8 @@ +# `rustdoc` + +`rustdoc` has many options and can accept a wide variety of arguments, +and its behavior can vary depending on the values of several environment +variables. + +We document its command-line options, arguments, and operative environment +variables here. diff --git a/src/undocumented.md b/src/undocumented.md index e7eaf10d3..58987af1d 100644 --- a/src/undocumented.md +++ b/src/undocumented.md @@ -14,9 +14,7 @@ to shrink! specified. - [Flexible target specification] - Some---but not all---flags are documented in [Conditional compilation] -- [Require parentheses for chained comparisons] - [`dllimport`] - one element mentioned but not explained at [FFI attributes] -- [define `crt_link`] - [define `unaligned_access`] [`libstd` facade]: https://github.com/rust-lang/rfcs/pull/40 @@ -24,10 +22,6 @@ to shrink! [Attributes on `match` arms]: https://github.com/rust-lang/rfcs/pull/49 [Flexible target specification]: https://github.com/rust-lang/rfcs/pull/131 [Conditional compilation]: attributes.html#conditional-compilation -[Unambiguous function call syntax]: https://github.com/rust-lang/rfcs/pull/132 -[Require parentheses for chained comparisons]: https://github.com/rust-lang/rfcs/pull/558 -[Integer overflow not `unsafe`]: https://github.com/rust-lang/rfcs/pull/560 [`dllimport`]: https://github.com/rust-lang/rfcs/pull/1717 [FFI attributes]: attributes.html#ffi-attributes -[define `crt_link`]: https://github.com/rust-lang/rfcs/pull/1721 [define `unaligned_access`]: https://github.com/rust-lang/rfcs/pull/1725 From ea5facd864ac0504312afbab6c49e929b7e47b5a Mon Sep 17 00:00:00 2001 From: "A.J. Gardner" Date: Sun, 21 Jan 2018 17:58:14 -0600 Subject: [PATCH 2/3] Point at rustdoc and cargo books --- src/SUMMARY.md | 1 + src/tools.md | 1 + src/tools/cargo.md | 3 +++ src/tools/rustdoc.md | 7 +------ 4 files changed, 6 insertions(+), 6 deletions(-) create mode 100644 src/tools/cargo.md diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 7e6563538..9823cfb00 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -85,6 +85,7 @@ - [Tools](tools.md) - [rustc](tools/rustc.md) - [rustdoc](tools/rustdoc.md) + - [cargo](tools/cargo.md) [Appendix: Influences](influences.md) diff --git a/src/tools.md b/src/tools.md index 36286dc11..e9483ef60 100644 --- a/src/tools.md +++ b/src/tools.md @@ -12,3 +12,4 @@ source code. [rustc]: tools/rustc.html [rustdoc]: tools/rustdoc.html +[cargo]: tools/cargo.html diff --git a/src/tools/cargo.md b/src/tools/cargo.md new file mode 100644 index 000000000..a8bb0739f --- /dev/null +++ b/src/tools/cargo.md @@ -0,0 +1,3 @@ +# Cargo + +`cargo` has its own reference [here](../cargo/reference/index.html). diff --git a/src/tools/rustdoc.md b/src/tools/rustdoc.md index fd555ec55..899ac03f7 100644 --- a/src/tools/rustdoc.md +++ b/src/tools/rustdoc.md @@ -1,8 +1,3 @@ # `rustdoc` -`rustdoc` has many options and can accept a wide variety of arguments, -and its behavior can vary depending on the values of several environment -variables. - -We document its command-line options, arguments, and operative environment -variables here. +`rustdoc` has its own book [here](../rustdoc/index.html). From 3347135365f42688ae7a5c5096c91aebf61ba78c Mon Sep 17 00:00:00 2001 From: "A.J. Gardner" Date: Sun, 21 Jan 2018 23:24:52 -0600 Subject: [PATCH 3/3] Remove nightly-only information --- src/tools/rustc.md | 13 ++++--------- 1 file changed, 4 insertions(+), 9 deletions(-) diff --git a/src/tools/rustc.md b/src/tools/rustc.md index 00714c883..e3fcb8cce 100644 --- a/src/tools/rustc.md +++ b/src/tools/rustc.md @@ -40,15 +40,10 @@ Providing the `-g` option is equivalent to `-C debuginfo=2`. If both `-g` and ### Optimization To produce optimized output, use the `-C opt-level=val` option, where `val` -may be one of `0`, `1`, `2`, `3`. The nightly compiler will also accept `s`, -or `z`. The default is `0`. - - `0-3` direct `rustc` to optimize for execution speed with `0` meaning no - optimizations, and `3` meaning aggressive optimization. - - `s` and `z` direct `rustc` to optimize for output size, with `s` meaning - typical size optimizations and `z` meaning aggressive size optimizations. +may be one of `0`, `1`, `2`, `3`. The default is `0`. + +The numbers indicate increasing levels of optimization for execution speed, +with `0` meaning no optimizations, and `3` meaning aggressive optimization. Providing the option `-O` is equivalent to `-C opt-level=2`. If both `-O` and `-C opt-level` are provided, the compiler will complain. - -If `s` or `z` are provided on a non-nightly compiler, the compiler will -complain.