At the end, point to docs that might be interesting next

Add info about what's different between debug/release

Add info about `build-dependencies` to the specifying deps page

Add a `[dev-dependencies]` example

Correct typo when referring to 64 bit

Clarify statements about ignoring/checking in Cargo.lock

Small rewordings

Clarify that you should not manually edit Cargo.lock

Add an ascii directory tree to the project layout section

Clarify that integration tests go in tests/

"External" is a bit confusing. Then if we say where integration tests
go, that might make someone wonder where the unit tests go, so I added a
note about unit tests.

Reword note about git init default to be in the positive

Remove section about converting a project to cargo

Since most projects start with cargo these days.

Replace references to conduit(-static) with uuid/rand

Since they're official rust crates.

Combine related thoughts into the same paragraph

Reword to not call a non-rust-tuple thing a tuple

Use — instead of --

Use code formatting for `git`

Add all three channels to the sample .travis.yml

Replace refs to color-rs crate to rust-lang's rand crate

Bonus: rand has a `next` branch so the git branch example makes more
sense!

Clarify that release builds go in the release dir, not another subdir

Good call @steveklabnik! This matches much more nicely with the contrast
to `target/debug`.

Link crates.io everywhere

Fix markdown links that repeat their link text unnecessarily

Add instructions for rendering docs locally to the README

Make the crates.io docs about publishing only, not using

Try to make this flow a bit more and have sections based on what
situation you might find yourself in.

Consolidate all info about specifying deps into one page.

I think information about specifying dependencies deserves to have its
own page since this info is commonly needed and there are a LOT of
different ways to specify dependencies.

Previously this information was spread across multiple pages, now
there's one place to go if you're looking for any of these ways, rather
than checking the multiple pages this info was spread across before.

Incorporate "using crates from crates.io" into the main guide

Connects to rust-lang/cargo#1035. Using crates from crates.io is a
common thing that many people will want to know how to do right away and
deserves to be part of the main guide.

Move the Travis CI section under the testing section

I'm guessing the path dependency section got added in between. Also
linked to the Travis CI rust docs and removed the hyphen since Travis CI
seems to spell it without.

Small rewording changes; mostly to clear up potential ambiguity

Correct reference to `foo` to `hello_world`

Copypasta, or forgotten name change

Clarify that the "somewhere" is github

Mention that binary location changes when using --release

Remove out of place instructions on passing args and flags

This doesn't feel like it fits very well at this point, since our
example program doesn't take args and beginners to cargo probably don't
have a reason to want to pass flags on to rustc at this point. Also it
doesn't even say rustc, just "which flags go where"... where would they
go?!?!

Correct `Fresh` to `Compiling` since we aren't running with -v

I only see `Fresh` if I use `cargo run -v`, but this example uses `cargo
run`. Someone following along might not see either of these if they just
built in the previous step, though, so clarify that you'll only see that
if you have made changes.

Remove extranneous commas

Steve and commas, sittin in a tree!

Fixes rust-lang/crates.io#334.

Auto merge of #2682 - srinivasreddy:refactor_2, r=alexcrichton

remove deprecated attr - change connect() to join()

remove deprecated attr - change connect() to join()

Auto merge of #2681 - alexcrichton:cargo-env-home, r=brson

Canonicalize CARGO_HOME fallback on Windows

This commit ensures that we always return the same fallback value on Windows
regardless of whichever shell we happen to be run from. We do this by removing
the `$HOME` environment variable which `std::env::home_dir` will inspect to
force it to fall back to the system APIs. If the old directory exists then we
favor that one, but otherwise we favor locations like `C:\Users\$user`

Supercedes and closes #2604

Canonicalize CARGO_HOME fallback on Windows

This commit ensures that we always return the same fallback value on Windows
regardless of whichever shell we happen to be run from. We do this by removing
the `$HOME` environment variable which `std::env::home_dir` will inspect to
force it to fall back to the system APIs. If the old directory exists then we
favor that one, but otherwise we favor locations like `C:\Users\$user`

Supercedes and closes #2604

Auto merge of #2678 - matklad:simplify-tests-2, r=alexcrichton

Simplify more tests

This is the followup of #2670

