it's not related to this feature

to match the type signature of the llvm.used variable

similar to GCC's __attribute((used))__. This attribute prevents LLVM from
optimizing away a non-exported symbol, within a compilation unit (object file),
when there are no references to it.

This is better explained with an example:

```
#[used]
static LIVE: i32 = 0;

static REFERENCED: i32 = 0;

static DEAD: i32 = 0;

fn internal() {}

pub fn exported() -> &'static i32 {
    &REFERENCED
}
```

Without optimizations, LLVM pretty much preserves all the static variables and
functions within the compilation unit.

```
$ rustc --crate-type=lib --emit=obj symbols.rs && nm -C symbols.o
0000000000000000 t drop::h1be0f8f27a2ba94a
0000000000000000 r symbols::REFERENCED::hb3bdfd46050bc84c
0000000000000000 r symbols::DEAD::hc2ea8f9bd06f380b
0000000000000000 r symbols::LIVE::h0970cf9889edb56e
0000000000000000 T symbols::exported::h6f096c2b1fc292b2
0000000000000000 t symbols::internal::h0ac1aadbc1e3a494
```

With optimizations, LLVM will drop dead code. Here `internal` is dropped because
it's not a exported function/symbol (i.e. not `pub`lic). `DEAD` is dropped for
the same reason. `REFERENCED` is preserved, even though it's not exported,
because it's referenced by the `exported` function. Finally, `LIVE` survives
because of the `#[used]` attribute even though it's not exported or referenced.

```
$ rustc --crate-type=lib -C opt-level=3 --emit=obj symbols.rs && nm -C symbols.o
0000000000000000 r symbols::REFERENCED::hb3bdfd46050bc84c
0000000000000000 r symbols::LIVE::h0970cf9889edb56e
0000000000000000 T symbols::exported::h6f096c2b1fc292b2
```

Note that the linker knows nothing about `#[used]` and will drop `LIVE`
because no other object references to it.

```
$ echo 'fn main() {}' >> symbols.rs
$ rustc symbols.rs && nm -C symbols | grep LIVE
```

At this time, `#[used]` only works on `static` variables.

Rollup of 1 pull requests

- Successful merges: #40998
- Failed merges: #41045

travis: Split all dist builders in two

