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 <#4220>.

First step for <#4040>.

src/doc/MIGRATION_MAP

@@ -0,0 +1,13 @@
+build-script.md book/src/03-05-build-scripts.md
+config.md book/src/03-03-config.md
+crates-io.md book/src/03-06-crates-io.md
+environment-variables.md book/src/03-04-environment-variables.md
+external-tools.md book/src/03-09-external-tools.md
+faq.md book/src/faq.md
+guide.md book/src/guide.md book/src/02-*.md
+index.md book/src/SUMMARY.md book/src/01-*.md
+manifest.md book/src/03-02-manifest.md
+pkgid-spec.md book/src/03-07-pkgid-spec.md
+policies.md book/src/03-10-policies.md
+source-replacement.md book/src/03-08-source-replacement.md
+specifying-dependencies.md book/src/03-01-specifying-dependencies.md

src/doc/README.md

@@ -0,0 +1,6 @@
+# Cargo Documentation
+
+NOTE: Cargo documentation is under migration to mdBook-based structure. All the
+`*.md` files here shall be kept in sync with the `*.md` files under `book/src/`.
+See `MIGRATION_MAP` file here and <https://github.com/rust-lang/cargo/pull/4453>
+for details.

src/doc/book/.gitignore

@@ -0,0 +1 @@
+/book

src/doc/book/README.md

@@ -0,0 +1,47 @@
+# The Cargo Book
+
+
+### Requirements
+
+Building the book requires [mdBook]. To get it:
+
+[mdBook]: https://github.com/azerupi/mdBook
+
+```bash
+$ cargo install mdbook
+```
+
+### Building
+
+To build the book:
+
+```bash
+$ mdbook build
+```
+
+The output will be in the `book` subdirectory. To check it out, open it in
+your web browser.
+
+_Firefox:_
+```bash
+$ firefox book/index.html                       # Linux
+$ open -a "Firefox" book/index.html             # OS X
+$ Start-Process "firefox.exe" .\book\index.html # Windows (PowerShell)
+$ start firefox.exe .\book\index.html           # Windows (Cmd)
+```
+
+_Chrome:_
+```bash
+$ google-chrome book/index.html                 # Linux
+$ open -a "Google Chrome" book/index.html       # OS X
+$ Start-Process "chrome.exe" .\book\index.html  # Windows (PowerShell)
+$ start chrome.exe .\book\index.html            # Windows (Cmd)
+```
+
+
+## Contributing
+
+Given that the book is still in a draft state, we'd love your help! Please feel free to open
+issues about anything, and send in PRs for things you'd like to fix or change. If your change is
+large, please open an issue first, so we can make sure that it's something we'd accept before you
+go through the work of getting a PR together.

src/doc/book/src/01-01-installation.md

