[doc] Sync back doc/book changes into old docs

[doc/book] Add book.toml

[doc/book] Final touches to introduction.md

[doc/book] Assign langs to more code blocks

[doc/book] Create dir for book sections

[doc/book] Improve page titles

[src/doc/book] Add introduction page

[doc/book] Expand installation.md

Import install text and links from <https://crates.io/install>, as we
want to drop that page and redirect it to here.

See <https://github.com/rust-lang/crates.io/issues/1029>

Auto merge of #4453 - behnam:book, r=alexcrichton

Import mdBook-based docs and sync

Since we decided to keep the mdBook-based docs in-repo, I have imported the existing converted docs from <https://github.com/istankovic/cargo-book> under `/src/doc/book/` here, and have synced the current docs and the mdBook-based ones manually, file-by-file.

I have created a `MIGRATION_MAP` file, which shows the relationship between old docs and new ones. The first column is the old file, the second column is the canonical location in mdBook, and the rest of columns are globs of other files in mdBook containing content from the old file.

The first and second column of `MIGRATION_MAP` shall later be used to create redirect rules from `doc.crates.io/` to `doc.rust-lang.org/cargo/`.

I will also add a README file to remind everyone to keep these files in sync during the migration.

There are also two or three small wording fixes here, which I'll note inline.

This is a retry of <https://github.com/rust-lang/cargo/pull/4220>.

First step for <https://github.com/rust-lang/cargo/issues/4040>.

Auto merge of #4447 - lucaskolstad:proc-macro-crates-host-deps-linkage, r=alexcrichton

Add host dependency path via -L for cargo_test.

Proc-macro crates' dependencies in the host dependency directory cannot
be found when running `cargo test` with the `--target {target}` flag
set as reported in #4224. This adds the host dependency directory to the
search path to find those missing dependencies with -L when building tests
and adds a test case that fails before and passes after this patch.

A new function `find_host_deps(..)` is added to accomplish this which can
determine the path of the host dependencies directory from within
`run_doc_tests(..)` where the missing library search path is needed.

Fixes #4224
Fixes #4254

Modeled after a similar patch: a298346d6e8862992be3fd93dd8a6c833cc72719

**Concerns**

The test case seems to require a non-local crate from crates.io to example the failure before this patch. Couldn't make it fail with simply another local subcrate, but if others think it's possible that'd be great. This means that during tests for the cargo project itself that this test case actually downloads and compiles a crate, which I don't think any other tests do and is obviously not ideal and is perhaps even unacceptable. I've used the base64 crate pretty arbitrarily, but which crate it is really doesn't matter to test the case's content. So if anyone knows a tiny or empty crate on crates.io to use instead that'd speed this up and if someone can figure out how to make it fail before this patch is applied without downloading an external crate that would help as well.

Also, I'm not 100% confident about the `find_host_deps(..)` style and whether it's the best way to find the host dependencies directory with just the `TestOptions` and `Compilation` structs available since I'm new to this project. Any comments are appreciated.

Tweak proc_macro test to correctly test case.

Minor change causes the test to actually test the case instead of always
passing regardless of the fix that adds the host dependency directory to
the library search path.

[src/doc/book] Use package registry for crates.io

[src/doc/book] Fix header casings

[src/doc/book] Move a paragraph to cargo-in-depth.md

[src/doc/book] Add all sub-chapters to cargo-in-depth.md

[src/doc/book] Drop unused images

[src/doc] Add README.md

[src/doc/book] Update SUMMARY.md

[src/doc/book] Update 03-01-specifying-dependencies.md from specifying-dependencies.md

[src/doc/book] Check 03-08-source-replacement.md

[src/doc/book] Update 03-10-policies.md from policies.md

[src/doc/book] Check 03-07-pkgid-spec.md

[src/doc/book] Update 03-02-manifest.md from manifest.md

[src/doc/book] Apply 01-*.md changes into index.md

Replace plugins_dylib_path with host_deps_output.

The plugins_dylib_path field on Compilation is removed because it is
identical to host_deps_output, it is only used in one easily replaced
location, and because host_deps_output is a more general name that
includes its new usage location in cargo_test.rs as well while better
matching the corresponding deps_output field.

Also de-indents erroneously indented lines in a test case.

[src/doc/book] Update guide.md and 02-*.md from guide.md

