Stabilize cargo script by epage · Pull Request #16569 · rust-lang/cargo

epage · 2026-01-30T14:32:38Z

RFC: https://rust-lang.github.io/rfcs/3502-cargo-script.html
Tracking issue: #12207
Frontmatter stabilization: rust-lang/rust#148051

This stabilizes an MVP of Cargo script

Cargo scripts are Rust source files without an extension or with a .rs extension
They may have a frontmatter block with manifest content
Changes from Cargo.toml
- package.name is optional, defaults to the file stem
- package.edition defaults to current edition, not 2015 edition, with a warning
- package.build, package.links, package.default-run, package.workspace, package.auto-* are disallowed
- workspace, build-dependencies, and any build-target tables are disallowed
- Workspace auto-discovery does not run
package.name defaulting logic
- strips leading numbers
  - If nothing left after this, calls it package
- replaces non-UnicodeXID characters with - or _
- commonly reserved names are allowed:
  - windows names, like con
  - sysroot names, like test
  - keywords, like self
- disallowed names on a short-term basis:
  - build-dir directories like deps
cargo foo precedence:
1. built-in command
2. script if there is a .rs extension or a path component is present (e.g. ./foo )
3. aliases
4. plugins
Command support:
- cargo install errors on publishing a script
- cargo package errors on publishing a script
- cargo publish errors on publishing a script
Script metadata
- arg0 is set on a best-effort basis to the script's path
- CARGO_MANIFEST_PATH was previously stabilized in addition to the existing CARGO_MANIFEST_DIR
cargo foo.rs loads config relative to foo
- Like cargo install --path bar/ and unlike the rest of the Cargo commands
- Regular cargo run --manifest-path foo.rs loads from current dir
- See also fix(script): Load config relative to the script #16620

Pseudo-config defaults

[build]
build-dir = "{cargo-cache-home}/build/{workspace-path-hash}"
target-dir = "{build-dir}/target"
[resolver]
lockfile-path = "{build-dir}/{workspace-path-hash}/Cargo.lock"

Whats missing:

rustfmt styling frontmatter according to the Style Guide
rust-analyzer handling manifest in frontmatter
playground support

Known issues:

