make RemainingCandidates::next peekable.
`candidates.next` always came with a `candidates.clone().next(prev_active).is_ok` so lets just make that part of `next`. no `clone` needed.

Auto merge of #5063 - Eh2406:TestssuiteV3, r=matklad

Reorganize integration tests as one crate with many modules. Issue #4867. Rebased V3

This is an automatic rebase of @rochamatcomp's work in #5022, as requested in [#5038](https://github.com/rust-lang/cargo/pull/5038#issuecomment-365200227).

I take no credit for the changes; I just wanted faster test for my work. :-)

fix winapi import

Adding cargo.rs file tests as cargo_command.rs.

Reorganize integration tests as one crate with many modules. Issue #4867.

Auto merge of #5058 - sfackler:patch-2, r=Mark-Simulacrum

Update default codegen-units

It's been 16 since rustc 1.24.

Update default codegen-units

It's been 16 since rustc 1.24.

Auto merge of #5051 - cardoe:fix-doc-instructions, r=matklad

update contributing to show how to build the docs

The contributing guide referenced a script that was deleted in
1271bb4de0c0 so it wasn't possible to follow the contributing guide
successfully prior to contributing doc improvements.

Auto merge of #5041 - pwoolcoc:display-path-to-custom-commands-when-verbose, r=matklad

When -v is passed with --list, display path to custom commands

With this change, output of `cargo --list` changes slightly when 1 or more `-v` flags are passed:

```
 ± ./target/debug/cargo --list -v
Installed Commands:
    add                  /path/to/home/.cargo/bin/cargo-add
    bench
    build
    canoe                /path/to/home/.cargo/bin/cargo-canoe
    check
    clean
    do                   /path/to/home/.cargo/bin/cargo-do
    doc
    fetch
    fmt                  /path/to/home/.cargo/bin/cargo-fmt
    ...
```

Auto merge of #4953 - alexcrichton:rename-via-as, r=matklad

Implement renaming dependencies in the manifest

This commit implements a new unstable feature for manifests which allows
renaming a crate when depending on it. For example you can do:

```toml
cargo-features = ["dependencies-as"]

...

[dependencies]
foo = "0.1"
bar = { version = "0.1", registry = "custom", package = "foo" }
baz = { git = "https://github.com/foo/bar", package = "foo" }
```

Here three crates will be imported but they'll be made available to the Rust
source code via the names `foo` (crates.io), `bar` (the custom registry), and
`baz` (the git dependency). The *package* name, however, will be `foo` for all
of them. In other words the git repository here would be searched for a crate
called `foo`. For example:

```rust
extern crate foo; // crates.io
extern crate bar; // registry `custom`
extern crate baz; // git repository
```

The intention here is to enable a few use cases:

* Enable depending on the same named crate from different registries
* Allow depending on multiple versions of a crate from one registry
* Removing the need for `extern crate foo as bar` syntactically in Rust source

Currently I don't think we're ready to stabilize this so it's just a nightly
feature, but I'm hoping we can continue to iterate on it!

cc #1311

Auto merge of #5050 - cardoe:add-dependency-info, r=matklad

doc: add explicit example with ^ and leading 0

Since the leading 0 is treated a bit special, its worth it to have an
explicit example to match the above example of the major version being >
0.

update contributing to show how to build the docs

The contributing guide referenced a script that was deleted in
1271bb4de0c0 so it wasn't possible to follow the contributing guide
successfully prior to contributing doc improvements.

doc: add explicit example with ^ and leading 0

Since the leading 0 is treated a bit special, its worth it to have an
explicit example to match the above example of the major version being >
0.

When -v is passed with --list, display path to custom commands

Auto merge of #5037 - Eh2406:conflict_tracking, r=alexcrichton

Conflict tracking

This is an alternative implementation of #4834. This is slower but hopefully more flexible and clearer. The idea is to keep a list of `PackageId`'s that have caused us to skip a `Candidate`. Then we can use the list when we are backtracking if any items in our list have not been activated then we will have new `Candidate`'s to try so we should stop backtracking. Or to say that another way; We can continue backtracking as long as all the items in our list is still activated.

Next this new framework was used to make the error messages more focused. We only need to list the versions that conflict, as opposed to all previously activated versions.