[src/doc/book] Check faq.md

[src/doc/book] Update 03-09-external-tools.md from external-tools.md

[src/doc/book] Update 03-04-environment-variables.md from environment-variables.md

[src/doc/book] Update 03-06-crates-io.md from crates-io.md

[src/doc/book] Update 03-05-build-scripts.md from build-script.md

[src/doc/book] Update 03-03-config.md from config.md

[src/doc/book] Add .gitignore

Using `mdbook init` command.

Also, update `.gitignore` file manually and add a leading slash.
(Upstream fix for mdBook: <https://github.com/azerupi/mdBook/pull/413>)

[src/doc/book] Import from cargo-book repo

Remove find_host_deps and use Compilation field.

This patch removes the addition of the find_host_deps() function by
adding a host_deps_output field to the Compilation struct instead. The
test case is altered to not use an external crate from crates.io but
instead use the Package.publish(..) method.

Auto merge of #4451 - steveklabnik:relax-rustdoc-tests, r=alexcrichton

relax rustdoc tests

This was asserting on the output directly, rather than just what it contains.

In https://github.com/rust-lang/rust/pull/44138 we are adding deprecations, and so it
breaks these tests.

Don't use deprecated rustdoc flags in tests

In rust-lang/rust#44138 we are adding deprecations, and so it
breaks these tests.

Auto merge of #4440 - nisargthakkar:publish_target, r=alexcrichton

Adding target support to cargo package and cargo publish

Fixing Issue #4012

Same as #4077 but couldn't reopen the PR due to force push after rebasing from master

Removing redundant extern

Adding tests for --target with cargo publish and cargo package

Adding target support to cargo package and cargo publish

Add host dependency path via -L for cargo_test.

Proc-macro crates' dependencies in the host dependency directory cannot
be found when running `cargo test` with the `--target {target}` flag
set. This adds the host dependency directory with -L when building tests
and a test case that fails before and passes after this patch.

A new function find_host_deps(..) is added to accomplish this which can
determine the path of the host dependencies directory from within
run_doc_tests(..) where the missing library search path is needed.

Fixes #4224
Fixes #4254

Auto merge of #4442 - Xanewok:process-builder-program, r=alexcrichton

Allow to substitute executed program in `ProcessBuilder`

Extends #4424. Sorry for the noise, turns out it'd also be useful to substite the executed program (e.g. for rls, which needs to use a rustc shim itself) without having to copy over manually all parts of the `ProcessBuilder`.

While I'm at it, do you think this needs even more functionality, like being able to specify `None` for the `cwd` or `jobserver` (currently API exposes only ability to specify `Some(...)` as values for those)?

r? @alexcrichton

Auto merge of #4445 - alexcrichton:bump, r=matklad

Bump Cargo to 0.23.0

Fix tests on nightly

Bump Cargo to 0.23.0

Allow to substitute executed program in `ProcessBuilder`

Auto merge of #4441 - vignesh-sankaran:manifest-doc-fix, r=alexcrichton

Replace maintenance status with ellipses

Since the default maintenance status isn't set to none if it isn't set, feel it'd be more appropriate to have ellipses instead like the other badge docs.

Replace maintenance status badge none with ellipses

Auto merge of #4439 - ishitatsuyuki:bench-cleanup, r=matklad

Gate extern crates for bench tests

I tried my best to skim through the `extern crate` statements, and I hope this will unblock the unused extern crates PR.

Fix remaining test failures

tests/cfg: allow unused extern crates

tests/build-script: allow unused extern crates

Gate feature for bench tests

Gate extern crates for bench tests

Auto merge of #4358 - Mark-Simulacrum:fix-cfg-cargo, r=alexcrichton

Discover crate type information late if necessary.

Some crates aren't found during eager crate-type searching due to being behind `cfg(...)` flags. We still want to be able to handle these, though, so when necessary we now call rustc again to get crate-type information for these cfg-ed crates.

This is necessary for https://github.com/rust-lang/rust/pull/41991.

r? @alexcrichton

Auto merge of #4437 - ishitatsuyuki:deps-purge, r=matklad

Purge deps, round 2

Sorry for creating so much iterations, I have no local build of the new compiler :)

Discover crate type information late if necessary.

Some crates aren't found during eager crate-type searching due to being
behind `cfg(...)` flags. We still want to be able to handle these,
though, so when necessary we now call rustc again to get crate-type
information for these cfg-ed crates.