cargo remove prints the "unset edition" warning twice
Some users are asking for reduced noise (Cargo script should only output messages from the script for no-change builds #16388)
Shebang stripping isn't as complete as rustc in that it only considers whitespace between #! and [] and not comments
Users write throwaway scripts or move their scripts and they then leak the entire build-dir. Garbage collect whole target/ #13136 will resolve this.

Risks

~~If people share their build-dir across projects, then multiple scripts will point to the same Cargo.lock, fighting over what is locked in it~~ (fix(script): Make the lockfile script-specific independent of build-dir #16619)
~~Not allowing local config for scripts could become a problem as we get into workspace support as people would expect their repo's config to be respected when it won't be~~ (fix(script): Load config relative to the script #16620)
Changing package name rules impacts programmatic output
Precedence rules for cargo foo
- In particularly, requiring an extension or path element should be safe, especially for most uses of shebang but you can intentionally contrive a shebang and PATH that makes this not work

Future possibilities

Membership in workspaces including opt-in discovery (Less invasive way of controlling workspace membership #16563)
- Check workspace member existence as dir. #8511 makes this more difficult
Publish support
Lib support
- main question is how to denote it is a lib
Build script delegation support (Tracking issue for RFC 2196, "metabuild: semantic build scripts for Cargo" #14903)
Use as artifact dependencies
GC build-dirs (Garbage collect whole target/ #13136)
Reduce special casing in manifests with Make package.name optional #12689
cargo Cargo.toml support

rustbot · 2026-01-30T14:32:43Z

r? @weihanglo

rustbot has assigned @weihanglo.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

epage · 2026-01-30T15:25:05Z

+    match manifest_path.is_file() {
+        true => {}


Cleaned up in the next commit

epage · 2026-01-30T15:25:33Z

+    // TODO: remove once frontmatter hits nightly
    if unit.pkg.manifest().is_embedded() {


Blocked on rust-lang/rust#148051 hitting nightly

epage · 2026-01-30T15:25:39Z

+    // TODO: remove once frontmatter hits nightly
    if unit.pkg.manifest().is_embedded() {


Blocked on rust-lang/rust#148051 hitting nightly

epage · 2026-01-30T15:39:45Z

@rfcbot fcp merge T-cargo

For me, my biggest concerns are the first two Risks listed.

rust-rfcbot · 2026-01-30T15:39:46Z

Team member @epage has proposed to merge this. The next step is review by the rest of the tagged team members:

Concerns:

edition-behavior (Stabilize cargo script #16569 (comment))
security (Stabilize cargo script #16569 (comment))

Once a majority of reviewers approve (and at most 2 approvals are outstanding), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up!

See this document for info about what commands tagged team members can give me.

weihanglo

Should we inform rustfmt team that we're going to stabilize this and leave frontmatter style issue unresolved? I remembered that let-else has caused confusions and frustrations when we stabilized it in the language syntax side but rustfmt didn't format it: rust-lang/rustfmt#4914.

At least the rustfmt team should be aware of the potential incoming volume of issues regarding this.

View changes since this review

weihanglo · 2026-01-31T11:46:57Z

 in the [TOML] format. It contains metadata that is needed to compile the package. Checkout
 the `cargo locate-project` section for more detail on how cargo finds the manifest file.

+The content of the manifest can also be embedded inside of the frontmatter inside of a Rust source file:


Not a blocker but not satisfied with the current stable doc. I would love to see a dedicated section for Cargo scripts with some examples, and all other mentions of "script" to link back to that section. Currently it is a bit not obvious when it is mentioned.

The original unstable docs has some good stuff in it but maybe it depends on many stuff we want to commit as "stable"

(Or it was migrated to elsewhere? The diff is too large that I could have missed it)

Was unsure how to handle it. A guide? If so, where does it fit in. A reference? Does it get its own page or a section on manifests?

Or a reference-like doc in src/doc/man/cargo.md, and we have another standalone guide? In manifest is not too bad but script is more than manifest.

weihanglo · 2026-01-31T12:08:32Z

rustfmt styling frontmatter according to the Style Guide

rust-analyzer handling manifest in frontmatter

playground support

All these teams actually

weihanglo · 2026-01-31T12:16:09Z

Pseudo-config defaults

This is worth calling out in user doc that whether the target directory of script is considered implementation details.

epage · 2026-01-31T14:08:29Z

Should we inform rustfmt team that we're going to stabilize this and leave frontmatter style issue unresolved? I remembered that let-else has caused confusions and frustrations when we stabilized it in the language syntax side but rustfmt didn't format it: rust-lang/rustfmt#4914.

At least the rustfmt team should be aware of the potential incoming volume of issues regarding this.

View changes since this review

This was handled as part of the Frontmatter stabilization.

weihanglo · 2026-01-31T15:16:37Z

 in the [TOML] format. It contains metadata that is needed to compile the package. Checkout
 the `cargo locate-project` section for more detail on how cargo finds the manifest file.

+The content of the manifest can also be embedded inside of the frontmatter inside of a Rust source file:


Or a reference-like doc in src/doc/man/cargo.md, and we have another standalone guide? In manifest is not too bad but script is more than manifest.

rust-rfcbot · 2026-02-20T16:11:17Z

The final comment period, with a disposition to merge, as per the review above, is now complete.

As the automated representative of the governance process, I would like to thank the author for their work and everyone else who contributed.

SamB · 2026-04-02T19:45:01Z

 }

-#[cargo_test(nightly, reason = "-Zscript is unstable")]
+#[cargo_test(nightly, reason = "`#[feature(frontmatter]` hasn't hit stable yet")]


That attribute seems typoed throughout, shouldn't it be:

Suggested change

#[cargo_test(nightly, reason = "`#[feature(frontmatter]` hasn't hit stable yet")]

#[cargo_test(nightly, reason = "`#![feature(frontmatter)]` hasn't hit stable yet")]

Mark-Simulacrum · 2026-04-08T02:20:23Z

+
+`cargo` _script_ operate on system or user level, not project level.
+This means that the local [configuration discovery] is ignored.
+Instead, the configuration discovery begins at `$CARGO_HOME/config.toml`.


View changes since the review

Is this documentation outdated? If I'm interpreting #16620 correctly, Cargo will read config.toml from $SCRIPT_FILE_DIRECTORY/config.toml, or am I misreading that PR?

The comment in that PR notes that it operates like cargo install --path, which I think means these docs should say what that does? (https://doc.rust-lang.org/nightly/cargo/commands/cargo-install.html#configuration-discovery)

Thanks. This has gone through several changes and I forgot to make sure this aligned with the latest version.

ehuss · 2026-04-09T03:17:36Z

I should have done this earlier. I think there are some concerns that are worth addressing before merging.

The concern about edition behavior is described in rust-lang/rust#152254.

@rfcbot concern edition-behavior

Additionally, I think there is a security concern that we should take very seriously. The interaction of cargo-script with RFC#3279 could make it very easy to expose a user to dangerous behavior. This is also described somewhat in rust-lang/rust#152254.

@rfcbot concern security

rustbot · 2026-04-14T14:26:40Z

☔ The latest upstream changes (possibly #16851) made this pull request unmergeable. Please resolve the merge conflicts.

rustbot · 2026-04-17T20:23:09Z

This PR was rebased onto a different master commit. Here's a range-diff highlighting what actually changed.

Rebasing is a normal part of keeping PRs up to date, so no action is needed—this note is just to help reviewers.

epage added the T-cargo Team: Cargo label Jan 30, 2026

rustbot assigned weihanglo Jan 30, 2026

epage marked this pull request as draft January 30, 2026 14:32

rustbot removed the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Jan 30, 2026

epage commented Jan 30, 2026

View reviewed changes

weihanglo reviewed Jan 30, 2026

View reviewed changes

Comment thread src/bin/cargo/commands/run.rs

epage force-pushed the script-stable branch from 9b5af41 to 4284ce0 Compare January 30, 2026 15:28

epage marked this pull request as ready for review January 30, 2026 15:39

rustbot added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Jan 30, 2026

rust-rfcbot added proposed-final-comment-period An FCP proposal has started, but not yet signed off. disposition-merge FCP with intent to merge labels Jan 30, 2026

epage mentioned this pull request Jan 30, 2026

Tracking issue for release notes of #148051: Stabilize Frontmatter rust-lang/rust#151840

Open

weihanglo reviewed Jan 31, 2026

View reviewed changes

This comment has been minimized.

Sign in to view

epage force-pushed the script-stable branch from 0069af1 to ebaf44c Compare February 20, 2026 15:33

This comment has been minimized.

Sign in to view

rust-rfcbot added finished-final-comment-period FCP complete to-announce and removed final-comment-period FCP — a period for last comments before action is taken labels Feb 20, 2026

epage force-pushed the script-stable branch from ebaf44c to 6139956 Compare February 20, 2026 18:44

This comment has been minimized.

Sign in to view

epage force-pushed the script-stable branch from 6139956 to d2ccba3 Compare February 20, 2026 19:55

This comment has been minimized.

Sign in to view

epage mentioned this pull request Mar 4, 2026

feat: Add custom completer for cargo <TAB> to cargo scripts #16697

Closed

This comment has been minimized.

Sign in to view

SamB reviewed Apr 2, 2026

View reviewed changes

SamB mentioned this pull request Apr 2, 2026

Proper support for standalone/detached files rust-lang/rust-analyzer#14318

Open

epage added 3 commits April 3, 2026 09:54

feat: Stabilize cargo script

01d10b0

refactor(cli): Simplify script logic

1bf3f25

docs: Document cargo script

4be2873

epage force-pushed the script-stable branch from d2ccba3 to 8dfd965 Compare April 3, 2026 14:54

This comment has been minimized.

Sign in to view

Mark-Simulacrum reviewed Apr 8, 2026

View reviewed changes

rust-rfcbot added the proposed-final-comment-period An FCP proposal has started, but not yet signed off. label Apr 9, 2026

epage force-pushed the script-stable branch from 8dfd965 to 89cd5a8 Compare April 9, 2026 14:15

This comment has been minimized.

Sign in to view

ehuss moved this from FCP merge to FCP blocked in Cargo status tracker Apr 14, 2026

epage force-pushed the script-stable branch from 89cd5a8 to 4be2873 Compare April 17, 2026 20:23

		// TODO: remove once frontmatter hits nightly
		if unit.pkg.manifest().is_embedded() {

	#[cargo_test(nightly, reason = "`#[feature(frontmatter]` hasn't hit stable yet")]
	#[cargo_test(nightly, reason = "`#![feature(frontmatter)]` hasn't hit stable yet")]

Conversation

epage commented Jan 30, 2026 • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

rustbot commented Jan 30, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

epage commented Jan 30, 2026

Uh oh!

rust-rfcbot commented Jan 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

weihanglo left a comment • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

weihanglo commented Jan 31, 2026

Uh oh!

weihanglo commented Jan 31, 2026

Uh oh!

epage commented Jan 31, 2026

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

This comment has been minimized.

This comment has been minimized.

rust-rfcbot commented Feb 20, 2026

Uh oh!

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

Choose a reason for hiding this comment

Uh oh!

This comment has been minimized.

Mark-Simulacrum Apr 8, 2026 • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ehuss commented Apr 9, 2026

Uh oh!

This comment has been minimized.

rustbot commented Apr 14, 2026

Uh oh!

rustbot commented Apr 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

8 participants

epage commented Jan 30, 2026 •

edited by rustbot

Loading

rust-rfcbot commented Jan 30, 2026 •

edited

Loading

weihanglo left a comment •

edited by rustbot

Loading

Mark-Simulacrum Apr 8, 2026 •

edited by rustbot

Loading