@@ -0,0 +1,21 @@
+## Installation
+
+The easiest way to get Cargo is to get the current stable release of Rust by
+using the `rustup` script:
+
+```shell
+$ curl -sSf https://static.rust-lang.org/rustup.sh | sh
+```
+
+This will get you the current stable release of Rust for your platform along
+with the latest Cargo.
+
+If you are on Windows, you can directly download the latest stable Rust and nightly Cargo:
+
+- [Rust (32-bit)](https://static.rust-lang.org/dist/rust-1.17.0-i686-pc-windows-gnu.msi)
+- [Cargo (32-bit)](https://static.rust-lang.org/cargo-dist/cargo-nightly-i686-pc-windows-gnu.tar.gz)
+
+- [Rust (64-bit)](https://static.rust-lang.org/dist/rust-1.17.0-x86_64-pc-windows-gnu.msi)
+- [Cargo (64-bit)](https://static.rust-lang.org/cargo-dist/cargo-nightly-x86_64-pc-windows-gnu.tar.gz)
+
+Alternatively, you can [build Cargo from source](https://github.com/rust-lang/cargo#compiling-from-source).

src/doc/book/src/01-02-first-steps.md

@@ -0,0 +1,70 @@
+## First Steps with Cargo
+
+To start a new project with Cargo, use `cargo new`:
+
+```shell
+$ cargo new hello_world --bin
+```
+
+We’re passing `--bin` because we’re making a binary program: if we
+were making a library, we’d leave it off.
+
+Let’s check out what Cargo has generated for us:
+
+```shell
+$ cd hello_world
+$ tree .
+.
+├── Cargo.toml
+└── src
+    └── main.rs
+
+1 directory, 2 files
+```
+
+This is all we need to get started. First, let’s check out `Cargo.toml`:
+
+```toml
+[package]
+name = "hello_world"
+version = "0.1.0"
+authors = ["Your Name <you@example.com>"]
+```
+
+This is called a **manifest**, and it contains all of the metadata that Cargo
+needs to compile your project.
+
+Here’s what’s in `src/main.rs`:
+
+```
+fn main() {
+    println!("Hello, world!");
+}
+```
+
+Cargo generated a “hello world” for us. Let’s compile it:
+
+```shell
+$ cargo build
+   Compiling hello_world v0.1.0 (file:///path/to/project/hello_world)
+```
+
+And then run it:
+
+```shell
+$ ./target/debug/hello_world
+Hello, world!
+```
+
+We can also use `cargo run` to compile and then run it, all in one step:
+
+```shell
+$ cargo run
+     Fresh hello_world v0.1.0 (file:///path/to/project/hello_world)
+   Running `target/hello_world`
+Hello, world!
+```
+
+## Going further
+
+For more details on using Cargo, check out the [Cargo Guide](guide.html)

src/doc/book/src/02-01-why-cargo-exists.md

@@ -0,0 +1,12 @@
+## Why Cargo Exists
+
+Cargo is a tool that allows Rust projects to declare their various
+dependencies and ensure that you’ll always get a repeatable build.
+
+To accomplish this goal, Cargo does four things:
+
+* Introduces two metadata files with various bits of project information.
+* Fetches and builds your project’s dependencies.
+* Invokes `rustc` or another build tool with the correct parameters to build
+  your project.
+* Introduces conventions to make working with Rust projects easier.

src/doc/book/src/02-02-creating-a-new-project.md

@@ -0,0 +1,89 @@
+## Creating a New Project
+
+To start a new project with Cargo, use `cargo new`:
+
+```shell
+$ cargo new hello_world --bin
+```
+
+We’re passing `--bin` because we’re making a binary program: if we
+were making a library, we’d leave it off. This also initializes a new `git`
+repository by default. If you don't want it to do that, pass `--vcs none`.
+
+Let’s check out what Cargo has generated for us:
+
+```shell
+$ cd hello_world
+$ tree .
+.
+├── Cargo.toml
+└── src
+    └── main.rs
+
+1 directory, 2 files
+```
+
+If we had just used `cargo new hello_world` without the `--bin` flag, then
+we would have a `lib.rs` instead of a `main.rs`. For now, however, this is all
+we need to get started. First, let’s check out `Cargo.toml`:
+
+```toml
+[package]
+name = "hello_world"
+version = "0.1.0"
+authors = ["Your Name <you@example.com>"]
+```
+
+This is called a **manifest**, and it contains all of the metadata that Cargo
+needs to compile your project.
+
+Here’s what’s in `src/main.rs`:
+
+```
+fn main() {
+    println!("Hello, world!");
+}
+```
+
+Cargo generated a “hello world” for us. Let’s compile it:
+
+```shell
+$ cargo build
+   Compiling hello_world v0.1.0 (file:///path/to/project/hello_world)
+```
+
+And then run it:
+
+```shell
+$ ./target/debug/hello_world
+Hello, world!
+```
+
+We can also use `cargo run` to compile and then run it, all in one step (You
+won't see the `Compiling` line if you have not made any changes since you last
+compiled):
+
+```shell
+$ cargo run
+   Compiling hello_world v0.1.0 (file:///path/to/project/hello_world)
+     Running `target/debug/hello_world`
+Hello, world!
+```
+
+You’ll now notice a new file, `Cargo.lock`. It contains information about our
+dependencies. Since we don’t have any yet, it’s not very interesting.
+
+Once you’re ready for release, you can use `cargo build --release` to compile
+your files with optimizations turned on:
+
+```shell
+$ cargo build --release
+   Compiling hello_world v0.1.0 (file:///path/to/project/hello_world)
+```
+
+`cargo build --release` puts the resulting binary in `target/release` instead of
+`target/debug`.
+
+Compiling in debug mode is the default for development-- compilation time is
+shorter since the compiler doesn't do optimizations, but the code will run
+slower. Release mode takes longer to compile, but the code will run faster.

src/doc/book/src/02-03-working-on-an-existing-project.md

@@ -0,0 +1,22 @@
+## Working on an Existing Cargo Project
+
+If you download an existing project that uses Cargo, it’s really easy
+to get going.
+
+First, get the project from somewhere. In this example, we’ll use `rand`
+cloned from its repository on GitHub:
+
+```shell
+$ git clone https://github.com/rust-lang-nursery/rand.git
+$ cd rand
+```
+
+To build, use `cargo build`:
+
+```shell
+$ cargo build
+   Compiling rand v0.1.0 (file:///path/to/project/rand)
+```
+
+This will fetch all of the dependencies and then build them, along with the
+project.

src/doc/book/src/02-04-dependencies.md

@@ -0,0 +1,90 @@
+## Dependencies
+
+[crates.io] is the Rust community's central package registry that serves as a
+location to discover and download packages. `cargo` is configured to use it by
+default to find requested packages.
+
+To depend on a library hosted on [crates.io], add it to your `Cargo.toml`.
+
+[crates.io]: https://crates.io/
+
+### Adding a dependency
+
+If your `Cargo.toml` doesn't already have a `[dependencies]` section, add that,
+then list the crate name and version that you would like to use. This example
+adds a dependency of the `time` crate:
+
+```toml
+[dependencies]
+time = "0.1.12"
+```
+
+The version string is a [semver] version requirement. The [specifying
+dependencies](03-01-specifying-dependencies.html) docs have more information about
+the options you have here.
+
+[semver]: https://github.com/steveklabnik/semver#requirements
+
+If we also wanted to add a dependency on the `regex` crate, we would not need
+to add `[dependencies]` for each crate listed. Here's what your whole
+`Cargo.toml` file would look like with dependencies on the `time` and `regex`
+crates:
+
+```toml
+[package]
+name = "hello_world"
+version = "0.1.0"
+authors = ["Your Name <you@example.com>"]
+
+[dependencies]
+time = "0.1.12"
+regex = "0.1.41"
+```
+
+Re-run `cargo build`, and Cargo will fetch the new dependencies and all of
+their dependencies, compile them all, and update the `Cargo.lock`:
+
+```shell
+$ cargo build
+      Updating registry `https://github.com/rust-lang/crates.io-index`
+   Downloading memchr v0.1.5
+   Downloading libc v0.1.10
+   Downloading regex-syntax v0.2.1
+   Downloading memchr v0.1.5
+   Downloading aho-corasick v0.3.0
+   Downloading regex v0.1.41
+     Compiling memchr v0.1.5
+     Compiling libc v0.1.10
+     Compiling regex-syntax v0.2.1
+     Compiling memchr v0.1.5
+     Compiling aho-corasick v0.3.0
+     Compiling regex v0.1.41
+     Compiling hello_world v0.1.0 (file:///path/to/project/hello_world)
+```
+
+Our `Cargo.lock` contains the exact information about which revision of all of
+these dependencies we used.
+
+Now, if `regex` gets updated, we will still build with the same revision until
+we choose to `cargo update`.
+
+You can now use the `regex` library using `extern crate` in `main.rs`.
+
+```
+extern crate regex;
+
+use regex::Regex;
+
+fn main() {
+    let re = Regex::new(r"^\d{4}-\d{2}-\d{2}$").unwrap();
+    println!("Did our date match? {}", re.is_match("2014-01-01"));
+}
+```
+
+Running it will show:
+
+```shell
+$ cargo run
+   Running `target/hello_world`
+Did our date match? true
+```