Purge deps, round 2

Auto merge of #4435 - ishitatsuyuki:deps-purge, r=matklad

Purge unused extern crates

Purge unused extern crates

Auto merge of #4433 - alexcrichton:unstable-features, r=matklad

Add infrastructure for nightly features and flags

This PR starts adding infrastructure in Cargo for nightly features and nightly flags. The current design looks like:

* There's a new `package.cargo-features` manifest key which accepts an array of strings. This array of strings is the list of enabled Cargo features for that crate.
* A new suite of flags behind `-Z`, like the compiler, are accepted on the command line for all commands.
* Features and unstable flags in Cargo are required to be used on Cargo's nightly channel, which is the same as Rust's nightly channel.
* Features and unstable flags cannot be used on the stable/beta channels of Rust/Cargo.
* Crates which enable features in their manifest are disallowed from being published to crates.io

The motivation behind this support is unblock a number of efforts in Cargo by allowing them to safely get implemented behind a nightly feature gate. Once behind a feature gate they can iterate in-tree without having to worry about "insta stability" and we can also get valuable usage feedback about upstream users.

Closes https://github.com/rust-lang/cargo/issues/4409

Add infrastructure for nightly Cargo flags

Add support for nightly features in Cargo

Auto merge of #4431 - vignesh-sankaran:maintenance-badge-docs, r=alexcrichton

Add maintenance badge docs

Pending merging of [this PR for crates.io](https://github.com/rust-lang/crates.io/pull/952). This should close off [#704 on crates.io](https://github.com/rust-lang/crates.io/issues/704). I've also updated the badge metadata docs and reordered the fields into groups by build, code coverage, and maintenance.

So I've decided to put the list of possible badge options in the documentation, we'll have to find another place to put more detailed descriptions of the available maintenance badges.

Added maintenance badge and reordered badge metadata fields

Auto merge of #4432 - potocpav:patch-1, r=matklad

Correct a paragraph

The previous formulation was incorrect in the descriptions of the `x` and `y` version numbers.

Correct an inaccuracy

Auto merge of #4429 - ishitatsuyuki:test-purge, r=matklad

cargotest: purge deps

Blocking rust-lang/rust#42588.

Correct and reword a paragraph

The previous formulation was incorrect in the descriptions of the `x` and `y` version numbers.

cargotest: purge deps

Auto merge of #4424 - Xanewok:process-builder-api, r=alexcrichton

Add `fn args_replace` and `fn get_program` to `ProcessBuilder`

`Executor::exec()` provides a `ProcessBuilder` argument representing compiler call and if someone wants to use it or modify it for their own purposes, they have to (partially) recreate it themselves.

This:
* makes the argument modification possible (via `args_replace`, analogous to `env_remove`)
* exposes the program that will be run (via `get_program`, in case `rustc` is overriden via wrapper etc.).

r? @alexcrichton

Add `fn args_replace` and `fn get_program` to `ProcessBuilder`

Auto merge of #4416 - Xanewok:more-executor-params, r=alexcrichton

Expose `Target` and `Unit` params to appropriate `Executor` callbacks

This effectively does only two things:
* Pass existing `&Unit` to `init()`
* Pass existing `&Target` to `exec()`s

Also updated doc comments slightly.

The `init()` is called for every `Work` preparation by `rustc()` and since it's not called once (not sure if intended?), it'd be good to include more information for which `Unit` the `rustc` process invocation has been initially prepared (I think more importantly it shows that `init()` is called many times for many targets).
Additionally, it'd be good to know about `Unit` compiled in the `exec()` callbacks in more structured manner (so the user doesn't have to parse the `ProcessBuilder` arguments and/or make certain assumptions) and since `target` was already cloned and moved into the closure, it was only a matter of exposing it.

I think it'd be ideal to provide all the necessary information to recreate a `Unit` but with a static lifetime needed for the closure, however this would mean cloning more data per-target ([`Kind`](https://github.com/rust-lang/cargo/blob/master/src/cargo/ops/cargo_rustc/mod.rs#L41) should be basically free, however not sure if cloning [`Profile`](https://github.com/rust-lang/cargo/blob/master/src/cargo/core/manifest.rs#L151) is acceptable). With this, `Executor` users could query `Context` more easily (e.g. to get a unit dep graph! :smile:), as the API accepts `Unit`s in many places.