Previously we would use one builder on Travis to produce two sets of host
compilers for two different targets. Unfortunately though we've recently
increased how much we're building for each target so this is starting to take
unnecessarily long (#40804). This commit splits the dist builders in two by
ensuring that we only dist one target on each builder, which should take a much
shorter amount of time. This should also unblock other work such as landing the
RLS (#40584).

Previously we would use one builder on Travis to produce two sets of host
compilers for two different targets. Unfortunately though we've recently
increased how much we're building for each target so this is starting to take
unnecessarily long (#40804). This commit splits the dist builders in two by
ensuring that we only dist one target on each builder, which should take a much
shorter amount of time. This should also unblock other work such as landing the
RLS (#40584).

save-analysis: track associated types

r? @EddyB

Add support for image, rules and footnotes

Part of #40912.

r? @rust-lang/docs

PS: the footnotes are waiting for https://github.com/google/pulldown-cmark/pull/21 to be merged to be fully working.

travis: Compile OSX releases with Xcode 7

Unfortunately what we're using right now, Xcode 8.2, cannot compile LLVM for OSX
10.7. We've done this historically and Gecko would like to maintain this
compabitiliby. This commit moves our release builders for OSX to using Xcode 7
which can compile LLVM for 10.7.

The builders running tests continue to use Xcode 8.2, however, because the LLDB
version with Xcode 7, 350, is blacklisted in running our LLDB tests. To continue
running LLDB tests we'll stick with Xcode 8.2.

Rollup of 6 pull requests

- Successful merges: #40703, #40728, #40763, #40871, #40935, #40947
- Failed merges:

Test sort algorithms using a random cmp function

This ensures that sorting using a broken comparison function doesn't panic nor fail in some other way (especially not segfault).

r? @alexcrichton

Modify str Structs descriptions

References #29375. Modified descriptions of multiple structs to be more in line with structs found under [`std::iter`](https://doc.rust-lang.org/std/iter/#structs), such as [`Chain`](https://doc.rust-lang.org/std/iter/struct.Chain.html) and [`Enumerate`](https://doc.rust-lang.org/std/iter/struct.Enumerate.html)

Adding links for Atomics docs #29377

r? @steveklabnik

This should be good for `std::sync::atomic`. The other pages still need more (examples, etc.).

Add helpful hint in io docs about how ? is not allowed in main()

This is my effort to help alleviate the confusion caused by the error message:
```rust
error[E0277]: the trait bound `(): std::ops::Carrier` is not satisfied
  --> hello_world.rs:72:5
   |
72 |     io::stdin().read_line(&mut d_input)?;
   |     ------------------------------------
   |     |
   |     the trait `std::ops::Carrier` is not implemented for `()`
   |     in this macro invocation
   |
   = note: required by `std::ops::Carrier::from_error`

error: aborting due to previous error
```
This has been discussed at length in https://github.com/rust-lang/rust/issues/35946, but I figured it would be helpful to mention in the docs.
Reading user input is one of the first things beginners will look up in the docs, so my thinking was they'd see this warning here and not have to deal with the [tricky error message](https://blog.rust-lang.org/2017/03/02/lang-ergonomics.html).

If you think this isn't the right place to put this in the docs, that's understandable, I'm open to suggestions for putting it elsewhere or removing it entirely.

Make overlapping_inherent_impls lint a hard error

Closes #36889.

Add missing urls in ptr docs

r? @rust-lang/docs

Unfortunately what we're using right now, Xcode 8.2, cannot compile LLVM for OSX
10.7. We've done this historically and Gecko would like to maintain this
compabitiliby. This commit moves our release builders for OSX to using Xcode 7
which can compile LLVM for 10.7.

The builders running tests continue to use Xcode 8.2, however, because the LLDB
version with Xcode 7, 350, is blacklisted in running our LLDB tests. To continue
running LLDB tests we'll stick with Xcode 8.2.

Rollup of 10 pull requests

- Successful merges: #40694, #40842, #40869, #40888, #40898, #40904, #40925, #40928, #40929, #40934
- Failed merges:

Improve the docs for the write and writeln macros

This change reduces duplication by linking the documentation for
`writeln!` to `write!`. It also restructures the `write!` documentation
to read in a more logical manner (I hope; feedback would be welcome).

Updates #29329, #29381

Implement all PartialOrd methods for Reverse

When making a forwarding wrapper we must in general forward all methods,
so that we use the type's own `lt` for example instead of the default.

Example important case: f32's partial_cmp does several operations but
its lt is a primitive.

Follow up on #40720

adding debug in consume_body function

When in debug_assertions=true mode, the function consume_body lacks some debug output, which makes it harder to follow the control flow. This commit adds this needed debug.

Add missing link in unstable-book

add link to specialization's tracking issue

Add example to std::process::abort

This is a first step in order to complete this issue: https://github.com/rust-lang/rust/issues/29370
I submitted this PR with the help of @steveklabnik More info here: https://github.com/rust-lang/rust/issues/29370#issuecomment-290089330

It's my first PR on Rust, I'm learning how to contribute: Should I ping someone? I will post another PR with a more complicated example soon, I prefer send it separately (cause maybe I made some mistakes).

Remove unused feature from error index generator

Remove feature `rustdoc`.

Make the rustdoc sidebar white on `src` pages

Fixes #40724

Improve os::linux documentation (#29367)

Improve `os::linux` documentation according to #29367

r? @steveklabnik

Implement AsRawFd/IntoRawFd for RawFd

This is useful to build os abstraction like the nix crate does.
It allows to define functions, which accepts generic arguments
of data structures convertible to RawFd, including RawFd itself.
For example:

```
fn write<FD: AsRawFd>(fd: FD, buf: &[u8]) -> Result<usize>
write(file, buf);
```
instead of:
```
fn write(fd: RawFd, buf: &[u8]) -> Result<usize>
write(file.as_raw_fd(), buf);
```

cc @kamalmarhubi

Sync all unstable features with Unstable Book; add tidy lint.

Add a tidy lint that checks for...

* Unstable Book sections with no corresponding SUMMARY.md links
* unstable features that don't have Unstable Book sections
* Unstable Book sections that don't have corresponding unstable features

Add a tidy lint that checks for...

* Unstable Book sections with no corresponding SUMMARY.md links
* unstable features that don't have Unstable Book sections
* Unstable Book sections that don't have corresponding unstable features