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.~~
Remove trailing whitespace at the end of lines
According the rules of styling Rust code there should not be trailing whitespace at the end of lines or files. I thought that it might be good to remove trailing whitespace from other files also, if it does not break anything.
This adds checks to ensure that:
* link anchors refer to existing id's on the target page
* id's are unique within an html document
* page redirects are valid
(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 `optional 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.
Add note on `str` being an unsized type in strings section of book
The book section on Rust strings mentions `&str` and `String` but does not address why `str` is not used directly. This adds a short blurb and a link to the unsized types chapter. The second draft of the book will go more in-depth on this, but this should help a bit for now. Thanks #rust for clarifying this point, and let me know if it needs rewording or different placement 😄.
CC @steveklabnik @Kimundi
Document heap allocation location guarantee
```
14:25 < aidanhs> is there any guarantee that boxes will not move the value on the heap when they are moved?
14:26 <@steveklabnik> aidanhs: ... i'm not sure if it's a guarantee, but it follows, generally
14:26 <@steveklabnik> aidanhs: moves mean memcpy, so you're memcpying the structure of the box itself, which is copying the pointer
14:26 <@steveklabnik> so the pointer won't be updated
14:26 <@steveklabnik> moves cannot do complex things like move the memory around on the heap
14:26 <@kmc> aidanhs: I would say it's guaranteed
14:27 < aidanhs> steveklabnik: yeah, that's what I was thinking, it'd be pretty strange for rust to do something, but I couldn't find any docs one way or the other
14:27 <@steveklabnik> kmc: aidanhs yeah, it's like a borderline thing that we don't explicitly guanratee but i think IS guaranteed by our other guarantees
14:27 <@steveklabnik> mostly that move == memcpy
14:28 < aidanhs> kmc: steveklabnik great thanks! would a PR to the rust reference along these lines be ok?
14:28 < jmesmon> aidanhs: I believe owning_ref has some discussion of that (stable references)
14:29 <@steveklabnik> aidanhs: i would probably take that, yeah
14:29 < aidanhs> jmesmon: thanks, I'll take a look at that
```
https://botbot.me/mozilla/rust/2016-02-22/?msg=60657619&page=18
r? @steveklabnik
Docs: Change "statements" to "expressions" on `match`
I apt to use `expressions` over `statements`, because `match` is a expression in essence, though it can become a statement when followed a semicolon.
Simplifying some of the phrasing explaining lifetime elision
Just simplifying some of the language expressing what kind of inference Rust can and can't do on function signatures.
Update of the book; Error handling, section on custom error types: we…
… should also show the changes to the `cause` method.
When I started creating my own error type, I found that we also have to update the cause method, otherwise we have a missing match branch.
It would also be nice to elaborate on the relationship and difference between the description() and fmt() method, but that should be done by someone with more experience with them. :)
docs: `let` introduces a statement
I changes *expression* to *statement* to make more accurate, because in Rust, `let` introduces a declaration statement.
Add a link validator to rustbuild
This commit was originally targeted at just adding a link checking script to the rustbuild system. This ended up snowballing a bit to extend rustbuild to be amenable to various tools we have as part of the build system in general.
There's a new `src/tools` directory which has a number of scripts/programs that are purely intended to be used as part of the build system and CI of this repository. This is currently inhabited by rustbook, the error index generator, and a new linkchecker script added as part of this PR. I suspect that more tools like compiletest, tidy scripts, snapshot scripts, etc will migrate their way into this directory over time.
The commit which adds the error index generator shows the steps necessary to add new tools to the build system, namely:
1. New steps are defined for building the tool and running the tool
2. The dependencies are configured
3. The steps are implemented
In terms of the link checker, these commits do a few things:
* A new `src/tools/linkchecker` script is added. This will read an entire documentation tree looking for broken relative links (HTTP links aren't followed yet).
* A large number of broken links throughout the documentation were fixed. Many of these were just broken when viewed from core as opposed to std, but were easily fixed.
* A few rustdoc bugs here and there were fixed
Small grammar fix in Guessing Game
When it was Option.expect(), there was an .ok().expect(), but now that it uses Result.expect(), there's only one method, not two.
Fixes#31912
Remove final note from testing chapter.
The information that documentation tests cannot be run in binary crates is already given at the beginning of the section.
A few categories:
* Links into compiler docs were just all removed as we're not generating
compiler docs.
* Move up one more level to forcibly go to std docs to fix inlined documentation
across the facade crates.
Clarify the semantics of enum discriminants
cf. https://doc.rust-lang.org/error-index.html#E0082
> The default type for enum discriminants is isize, but it can be adjusted by adding the repr attribute to the enum declaration.
It would be great if anyone could check my English.
This PR implements [RFC 1192](https://github.com/rust-lang/rfcs/blob/master/text/1192-inclusive-ranges.md), which is triple-dot syntax for inclusive range expressions. The new stuff is behind two feature gates (one for the syntax and one for the std::ops types). This replaces the deprecated functionality in std::iter. Along the way I simplified the desugaring for all ranges.
This is my first contribution to rust which changes more than one character outside of a test or comment, so please review carefully! Some of the individual commit messages have more of my notes. Also thanks for putting up with my dumb questions in #rust-internals.
- For implementing `std::ops::RangeInclusive`, I took @Stebalien's suggestion from https://github.com/rust-lang/rfcs/pull/1192#issuecomment-137864421. It seemed to me to make the implementation easier and increase type safety. If that stands, the RFC should be amended to avoid confusion.
- I also kind of like @glaebhoerl's [idea](https://github.com/rust-lang/rfcs/pull/1254#issuecomment-147815299), which is unified inclusive/exclusive range syntax something like `x>..=y`. We can experiment with this while everything is behind a feature gate.
- There are a couple of FIXMEs left (see the last commit). I didn't know what to do about `RangeArgument` and I haven't added `Index` impls yet. Those should be discussed/finished before merging.
cc @Gankro since you [complained](https://www.reddit.com/r/rust/comments/3xkfro/what_happened_to_inclusive_ranges/cy5j0yq)
cc #27777#30877rust-lang/rust#1192rust-lang/rfcs#1254
relevant to #28237 (tracking issue)
Vectors come up in sections dedicated to ownership with the assumption that we know something about it but we haven't seen it yet. On the other hand, you need not know anything about ownership or lifetimes to understand the basics of vectors covered in the vector section of the book. Additionally, by moving it where it is there is a natural progression from loops to an iterative type which discusses for loops. This kind of interaction is generally better for learning.
I would like to have moved the struct section as well but I'm less confident about how to handle it since the ownership sections discuss structs and the structs section talks about mutable borrow.
This commit implements documentation generation of the nomicon, the book, the
style guide, and the standalone docs. New steps were added for each one as well
as appropriate makefile targets for each one as well.
This commit is the result of the FCPs ending for the 1.8 release cycle for both
the libs and the lang suteams. The full list of changes are:
Stabilized
* `braced_empty_structs`
* `augmented_assignments`
* `str::encode_utf16` - renamed from `utf16_units`
* `str::EncodeUtf16` - renamed from `Utf16Units`
* `Ref::map`
* `RefMut::map`
* `ptr::drop_in_place`
* `time::Instant`
* `time::SystemTime`
* `{Instant,SystemTime}::now`
* `{Instant,SystemTime}::duration_since` - renamed from `duration_from_earlier`
* `{Instant,SystemTime}::elapsed`
* Various `Add`/`Sub` impls for `Time` and `SystemTime`
* `SystemTimeError`
* `SystemTimeError::duration`
* Various impls for `SystemTimeError`
* `UNIX_EPOCH`
* `ops::{Add,Sub,Mul,Div,Rem,BitAnd,BitOr,BitXor,Shl,Shr}Assign`
Deprecated
* Scoped TLS (the `scoped_thread_local!` macro)
* `Ref::filter_map`
* `RefMut::filter_map`
* `RwLockReadGuard::map`
* `RwLockWriteGuard::map`
* `Condvar::wait_timeout_with`
Closes#27714Closes#27715Closes#27746Closes#27748Closes#27908Closes#29866
Refinement of paragraph referenced by [this issue](https://github.com/rust-lang/rust/issues/31927).
The paragraph in question had been adjusted already, but I've made some further clarifications which should help with readability and not leave the reader any `dangling pointers`.
As a Rust newbie, I found the book's explanation for why the `filter` closure gets a reference very confusing, and tried to figure out why `filter` is somehow less consumptive than `map` -- but it isn't; that's controlled by `iter`/`into_iter`. I flailed around for a while until @habnabit explained it to me, and in retrospect it is quite obvious :-)
Reference implied that use declarations may appear *only* at the top of blocks and modules, but it is not the case, and the following is valid:
```Rust
fn foo() {
let x = 92;
use baz::bar;
}
```
r? @steveklabnik
This commit implements documentation generation of the nomicon, the book, the
style guide, and the standalone docs. New steps were added for each one as well
as appropriate makefile targets for each one as well.
I feel sorry for bothering you with such a literally one character changes. If it is counter productive feel free to point it out in the comments, that would be totally understandable. I could try to pack such a changes together in one PR to make them less distractive.
r? @steveklabnik
Not everyone knows this convention. We could just rename the variables in the
example, but since this notation is commonly used it's a good opportunity to
introduce it.
r? @steveklabnik
This is a minor change. Please see title. IMO this is important since this is the first instance when we talk about allocating a vector. Not saying that it is allocated on the stack here leaves room for speculation and this might put off some people (they might not even read the later sections which go into more detail about this).
The scope of these refactorings is a little bit bigger than the title implies. See each commit for details.
I’m submitting this for nitpicking now (the first 4 commits), because I feel the basic idea/implementation is sound and should work. I will eventually expand this PR to cover the translator changes necessary for all this to work (+ tests), ~~and perhaps implement a dynamic dropping scheme while I’m at it as well.~~
r? @nikomatsakis
Currently the `mipsel-unknown-linux-gnu` target doesn't actually set the
`target_arch` value to `mipsel` but it rather uses `mips`. Alternatively the
`powerpc64le` target does indeed set the `target_arch` as `powerpc64le`,
causing a bit of inconsistency between theset two.
As these are just the same instance of one instruction set, let's use
`target_endian` to switch between them and only set the `target_arch` as one
value. This should cut down on the number of `#[cfg]` annotations necessary and
all around be a little more ergonomic.
Some other shufflings as well:
* Three powerpc triples for Linux have been added recently
* An armv7 linux triple was added recently
* The 64-bit Solaris triple is now mentioned in tier 3
We are currently now also building nightlies for iOS, powerpc triples, and
armv7, but there hasn't been much vetting of the triples themselves so I've left
them in tier 3 for now.
Fixes#31334
This is just a quicker fix for this issue; since I'm working on the next draft of the book, I don't want to put a huuuge amount of work into improving it here.
Updated documentation to clarify the difference between `and_then` and `map`. This also explains why we need `and_then` in addition to `map`. Please look at the diff for more information.
r? @alexcrichton
Currently the `mipsel-unknown-linux-gnu` target doesn't actually set the
`target_arch` value to `mipsel` but it rather uses `mips`. Alternatively the
`powerpc64le` target does indeed set the `target_arch` as `powerpc64le`,
causing a bit of inconsistency between theset two.
As these are just the same instance of one instruction set, let's use
`target_endian` to switch between them and only set the `target_arch` as one
value. This should cut down on the number of `#[cfg]` annotations necessary and
all around be a little more ergonomic.
Some other shufflings as well:
* Three powerpc triples for Linux have been added recently
* An armv7 linux triple was added recently
* The 64-bit Solaris triple is now mentioned in tier 3
We are currently now also building nightlies for iOS, powerpc triples, and
armv7, but there hasn't been much vetting of the triples themselves so I've left
them in tier 3 for now.