It contains [one](https://github.com/rust-lang/cargo/commit/28887beee054bfa9b56207667df3f5ae38a8ac6f#diff-ebcf8bfb935037902f135a7c225479b5L322) more or less significant change, everything else is just search/replace.

r? @alexcrichton

remove useless formats

simplify tests

remove ADDING, REMOVING, DOCTEST, DOWNLOADING, PACKAGING, UPLOADING,
VERIFYING, ARCHIVING, INSTALLING, REPLACING constants

Auto merge of #2396 - sbeckeriv:network-retry-1602, r=alexcrichton

Network retry issue 1602

Dearest Reviewer,

This branch resolves #1602 which relates to retrying network
issues automatically. There is a new utility helper for retrying
any network call.

There is a new config called net.retry value in the .cargo.config
file. The default value is 2. The documentation has also been
updated to reflect the new value.

Thanks
Becker

Network retry issue 1602

Dearest Reviewer,

This branch resolves #1602 which relates to retrying network
issues automatically. There is a new utility helper for retrying
any network call.

There is a new config called net.retry value in the .cargo.config
file. The default value is 2. The documentation has also been
updated to reflect the new value.

Thanks
Becker

Auto merge of #2674 - alexcrichton:less-third-party-cruft, r=brson

Don't print extra error info for subcommands

Assume they take care of error printing, so just ferry along the exit status if
they fail

Closes #2673

Don't print extra error info for subcommands

Assume they take care of error printing, so just ferry along the exit status if
they fail

Closes #2673

Auto merge of #2670 - matklad:simplify-tests, r=alexcrichton

Simplify tests

@alexcrichton I think there is one bit of tests that could be simplified.

What do you think about writing this

```Rust
test!(simple {
    pkg("foo", "0.0.1");

    assert_that(cargo_process("install").arg("foo"),
                execs().with_status(0).with_stdout(&format!("\
[UPDATING] registry `[..]`
[DOWNLOADING] foo v0.0.1 (registry file://[..])
[COMPILING] foo v0.0.1 (registry file://[..])
[INSTALLING] {home}[..]bin[..]foo[..]
",
        home = cargo_home().display())));
    assert_that(cargo_home(), has_installed_exe("foo"));

    assert_that(cargo_process("uninstall").arg("foo"),
                execs().with_status(0).with_stdout(&format!("\
[REMOVING] {home}[..]bin[..]foo[..]
",
        home = cargo_home().display())));
    assert_that(cargo_home(), is_not(has_installed_exe("foo")));
});
```

instead of this

```Rust
test!(simple {
    pkg("foo", "0.0.1");

    assert_that(cargo_process("install").arg("foo"),
                execs().with_status(0).with_stdout(&format!("\
{updating} registry `[..]`
{downloading} foo v0.0.1 (registry file://[..])
{compiling} foo v0.0.1 (registry file://[..])
{installing} {home}[..]bin[..]foo[..]
",
        updating = UPDATING,
        downloading = DOWNLOADING,
        compiling = COMPILING,
        installing = INSTALLING,
        home = cargo_home().display())));
    assert_that(cargo_home(), has_installed_exe("foo"));

    assert_that(cargo_process("uninstall").arg("foo"),
                execs().with_status(0).with_stdout(&format!("\
{removing} {home}[..]bin[..]foo[..]
",
        removing = REMOVING,
        home = cargo_home().display())));
    assert_that(cargo_home(), is_not(has_installed_exe("foo")));
});
```

This PR has a proof of concept implementation of this feature applied to a couple of tests.

r? @alexcrichton

simplify tests

remove RUNNING, COMPILING, ERROR, DOCUMENTING, FRESH and UPDATING
constants

Auto merge of #2669 - mbrubeck:dev-dep-doc, r=alexcrichton

Document that dev-dependencies are used when building examples

None

Simplify tests

Document that dev-dependencies are used when building examples

Auto merge of #2666 - matklad:simplify, r=alexcrichton

Simplify error printing

Simplify error printing

Auto merge of #2656 - knight42:fix, r=alexcrichton

zsh: enable autocompletion for sub-command `init`

Auto merge of #2647 - alx741:improve-manpage, r=alexcrichton

Man page: Improve build command section

Addresses #2645

This is a proposal for improving the documentation available in the man page about each command; It has been applied to the **build** command only, if it is useful i will do the same with the other ones.

Auto merge of #2653 - frewsxcv:cleanup, r=alexcrichton

A few cleanup commits.

None

zsh: enable autocompletion for sub-command `init`

Add man sub-pages in Makefile.in

Man page: Add cargo-build page

Man page: Add reference to cargo-build page

Utilize `if let` over single branch `match`.

Remove `String` ownership constraint, fewer allocations.

Turn `url_ref` utility function into method.

Auto merge of #2648 - frewsxcv:unused-to-url, r=alexcrichton

Remove unused `ToUrl` impls.

None

Remove unused `ToUrl` impls.

Man page: Improve build command section

Auto merge of #2635 - frewsxcv:toml-cleanup, r=alexcrichton

Various cleanup in `src/cargo/util/toml.rs`.

None

Auto merge of #2639 - SimonSapin:url-1.0, r=alexcrichton

Update to rust-url 1.x

This is ready to go now :)

Auto merge of #2634 - frewsxcv:flake8, r=alexcrichton

Address flake8 issues.

None

Update to rust-url 1.x

Auto merge of #2636 - sanxiyn:unused-trait-import, r=alexcrichton

Remove unused trait imports

Update OpenSSL version to 1.0.2h

Remove unused trait imports

Utilize `if let` construct over single branch `match`.

Remove unnecessary `Vec` allocation when iterating.

Refactor `TomlTarget` validation functions into methods.

Use constructor pattern for `project_layout` in `toml.rs`.

