Skip to content

Commit

Permalink
Auto merge of #6311 - alexcrichton:stabilize-renames, r=the-whole-team
Browse files Browse the repository at this point in the history 
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
  • Loading branch information
@bors
bors committed Nov 15, 2018
2 parents ac0bb47 + 1533a04 commit b3d0b2e
Show file tree
Hide file tree
Showing 4 changed files with 67 additions and 151 deletions.
2 changes: 1 addition & 1 deletion src/cargo/core/features.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down
61 changes: 60 additions & 1 deletion src/doc/src/reference/specifying-dependencies.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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!
```
55 changes: 0 additions & 55 deletions src/doc/src/reference/unstable.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
100 changes: 6 additions & 94 deletions tests/testsuite/rename_deps.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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();
Expand All @@ -74,8 +12,6 @@ fn rename_dependency() {
.file(
"Cargo.toml",
r#"
cargo-features = ["rename-dependency"]
[project]
name = "foo"
version = "0.0.1"
Expand All @@ -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]
Expand All @@ -97,8 +33,6 @@ fn rename_with_different_names() {
.file(
"Cargo.toml",
r#"
cargo-features = ["rename-dependency"]
[project]
name = "foo"
version = "0.0.1"
Expand All @@ -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]
Expand All @@ -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"
Expand Down Expand Up @@ -196,8 +129,6 @@ fn rename_and_patch() {
.file(
"Cargo.toml",
r#"
cargo-features = ["rename-dependency"]
[package]
name = "test"
version = "0.1.0"
Expand All @@ -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]
Expand All @@ -227,8 +158,6 @@ fn rename_twice() {
.file(
"Cargo.toml",
r#"
cargo-features = ["rename-dependency"]
[package]
name = "test"
version = "0.1.0"
Expand All @@ -243,7 +172,6 @@ fn rename_twice() {
.build();

p.cargo("build -v")
.masquerade_as_nightly_cargo()
.with_status(101)
.with_stderr(
"\
Expand All @@ -264,8 +192,6 @@ fn rename_affects_fingerprint() {
.file(
"Cargo.toml",
r#"
cargo-features = ["rename-dependency"]
[package]
name = "test"
version = "0.1.0"
Expand All @@ -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"
Expand All @@ -295,7 +219,6 @@ fn rename_affects_fingerprint() {
);

p.cargo("build -v")
.masquerade_as_nightly_cargo()
.with_status(101)
.run();
}
Expand All @@ -309,8 +232,6 @@ fn can_run_doc_tests() {
.file(
"Cargo.toml",
r#"
cargo-features = ["rename-dependency"]
[project]
name = "foo"
version = "0.0.1"
Expand All @@ -328,7 +249,6 @@ fn can_run_doc_tests() {
).build();

foo.cargo("test -v")
.masquerade_as_nightly_cargo()
.with_stderr_contains(
"\
[DOCTEST] foo
Expand Down Expand Up @@ -363,8 +283,6 @@ fn features_still_work() {
.file(
"a/Cargo.toml",
r#"
cargo-features = ["rename-dependency"]
[package]
name = "p1"
version = "0.1.0"
Expand All @@ -377,8 +295,6 @@ fn features_still_work() {
.file(
"b/Cargo.toml",
r#"
cargo-features = ["rename-dependency"]
[package]
name = "p2"
version = "0.1.0"
Expand All @@ -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]
Expand All @@ -405,7 +321,6 @@ fn features_not_working() {
.file(
"Cargo.toml",
r#"
cargo-features = ["rename-dependency"]
[package]
name = "test"
version = "0.1.0"
Expand All @@ -422,7 +337,6 @@ fn features_not_working() {
.build();

p.cargo("build -v")
.masquerade_as_nightly_cargo()
.with_status(101)
.with_stderr(
"\
Expand All @@ -440,7 +354,6 @@ fn rename_with_dash() {
.file(
"Cargo.toml",
r#"
cargo-features = ["rename-dependency"]
[package]
name = "qwerty"
version = "0.1.0"
Expand All @@ -455,6 +368,5 @@ fn rename_with_dash() {
.build();

p.cargo("build")
.masquerade_as_nightly_cargo()
.run();
}

0 comments on commit b3d0b2e

Please sign in to comment.