From 28c1f6310b79eba257773f95f726e4f675971d42 Mon Sep 17 00:00:00 2001 From: "Carol (Nichols || Goulding)" Date: Fri, 13 May 2016 12:58:26 -0400 Subject: [PATCH 01/34] Remove extranneous commas Steve and commas, sittin in a tree! Fixes rust-lang/crates.io#334. --- src/doc/guide.md | 34 +++++++++++++++++----------------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/src/doc/guide.md b/src/doc/guide.md index e305aab5c5b..3b97fc10811 100644 --- a/src/doc/guide.md +++ b/src/doc/guide.md @@ -6,7 +6,7 @@ about how to use Cargo to develop Rust projects. # 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. +dependencies and ensure that you’ll always get a repeatable build. To accomplish this goal, Cargo does four things: @@ -48,7 +48,7 @@ $ tree . 1 directory, 2 files ``` -If we had just used `cargo new hello_world` without the `--bin` flag, then the +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`: @@ -92,7 +92,7 @@ class="s1"> Fresh hello_world v0.1.0 (file:///path/to/project/hello_w class="s1"> Running `target/debug/hello_world` Hello, world! -To pass some arguments to your program, use `cargo run first_arg second_arg`. +To pass some arguments to your program, use `cargo run first_arg second_arg`. If flags are being passed, use a “--” separator to tell Cargo which flags go where, like `cargo run -- --foo -b bar`. You’ll now notice a new file, `Cargo.lock`. It contains information about our @@ -194,7 +194,7 @@ Did our date match? true 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 +Now, if `regex` gets updated, we will still build with the same revision until we choose to `cargo update`. # Project Layout @@ -248,8 +248,8 @@ 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. `bjz` could update `color-rs` in the meantime, and my build would -include this commit, while yours would not. Therefore, we would get different -builds. This would be bad, because we want reproducible builds. +include this commit 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`: @@ -258,7 +258,7 @@ We could fix this problem by putting a `rev` line in our `Cargo.toml`: color = { git = "https://github.com/bjz/color-rs.git", rev = "bf739419" } ``` -Now, our builds will be the same. But, there’s a big drawback: now we have to +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. @@ -276,7 +276,7 @@ authors = ["Your Name "] color = { git = "https://github.com/bjz/color-rs.git" } ``` -Cargo will take the latest commit, and write that information out into our +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 @@ -295,12 +295,12 @@ source = "git+https://github.com/bjz/color-rs.git#bf739419e2d31050615c1ba1a395b4 ``` 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, +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: +re-calculate the dependencies and update things for us: ```shell $ cargo update # updates all dependencies @@ -314,7 +314,7 @@ specification. # Overriding Dependencies -Sometimes, you may want to override one of Cargo’s dependencies. For example, +Sometimes you may want to override one of Cargo’s dependencies. For example, let’s say you’re working on a project, `conduit-static`, which depends on the package `conduit`. You find a bug in `conduit`, and you want to write a patch. Here’s what `conduit-static`’s `Cargo.toml` looks like: @@ -355,7 +355,7 @@ it will search for a `.cargo` in: * `/` This allows you to specify your overrides in a parent directory that -includes commonly used packages that you work on locally, and share them +includes commonly used packages that you work on locally and share them with all projects. To specify overrides, create a `.cargo/config` file in some ancestor of @@ -382,7 +382,7 @@ documentation](config.html). # Tests Cargo can run your tests with the `cargo test` command. Cargo runs tests in two -places: in each of your `src` files, and any tests in `tests/`. Tests +places: in each of your `src` files and any tests in `tests/`. Tests in your `src` files should be unit tests, and tests in `tests/` should be integration-style tests. As such, you’ll need to import your crates into the files in `tests`. @@ -402,7 +402,7 @@ running 0 tests test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured -Of course, if your project has tests, you’ll see more output, with the +Of course, if your project has tests, you’ll see more output with the correct number of tests. You can also run a specific test by passing a filter: @@ -413,7 +413,7 @@ You can also run a specific test by passing a filter: This will run any test with `foo` in its name. `cargo test` runs additional tests as well. For example, it will compile any -examples, you’ve included, and will also test the examples in your +examples you’ve included and will also test the examples in your documentation. Please see the [testing guide][testing] in the Rust documentation for more details. @@ -446,8 +446,8 @@ in the `hello_utils` folder (relative to the `Cargo.toml` it’s written in). And that’s it! The next `cargo build` will automatically build `hello_utils` and all of its own dependencies, and others can also start using the crate as well. -However, dependencies with only a path are not permitted on crates.io so if we -wanted to publish our `hello_world` crate we would need to publish a version of +However, dependencies with only a path are not permitted on crates.io. If we +wanted to publish our `hello_world` crate, we would need to publish a version of `hello_utils` to crates.io (or specify a git repository location) and specify it in the dependencies line: From 2c1147f7841a0f2fdb0e3d12b62f11ce07a5673f Mon Sep 17 00:00:00 2001 From: "Carol (Nichols || Goulding)" Date: Fri, 13 May 2016 12:25:37 -0400 Subject: [PATCH 02/34] 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. --- src/doc/guide.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/src/doc/guide.md b/src/doc/guide.md index 3b97fc10811..4aba5ad6bc3 100644 --- a/src/doc/guide.md +++ b/src/doc/guide.md @@ -83,11 +83,13 @@ $ ./target/debug/hello_world Hello, world! ``` -We can also use `cargo run` to compile and then run it, all in one step: +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): 
$ cargo run
      Fresh hello_world v0.1.0 (file:///path/to/project/hello_world)
+class="s1">   Compiling hello_world v0.1.0 (file:///path/to/project/hello_world)
    Running `target/debug/hello_world`
 Hello, world!
From c79216345fb6f5024540bbf0dd9468afd3d16ee4 Mon Sep 17 00:00:00 2001 From: "Carol (Nichols || Goulding)" Date: Fri, 13 May 2016 12:27:10 -0400 Subject: [PATCH 03/34] 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?!?! --- src/doc/guide.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/src/doc/guide.md b/src/doc/guide.md index 4aba5ad6bc3..912566d14fb 100644 --- a/src/doc/guide.md +++ b/src/doc/guide.md @@ -94,9 +94,6 @@ class="s1"> Compiling hello_world v0.1.0 (file:///path/to/project/hello class="s1"> Running `target/debug/hello_world` Hello, world! -To pass some arguments to your program, use `cargo run first_arg second_arg`. -If flags are being passed, use a “--” separator to tell Cargo which flags go where, like `cargo run -- --foo -b bar`. - 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. From c99ef3e7a46bcdd0353ce0e5743bb3272443b949 Mon Sep 17 00:00:00 2001 From: "Carol (Nichols || Goulding)" Date: Fri, 13 May 2016 12:31:57 -0400 Subject: [PATCH 04/34] Mention that binary location changes when using --release --- src/doc/guide.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/src/doc/guide.md b/src/doc/guide.md index 912566d14fb..a175dec8954 100644 --- a/src/doc/guide.md +++ b/src/doc/guide.md @@ -103,6 +103,9 @@ Once you’re ready for release, you can use `cargo build --release` to compile Compiling hello_world v0.1.0 (file:///path/to/project/hello_world) +`cargo build --release` puts the resulting binary in +`target/release/hello_world` instead of `target/debug`. + # Working on an existing Cargo project If you download an existing project that uses Cargo, it’s really easy From d36b183530a647fc9872120d6848385df9603622 Mon Sep 17 00:00:00 2001 From: "Carol (Nichols || Goulding)" Date: Fri, 13 May 2016 12:34:31 -0400 Subject: [PATCH 05/34] Clarify that the "somewhere" is github --- src/doc/guide.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/doc/guide.md b/src/doc/guide.md index a175dec8954..e66454fee41 100644 --- a/src/doc/guide.md +++ b/src/doc/guide.md @@ -111,7 +111,8 @@ class="s1"> Compiling hello_world v0.1.0 (file:///path/to/project/hello 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 `color-rs`: +First, get the project from somewhere. In this example, we’ll use `color-rs` +cloned from its repository on GitHub: ```sh $ git clone https://github.com/bjz/color-rs.git From a05a80b6f2cacc878d6e4b0acdbbcb47c8673cf6 Mon Sep 17 00:00:00 2001 From: "Carol (Nichols || Goulding)" Date: Fri, 13 May 2016 12:39:15 -0400 Subject: [PATCH 06/34] Correct reference to `foo` to `hello_world` Copypasta, or forgotten name change --- src/doc/guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/doc/guide.md b/src/doc/guide.md index e66454fee41..31dee492d83 100644 --- a/src/doc/guide.md +++ b/src/doc/guide.md @@ -186,7 +186,7 @@ dependencies, compile them all, and update the `Cargo.lock`: Compiling memchr v0.1.5 Compiling aho-corasick v0.3.0 Compiling regex v0.1.41 - Compiling foo v0.1.0 (file:///path/to/project/hello_world) + Compiling hello_world v0.1.0 (file:///path/to/project/hello_world) Run it: From d571d4baf696c9609d0fded7367c496897e12989 Mon Sep 17 00:00:00 2001 From: "Carol (Nichols || Goulding)" Date: Fri, 13 May 2016 14:00:46 -0400 Subject: [PATCH 07/34] Small rewording changes; mostly to clear up potential ambiguity --- src/doc/guide.md | 34 ++++++++++++++++++---------------- 1 file changed, 18 insertions(+), 16 deletions(-) diff --git a/src/doc/guide.md b/src/doc/guide.md index 31dee492d83..29a352a0ae6 100644 --- a/src/doc/guide.md +++ b/src/doc/guide.md @@ -119,7 +119,7 @@ $ git clone https://github.com/bjz/color-rs.git $ cd color-rs ``` -To build, just use `cargo build`: +To build, use `cargo build`: 
$ cargo build
    Compiling color v0.1.0 (file:///path/to/project/color-rs)
@@ -251,7 +251,7 @@ 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. `bjz` could update `color-rs` in the meantime, and my build would -include this commit while yours would not. Therefore, we would get different +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`: @@ -320,7 +320,8 @@ specification. Sometimes you may want to override one of Cargo’s dependencies. For example, let’s say you’re working on a project, `conduit-static`, which depends on the package `conduit`. You find a bug in `conduit`, and you want to write a -patch. Here’s what `conduit-static`’s `Cargo.toml` looks like: +patch and be able to test out your patch by using your version of `conduit` +in `conduit-static`. Here’s what `conduit-static`’s `Cargo.toml` looks like: ```toml [package] @@ -340,7 +341,7 @@ $ git clone https://github.com/conduit-rust/conduit.git ``` You’d like to have `conduit-static` use your local version of `conduit`, -rather than the one on GitHub, while you fix the bug. +rather than the one on crates.io, while you fix the bug. Cargo solves this problem by allowing you to have a local configuration that specifies an **override**. If Cargo finds this configuration when @@ -384,13 +385,14 @@ documentation](config.html). # Tests -Cargo can run your tests with the `cargo test` command. Cargo runs tests in two -places: in each of your `src` files and any tests in `tests/`. Tests -in your `src` files should be unit tests, and tests in `tests/` should be +Cargo can run your tests with the `cargo test` command. Cargo looks for tests +to run in two places: in each of your `src` files and any tests in `tests/`. +Tests in your `src` files should be unit tests, and tests in `tests/` should be integration-style tests. As such, you’ll need to import your crates into the files in `tests`. -To run your tests, just run `cargo test`: +Here's an example of running `cargo test` in our project, which currently has +no tests: 
$ cargo test
-Of course, if your project has tests, you’ll see more output with the -correct number of tests. +If our project had tests, we would see more output with the correct number of +tests. You can also run a specific test by passing a filter: @@ -415,7 +417,7 @@ You can also run a specific test by passing a filter: This will run any test with `foo` in its name. -`cargo test` runs additional tests as well. For example, it will compile any +`cargo test` runs additional checks as well. For example, it will compile any examples you’ve included and will also test the examples in your documentation. Please see the [testing guide][testing] in the Rust documentation for more details. @@ -437,7 +439,7 @@ $ cargo new hello_utils This will create a new folder `hello_utils` inside of which a `Cargo.toml` and `src` folder are ready to be configured. In order to tell Cargo about this, open -up `hello_world/Cargo.toml` and add these lines: +up `hello_world/Cargo.toml` and add `hello_utils` to your dependencies: ```toml [dependencies] @@ -449,10 +451,10 @@ in the `hello_utils` folder (relative to the `Cargo.toml` it’s written in). And that’s it! The next `cargo build` will automatically build `hello_utils` and all of its own dependencies, and others can also start using the crate as well. -However, dependencies with only a path are not permitted on crates.io. If we -wanted to publish our `hello_world` crate, we would need to publish a version of -`hello_utils` to crates.io (or specify a git repository location) and specify it -in the dependencies line: +However, crates that use dependencies specified with only a path are not +permitted on crates.io. If we wanted to publish our `hello_world` crate, we +would need to publish a version of `hello_utils` to crates.io (or specify a git +repository location) and specify its version in the dependencies line as well: ```toml [dependencies] From c4d4529030c66bd123686a667685439fd500d262 Mon Sep 17 00:00:00 2001 From: "Carol (Nichols || Goulding)" Date: Fri, 13 May 2016 14:10:42 -0400 Subject: [PATCH 08/34] 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. --- src/doc/guide.md | 19 +++++++++++-------- 1 file changed, 11 insertions(+), 8 deletions(-) diff --git a/src/doc/guide.md b/src/doc/guide.md index 29a352a0ae6..f714a3956bc 100644 --- a/src/doc/guide.md +++ b/src/doc/guide.md @@ -424,6 +424,17 @@ documentation for more details. [testing]: https://doc.rust-lang.org/book/testing.html +## Travis CI + +To test your project on Travis CI, here is a sample `.travis.yml` file: + +``` +language: rust +``` + +Please see the [Travis CI Rust documentation](https://docs.travis-ci.com/user/languages/rust/) +for more information. + # Path Dependencies Over time our `hello_world` project has grown significantly in size! It’s gotten @@ -460,11 +471,3 @@ repository location) and specify its version in the dependencies line as well: [dependencies] hello_utils = { path = "hello_utils", version = "0.1.0" } ``` - -## Travis-CI - -To test your project on Travis-CI, here is a sample `.travis.yml` file: - -``` -language: rust -``` From 1364b6275beb6d6647dafd3a7037cccbc2817a76 Mon Sep 17 00:00:00 2001 From: "Carol (Nichols || Goulding)" Date: Fri, 13 May 2016 14:16:39 -0400 Subject: [PATCH 09/34] 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. --- src/doc/crates-io.md | 34 ++-------------------- src/doc/guide.md | 68 ++++++++++++++++++++++++++------------------ 2 files changed, 42 insertions(+), 60 deletions(-) diff --git a/src/doc/crates-io.md b/src/doc/crates-io.md index 7281c31c541..6914938a954 100644 --- a/src/doc/crates-io.md +++ b/src/doc/crates-io.md @@ -1,35 +1,3 @@ -% Cargo and crates.io - -In addition to using dependencies from git repositories (as mentioned in -[the guide](guide.html)) Cargo can also publish to and download from the -[crates.io][crates-io] central repository. This site serves as a location to -discover and download packages, and `cargo` is configured to use it by default -to find requested packages. - -The guide will explain how crates can use crates.io through the `cargo` command -line tool. - -[crates-io]: https://crates.io/ - -# Using crates.io-based crates - -The method of specifying a dependency on a crate from crates.io is slightly -different than the method of specifying a dependency on a git repository. The -syntax for doing so is: - -```toml -[dependencies] -glob = "0.0.3" -``` - -With this format, adding new dependencies should just add a new line, you don’t -need to add `[dependencies]` for each dependency listed, for example: - -```toml -[dependencies] -glob = "0.0.3" -num = "0.0.4" -``` The string value for each key in this table is a [semver][semver] version requirement. @@ -311,3 +279,5 @@ explicitly whitelisted crates.io querying the org in question by pressing the “Grant Access” button next to its name: ![Authentication Access Control](images/auth-level-acl.png) + +[crates-io]: https://crates.io/ \ No newline at end of file diff --git a/src/doc/guide.md b/src/doc/guide.md index f714a3956bc..d3c79c5daf6 100644 --- a/src/doc/guide.md +++ b/src/doc/guide.md @@ -127,21 +127,35 @@ To build, use `cargo build`: This will fetch all of the dependencies and then build them, along with the project. -# Adding Dependencies +# Adding Dependencies from crates.io -To depend on a library, add it to your `Cargo.toml`. +[crates.io][crates-io] is the Rust community's central repository 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 -It’s quite simple to add a dependency. Simply add it to your `Cargo.toml` file: +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" ``` -Re-run `cargo build` to download the dependencies and build your source with the new dependencies. +The version string is a [semver][semver] version requirement. + +[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] @@ -150,27 +164,12 @@ version = "0.1.0" authors = ["Your Name "] [dependencies] +time = "0.1.12" regex = "0.1.41" ``` -You added the `regex` library, which provides support for regular expressions. - -Now, you can pull in that 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")); -} -``` - -The next time we build, Cargo will fetch this new dependency, all of its -dependencies, compile them all, and update the `Cargo.lock`: +Re-run `cargo build`, and Cargo will fetch the new dependencies and all of +their dependencies, compile them all, and update the `Cargo.lock`: 
$ cargo build
     Updating registry `https://github.com/rust-lang/crates.io-index`
@@ -188,18 +187,31 @@ dependencies, compile them all, and update the `Cargo.lock`:
    Compiling regex v0.1.41
    Compiling hello_world v0.1.0 (file:///path/to/project/hello_world)
-Run it: - -
$ cargo run
-     Running `target/hello_world`
-Did our date match? true
- 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: + +
$ cargo run
+     Running `target/hello_world`
+Did our date match? true
+ # Project Layout Cargo uses conventions for file placement to make it easy to dive into a new From 1c555a8586950d3a4f2ff7d92a1122569b417aca Mon Sep 17 00:00:00 2001 From: "Carol (Nichols || Goulding)" Date: Fri, 13 May 2016 15:13:36 -0400 Subject: [PATCH 10/34] 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. --- Makefile.in | 2 +- src/doc/crates-io.md | 69 ------- src/doc/guide.md | 109 +---------- src/doc/header.html | 1 + src/doc/manifest.md | 100 +--------- src/doc/specifying-dependencies.md | 304 +++++++++++++++++++++++++++++ 6 files changed, 313 insertions(+), 272 deletions(-) create mode 100644 src/doc/specifying-dependencies.md diff --git a/Makefile.in b/Makefile.in index 96e96036404..245353fed1d 100644 --- a/Makefile.in +++ b/Makefile.in @@ -136,7 +136,7 @@ clean: # === Documentation DOCS := index faq config guide manifest build-script pkgid-spec crates-io \ - environment-variables + environment-variables specifying-dependencies DOC_DIR := target/doc DOC_OPTS := --markdown-no-toc \ --markdown-css stylesheets/normalize.css \ diff --git a/src/doc/crates-io.md b/src/doc/crates-io.md index 6914938a954..58d4a446d2c 100644 --- a/src/doc/crates-io.md +++ b/src/doc/crates-io.md @@ -1,72 +1,3 @@ - -The string value for each key in this table is a [semver][semver] version -requirement. - -[semver]: https://github.com/steveklabnik/semver#requirements - -**Caret requirements** allow SemVer compatible updates to a specified version. - -`^1.2.3` is an example of a caret requirement. - -When considering “compatible” versions, `0.1` and `0.2` are not considered -compatible, but `1.0` and `1.1` are for example. If no operator is specified, -this is the default requirement (e.g. `1.3` is the same as `^1.3`). - -`0.0.x` is not considered compatible with any other version. Missing minor and -patch versions are desugared to `0` but allow flexibility for that value. - -```notrust -^1.2.3 := >=1.2.3 <2.0.0 -^0.2.3 := >=0.2.3 <0.3.0 -^0.0.3 := >=0.0.3 <0.0.4 -^0.0 := >=0.0.0 <0.1.0 -^0 := >=0.0.0 <1.0.0 -``` - -**Tilde requirements** specify a minimal version with some ability to update. - -`~1.2.3` is an example of a tilde requirement. - -```notrust -~1.2.3 := >=1.2.3 <1.3.0 -~1.2 := >=1.2.0 <1.3.0 -~1 := >=1.0.0 <2.0.0 -``` - -**Wildcard requirements** allow for any version where the wildcard is positioned. - -`*`, `1.*` and `1.2.*` are examples of wildcard requirements. - -```notrust -* := >=0.0.0 -1.* := >=1.0.0 <2.0.0 -1.2.* := >=1.2.0 <1.3.0 -``` - -**Inequality requirements** allow manually specifying a version range or an -exact version to depend on. - -Here are some examples of inequality requirements: - -```notrust ->= 1.2.0 -> 1 -< 2 -= 1.2.3 -``` - -Multiple version requirements can also be separated with a comma, e.g. `>= 1.2, -< 1.5`. - -# Pre-1.0 versions - -While SemVer says that there is no compatibility before 1.0.0, many programmers -treat a `0.x.y` release in the same way as a `1.x.y` release: that is, `y` is -incremented for bugfixes, and `x` is incremented for new features. - -As such, Cargo considers a `0.x.y` and `0.x.z` version, where `z > y`, to be -compatible. - # Publishing crates Ok, now that we’ve got a crate which is using dependencies from crates.io, diff --git a/src/doc/guide.md b/src/doc/guide.md index d3c79c5daf6..96252483be4 100644 --- a/src/doc/guide.md +++ b/src/doc/guide.md @@ -148,7 +148,9 @@ adds a dependency of the `time` crate: time = "0.1.12" ``` -The version string is a [semver][semver] version requirement. +The version string is a [semver][semver] version requirement. The [specifying +dependencies](specifying-dependencies.html) docs have more information about +the options you have here. [semver]: https://github.com/steveklabnik/semver#requirements @@ -327,74 +329,6 @@ that the argument to `cargo update` is actually a [Package ID Specification](pkgid-spec.html) and `color` is just a short specification. -# Overriding Dependencies - -Sometimes you may want to override one of Cargo’s dependencies. For example, -let’s say you’re working on a project, `conduit-static`, which depends on -the package `conduit`. You find a bug in `conduit`, and you want to write a -patch and be able to test out your patch by using your version of `conduit` -in `conduit-static`. Here’s what `conduit-static`’s `Cargo.toml` looks like: - -```toml -[package] -name = "conduit-static" -version = "0.1.0" -authors = ["Yehuda Katz "] - -[dependencies] -conduit = "0.7" -``` - -You check out a local copy of `conduit`, let’s say in your `~/src` directory: - -```shell -$ cd ~/src -$ git clone https://github.com/conduit-rust/conduit.git -``` - -You’d like to have `conduit-static` use your local version of `conduit`, -rather than the one on crates.io, while you fix the bug. - -Cargo solves this problem by allowing you to have a local configuration -that specifies an **override**. If Cargo finds this configuration when -building your package, it will use the override on your local machine -instead of the source specified in your `Cargo.toml`. - -Cargo looks for a directory named `.cargo` up the directory hierarchy of -your project. If your project is in `/path/to/project/conduit-static`, -it will search for a `.cargo` in: - -* `/path/to/project/conduit-static` -* `/path/to/project` -* `/path/to` -* `/path` -* `/` - -This allows you to specify your overrides in a parent directory that -includes commonly used packages that you work on locally and share them -with all projects. - -To specify overrides, create a `.cargo/config` file in some ancestor of -your project’s directory (common places to put it is in the root of -your code directory or in your home directory). - -Inside that file, put this: - -```toml -paths = ["/path/to/project/conduit"] -``` - -This array should be filled with directories that contain a `Cargo.toml`. In -this instance, we’re just adding `conduit`, so it will be the only one that’s -overridden. This path must be an absolute path. - -Note: using a local configuration to override paths will only work for crates -that have been published to crates.io. You cannot use this feature to tell Cargo -how to find local unpublished crates. - -More information about local configuration can be found in the [configuration -documentation](config.html). - # Tests Cargo can run your tests with the `cargo test` command. Cargo looks for tests @@ -446,40 +380,3 @@ language: rust Please see the [Travis CI Rust documentation](https://docs.travis-ci.com/user/languages/rust/) for more information. - -# Path Dependencies - -Over time our `hello_world` project has grown significantly in size! It’s gotten -to the point that we probably want to split out a separate crate for others to -use. To do this Cargo supports **path dependencies** which are typically -sub-crates that live within one repository. Let’s start off by making a new -crate inside of our `hello_world` project: - -```shell -# inside of hello_world/ -$ cargo new hello_utils -``` - -This will create a new folder `hello_utils` inside of which a `Cargo.toml` and -`src` folder are ready to be configured. In order to tell Cargo about this, open -up `hello_world/Cargo.toml` and add `hello_utils` to your dependencies: - -```toml -[dependencies] -hello_utils = { path = "hello_utils" } -``` - -This tells Cargo that we depend on a crate called `hello_utils` which is found -in the `hello_utils` folder (relative to the `Cargo.toml` it’s written in). - -And that’s it! The next `cargo build` will automatically build `hello_utils` and -all of its own dependencies, and others can also start using the crate as well. -However, crates that use dependencies specified with only a path are not -permitted on crates.io. If we wanted to publish our `hello_world` crate, we -would need to publish a version of `hello_utils` to crates.io (or specify a git -repository location) and specify its version in the dependencies line as well: - -```toml -[dependencies] -hello_utils = { path = "hello_utils", version = "0.1.0" } -``` diff --git a/src/doc/header.html b/src/doc/header.html index d42cdba7b20..17abf7a89f0 100644 --- a/src/doc/header.html +++ b/src/doc/header.html @@ -30,6 +30,7 @@

CARGO