Auto merge of #4916 - tari:doc-recovery, r=alexcrichton

Recover doc changes lost in #4904

Fixes #4906.

src/doc/src/guide/build-cache.md

@@ -0,0 +1,14 @@
+## Build cache
+
+Cargo shares build artifacts among all the packages of a single workspace.
+Today, Cargo does not share build results across different workspaces, but 
+a similar result can be achieved by using a third party tool, [sccache].
+
+To setup `sccache`, install it with `cargo install sccache` and set 
+`RUSTC_WRAPPER` environmental variable to `sccache` before invoking Cargo.
+If you use bash, it makes sense to add `export RUSTC_WRAPPER=sccache` to 
+`.bashrc`. Refer to sccache documentation for more details.
+
+[sccache]: https://github.com/mozilla/sccache
+
+

src/doc/src/guide/index.md

@@ -11,3 +11,4 @@ develop Rust projects.
 * [Cargo.toml vs Cargo.lock](guide/cargo-toml-vs-cargo-lock.html)
 * [Tests](guide/tests.html)
 * [Continuous Integration](guide/continuous-integration.html)
+* [Build Cache](guide/build-cache.html)

src/doc/src/reference/build-scripts.md

@@ -47,8 +47,14 @@ the source directory of the build script’s package.
 
 All the lines printed to stdout by a build script are written to a file like
 `target/debug/build/<pkg>/output` (the precise location may depend on your
-configuration). Any line that starts with `cargo:` is interpreted directly by
-Cargo. This line must be of the form `cargo:key=value`, like the examples below:
+configuration). If you would like to see such output directly in your terminal,
+invoke cargo as 'very verbose' with the `-vv` flag. Note that if neither the
+build script nor project source files are modified, subsequent calls to
+cargo with `-vv` will **not** print output to the terminal because a
+new build is not executed. Run `cargo clean` before each cargo invocation
+if you want to ensure that output is always displayed on your terminal.
+Any line that starts with `cargo:` is interpreted directly by Cargo.
+This line must be of the form `cargo:key=value`, like the examples below:
 
 ```shell
 # specially recognized by Cargo
@@ -371,24 +377,26 @@ portable, and standardized. For example, the build script could be written as:
 ```rust,ignore
 // build.rs
 
-// Bring in a dependency on an externally maintained `gcc` package which manages
+// Bring in a dependency on an externally maintained `cc` package which manages
 // invoking the C compiler.
-extern crate gcc;
+extern crate cc;
 
 fn main() {
-    gcc::compile_library("libhello.a", &["src/hello.c"]);
+    cc::Build::new()
+        .file("src/hello.c")
+        .compile("hello");
 }
 ```
 
-Add a build time dependency on the `gcc` crate with the following addition to
+Add a build time dependency on the `cc` crate with the following addition to
 your `Cargo.toml`:
 
 ```toml
 [build-dependencies]