r? @alexcrichton
cc @nrc

EDIT:
This changes the public API, not sure if there's something else I should do about it, only ran `cargo test` locally.

Auto merge of #4364 - RalfJung:feat, r=alexcrichton

Required dependencies are not features

Also, while I was at it, I fixed an error message which complained about something not being an optional dependency, when really what mattered was that it was not a dependency at all.

I made a bunch of guesses about how things work. These guesses ended up as comments in the commit (so hopefully, the next reader of these files has to guess less). I am not totally certain these comments are all correct, so please yell if not. :)

In particular, for resolve_features, I observed that dependencies get compiled even when they are not returned from that function. But judging from how the function used to behave, it actually returns all dependencies, even those that have nothing to do with any features. (Making the name rather misleading, TBH...)

Fixes #4363

Expose `Target` and `Unit` params to appropriate `Executor` callbacks

fix borrowing the shell twice

Using required dep as a feature is a warning for now, not an error

Auto merge of #4400 - behnam:pr4157, r=alexcrichton

[check|build|rustc] Add --all-targets option

`cargo check` does not check all targets by default, and to check all,
you need to call it `cargo check --tests --examples --bins --benches`.

Here, we implement `--all-targets` For `check`, `build`, and `rustc`.

For consitency, `--all-targets` is also added to other commands like
`test` although "all targets" is the default behavior.

This is a rebase of <https://github.com/rust-lang/cargo/pull/4157>

improve misleading error message

detect required dependencies used as features

test for mandatory dependencies not to be considered features

Auto merge of #4404 - parkovski:master, r=alexcrichton

Fix #4370 - init panic in C:\ or /

This fixes the crash in this issue, but the error message is strange - unable to create directory 'C:\\.'. I don't have write permissions there without becoming admin, so I suspect it's just a permission issue, but the weird error can be fixed by calling Path::canonicalize on line 300.

Fix #4370 - init panic in C:\ or /

Auto merge of #4402 - bluss:doc-rustdocflags, r=alexcrichton

Document `RUSTDOCFLAGS`

Documentation for this environment variable was missing. It's supported in stable releases of Rust already.

Document `RUSTDOCFLAGS`

Auto merge of #4389 - matklad:testless, r=alexcrichton

Allow to skip test code during publishing

closes #4365

I don't have time to review this code carefully right now, but looks like it does the job.

Allow to skip test code during publishing

Auto merge of #4393 - burtonageo:update-cargo-new-template, r=matklad

Update lib template for `cargo new` so that the placeholder test contains an assertion

When you run `rustfmt` on the default generated lib template, it modifies it as shown [here](https://play.rust-lang.org/?gist=bd44610731e26e76719e75d47e598990&version=undefined)

[check|build|rustc] Add --all-targets option

`cargo check` does not check all targets by default, and to check all,
you need to call it `cargo check --tests --examples --bins --benches`.

Here, we implement `--all-targets` For `check`, `build`, and `rustc`.

For consitency, `--all-targets` is also added to other commands like
`test` although "all targets" is the default behavior.

This is a rebase of <https://github.com/rust-lang/cargo/pull/4157>

Auto merge of #4398 - debris:url_4394, r=alexcrichton

Fixed panic when canonicalizing not-a-base-url, fixes #4394

Fixes #4394. Majority of the changes are caused by propagating error upstream to `SourceId` and `GitSource`.

Fix implementation and tests for cannot-be-a-base-url canonicalization

Fixed panic when canonicalizing not-a-base-url, fixes #4394

Auto merge of #4396 - vignesh-sankaran:documentation-blacklist-list-fix, r=matklad

Fix list rendering in manifest.md

Fixes a list rendering problem introduced in #4237.

Fix list rendering for blacklisted hosts

Add a placeholder assertion in the new lib project template

Fix tests

Update lib template for `cargo new` so that it conforms to rustfmt style by default

Auto merge of #4390 - alexcrichton:read-hard-links, r=matklad

Use `same-file` to avoid unnecessary hard links

This is targeted at removing the need for a workaround in rust-lang/rust#39518,
allowing the main rust build system to move back to hard links which should be
much more efficient.

Auto merge of #4386 - pornel:backups, r=alexcrichton

Exclude target directory from Time Machine

Fixes #3884