Skip to content

Commit c148ae6

Browse files
committed
New RFC: cargo run to accept pkgid of dependencies
1 parent e0d0dfb commit c148ae6

File tree

1 file changed

+117
-0
lines changed

1 file changed

+117
-0
lines changed

text/0000-cargo-run-deps.md

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
- Feature Name: `cargo-run-deps`
2+
- Start Date: 2021-08-24
3+
- RFC PR: [rust-lang/rfcs#3168](https://github.com/rust-lang/rfcs/pull/3168)
4+
- Rust Issue: [rust-lang/rust#0000](https://github.com/rust-lang/rust/issues/0000)
5+
6+
# Summary
7+
[summary]: #summary
8+
9+
In addition to binaries from workspace members, teach `cargo run` to execute binaries from dependent packages.
10+
11+
# Motivation
12+
[motivation]: #motivation
13+
14+
Right now, `cargo` lacks a way to run binaries that belong to packages which are not members of the current workspace.
15+
16+
This is desirable for multiple reasons:
17+
18+
- make binaries from dependencies available to external scripts, especially Continuous Integration (CI) scripts.
19+
- ensure a specific version of the binary as specified by the manifest is run, which might differ from the version installed globally.
20+
- avoid clashes in the global installation directory.
21+
- make binaries callable from `build.rs` through `cargo run` as a shim.
22+
- make the build process self-contained, instead of requiring the user a manual installation step.
23+
- build binary dependencies lazily, only when they are needed, thus avoiding inflating build times unless necessary.
24+
25+
Several issues related to this request have been opened against `cargo`:
26+
27+
- [rust-lang/cargo/issues/2267](https://github.com/rust-lang/cargo/issues/2267): Make commands in dev-dependencies available to run
28+
- [rust-lang/cargo/issues/872](https://github.com/rust-lang/cargo/issues/872): Cargo needs a way to run an executable out of a build-dependency
29+
30+
# Guide-level explanation
31+
[guide-level-explanation]: #guide-level-explanation
32+
33+
Cargo allows you to depend on other packages as part of its manifest. Some of them might define their own runnable binary targets, but a dependency in a manifest implicitly imples building it only as a library.
34+
35+
For instance, you can depend on `mdbook` when building your project as follows:
36+
37+
```toml
38+
[build-dependencies]
39+
mdbook = { version = "0.4.12" }
40+
```
41+
42+
This will build the `mdbook` crate's library, but not the corresponding binary.
43+
44+
If you wanted to invoke `mdbook` inside your `build.rs` script, you could use `cargo run --package mdbook` as a wrapper.
45+
46+
```rust
47+
// build.rs
48+
use std::{env, process::Command};
49+
50+
fn main() {
51+
let cargo_path = env::var("CARGO").unwrap();
52+
let mut mdbook = Command::new(cargo_path).args(&[
53+
"run",
54+
"--package",
55+
"mdbook",
56+
"--",
57+
"--version",
58+
]);
59+
60+
assert!(mdbook.status().expect("mdbook v0.4.12").success());
61+
}
62+
```
63+
64+
This will take care of (re)building the `mdbook` binary if needed, at the version specified in the manifest, and then invoke it with the passed parameters. As usual, in case multiple binaries are available for one package, the `--bin` option can be passed to select the right one.
65+
66+
# Reference-level explanation
67+
[reference-level-explanation]: #reference-level-explanation
68+
69+
The scope of this RFC is to alter the behavior of `cargo run` so that in addition to binaries part of the workspace, it will allow also to run binaries from dependencies which are listed inside the locked manifest for the workspace.
70+
71+
In order to do that, we would relax the constraints of `cargo run` to accept a package id describing any package part of `Cargo.lock` (by virtue of the `--package=<pkgid>` command line parameter). The required steps would be:
72+
73+
- if the specified `pkgid` is not related to a workspace member, use the resolver against the locked manifest to determine acceptable versions of dependencies. The resulting set should have a size of one, or we fail.
74+
- from the resulting package, select either the target specified by the `--bin` option, or the default binary target if none is specified. If we get no match, we fail.
75+
- trigger compilation of the corresponding target with the host system as the target system. This is important when cross-compiling.
76+
- execute the resulting compiled binary, passing the trailing arguments of `cargo run` to it.
77+
78+
79+
# Drawbacks
80+
[drawbacks]: #drawbacks
81+
82+
[rust-lang/rfcs#3028](https://github.com/rust-lang/rfcs/pull/3028) has an overlap with this feature. They are not mutually exclusive and can be implemented mostly independently, but at some point we expect the implementation to require a rework to take in account for the first one to be merged, whichever may come first.
83+
84+
# Rationale and alternatives
85+
[rationale-and-alternatives]: #rationale-and-alternatives
86+
87+
Right now, users are required to manually install dependencies to either a global location, or to a dedicated location but then to also manually adjust their `PATH` variable to compensate. In case a global location is used, multiple versions of binaries cannot be parallel-installable.
88+
89+
This RFC keeps binary dependencies built within the workspace's `target/` directory, avoiding them spilling out of the projects they are meant for, when they are not needed globally.
90+
91+
It also ensures reproducibility of builds, since it avoids a different, potentially incompatible, version of a binary to be picked up by mistake. This is particularly relevant for some tools such as e.g. `mdbook-bib`, which complain if run with a different library version of `mdbook` they were built against as part of the manifest spec.
92+
93+
The design mimicks several of other package managers of related programming languages. See the [prior art](#prior-art) section. This allows newcomers to get a quick and intuitive way to run binaries.
94+
95+
# Prior art
96+
[prior-art]: #prior-art
97+
98+
Many other package managers from other languages provide the same functionality:
99+
100+
- Node.js provides the `npx` binary,
101+
- PHP's Composer has `php composer exec`.
102+
- In Python, several alternatives exist, such as `pipenv run`.
103+
- Ruby's Bundler allows to invoke binaries via `bundle exec`
104+
105+
[rust-lang/rfcs#3028](https://github.com/rust-lang/rfcs/pull/3028) is a more extensive, alternative proposal that also allows embeddding the resulting binary into the crate. This RFC provides a simpler alternative; additionally, it provides a way to run the built binaries from the command line, which is something not explicitly covered by RFC 3028. This is especially useful with CI integration, to bind the same version of tools as used on the developer's machine. It also lazily allows a selective build of some tools, such as `mdbook`, for those CI builds that do not require a full build.
106+
107+
[rust-lang/cargo/pull/9833](https://github.com/rust-lang/cargo/pull/9833) provides an initial implementation of this RFC, showing that it is likely a localized change; it might make it faster to merge than RFC 3028.
108+
109+
# Unresolved questions
110+
[unresolved-questions]: #unresolved-questions
111+
112+
- Decide whether binaries from transitive dependencies should also be allowed to be run, or if it should be disallowed.
113+
114+
# Future possibilities
115+
[future-possibilities]: #future-possibilities
116+
117+
By virtue of accepting a fully qualified package id, `cargo run` can be extended to allow running any specific binary crate, regardless of whether it is part of the locked manifest. This would help to run several different versions of a binary in parallel without installing them first, which results in the previous binary to be overwritten. It might be particularly desirable e.g. for regression testing of tools such as `mdbook`, `tarpaulin`, `rusty-hook`, etc.

0 commit comments

Comments
 (0)