Why is this more flexible?
1. It is not limited to conflicts within the same package. If `RemainingCandidates.next` skips something  because of a links attribute, that is easy to record, just add the `PackageId` to the set `conflicting_prev_active`.
2. Arbitrary things can add conflicts to the backtracking. If we fail to activate because some dependency needs a feature that does not exist, that is easy to record, just add the `PackageId` to the set `conflicting_activations`.
3. All things that could cause use to fail will be in the error messages, as the error messages loop over the set.
4. With a simple extension, replacing the `HashSet` with a `HashMap<_, Reason>`, we can customize the error messages to show the nature of the conflict.

@alexcrichton, @aidanhs, Does the logic look right? Does this seem clearer to you?

Don't store conflicting_activations for backtracking.
If we need it later we can always add it back in.

Auto merge of #5040 - daboross:patch-1, r=alexcrichton

Remove cargo-only downloads from installation docs

This also copies extra instructions for installing rust from https://doc.rust-lang.org/book/first-edition/getting-started.html#installing-rust-1.

I wasn't able to test the changes locally, but they're fairly minimal, so I trust they will render alright.

Fixes #5027.

Remove cargo-only downloads from installation docs

This also copies extra instructions for installing rust from https://doc.rust-lang.org/book/first-edition/getting-started.html#installing-rust-1.

Fixes https://github.com/rust-lang/cargo/issues/5027.

Auto merge of #5039 - lawliet89:docopt-bounds, r=alexcrichton

Fix DocOpt deserialization type bounds

This is wrt https://github.com/docopt/docopt.rs/pull/222

DocOpt does not support deserializing borrowed types.

This change was reverted in
https://github.com/docopt/docopt.rs/commit/7292a374e69afb192bb7aaa00f9d9f4afebc200d
because it broke crates like Cargo etc.

Fix DocOpt deserialization type bounds

This is wrt https://github.com/docopt/docopt.rs/pull/222

DocOpt does not support deserializing borrowed types.

This change was reverted in
https://github.com/docopt/docopt.rs/commit/7292a374e69afb192bb7aaa00f9d9f4afebc200d
because it broke crates like Cargo etc.

Auto merge of #5029 - matklad:new-defaults-to-bin, r=withoutboats

New defaults to bin

So this switches `cargo new` default from `--lib` to `--bin`, as discussed on IRC.

The first two commits are just refactorings, and the last one actually flips the switch. Surprisingly enough, no tests need to be modified it seems!

r? @withoutboats

Use the conflict tracking in the error messages to only show the versions that are in conflict

Implement renaming dependencies in the manifest

This commit implements a new unstable feature for manifests which allows
renaming a crate when depending on it. For example you can do:

```toml
cargo-features = ["dependencies-as"]

...

[dependencies]
foo = "0.1"
bar = { version = "0.1", registry = "custom", package = "foo" }
baz = { git = "https://github.com/foo/bar", package = "foo" }
```

Here three crates will be imported but they'll be made available to the Rust
source code via the names `foo` (crates.io), `bar` (the custom registry), and
`baz` (the git dependency). The *package* name, however, will be `foo` for all
of them. In other words the git repository here would be searched for a crate
called `foo`. For example:

```rust
extern crate foo; // crates.io
extern crate bar; // registry `custom`
extern crate baz; // git repository
```

The intention here is to enable a few use cases:

* Enable depending on the same named crate from different registries
* Allow depending on multiple versions of a crate from one registry
* Removing the need for `extern crate foo as bar` syntactically in Rust source

Currently I don't think we're ready to stabilize this so it's just a nightly
feature, but I'm hoping we can continue to iterate on it!

Auto merge of #5033 - alexcrichton:update-deps, r=matklad

Update dependencies

Just a few major updates here and there

Update dependencies

Just a few major updates here and there

Auto merge of #5032 - matklad:lazycell, r=alexcrichton

Switch to lazycell from crate.io

This switches from a home-grown implementation of `lazycell` to the one from crates.io.

There are no particularly large improvements here, but our own lazy cell is definitely unsafe in theory, because of potential reentrancy in `get_or_try_init`, and the one from crates.io does not have at least this hole :-)

Note that `rustc` already has `lazycell` in its Cargo.lock (because of clippy I guess?), albeit with a lower version, 0.5.

Auto merge of #5031 - matthiaskrgr:readme_docs, r=alexcrichton

readme: add link to the cargo documentation on docs.rs