Minor whitespace fixes for flake8.

Remove unused Python imports.

Auto merge of #2405 - gkoz:reinstall, r=alexcrichton

Add `--force` flag to cargo install

Close #2082.

Adding `--force` (`-f`) instructs cargo to overwrite existing binaries (updating the metadata accordingly).
This allows updating crates via `cargo install -f <crate>`.

Installation happens in two stages now: binaries are copied into a temporary subdirectory of the destination first, then moved into destination. This should catch some errors earlier.

In case of installation error cargo will remove new binaries but won't attempt to undo successful overwrites.

cargo-install: move binaries from the build dir if possible

Try moving the binaries (and fall back to copying) if the build
directory is a temporary one (source isn't a local path).

Add `--force` flag to cargo install

Close #2082

Adding `--force` (`-f`) instructs cargo to overwrite existing binaries
(updating the metadata accordingly).
This allows updating crates via `cargo install -f <crate>`.

Installation happens in two stages now: binaries are copied into a
temporary subdirectory of the destination first, then moved into
destination. This should catch some errors earlier.

In case of installation error cargo will remove new binaries but won't
attempt to undo successful overwrites.

Auto merge of #2629 - alexcrichton:moar-rustflags, r=brson

Pass RUSTFLAGS when we learn about target info

This should help us learn about `target_feature` additions!

Closes #2628

Pass RUSTFLAGS when we learn about target info

This should help us learn about `target_feature` additions!

Closes #2628

Auto merge of #2623 - alexcrichton:nfs-lol-no, r=brson

Don't use flock on NFS mounts

Completely skip file locking when we detect an NFS mount via `statfs`.

Closes #2615

Auto merge of #2625 - aidanhs:aphs-path-crates-io, r=alexcrichton

`path` dependencies are ignored from crates.io

`path` dependencies are ignored from crates.io

Don't use flock on NFS mounts

Completely skip file locking when we detect an NFS mount via `statfs`.

Closes #2615

Auto merge of #2619 - japaric:freebsd32, r=alexcrichton

prepare for i686-unknown-freebsd nightlies

Tested with:

```
$ python -B src/etc/install-deps.py
$ ./configure --local-rust-root=$PWD/rustc --enable-optimize --enable-nightly --target=i686-unknown-freebsd
$ make
```

r? @alexcrichton

prepare for i686-unknown-freebsd nightlies

Auto merge of #2617 - sanxiyn:reset-rustflags, r=alexcrichton

Reset RUSTFLAGS when running tests

Reset RUSTFLAGS when running tests

Auto merge of #2610 - japaric:install-from-tempdir, r=alexcrichton

cargo-install: prefer building artifacts in the system temporary directory

and each cargo-install instance creates and uses its own build directory. This
allows running several cargo-install instances in parallel.

If we fail to create a temporary directory for whatever reason fallback to
creating and using a target-install directory in the current directory.

closes #2606

---

r? @alexcrichton

Qs:
- Should we preserve the current behavior (`target-install` in `cwd`) as a fallback or remove it and error if we can't create a `TempDir` in `env::temp_dir()`? (we currently error if we can't create `target-install` directory in `cwd`)

- Should I add tests for the issues I raised at #2606? If yes, how can I test `cargo-install` parallelism? Lack of "Blocking waiting for file lock on build directory" in the output of the `cargo` commands? or something else?

add tests for #2606

cargo-install: prefer building artifacts in the system temporary directory

and each cargo-install instance creates and uses its own build directory. This
allows running several cargo-install instances in parallel.

If we fail to create a temporary directory for whatever reason fallback to
creating and using a target-install directory in the current directory.

closes #2606

Auto merge of #2602 - durka:patch-5, r=alexcrichton

fix rerun-if-changed documentation

The documentation corresponded to the initial proposed implementation, which was changed to remove special handling of directories before it was ever merged.

closes #2599
r? @alexcrichton

fix rerun-if-changed documentation

The documentation corresponded to the initial proposed implementation, which was changed to remove special handling of directories before it was ever merged.

Auto merge of #2578 - alexcrichton:test-doc, r=brson

Add `cargo test --doc`

Supports testing only the documentation (like `--lib`, `--bin`, etc).

Auto merge of #2551 - alexcrichton:explain, r=brson

Add support for `cargo --explain`

The error messages in the compiler are being tweaked and will likely drop the
`rustc --explain` part of the error message in favor of `--explain`. In that
case you're expected to basically take whatever tool you're using and pass
`--explain` to it with an error code, so let's add it to Cargo as well!

Add support for `cargo --explain`

The error messages in the compiler are being tweaked and will likely drop the
`rustc --explain` part of the error message in favor of `--explain`. In that
case you're expected to basically take whatever tool you're using and pass
`--explain` to it with an error code, so let's add it to Cargo as well!

Auto merge of #2576 - alexcrichton:silence-warnings-with-q, r=brson

Don't print warnings when -q is passed

Closes #2571