This is part of #28572, but doesn't complete it. Amongst other things,
this patch:
* Increases consistency in the way feature flags are used with other
docs.
* Removes the ignores, which is nice: we actually had some syntax errors
in the examples 😭.
* Mentions #![no_core]
Realistically, this document used to be in the order of least to most:
nothing, then adding core. But with the changes in RFC 1184, this is
backwards: it now shows stuff that uses core from the beginning. In the
future, I'd like to revamp this to go from 'most to least', but I'd like
to see the discussion in https://github.com/rust-lang/rust/issues/27701
goes before I write more.
We don't completely cover documentation tests in the testing chapter,
since we cover them in the documentation chapter. So make sure people
know that.
Fixes#28082
The original blog post referred to examples by their file names, and now
that it's in guide form, there is no file name. So edit the text so that
it makes a bit more sense.
Fixes#28428
The links in the rustdoc for several places in fmt were trying to link to
the std::fmt module but actually linking to std, which was confusing.
While trying to figure out why I noticed that the documentation chapter of
the Rust book has examples that show this same bug (although it doesn't seem
widespread in practice).
r? @steveklabnik
We don't completely cover documentation tests in the testing chapter,
since we cover them in the documentation chapter. So make sure people
know that.
Fixes#28082
The original blog post referred to examples by their file names, and now
that it's in guide form, there is no file name. So edit the text so that
it makes a bit more sense.
Fixes#28428
The links in the rustdoc for several places in fmt were trying to link to
the std::fmt module but actually linking to std, which was confusing.
While trying to figure out why I noticed that the documentation chapter of
the Rust book has examples that show this same bug (although it doesn't seem
widespread in practice).
This is part of #28572, but doesn't complete it. Amongst other things,
this patch:
* Increases consistency in the way feature flags are used with other
docs.
* Removes the ignores, which is nice: we actually had some syntax errors
in the examples 😭.
* Mentions #![no_core]
Realistically, this document used to be in the order of least to most:
nothing, then adding core. But with the changes in RFC 1184, this is
backwards: it now shows stuff that uses core from the beginning. In the
future, I'd like to revamp this to go from 'most to least', but I'd like
to see the discussion in https://github.com/rust-lang/rust/issues/27701
goes before I write more.
- Expand the first paragraph
- Improve readability by partitioning the chapter into the following
sections: "Patterns", "Type annotations", "Mutability", and
"Initializing bindings"
- Add "Scope and shadowing" section (fix#28177)
This was non-obvious to me: with no example, I assumed `Electron {}` and
didn't know what else to try when it didn't work. The correct form is
weird because it looks like you're assigning the struct name rather than
an instance of the struct.
r? @steveklabnik
the example for `find` was misleading in that it fails to mention the result is either `None` or `Some` containing only the first match. Further confusing the issue is the `println!` statement, "We got some numbers!"
This wasn't complete (you need a `./configure`), and it is already
documented well in the main README.
Also adds a reference to the books that this also generates.
This was non-obvious to me: with no example, I assumed `Electron {}` and
didn't know what else to try when it didn't work. The correct form is
weird because it looks like you're assigning the struct name rather than
an instance of the struct.
the example for `find` was misleading in that it fails to mention the result is either `None` or `Some` containing only the first match. Further confusing the issue is the `println!` statement, "We got some numbers!"
This adds a new target property, `target_vendor`. It is to be be used as a matcher for conditional compilation. The vendor is part of the [autoconf target triple](http://llvm.org/docs/doxygen/html/classllvm_1_1Triple.html#details): `<arch><sub>-<vendor>-<os>-<env>`. `arch`, `target_os` and `target_env` are already supported by Rust.
This change was suggested in PR #28593. It enables conditional compilation based on the vendor. This is needed for the rumprun target, which needs to match against both, target_os and target_vendor.
The default value for `target_vendor` is "unknown", "apple" and "pc" are other common values.
Matching against the `target_vendor` is introduced behind the feature gate `#![feature(cfg_target_vendor)]`.
This is the first time I messed around with rustc internals. I just added the my code where I found the existing `target_*` variables, hopefully I haven't missed anything. Please review with care. :)
r? @alexcrichton
This adds a new target property, `target_vendor` which can be used as a
matcher for conditional compilation. The vendor is part of the autoconf
target triple: <arch><sub>-<vendor>-<os>-<env>
The default value for `target_vendor` is "unknown".
Matching against the `target_vendor` with `#[cfg]` is currently feature
gated as `cfg_target_vendor`.
This changes how rustic generate `id` and `href` attributes for section header anchor. Now they are more github-like.
Also fixes breakage in docs caused by this and broken links in "Error Handling" section of book.
r? @steveklabnik
cc @alexcrichton
In code like `let x = 5`, I am initially confused as to the meaning of "let doesn't take a name on the left hand side, it actually accepts a pattern." - I interpret that as the pattern being located as: `<pattern> let [...]`.
I think what is meant is that the name/pattern is on the left hand side *of the assignment*, rather than to the left of the *let* statement. This change clarifies that.
Using "later" in this context makes more sense than "greater" so it's been changed to match the Linux requirement above it rather than the other way around.
- Headlines begin at 1st level now like the rest of the book
- All Headlines a blank line above and below
- Fix links in this chapter's TOC
r? @steveklabnik
This commit does some refactoring to make almost all of the `std::rt` private.
Specifically, the following items are no longer part of its API:
* DEFAULT_ERROR_CODE
* backtrace
* unwind
* args
* at_exit
* cleanup
* heap (this is just alloc::heap)
* min_stack
* util
The module is now tagged as `#[doc(hidden)]` as the only purpose it's serve is
an entry point for the `panic!` macro via the `begin_unwind` and
`begin_unwind_fmt` reexports.
This commit does some refactoring to make almost all of the `std::rt` private.
Specifically, the following items are no longer part of its API:
* DEFAULT_ERROR_CODE
* backtrace
* unwind
* args
* at_exit
* cleanup
* heap (this is just alloc::heap)
* min_stack
* util
The module is now tagged as `#[doc(hidden)]` as the only purpose it's serve is
an entry point for the `panic!` macro via the `begin_unwind` and
`begin_unwind_fmt` reexports.
r? @steveklabnik
The phrase 'academic research' rubs me the wrong way. I have some concern about the role of this page and think it could be expanded to more than just academic papers and cleaned up a lot.
I took a stab at fixing #28064. Not sure if this all-features-in-one-example approach is the right one. Also I completely made up the terms "star globbing" and "brace expansion globbing" -- they are just called "glob-like syntax" in the reference.
I took a stab at fixing #28064. Not sure if this all-features-in-one-example approach is the right one. Also I completely made up the terms "star globbing" and "brace expansion globbing" -- they are just called "glob-like syntax" in the reference.
As I understand, there are no proc closures in Rust any more. So this pr removes `procedure_type` production. It isn't used anywhere. The `proc` is still a keyword.
r? @steveklabnik
@bors: r+ rollup
I have two issues with the section "Deref and method calls" of the book's chapter "Deref coercions".
- (Minor) It says "In other words, these are the same two things in Rust:", followed by a code block in which no two things seem similar, much less the same. Presumably this sentence made more sense in a previous revision.
- The next paragraph conflates two concepts which, imho, should kept separate. They are
- deref coercion, i.e. inserting as many `*` as necessary and
- implicitly referencing the receiver, i.e. inserting a single `&` to satisfy the method's `self` parameter type.
I appreciate that with the proposed changes the example becomes very contrived, even for a foo-bar-baz one. However, the current exmplanation is just wrong.
This adds missing `?` marks to productions for loops and break/continue.
It also adds missing option label to while let loop.
Note that '[' foo ']' means grouping in BNF, and '?' is used for possible missing items.
r? @steveklabnik
Originally in an example it reads as follows:
```rust
fn inverse<T>() -> T
// this is using ConvertTo as if it were "ConvertFrom<i32>"
where i32: ConvertTo<T> {
42.convert()
}
```
There was no mention of `ConvertFrom` elsewhere in the page other than in this comment. Is this supposed to be `ConvertTo<i64>` ?
I'm confused by this example.
It came up twice in quick succession on IRC that rustdoc doesn't run tests in bin crates, and doesn't give any explanation/warning either as to why. I thought it couldn't hurt to emphasize that in the Book.
The chapter on concurrency has two examples that both start with:
let something = thread::spawn(…
but the returned values have different types, because the second example has `.join()` at the end of the expression.
I haven't noticed that join at first, and was wondering how is that possible that the result can have `.is_err()` and `.join()` methods.
I've changed the second example to have the same structure as the first, so they're easy to compare.
Per @steveklabnik's comment [here](https://github.com/rust-lang/cargo/issues/739#issuecomment-130085860), the Pandoc components of the Makefile are no longer used, and as such the corresponding components of the documentation are out of date.
- I've removed the Pandoc (and therefore also LaTeX) elements of the makefile and confirmed that the build proceeds correctly.
- I updated the documentation to reference `rustdoc` and of Pandoc.
r? @steveklabnik
The previous wording was confusing. While would we need to go through
the whole list just to find the first code point? `chars()` being an
iterator, we only need to walk from the beginning of the list.
Note that I am not a native English speaker and I have still difficulties to spot if a "the" is needed somewhere. Feel free to take this PR as a mere suggestion.
r? @steveklabnik
To correctly reexport statically included libraries from a DLL on Windows, the
compiler will soon need to have knowledge about what symbols are statically
included and which are not. To solve this problem a new unstable
`#[linked_from]` attribute is being added and recognized on `extern` blocks to
indicate which native library the symbols are coming from.
The compiler then keeps track of what the set of FFI symbols are that are
included statically. This information will be used in a future commit to
configure how we invoke the linker on Windows.
This commit removes all morestack support from the compiler which entails:
* Segmented stacks are no longer emitted in codegen.
* We no longer build or distribute libmorestack.a
* The `stack_exhausted` lang item is no longer required
The only current use of the segmented stack support in LLVM is to detect stack
overflow. This is no longer really required, however, because we already have
guard pages for all threads and registered signal handlers watching for a
segfault on those pages (to print out a stack overflow message). Additionally,
major platforms (aka Windows) already don't use morestack.
This means that Rust is by default less likely to catch stack overflows because
if a function takes up more than one page of stack space it won't hit the guard
page. This is what the purpose of morestack was (to catch this case), but it's
better served with stack probes which have more cross platform support and no
runtime support necessary. Until LLVM supports this for all platform it looks
like morestack isn't really buying us much.
cc #16012 (still need stack probes)
Closes#26458 (a drive-by fix to help diagnostics on stack overflow)
r? @brson
This commit removes all morestack support from the compiler which entails:
* Segmented stacks are no longer emitted in codegen.
* We no longer build or distribute libmorestack.a
* The `stack_exhausted` lang item is no longer required
The only current use of the segmented stack support in LLVM is to detect stack
overflow. This is no longer really required, however, because we already have
guard pages for all threads and registered signal handlers watching for a
segfault on those pages (to print out a stack overflow message). Additionally,
major platforms (aka Windows) already don't use morestack.
This means that Rust is by default less likely to catch stack overflows because
if a function takes up more than one page of stack space it won't hit the guard
page. This is what the purpose of morestack was (to catch this case), but it's
better served with stack probes which have more cross platform support and no
runtime support necessary. Until LLVM supports this for all platform it looks
like morestack isn't really buying us much.
cc #16012 (still need stack probes)
Closes#26458 (a drive-by fix to help diagnostics on stack overflow)
The previous wording was confusing. While would we need to go through
the whole list just to find the first code point? `chars()` being an
iterator, we only need to walk from the beginning of the list.
Keeping integer values and integer references in the "value" columns made the examples quite difficult for me to follow. I've added unicode arrows to make references more obvious, without using a character with actual meaning in the rust language (like `&` or previously `~`).
I got a bit confused reading the guide over why all of a sudden there was an asterisk in the code. I was explained what it was there for in the IRC, and I think it should added it to the docs to prevent any further confusion!
In Section 3.2, TARPL says that "standard allocators (including jemalloc, the one used by default in Rust) generally consider passing in 0 for the size of an allocation as Undefined Behaviour."
However, the C standard and jemalloc manual says allocating zero bytes
should succeed:
- C11 7.22.3 paragraph 1: "If the size of the space requested is zero, the behavior is implementation-defined: either a null pointer is returned, or the behavior is as if the size were some nonzero value, except that the returned pointer shall not be used to access an object."
- [jemalloc manual](http://www.freebsd.org/cgi/man.cgi?query=jemalloc&sektion=3): "The malloc and calloc functions return a pointer to the allocated memory if successful; otherwise a NULL pointer is returned and errno is set to ENOMEM."
+ Note that the description for `allocm` says "Behavior is undefined if size is 0," but it is an experimental API.
r? @Gankro
In Section 3.2, TARPL says that "standard allocators (including jemalloc, the one used by default in Rust) generally consider passing in 0 for the size of an allocation as Undefined Behaviour."
However, the C standard and jemalloc manual says allocating zero bytes
should succeed:
- C11 7.22.3 paragraph 1: "If the size of the space requested is zero, the behavior is implementation-defined: either a null pointer is returned, or the behavior is as if the size were some nonzero value, except that the returned pointer shall not be used to access an object."
- [jemalloc manual](http://www.freebsd.org/cgi/man.cgi?query=jemalloc&sektion=3): "The malloc and calloc functions return a pointer to the allocated memory if successful; otherwise a NULL pointer is returned and errno is set to ENOMEM."
+ Note that the description for `allocm` says "Behavior is undefined if size is 0," but it is an experimental API.
'work' can refer to the game itself, ie, 'this compiles but the game isn't finished,'
so 'compile' is a more clear way to describe the problem.
Thanks jhun on irc
'work' can refer to the game itself, ie, 'this compiles but the game isn't finished,'
so 'compile' is a more clear way to describe the problem.
Thanks jhun on irc
- Move "Destructuring" after "Multiple patterns", because some of
later sections include examples which make use of destructuring.
- Move "Ignoring bindings" after "Destructoring", because the former
features Result<T,E> destructuring. Some of examples in later
sections use "_" and "..", so "Ignoring bindings" must be
positioned before them.
- Fix#27347 by moving "Ref and mut ref" before "Ranges" and
"Bindings", because "Bindings" section includes a somewhat
difficult example, which also makes use of "ref" and "mut ref"
operators.
- Move "Destructuring" after "Multiple patterns", because some of
later sections include examples which make use of destructuring.
- Move "Ignoring bindings" after "Destructoring", because the former
features Result<T,E> destructuring. Some of examples in later
sections use "_" and "..", so "Ignoring bindings" must be
positioned before them.
- Fix#27347 by moving "Ref and mut ref" before "Ranges" and
"Bindings", because "Bindings" section includes a somewhat
difficult example, which also makes use of "ref" and "mut ref"
operators.
- Fix#26968 by noting the difference between ".." and "_" more explicitly
- Change one of the examples to show the match-all behaviour of ".."
- Merge "Ignoring variants" and "Ignoring bindings" sections into the latter
r? @steveklabnik
Clarifications for those new to Rust and Cargo:
* It's a good idea to get rid of the original `main.exe` in project root
* Slight clarification on the use of `main.rs` vs `lib.rs`
* Clarify that the TOML file needs to be in project root
- Fix#26968 by noting the difference between ".." and "_" more explicitly
- Change one of the examples to show the match-all behaviour of ".."
- Merge "Ignoring variants" and "Ignoring bindings" sections into the latter
this makes the second code block consistent with the first code block -- other than being in reversed order, the first code block claims b is u16 and c is u32, whereas the second code block claims the opposite. seems to be an obvious typo.
This is *mostly* reducing *my* use of *italics* but there's some other misc changes interspersed as I went along.
This updates the italicizing alphabetically from `a` to `ra`.
r? @steveklabnik
Squashed at reviewer's request:
Add heading at the end of the introductory material
Spice up introductory paragraphs a bit
Use quotes instead of <code> for phrase
Remove "other" in "other restrictions" (it's not obvious that any other
restrictions have been mentioned)
"Default methods" is a second-level heading, but is not a subsection of
"Where clause"
Reword "Default methods" introduction: it's not the "last feature" on
this page
This includes a new example with Rectangle, instead of reusing HasArea,
because fn area would require the Mul trait, and the added complexity of
that would be better left for the Operators and Overloading chapter.
Squashed at reviewer's request: Move teaser for trait bounds to bottom
Guessing Game states that "Rust only imports a few things into every
program, the ‘prelude’". That isn't strictly true. That is all it
imports by default and the change clarifies that point.
I've been baking this out of tree for long enough. This is currently about ~2/5ths the size of TRPL. Time to get it in tree so it can be more widely maintained and scrutinized. I've preserved the whole gruesome history including various rewrites. I can definitely squash these a fair amount if desired. Some random people submitted minor fixes though, so they're mixed in.
Edit: forgot to link to rendered http://cglab.ca/~abeinges/blah/turpl/_book/
Edit2:
To streamline the review process, I'm going to break this into sections that need official "domain expert" approval:
# Summary
* [ ] references.md -- very important, needs work
* [x] Meet Safe and Unsafe: reviewed by @aturon
* [x] Data Layout: reviewed by @arielb1
* [x] Ownership: reviewed by @aturon ( and sorta @nikomatsakis ) -- significantly updated, may need re-r
* [x] Coversions: reviewed by @nrc
* [x] Uninitialized Memory: reviewed by @pnkfelix
* [x] Ownership-Oriented Resource Management: reviewed by @aturon
* [x] Unwinding: reviewed by @alexcrichton
* [x] Concurrency: reviewed by @aturon
* [x] Implementing Vec: r? @huonw