[Rendered](https://github.com/matthiaskrgr/cargo/blob/readme_docs/README.md)

Background: I was searching for cargo source code doc a while back, found the cargo book and crates.io doc relatively quickly but not the actual source code doc which I only found (after way to much time had passed)  when I looked up the cargo crate on crates.io and found the "Documentation" link :/

Hope this improves the situation a bit in the future.

readme: add link to the cargo documentation on docs.rs

Switch `cargo new` default to `--bin`

Switch to lazycell from crate.io

Auto merge of #5030 - alexcrichton:better-poll, r=matklad

Don't spin on empty fds in `read2` on Unix

This commit fixes what I think is some pathological behavior in Cargo where if
one stdio stream is closed before another then Cargo can accidentally spin in a
tight loop and not block appropriately. Previously, for example, if stderr
closed before stdout then Cargo would spin in a `poll` loop continuously getting
notified that stderr is closed.

The behavior is now changed so after a file descriptor is done we stop passing
it to `poll` and instead only pass the one remaining readable file descriptor.

Don't spin on empty fds in `read2` on Unix

This commit fixes what I think is some pathological behavior in Cargo where if
one stdio stream is closed before another then Cargo can accidentally spin in a
tight loop and not block appropriately. Previously, for example, if stderr
closed before stdout then Cargo would spin in a `poll` loop continuously getting
notified that stderr is closed.

The behavior is now changed so after a file descriptor is done we stop passing
it to `poll` and instead only pass the one remaining readable file descriptor.

Refactor `NewOptions` to make it slightly more clear

Cleanup

More directly track conflicts in backtracking, hopefully this will be easier to extend.

Auto merge of #5025 - Eh2406:error_mesges, r=alexcrichton

better resolver error messages

This is a start on beter resolver error messages. This is mostly trying to copy the `links` messages. In the process I found that we wor not testing the common case of having found candidates and still not resolving.

Any advice?

better error messages

Auto merge of #5024 - debris:helpful_message, r=alexcrichton

Add helpful message when running cargo doc --open

Add helpful message when running cargo doc --open in the root of the workspace.

closes #4962

old output:

```
 Documenting foo v0.1.0 (file:///Users/marek/projects/ethcore/tmp/dupa/foo)
 Documenting bar v0.1.0 (file:///Users/marek/projects/ethcore/tmp/dupa/bar)
    Finished dev [unoptimized + debuginfo] target(s) in 0.78 secs
error: Passing multiple packages and `open` is not supported
```

new output:

```
 Documenting foo v0.1.0 (file:///Users/marek/projects/ethcore/tmp/dupa/foo)
 Documenting bar v0.1.0 (file:///Users/marek/projects/ethcore/tmp/dupa/bar)
    Finished dev [unoptimized + debuginfo] target(s) in 0.81 secs
error: Passing multiple packages and `open` is not supported.
Please re-run this command with `-p <spec>` where `<spec>` is one of the following:
  foo
  bar
```

Add helpful message when running cargo doc --open in the root of the workspace, fixes #4962

generalize the path_to_top from the links errors

test for the most common cargo resolver error

Auto merge of #5020 - stefanbirkner:linkfix, r=alexcrichton

Fix link to documentation

Fix link to documentation

Auto merge of #5018 - brotzeit:clippy, r=alexcrichton

apply clippy suggestions

I want to try if this actually works =)

There are many other clippy suggestions. I wonder if I can take them for granted or if some of them would be refused.

For example:
```
warning: Constants have by default a `'static` lifetime
  --> src/cargo/lib.rs:53:23
   |
53 | pub const CARGO_ENV: &'static str = "CARGO";
   |                      -^^^^^^^---- help: consider removing `'static`: `&str`
   |
   = note: #[warn(const_static_lifetime)] on by default
   = help: for further information visit https://rust-lang-nursery.github.io/rust-clippy/v0.0.185/index.html#const_static_lifetime