-gcc = "0.3"
+gcc = "1.0"
 ```
 
-The [`gcc` crate](https://crates.io/crates/gcc) abstracts a range of build
+The [`cc` crate](https://crates.io/crates/cc) abstracts a range of build
 script requirements for C code:
 
 * It invokes the appropriate compiler (MSVC for windows, `gcc` for MinGW, `cc`
@@ -397,7 +405,7 @@ script requirements for C code:
   the compiler being used.
 * Other environment variables, such as `OPT_LEVEL`, `DEBUG`, etc., are all
   handled automatically.
-* The stdout output and `OUT_DIR` locations are also handled by the `gcc`
+* The stdout output and `OUT_DIR` locations are also handled by the `cc`
   library.
 
 Here we can start to see some of the major benefits of farming as much

src/doc/src/reference/config.md

@@ -76,6 +76,8 @@ runner = ".."
 # custom flags to pass to all compiler invocations that target $triple
 # this value overrides build.rustflags when both are present
 rustflags = ["..", ".."]
+# Whether or not to enable incremental compilation
+incremental = true
 
 [target.'cfg(...)']
 # Similar for the $triple configuration, but using the `cfg` syntax.

src/doc/src/reference/environment-variables.md

@@ -28,6 +28,10 @@ system:
 * `RUSTFLAGS` - A space-separated list of custom flags to pass to all compiler
   invocations that Cargo performs. In contrast with `cargo rustc`, this is
   useful for passing a flag to *all* compiler instances.
+* `CARGO_INCREMENTAL` - If this is set to 1 then Cargo will force incremental
+  compilation to be enabled for the current compilation, and when set to 0 it
+  will force disabling it. If this env var isn't present then cargo's defaults
+  will otherwise be used.
 
 Note that Cargo will also read environment variables for `.cargo/config`
 configuration values, as described in [that documentation][config-env]

src/doc/src/reference/manifest.md

@@ -199,7 +199,9 @@ license-file = "..."
 
 # Appveyor: `repository` is required. `branch` is optional; default is `master`
 # `service` is optional; valid values are `github` (default), `bitbucket`, and
-# `gitlab`.
+# `gitlab`; `id` is optional; you can specify the appveyor project id if you
+# want to use that instead. `project_name` is optional; use when the repository
+# name differs from the appveyor project name.
 appveyor = { repository = "...", branch = "master", service = "github" }
 
 # Circle CI: `repository` is required. `branch` is optional; default is `master`
@@ -299,6 +301,7 @@ codegen-units = 1  # if > 1 enables parallel code generation which improves
                    # compile times, but prevents some optimizations.
                    # Passes `-C codegen-units`. Ignored when `lto = true`.
 panic = 'unwind'   # panic strategy (`-C panic=...`), can also be 'abort'
+incremental = true # whether or not incremental compilation is enabled
 
 # The release profile, used for `cargo build --release`.
 [profile.release]
@@ -309,6 +312,7 @@ lto = false
 debug-assertions = false
 codegen-units = 1
 panic = 'unwind'
+incremental = false
 
 # The testing profile, used for `cargo test`.
 [profile.test]
@@ -319,6 +323,7 @@ lto = false
 debug-assertions = true
 codegen-units = 1
 panic = 'unwind'
+incremental = true
 
 # The benchmarking profile, used for `cargo bench` and `cargo test --release`.
 [profile.bench]
@@ -329,6 +334,7 @@ lto = false
 debug-assertions = false
 codegen-units = 1
 panic = 'unwind'
+incremental = false
 
 # The documentation profile, used for `cargo doc`.
 [profile.doc]
@@ -339,6 +345,7 @@ lto = false
 debug-assertions = true
 codegen-units = 1
 panic = 'unwind'
+incremental = true
 ```
 
 ### The `[features]` section
@@ -475,10 +482,12 @@ as:
 ```toml
 [workspace]
 
-# Optional key, inferred if not present
+# Optional key, inferred from path dependencies if not present.
+# Additional non-path dependencies that should be included must be given here.
+# In particular, for a virtual manifest, all members have to be listed.
 members = ["path/to/member1", "path/to/member2", "path/to/member3/*"]
 
-# Optional key, empty if not present
+# Optional key, empty if not present.
 exclude = ["path1", "path/to/dir2"]
 ```
 
@@ -528,10 +537,23 @@ crate will be treated as a normal package, as well as a workspace. If the
 `package` table is not present in a workspace manifest, it is called a *virtual
 manifest*.
 
-When working with *virtual manifests*, package-related cargo commands, like
-`cargo build`, won't be available anymore. But, most of such commands support
-the `--all` option, will execute the command for all the non-virtual manifest in
-the workspace.
+#### Package selection
+
+In a workspace, package-related cargo commands like `cargo build` apply to
+packages selected by `-p` / `--package` or `--all` command-line parameters.
+When neither is specified, the optional `default-members` configuration is used:
+
+```toml
+[workspace]
+members = ["path/to/member1", "path/to/member2", "path/to/member3/*"]
+default-members = ["path/to/member2", "path/to/member3/foo"]
+```
+
+When specified, `default-members` must expand to a subset of `members`.
+
+When `default-members` is not specified, the default is the root manifest
+if it is a package, or every member manifest (as if `--all` were specified
+on the command-line) for virtual workspaces.
 
 #TODO: move this to a more appropriate place
 ### The project layout
