From 2ad45a563ef60819360ecd54d6eccc5b588e6401 Mon Sep 17 00:00:00 2001 From: Behnam Esfahbod Date: Thu, 31 Aug 2017 15:07:55 -0700 Subject: [PATCH] [doc] Sync back doc/book changes into old docs --- src/doc/book/src/guide/project-layout.md | 104 ----------------------- src/doc/guide.md | 5 +- src/doc/index.md | 34 ++++++-- 3 files changed, 29 insertions(+), 114 deletions(-) diff --git a/src/doc/book/src/guide/project-layout.md b/src/doc/book/src/guide/project-layout.md index 1850e5efa..f9eb7d331 100644 --- a/src/doc/book/src/guide/project-layout.md +++ b/src/doc/book/src/guide/project-layout.md @@ -33,107 +33,3 @@ Cargo project: These are explained in more detail in the [manifest description](reference/manifest.html#the-project-layout). - -## Cargo.toml vs Cargo.lock - -`Cargo.toml` and `Cargo.lock` serve two different purposes. Before we talk -about them, here’s a summary: - -* `Cargo.toml` is about describing your dependencies in a broad sense, and is - written by you. -* `Cargo.lock` contains exact information about your dependencies. It is - maintained by Cargo and should not be manually edited. - -If you’re building a library that other projects will depend on, put -`Cargo.lock` in your `.gitignore`. If you’re building an executable like a -command-line tool or an application, check `Cargo.lock` into `git`. If you're -curious about why that is, see ["Why do binaries have `Cargo.lock` in version -control, but not libraries?" in the -FAQ](faq.html#why-do-binaries-have-cargolock-in-version-control-but-not-libraries). - -Let’s dig in a little bit more. - -`Cargo.toml` is a **manifest** file in which we can specify a bunch of -different metadata about our project. For example, we can say that we depend -on another project: - -```toml -[package] -name = "hello_world" -version = "0.1.0" -authors = ["Your Name "] - -[dependencies] -rand = { git = "https://github.com/rust-lang-nursery/rand.git" } -``` - -This project has a single dependency, on the `rand` library. We’ve stated in -this case that we’re relying on a particular Git repository that lives on -GitHub. Since we haven’t specified any other information, Cargo assumes that -we intend to use the latest commit on the `master` branch to build our project. - -Sound good? Well, there’s one problem: If you build this project today, and -then you send a copy to me, and I build this project tomorrow, something bad -could happen. There could be more commits to `rand` in the meantime, and my -build would include new commits while yours would not. Therefore, we would -get different builds. This would be bad because we want reproducible builds. - -We could fix this problem by putting a `rev` line in our `Cargo.toml`: - -```toml -[dependencies] -rand = { git = "https://github.com/rust-lang-nursery/rand.git", rev = "9f35b8e" } -``` - -Now our builds will be the same. But there’s a big drawback: now we have to -manually think about SHA-1s every time we want to update our library. This is -both tedious and error prone. - -Enter the `Cargo.lock`. Because of its existence, we don’t need to manually -keep track of the exact revisions: Cargo will do it for us. When we have a -manifest like this: - -```toml -[package] -name = "hello_world" -version = "0.1.0" -authors = ["Your Name "] - -[dependencies] -rand = { git = "https://github.com/rust-lang-nursery/rand.git" } -``` - -Cargo will take the latest commit and write that information out into our -`Cargo.lock` when we build for the first time. That file will look like this: - -```toml -[root] -name = "hello_world" -version = "0.1.0" -dependencies = [ - "rand 0.1.0 (git+https://github.com/rust-lang-nursery/rand.git#9f35b8e439eeedd60b9414c58f389bdc6a3284f9)", -] - -[[package]] -name = "rand" -version = "0.1.0" -source = "git+https://github.com/rust-lang-nursery/rand.git#9f35b8e439eeedd60b9414c58f389bdc6a3284f9" -``` - -You can see that there’s a lot more information here, including the exact -revision we used to build. Now when you give your project to someone else, -they’ll use the exact same SHA, even though we didn’t specify it in our -`Cargo.toml`. - -When we’re ready to opt in to a new version of the library, Cargo can -re-calculate the dependencies and update things for us: - -```shell -$ cargo update # updates all dependencies -$ cargo update -p rand # updates just “rand” -``` - -This will write out a new `Cargo.lock` with the new version information. Note -that the argument to `cargo update` is actually a -[Package ID Specification](reference/pkgid-spec.html) and `rand` is just a short -specification. diff --git a/src/doc/guide.md b/src/doc/guide.md index e2b7da397..e8986f78f 100644 --- a/src/doc/guide.md +++ b/src/doc/guide.md @@ -57,7 +57,7 @@ needs to compile your project. Here’s what’s in `src/main.rs`: -``` +```rust fn main() { println!("Hello, world!"); } @@ -201,7 +201,7 @@ we choose to `cargo update`. You can now use the `regex` library using `extern crate` in `main.rs`. -``` +```rust extern crate regex; use regex::Regex; @@ -339,7 +339,6 @@ dependencies = [ name = "rand" version = "0.1.0" source = "git+https://github.com/rust-lang-nursery/rand.git#9f35b8e439eeedd60b9414c58f389bdc6a3284f9" - ``` You can see that there’s a lot more information here, including the exact diff --git a/src/doc/index.md b/src/doc/index.md index f2fbf81a0..cf3f36b58 100644 --- a/src/doc/index.md +++ b/src/doc/index.md @@ -1,21 +1,41 @@ % Cargo, Rust’s Package Manager -# Installing +### Install Stable Rust and Cargo -The easiest way to get Cargo is to get the current stable release of Rust by +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. +After this, you can use the `rustup` command to also install `beta` or `nightly` +channels for Rust and Cargo. -If you are on Windows, you can directly download the latest 32bit ([Rust](https://static.rust-lang.org/dist/rust-1.0.0-i686-pc-windows-gnu.msi) -and [Cargo](https://static.rust-lang.org/cargo-dist/cargo-nightly-i686-pc-windows-gnu.tar.gz)) or 64bit ([Rust](https://static.rust-lang.org/dist/rust-1.0.0-x86_64-pc-windows-gnu.msi) and [Cargo](https://static.rust-lang.org/cargo-dist/cargo-nightly-x86_64-pc-windows-gnu.tar.gz)) Rust stable releases or Cargo nightlies. +### Install Nightly Cargo -Alternatively, you can build Cargo from source. +To install just Cargo, the current recommended installation method is through +the official nightly builds. Note that Cargo will also require that [Rust] is +already installed on the system. + +| Platform | 64-bit | 32-bit | +|------------------|-------------------|-------------------| +| Linux binaries | [tar.gz][linux64] | [tar.gz][linux32] | +| MacOS binaries | [tar.gz][mac64] | [tar.gz][mac32] | +| Windows binaries | [tar.gz][win64] | [tar.gz][win32] | + +### Build and Install Cargo from Source + +Alternatively, you can [build Cargo from source][compiling-from-source]. + +[rust]: https://www.rust-lang.org/ +[linux64]: https://static.rust-lang.org/cargo-dist/cargo-nightly-x86_64-unknown-linux-gnu.tar.gz +[linux32]: https://static.rust-lang.org/cargo-dist/cargo-nightly-i686-unknown-linux-gnu.tar.gz +[mac64]: https://static.rust-lang.org/cargo-dist/cargo-nightly-x86_64-apple-darwin.tar.gz +[mac32]: https://static.rust-lang.org/cargo-dist/cargo-nightly-i686-apple-darwin.tar.gz +[win64]: https://static.rust-lang.org/cargo-dist/cargo-nightly-x86_64-pc-windows-gnu.tar.gz +[win32]: https://static.rust-lang.org/cargo-dist/cargo-nightly-i686-pc-windows-gnu.tar.gz +[compiling-from-source]: https://github.com/rust-lang/cargo#compiling-from-source # Let’s get started -- 2.30.2