```

apply clippy suggestions

Auto merge of #5011 - Manishearth:stealing-chickens-off-the-internet, r=alexcrichton

Implement RFC 2052: Epoches

Todo:

 - Make epoches affect the fingerprint
 - Tests

cc https://github.com/rust-lang/rust/issues/44581

Rust PR: https://github.com/rust-lang/rust/pull/48014

r? @acrichto

epoch -> rust

Auto merge of #5017 - matthiaskrgr:manifest_cgu_lto, r=alexcrichton

manifest reference: correct statement: codegen-units=x is not ignored if lto=true.

Also fix typo along the way.

Auto merge of #4834 - aidanhs:aphs-better-backtrack, r=alexcrichton

Make resolution backtracking smarter

There's no need to try every candidate for every dependency when backtracking - instead, only try candidates if they *could* change the eventual failure that caused backtracking in the first place, i.e.
1. if we've backtracked past the parent of the dep that failed
2. the number of activations for the dep has changed (activations are only ever added during resolution I believe)

The two new tests before:
```
$ /usr/bin/time cargo test --test resolve -- --test-threads 1 --nocapture resolving_with_constrained_sibling_
    Finished dev [unoptimized + debuginfo] target(s) in 0.0 secs
     Running target/debug/deps/resolve-19b2a13e5a19eed8
38.45user 2.16system 0:42.00elapsed 96%CPU (0avgtext+0avgdata 47672maxresident)k
0inputs+1664096outputs (0major+10921minor)pagefaults 0swaps
```
After:
```
$ /usr/bin/time cargo test --test resolve -- --test-threads 1 --nocapture resolving_with_constrained_sibling_
    Finished dev [unoptimized + debuginfo] target(s) in 0.0 secs
     Running target/debug/deps/resolve-19b2a13e5a19eed8
[...]
0.36user 0.01system 0:00.49elapsed 76%CPU (0avgtext+0avgdata 47464maxresident)k
0inputs+32outputs (0major+11602minor)pagefaults 0swaps
```

You observe the issue yourself with the following (it should fail, but hangs for a while instead - I didn't bother timing it and waiting for it to finish. With this PR it terminates almost instantly):
```
$ cargo new --bin x
     Created binary (application) `x` project
$ /bin/echo -e 'serde = "=1.0.9"\nrust-s3 = "0.8"' >> x/Cargo.toml
$ cd x && cargo build
    Updating registry `https://github.com/rust-lang/crates.io-index`
   Resolving dependency graph...