@@ -550,7 +572,8 @@ each file you want to build.
 
 Your project can optionally contain folders named `examples`, `tests`, and
 `benches`, which Cargo will treat as containing examples,
-integration tests, and benchmarks respectively.
+integration tests, and benchmarks respectively. Analogous to `bin` targets, they
+may be composed of single files or directories with a `main.rs` file.
 
 ```shell
 ▾ src/           # directory containing source files
@@ -562,10 +585,16 @@ integration tests, and benchmarks respectively.
     main.rs
 ▾ examples/      # (optional) examples
   *.rs
+▾ */             # (optional) directories containing multi-file examples
+  main.rs
 ▾ tests/         # (optional) integration tests
   *.rs
+▾ */             # (optional) directories containing multi-file tests
+  main.rs
 ▾ benches/       # (optional) benchmarks
   *.rs
+▾ */             # (optional) directories containing multi-file benchmarks
+  main.rs
 ```
 
 To structure your code after you've created the files and folders for your
@@ -723,19 +752,28 @@ other copies. The syntax is similar to the `[dependencies]` section:
 [patch.crates-io]
 foo = { git = 'https://github.com/example/foo' }
 bar = { path = 'my/local/bar' }
+
+[dependencies.baz]
+git = 'https://github.com/example/baz'
+
+[patch.'https://github.com/example/baz']
+baz = { git = 'https://github.com/example/patched-baz', branch = 'my-branch' }
 ```
 
 The `[patch]` table is made of dependency-like sub-tables. Each key after
 `[patch]` is a URL of the source that's being patched, or `crates-io` if
 you're modifying the https://crates.io registry. In the example above
 `crates-io` could be replaced with a git URL such as
-`https://github.com/rust-lang-nursery/log`.
+`https://github.com/rust-lang-nursery/log`; the second `[patch]`
+section in the example uses this to specify a source called `baz`.
 
 Each entry in these tables is a normal dependency specification, the same as
 found in the `[dependencies]` section of the manifest. The dependencies listed
 in the `[patch]` section are resolved and used to patch the source at the
 URL specified. The above manifest snippet patches the `crates-io` source (e.g.
-crates.io itself) with the `foo` crate and `bar` crate.
+crates.io itself) with the `foo` crate and `bar` crate. It also
+patches the `https://github.com/example/baz` source with a `my-branch` that
+comes from elsewhere.
 
 Sources can be patched with versions of crates that do not exist, and they can
 also be patched with versions of crates that already exist. If a source is

src/doc/src/reference/publishing.md

@@ -52,7 +52,7 @@ accidentally package up that 2GB video asset, or large data files used for code
 generation, integration tests, or benchmarking.  There is currently a 10MB
 upload size limit on `*.crate` files. So, if the size of `tests` and `benches`
 directories and their dependencies are up to a couple of MBs, you can keep them
-in your package; otherwsie, better to exclude them.
+in your package; otherwise, better to exclude them.
 
 Cargo will automatically ignore files ignored by your version control system
 when packaging, but if you want to specify an extra set of files to ignore you

src/doc/src/reference/source-replacement.md

@@ -20,6 +20,12 @@ like so:
 [source.my-awesome-source]
 directory = "vendor"
 
+# Git sources can optionally specify a branch/tag/rev as well
+git = "https://example.com/path/to/repo"
+# branch = "master"
+# tag = "v1.0.1"
+# rev = "313f44e8"
+
 # The crates.io default source for crates is available under the name
 # "crates-io", and here we use the `replace-with` key to indicate that it's
 # replaced with our source above.