rustbuild: Run all markdown documentation tests
This commit adds support to rustbuild to run all documentation tests, basically
running `rustdoc --test` over all our documentation.
doc: Update our tier support
This modifies our listing of tiered platforms a few ways:
* All lists are alphabetized based on target now
* Lots of targets are moved up to "Tier 2" as we're gating on all these builds
and official releases are provided (and installable via rustup).
* A few targets now list having a compiler + cargo now as well.
No more platforms have been moved up to Tier 1 at this time, however. The only
real candidate is ``x86_64-unknown-linux-musl`, but that's not *quite* to a tier
1 level of quality just yet so let's hold off for another release or so to iron
it out a bit.
This commit adds support to rustbuild to run all documentation tests, basically
running `rustdoc --test` over all our documentation. This also includes support
for running the error index tests.
Reword explanation of 'size' types.
Do not reference machine 'pointers' in explanation of 'size' types.
I think the number of elements that can be directly addressed is a fundamental feature of a machine architecture in its own right. The fact that it coincides with the ‘size’ of a pointer should be viewed as an ‘implementation detail’ ;)
Doc fix: Update Cargo.toml in book/getting-started
The Cargo.toml mentioned in book/getting-started
is missing the section called `[dependencies]`
fixes https://github.com/rust-lang/rust/issues/32928
This modifies our listing of tiered platforms a few ways:
* All lists are alphabetized based on target now
* Lots of targets are moved up to "Tier 2" as we're gating on all these builds
and official releases are provided (and installable via rustup).
* A few targets now list having a compiler + cargo now as well.
No more platforms have been moved up to Tier 1 at this time, however. The only
real candidate is ``x86_64-unknown-linux-musl`, but that's not *quite* to a tier
1 level of quality just yet so let's hold off for another release or so to iron
it out a bit.
Suggest adding a where-clause when that can help
Suggest adding a where-clause when there is an unmet trait-bound that can be satisfied if some type can implement it.
r? @nikomatsakis
Remove error description of `move`
(1) `x` can be used in main() after the call to spawn(). Because the variables follow normal move semantics, though the keyword `move` is used, and i32 implements `Copy`.
(2) I remove this sentence because the previous sentence gives the referrence to `move closures`, and more description of `move` may be redundant.
Minor doc fixes in "Crates and Modules" and "Lifetimes" chapters
These commits fix a couple of (minor) issues in the _Crates and Modules_ and the _Lifetimes_ chapters of the book.
r? @steveklabnik
1. In the English/Japanese phrases example in the "Multiple File
Crates" section of the "Crates and Modules" chapter, there are a total
of 8 module files that Rust looks for, while only four were
listed. This commit lists all 8 explicitly.
2. Title case fix.
(1) `x` can be used in main() after the call to spawn(). Because the variables follow normal move semantics, though the keyword `move` is used, and i32 implements `Copy`.
(2) I remove this sentence because the previous sentence gives the referrence to `move closures`, and more description of `move` may be redundant.
allow RUST_BACKTRACE=0 to act as if unset
**UPDATE:** `RUST_BACKTRACE=0` to act as if the env. var is unset! (now `0` is what `disabled` was for, below)
When RUST_BACKTRACE is set to "disabled" then this acts as if the env. var is unset. So, either make sure `RUST_BACKTRACE` is not set OR set it to `disabled` to achieve the same effect.
Sample usage:
```bash
$ rustc -o /tmp/a.out -- <(echo 'fn main(){ panic!() }') && RUST_BACKTRACE=disabled /tmp/a.out
!! executing '/home/zazdxscf/build/1nonpkgs/rust/rust//x86_64-unknown-linux-gnu/stage2/bin//rustc' with args: '-o /tmp/a.out -- /dev/fd/63'
thread '<main>' panicked at 'explicit panic', /dev/fd/63:1
note: Run with `RUST_BACKTRACE=1` for a backtrace.
$ rustc -o /tmp/a.out -- <(echo 'fn main(){ panic!() }') && RUST_BACKTRACE=1 /tmp/a.out
!! executing '/home/zazdxscf/build/1nonpkgs/rust/rust//x86_64-unknown-linux-gnu/stage2/bin//rustc' with args: '-o /tmp/a.out -- /dev/fd/63'
thread '<main>' panicked at 'explicit panic', /dev/fd/63:1
stack backtrace:
1: 0x55709e8148c0 - sys::backtrace::tracing:👿:write::h140f24a0cfc189b98Ru
2: 0x55709e816a5b - panicking::default_hook::_$u7b$$u7b$closure$u7d$$u7d$::closure.45165
3: 0x55709e8166e8 - panicking::default_hook::hed419823688cb82aXoA
4: 0x55709e810fff - sys_common::unwind::begin_unwind_inner::hbb9642f6e212d56fmHt
5: 0x55709e810513 - sys_common::unwind::begin_unwind::h16232867470678019594
6: 0x55709e810489 - main::hb524f9576270962feaa
7: 0x55709e816314 - sys_common::unwind::try::try_fn::h1274188004693518534
8: 0x55709e813dfb - __rust_try
9: 0x55709e815dab - rt::lang_start::h712b1cd650781872ahA
10: 0x55709e810679 - main
11: 0x7efd1026859f - __libc_start_main
12: 0x55709e810348 - _start
13: 0x0 - <unknown>
```
Some programs(eg. [vim's syntactic](https://github.com/scrooloose/syntastic) used by [rust.vim](https://github.com/rust-lang/rust.vim)) cannot unset the env. var RUST_BACKTRACE if it's already set(eg. in .bashrc) but [they can set it to some value](cb5533e159/system/Z575/OSes/gentoo/on_baremetal/filesystem_now/gentoo/home/zazdxscf/build/1nonpkgs/rust.vim/upd (L17)), and I needed to ensure the env. var is unset in order to avoid this issue: https://github.com/rust-lang/rust/issues/29293
**EDIT:** Sample usage 2:
```bash
$ export RUST_BACKTRACE=1
$ rustc -o /tmp/a.out -- <(echo 'fn main(){ panic!() }') && /tmp/a.out
!! executing '/home/zazdxscf/build/1nonpkgs/rust/rust//x86_64-unknown-linux-gnu/stage2/bin//rustc' with args: '-o /tmp/a.out -- /dev/fd/63'
thread '<main>' panicked at 'explicit panic', /dev/fd/63:1
stack backtrace:
1: 0x55c2696738c0 - sys::backtrace::tracing:👿:write::h140f24a0cfc189b98Ru
2: 0x55c269675a5b - panicking::default_hook::_$u7b$$u7b$closure$u7d$$u7d$::closure.45165
3: 0x55c2696756e8 - panicking::default_hook::hed419823688cb82aXoA
4: 0x55c26966ffff - sys_common::unwind::begin_unwind_inner::hbb9642f6e212d56fmHt
5: 0x55c26966f513 - sys_common::unwind::begin_unwind::h16023941661074805588
6: 0x55c26966f489 - main::hb524f9576270962feaa
7: 0x55c269675314 - sys_common::unwind::try::try_fn::h1274188004693518534
8: 0x55c269672dfb - __rust_try
9: 0x55c269674dab - rt::lang_start::h712b1cd650781872ahA
10: 0x55c26966f679 - main
11: 0x7f593d58459f - __libc_start_main
12: 0x55c26966f348 - _start
13: 0x0 - <unknown>
$ rustc -o /tmp/a.out -- <(echo 'fn main(){ panic!() }') && RUST_BACKTRACE=disabled /tmp/a.out
!! executing '/home/zazdxscf/build/1nonpkgs/rust/rust//x86_64-unknown-linux-gnu/stage2/bin//rustc' with args: '-o /tmp/a.out -- /dev/fd/63'
thread '<main>' panicked at 'explicit panic', /dev/fd/63:1
note: Run with `RUST_BACKTRACE=1` for a backtrace.
```
Book: in beginner guide change irc channel #rust → #rust-beginners
I also would like to add the reference on the first README.md
Some like
```
most popular channel is [#rust], a venue for general discussion about
-Rust, and a good place to ask for help.
+Rust. And a good place to ask for help would be [#rust-beginners].
[IRC]: https://en.wikipedia.org/wiki/Internet_Relay_Chat
[#rust]: irc://irc.mozilla.org/rust
+[#rust-beginners]: irc://irc.mozilla.org/rust-beginners
```
So In the first page would be the two options for #rust or #rust-beginners
/# This is a combination of 16 commits.
/# The first commit's message is:
allow RUST_BACKTRACE=disabled to act as if unset
When RUST_BACKTRACE is set to "disabled" then this acts as if the env.
var is unset.
/# This is the 2nd commit message:
case insensitive "DiSaBLeD" RUST_BACKTRACE value
previously it expected a lowercase "disabled" to treat the env. var as
unset
/# This is the 3rd commit message:
RUST_BACKTRACE=0 acts as if unset
previously RUST_BACKTRACE=disabled was doing the same thing
/# This is the 4th commit message:
RUST_BACKTRACE=0|n|no|off acts as if unset
previously only RUST_BACKTRACE=0 acted as if RUST_BACKTRACE was unset
Now added more options (case-insensitive): 'n','no' and 'off'
eg. RUST_BACKTRACE=oFF
/# This is the 5th commit message:
DRY on the value of 2
DRY=don't repeat yourself
Because having to remember to keep the two places of '2' in sync is not
ideal, even though this is a simple enough case.
/# This is the 6th commit message:
Revert "DRY on the value of 2"
This reverts commit 95a0479d5cf72a2b2d9d21ec0bed2823ed213fef.
Nevermind this DRY on 2, because we already have a RY on 1,
besides the code is less readable this way...
/# This is the 7th commit message:
attempt to document unsetting RUST_BACKTRACE
/# This is the 8th commit message:
curb allocations when checking for RUST_BACKTRACE
this means we don't check for case-insensitivity anymore
/# This is the 9th commit message:
as decided, RUST_BACKTRACE=0 turns off backtrace
/# This is the 10th commit message:
RUST_TEST_NOCAPTURE=0 acts as if unset
(that is, capture is on)
Any other value acts as if nocapture is enabled (that is, capture is off)
/# This is the 11th commit message:
update other RUST_TEST_NOCAPTURE occurrences
apparently only one place needs updating
/# This is the 12th commit message:
update RUST_BACKTRACE in man page
/# This is the 13th commit message:
handle an occurrence of RUST_BACKTRACE
/# This is the 14th commit message:
ensure consistency with new rules for backtrace
/# This is the 15th commit message:
a more concise comment for RUST_TEST_NOCAPTURE
/# This is the 16th commit message:
update RUST_TEST_NOCAPTURE in man page
Book: Fix phrasing: “an associated type” → “an object with an associated type”.
From what I understood, `graph` is the object from which we create a trait object, and the associated types are `Graph::N` and `Graph::E`.
While implementing panic_fmt for the GameCube I noticed that the parameters given to it were completely broken. Turns out that panic_fmt requires the C ABI to work correctly. This should be fixed in the documentation, so that others don't make the same mistake. Thanks to mbrubeck in the IRC for helping me figure this out.
Not specifying extern for lang_items correctly should potentially also be a compiler error.
docs: make some text changes on Section `Macros`
(1) In contrast to `that`, `so that` expresses `result` indicated by the sentence, not `reason`;
(2) `block` is an expression, and may be have an expression, so I add `optionally an expression` to make more precise;
~~(3) When I read here, I was confused with what `the child` referred to. After modification, it would be better.~~