```

manifest reference: correct statement: codegen-units=x is not ignored if lto=true.

Also fix typo along the way.

Auto merge of #5013 - withoutboats:no-rust-rename, r=matklad

Do not rename packages on `cargo new`.

Prior to this commit, packages beginning with `rust` or ending with
`rs` were renamed automatically when created, unless they were
binaries. The ostensible purpose of this code was to avoid people
uploading "redundant" names to crates.io, which is a repository of
Rust packages.

This behavior was overly opinionated. It is not cargo's
responsibility to discourage users from naming their packages any
particular way. Without a sound technical reasons why packages
cannot be named a certain way, cargo should not be intervening in
users' package naming decisions.

It also did this by automatically renaming the package for the
user, as opposed to erroring. Though it printed a message about
the behavior, it did not give the user a choice to abort the
process; to overrule cargo they had to delete the new project
and start again using the `--name` argument.

`cargo new` is many users' first entrypoint to the Rust ecosystem.
This behavior teaches a user that Rust is opinionated and magical,
both of which are divisive attributes for a tool, and attributes
which do not generally describe Rust's attitude toward things like
names and formatting.

If crates.io wishes to enforce that users not upload packages with
names like this, it should be enforced by crates.io at publish
time.

Add tests for epoch

Include the epoch in the fingerprint

Pass -Zepoch flag when epoch feature exists

Feature gate epoches

Add epoch key to [package]

Add reference to clarifying comment

Remove tests related to stripping names.

Do not rename packages on `cargo new`.

Prior to this commit, packages beginning with `rust` or ending with
`rs` were renamed automatically when created, unless they were
binaries. The ostensible purpose of this code was to avoid people
uploading "redundant" names to crates.io, which is a repository of
Rust packages.

This behavior was overly opinionated. It is not cargo's
responsibility to discourage users from naming their packages any
particular way. Without a sound technical reasons why packages
cannot be named a certain way, cargo should not be intervening in
users' package naming decisions.

It also did this by automatically renaming the package for the
user, as opposed to erroring. Though it printed a message about
the behavior, it did not give the user a choice to abort the
process; to overrule cargo they had to delete the new project
and start again using the `--name` argument.

`cargo new` is many users' first entrypoint to the Rust ecosystem.
This behavior teaches a user that Rust is opinionated and magical,
both of which are divisive attributes for a tool, and attributes
which do not generally describe Rust's attitude toward things like
names and formatting.

If crates.io wishes to enforce that users not upload packages with
names like this, it should be enforced by crates.io at publish
time.

Auto merge of #4976 - mbrubeck:doc-check, r=alexcrichton

cargo doc: Generate rmeta files for dependencies instead of compiling rlibs

This makes `cargo doc` require only metadata (`.rmeta` files) instead of compiled libraries (`.rlib` files) for dependencies.  This makes `cargo doc` faster in cases where rlibs are not already built and/or metadata is already available.

Unfortunately, this is not a win for every workflow.  In the case where the user has already compiled but has not generated metadata, it makes `cargo doc` do extra work.  This is probably a common case, though tools like RLS and `cargo check` mean that many developers *will* have up-to-date metadata available.

It would become an unequivocal win if `cargo build` and `cargo check` re-used shared metadata (#3501). For now, starting from a clean working directory, the following sequences of commands will become:

* `cargo doc`: faster
* `cargo build; cargo doc`: slower
* `cargo check; cargo doc`: faster
* `cargo build --release; cargo doc`: faster
* `cargo check; cargo build; cargo doc`: no change

Clean up lib_or_check_profile code

cargo doc: Generate metadata instead of compiling dependencies

Auto merge of #5008 - matthiaskrgr:codespell, r=alexcrichton

fix a bunch of typos found by codespell

https://github.com/lucasdemarchi/codespell/

fix a bunch of typos found by codespell

Auto merge of #5004 - BurNiinTRee:pijul-config-key, r=matklad

Added "pijul" as a config key for cargo-new.vcs in .cargo/config

Currently Pijul can only be set as a version control from the command-line but not from the cargo-new.vcs key in .cargo/config

Added "pijul" as a config key for cargo-new.vcs in .cargo/config

Elaborate on test configuration, add a new test

Clearer desired behaviour with an assertion

Make resolution backtracking smarter

There's no need to try every candidate for every dependency - instead,
only try alternative candidates if they *could* change the eventual
failure that caused backtracking in the first place.

Auto merge of #4995 - alexcrichton:relative-env, r=matklad

Fix `RUSTC=./relative-path` when building

This commit adjusts the compiler location logic to resolve `./relative-path`
before invoking rustc to ensure it's no longer cwd-relative. This is how many
other variables like `CARGO_HOME` work, so it's applying similar logic.

Fix `RUSTC=./relative-path` when building

This commit adjusts the compiler location logic to resolve `./relative-path`
before invoking rustc to ensure it's no longer cwd-relative. This is how many
other variables like `CARGO_HOME` work, so it's applying similar logic.

Auto merge of #4990 - Eh2406:Zno-index-update, r=alexcrichton

add a -Z no-index-update for crater and benchmarking

This is a fix for #3479

add a test

Auto merge of #4996 - alexcrichton:document-lto, r=matklad

Document string values for LTO

Document string values for LTO

Auto merge of #4984 - alexcrichton:configure-lto, r=matklad

Allow configuration of LTO in [profile]

This should help give access to ThinLTO when desired!

Auto merge of #4991 - bennofs:master, r=matklad

Require at least version 0.1.9 of jobserver crate

There are some important fixes in jobserver >=0.1.8. With earlier
versions, it's possible for cargo to panic with a "failed to acquire
jobserver token" error, which can be very hard to track down.

Requiring the latest version of jobserver makes sure that no such error
can make it into downstream distributions.

Require at least version 0.1.9 of jobserver crate

There are some important fixes in jobserver >=0.1.8. With earlier
versions, it's possible for cargo to panic with a "failed to acquire
jobserver token" error, which can be very hard to track down.

Requiring the latest version of jobserver makes sure that no such error
can make it into downstream distributions.

add a -Z no-index-update for crater and benchmarking

Allow configuration of LTO in [profile]

This should help give access to ThinLTO when desired!

Auto merge of #4980 - Gilnaa:master, r=matklad

Fixed relaxed libtest tests

This fixes tests regarding the upcoming behaviour of libtest's benchmarks.
The previous PR was wrongly tested, this one fixes the problems.

Fixed relaxed libtest tests

Auto merge of #4957 - sfackler:registry-elaboration, r=alexcrichton

Elaborate registry names to index URLs when publishing

This avoids introducing a dependency on the publisher's name for the
registry.

Closes #4880

Auto merge of #4974 - alexcrichton:less-vendor-verify, r=matklad

Be less strict about loading directory sources

Historically Cargo has been pretty strict about loading directory sources by
ensuring that everything inside was a crate. This was intended to protect
against accidental misconfiguration by failing loudly rather than silently
returning fewer crates.

This has caused a number of issues, however:

* #4969
* #4811
* #3899

so it seems like this is too aspirational of Cargo

Closes #4811
Closes #4969

Be less strict about loading directory sources

Historically Cargo has been pretty strict about loading directory sources by
ensuring that everything inside was a crate. This was intended to protect
against accidental misconfiguration by failing loudly rather than silently
returning fewer crates.

This has caused a number of issues, however:

* #4969
* #4811
* #3899

so it seems like this is too aspirational of Cargo

Closes #4811
Closes #4969

Auto merge of #4973 - alexcrichton:dont-require-emscripten, r=matklad

Remove test that requires Emscripten

This seems relatively unlikely to regress in the future and otherwise arranging
Cargo to have a rustc that has Emscripten support will become difficult in the
near future in the Rust repo. All in all it seems like the course of action to
take is to delete this test for now.

Forbid credentials from registry URLs

Fixes for feedback

Elaborate registry names to index URLs when publishing

This avoids introducing a dependency on the publisher's name for the
registry.

Closes #4880

Remove test that requires Emscripten

This seems relatively unlikely to regress in the future and otherwise arranging
Cargo to have a rustc that has Emscripten support will become difficult in the
near future in the Rust repo. All in all it seems like the course of action to
take is to delete this test for now.

Auto merge of #4972 - varkor:lazy-cell-unused-unsafe, r=alexcrichton

Allow unused_unsafe in LazyCell in preparation for lib change

https://github.com/rust-lang/rust/pull/47204 makes `UnsafeCell::into_inner` safe, which means `LazyCell::into_inner` will no longer need an `unsafe` block. `LazyCell` is a blocker for the change in Rust: this fix should allow the change to take place.

Allow unused_unsafe in LazyCell in preparation for lib change

https://github.com/rust-lang/rust/pull/47204 makes `UnsafeCell::into_inner` safe, which means `LazyCell::into_inner` will no longer need an `unsafe` block. `LazyCell` is a blocker for the change in Rust: this fix should allow the change to take place.

Auto merge of #4971 - ehuss:overflow-checks-doc, r=alexcrichton

Add overflow-checks to reference documentation.

Fixes #4925.

Add overflow-checks to reference documentation.

Fixes #4925.

Auto merge of #4724 - pornel:sortpaths, r=alexcrichton

Sort native library paths for deterministic builds

Fixes #3800 by using a `BTreeSet`, which guarantees a deterministic iteration order.

Since the order was previously arbitrary, a sorted order is just as good. The list is so small, that any performance difference between `BTreeSet` and `HashSet` is negligible.

Test sorting of native library paths

Auto merge of #4970 - Gilnaa:master, r=alexcrichton

Relaxed testing of libtest outputs.

This PR relaxes some checks on libtest due to upcoming changes by this PR:
https://github.com/rust-lang/rust/pull/46450

Summary of expected changes:

- Crashing benchmarks are now caught and handled just like in tests, and should not crash the harness. The old cargo test checked that the panic text was printed in stderr. In the patched behaviour, the text is printed to stdout.
With the advice of @alexcrichton, I changed test to check for the text in either stream in order to account of the transition period.

Relaxed testing of libtest outputs.

Auto merge of #4968 - edunham:patch-1, r=alexcrichton

Link to crate type docs

This page (served at https://doc.rust-lang.org/cargo/reference/manifest.html) is the first hit I get when searching "cargo crate-type". The doc which actually explains `crate-type`, https://doc.rust-lang.org/reference/linkage.html, does not appear in the first page of results. I hope that linking the reference doc here will make it easier for others to find instead of having to dig into closed GitHub issues like I did to find it.

Link to crate type docs

This page (served at https://doc.rust-lang.org/cargo/reference/manifest.html) is the first hit I get when searching "cargo crate-type". The doc which actually explains `crate-type`, https://doc.rust-lang.org/reference/linkage.html, does not appear in the first page of results. I hope that linking the reference doc here will make it easier for others to find instead of having to dig into closed GitHub issues like I did to find it.