From 1533a0493a499e9cf0faa7f09b85b8b25d5041f6 Mon Sep 17 00:00:00 2001 From: Alex Crichton Date: Tue, 13 Nov 2018 11:37:49 -0800 Subject: [PATCH] Stabilize the `rename-dependency` feature This commit stabilizes Cargo's `rename-dependency` feature which allows renaming packages in `Cargo.toml`, enabling importing multiple versions of a single crate or simply avoiding a `use foo as bar` in `src/lib.rs`. Closes #5653 --- src/cargo/core/features.rs | 2 +- .../src/reference/specifying-dependencies.md | 61 ++++++++++- src/doc/src/reference/unstable.md | 55 ---------- tests/testsuite/rename_deps.rs | 100 ++---------------- 4 files changed, 67 insertions(+), 151 deletions(-) diff --git a/src/cargo/core/features.rs b/src/cargo/core/features.rs index bdf369bb3dc..7f20a490096 100644 --- a/src/cargo/core/features.rs +++ b/src/cargo/core/features.rs @@ -177,7 +177,7 @@ features! { [stable] edition: bool, // Renaming a package in the manifest via the `package` key - [unstable] rename_dependency: bool, + [stable] rename_dependency: bool, // Whether a lock file is published with this crate [unstable] publish_lockfile: bool, diff --git a/src/doc/src/reference/specifying-dependencies.md b/src/doc/src/reference/specifying-dependencies.md index 4bc4dedac4c..512862e5e9b 100644 --- a/src/doc/src/reference/specifying-dependencies.md +++ b/src/doc/src/reference/specifying-dependencies.md @@ -113,7 +113,7 @@ rand = { git = "https://github.com/rust-lang-nursery/rand" } Cargo will fetch the `git` repository at this location then look for a `Cargo.toml` for the requested crate anywhere inside the `git` repository -(not necessarily at the root - for example, specifying a member crate name +(not necessarily at the root - for example, specifying a member crate name of a workspace and setting `git` to the repository containing the workspace). Since we haven’t specified any other information, Cargo assumes that @@ -535,3 +535,62 @@ features = ["secure-password", "civet"] More information about features can be found in the [manifest documentation](reference/manifest.html#the-features-section). + +### Renaming dependencies in `Cargo.toml` + +When writing a `[dependencies]` section in `Cargo.toml` the key you write for a +dependency typically matches up to the name of the crate you import from in the +code. For some projects, though, you may wish to reference the crate with a +different name in the code regardless of how it's published on crates.io. For +example you may wish to: + +* Avoid the need to `use foo as bar` in Rust source. +* Depend on multiple versions of a crate. +* Depend on crates with the same name from different registries. + +To support this Cargo supports a `package` key in the `[dependencies]` section +of which package should be depended on: + +```toml +[package] +name = "mypackage" +version = "0.0.1" + +[dependencies] +foo = "0.1" +bar = { git = "https://github.com/example/project", package = "foo" } +baz = { version = "0.1", registry = "custom", package = "foo" } +``` + +In this example, three crates are now available in your Rust code: + +```rust +extern crate foo; // crates.io +extern crate bar; // git repository +extern crate baz; // registry `custom` +``` + +All three of these crates have the package name of `foo` in their own +`Cargo.toml`, so we're explicitly using the `package` key to inform Cargo that +we want the `foo` package even though we're calling it something else locally. +The `package` key, if not specified, defaults to the name of the dependency +being requested. + +Note that if you have an optional dependency like: + +```toml +[dependencies] +foo = { version = "0.1", package = 'bar', optional = true } +``` + +you're depending on the crate `bar` from crates.io, but your crate has a `foo` +feature instead of a `bar` feature. That is, names of features take after the +name of the dependency, not the package name, when renamed. + +Enabling transitive dependencies works similarly, for example we could add the +following to the above manifest: + +```toml +[features] +log-debug = ['foo/log-debug'] # using 'bar/log-debug' would be an error! +``` diff --git a/src/doc/src/reference/unstable.md b/src/doc/src/reference/unstable.md index d273a91b5ba..aeb52afff5e 100644 --- a/src/doc/src/reference/unstable.md +++ b/src/doc/src/reference/unstable.md @@ -63,61 +63,6 @@ publish = ["my-registry"] ``` -### rename-dependency -* Original Issue: [#1311](https://github.com/rust-lang/cargo/issues/1311) -* PR: [#4953](https://github.com/rust-lang/cargo/pull/4953) -* Tracking Issue: [#5653](https://github.com/rust-lang/cargo/issues/5653) - -The rename-dependency feature allows you to import a dependency -with a different name from the source. This can be useful in a few scenarios: - -* Depending on crates with the same name from different registries. -* Depending on multiple versions of a crate. -* Avoid needing `extern crate foo as bar` in Rust source. - -Just include the `package` key to specify the actual name of the dependency. -You must include `cargo-features` at the top of your `Cargo.toml`. - -```toml -cargo-features = ["rename-dependency"] - -[package] -name = "mypackage" -version = "0.0.1" - -[dependencies] -foo = "0.1" -bar = { version = "0.1", registry = "custom", package = "foo" } -baz = { git = "https://github.com/example/project", package = "foo" } -``` - -In this example, three crates are now available in your Rust code: - -```rust -extern crate foo; // crates.io -extern crate bar; // registry `custom` -extern crate baz; // git repository -``` - -Note that if you have an optional dependency like: - -```toml -[dependencies] -foo = { version = "0.1", package = 'bar', optional = true } -``` - -you're depending on the crate `bar` from crates.io, but your crate has a `foo` -feature instead of a `bar` feature. That is, names of features take after the -name of the dependency, not the package name, when renamed. - -Enabling transitive dependencies works similarly, for example we could add the -following to the above manifest: - -```toml -[features] -log-debug = ['foo/log-debug'] # using 'bar/log-debug' would be an error! -``` - ### publish-lockfile * Original Issue: [#2263](https://github.com/rust-lang/cargo/issues/2263) * PR: [#5093](https://github.com/rust-lang/cargo/pull/5093) diff --git a/tests/testsuite/rename_deps.rs b/tests/testsuite/rename_deps.rs index 209987b89ca..c8ee06dbcaa 100644 --- a/tests/testsuite/rename_deps.rs +++ b/tests/testsuite/rename_deps.rs @@ -3,68 +3,6 @@ use support::paths; use support::registry::Package; use support::{basic_manifest, project}; -#[test] -fn gated() { - let p = project() - .file( - "Cargo.toml", - r#" - [project] - name = "foo" - version = "0.0.1" - authors = [] - - [dependencies] - bar = { package = "foo", version = "0.1" } - "#, - ).file("src/lib.rs", "") - .build(); - - p.cargo("build") - .masquerade_as_nightly_cargo() - .with_status(101) - .with_stderr( - "\ -error: failed to parse manifest at `[..]` - -Caused by: - feature `rename-dependency` is required - -consider adding `cargo-features = [\"rename-dependency\"]` to the manifest -", - ).run(); - - let p = project() - .at("bar") - .file( - "Cargo.toml", - r#" - [project] - name = "foo" - version = "0.0.1" - authors = [] - - [dependencies] - bar = { version = "0.1", package = "baz" } - "#, - ).file("src/lib.rs", "") - .build(); - - p.cargo("build") - .masquerade_as_nightly_cargo() - .with_status(101) - .with_stderr( - "\ -error: failed to parse manifest at `[..]` - -Caused by: - feature `rename-dependency` is required - -consider adding `cargo-features = [\"rename-dependency\"]` to the manifest -", - ).run(); -} - #[test] fn rename_dependency() { Package::new("bar", "0.1.0").publish(); @@ -74,8 +12,6 @@ fn rename_dependency() { .file( "Cargo.toml", r#" - cargo-features = ["rename-dependency"] - [project] name = "foo" version = "0.0.1" @@ -88,7 +24,7 @@ fn rename_dependency() { ).file("src/lib.rs", "extern crate bar; extern crate baz;") .build(); - p.cargo("build").masquerade_as_nightly_cargo().run(); + p.cargo("build").run(); } #[test] @@ -97,8 +33,6 @@ fn rename_with_different_names() { .file( "Cargo.toml", r#" - cargo-features = ["rename-dependency"] - [project] name = "foo" version = "0.0.1" @@ -122,7 +56,7 @@ fn rename_with_different_names() { ).file("bar/src/lib.rs", "") .build(); - p.cargo("build").masquerade_as_nightly_cargo().run(); + p.cargo("build").run(); } #[test] @@ -148,8 +82,7 @@ fn lots_of_names() { "Cargo.toml", &format!( r#" - cargo-features = ["alternative-registries", "rename-dependency"] - + cargo-features = ["alternative-registries"] [package] name = "test" version = "0.1.0" @@ -196,8 +129,6 @@ fn rename_and_patch() { .file( "Cargo.toml", r#" - cargo-features = ["rename-dependency"] - [package] name = "test" version = "0.1.0" @@ -216,7 +147,7 @@ fn rename_and_patch() { .file("foo/src/lib.rs", "pub fn foo() {}") .build(); - p.cargo("build -v").masquerade_as_nightly_cargo().run(); + p.cargo("build -v").run(); } #[test] @@ -227,8 +158,6 @@ fn rename_twice() { .file( "Cargo.toml", r#" - cargo-features = ["rename-dependency"] - [package] name = "test" version = "0.1.0" @@ -243,7 +172,6 @@ fn rename_twice() { .build(); p.cargo("build -v") - .masquerade_as_nightly_cargo() .with_status(101) .with_stderr( "\ @@ -264,8 +192,6 @@ fn rename_affects_fingerprint() { .file( "Cargo.toml", r#" - cargo-features = ["rename-dependency"] - [package] name = "test" version = "0.1.0" @@ -277,13 +203,11 @@ fn rename_affects_fingerprint() { ).file("src/lib.rs", "extern crate foo;") .build(); - p.cargo("build -v").masquerade_as_nightly_cargo().run(); + p.cargo("build -v").run(); p.change_file( "Cargo.toml", r#" - cargo-features = ["rename-dependency"] - [package] name = "test" version = "0.1.0" @@ -295,7 +219,6 @@ fn rename_affects_fingerprint() { ); p.cargo("build -v") - .masquerade_as_nightly_cargo() .with_status(101) .run(); } @@ -309,8 +232,6 @@ fn can_run_doc_tests() { .file( "Cargo.toml", r#" - cargo-features = ["rename-dependency"] - [project] name = "foo" version = "0.0.1" @@ -328,7 +249,6 @@ fn can_run_doc_tests() { ).build(); foo.cargo("test -v") - .masquerade_as_nightly_cargo() .with_stderr_contains( "\ [DOCTEST] foo @@ -363,8 +283,6 @@ fn features_still_work() { .file( "a/Cargo.toml", r#" - cargo-features = ["rename-dependency"] - [package] name = "p1" version = "0.1.0" @@ -377,8 +295,6 @@ fn features_still_work() { .file( "b/Cargo.toml", r#" - cargo-features = ["rename-dependency"] - [package] name = "p2" version = "0.1.0" @@ -393,7 +309,7 @@ fn features_still_work() { ).file("b/src/lib.rs", "extern crate b;") .build(); - p.cargo("build -v").masquerade_as_nightly_cargo().run(); + p.cargo("build -v").run(); } #[test] @@ -405,7 +321,6 @@ fn features_not_working() { .file( "Cargo.toml", r#" - cargo-features = ["rename-dependency"] [package] name = "test" version = "0.1.0" @@ -422,7 +337,6 @@ fn features_not_working() { .build(); p.cargo("build -v") - .masquerade_as_nightly_cargo() .with_status(101) .with_stderr( "\ @@ -440,7 +354,6 @@ fn rename_with_dash() { .file( "Cargo.toml", r#" - cargo-features = ["rename-dependency"] [package] name = "qwerty" version = "0.1.0" @@ -455,6 +368,5 @@ fn rename_with_dash() { .build(); p.cargo("build") - .masquerade_as_nightly_cargo() .run(); }