Tracking Issue for cargo-script RFC 3424

[ehuss]

Summary

eRFC: #3424
RFC: rust-lang/rfcs#3502, rust-lang/rfcs#3503

Testing steps

Implementation:

• feat: Initial support for single-file packages #12245
• fix(embedded): Don't append hash to bin names #12269
• fix(embedded): Align package name sanitization with cargo-new #12255
• refactor(embedded): Switch to syn for parsing doc comments #12258
• fix(embedded): Don't create an intermediate manifest #12268
• feat(cli): Support cargo Cargo.toml #12281
  • Remove the support for Cargo.toml of the cargo-script #14670
• fix(embeded): Don't pollute the scripts dir with target/ #12282
• fix(embedded): Don't auto-discover build.rs files #12283
• fix(embedded): Don't pollute script dir with lockfile #12284
• CARGO_MANIFEST_PATH variable to replace CARGO_MANIFEST_DIR (feat: add CARGO_MANIFEST_PATH env variable #14404)
• fix: Allow embedded manifests in all commands  #12289
• fix(script): Process config relative to script, not CWD #12303
  • See Tracking Issue for cargo-script RFC 3424 #12207 (comment) for rustup (see also cargo install ignores the rust-toolchain.toml or uses the wrong one #11036)
• fix(script): Be quiet on programmatic output  #12305
• docs(unstable): Update script documentation #12308
• Evaluation Gate
  • Call for Testing (TWiR, mastadon)
  • t-cargo check-in
• fix(embedded): Error on intentionally unsupported commands  #12350
• feat(embedded): Hack in code fence support  #12681
• Evaluate Consider making the version field optional in Cargo.toml #9829
• Change config paths to only check CARGO_HOME (Change config paths to only check CARGO_HOME for cargo-script #14749)
• cargo pkgid support (Add cargo pkgid for cargo-script #14831, feat: add cargo pkgid support for cargo-script #14961)
• Remove auto-discovery of a [lib] (Cargo scripts try to build a nearby src/lib.rs if present #14476)
• Remove doc-comment support
• Remove hack from feat(embedded): Hack in code fence support  #12681, relying on rustc support for new syntax (see also Styling of Rust Frontmatter rustfmt#6388 for requirements)
• Allow newlines before code fence (fix(toml): Update frontmatter parser for RFC 3503 #14792)
• Harden code fence parser (fix(toml): Update frontmatter parser for RFC 3503 #14792)
• cargo add / cargo rm support (feat(toml): Allow adding/removing from cargo scripts #14857)
• cargo remove prints the edition warning twice
• cargo clippy support
• cargo fmt support (Styling of Rust Frontmatter rustfmt#6388)
• cargo fix support (fix(fix): Migrate cargo script manifests across editions #14864)
• Switch from minimally-invasive manifest defaults to proper normalization (refactor(embedded): Integrate cargo-script logic into main parser #15168)
• Double check shebang detection code against rustc (cargo (for cargo script) and rustc disagee on shebangs #15170)
• rust-analyzer support
  • Add shebang support for "cargo script" rust-analyzer#15318

Deferred / non-blocking:

• Users are subject to $CARGO passed to external subcommands can point to the wrong cargo if already set #15099
• cargo publish (including setting the includes implicitly)
• workspace support
• Reduce cargo foo.rs output noise
• RFC: Templating CARGO_TARGET_DIR to make it the parent of all target directories rfcs#3371 and last-seen zulip discussion for shared cache rather than a shared CARGO_TARGET_DIR like in the Pre-RFC
• Per-user compiled artifact cache #5931
• Make package.name optional #12689
• Cargo Scripts with -Zscript should override current_exe #12870
• cargo Cargo.toml support, see Remove the support for Cargo.toml of the cargo-script #14670
• cargo install --path (uses the same path syntax as [dependencies])

Documentation: https://doc.rust-lang.org/nightly/cargo/reference/unstable.html#script

Issues: Z-script Nightly: cargo script

Note: third-party support

• Support for shebang tree-sitter/tree-sitter-rust#183

Considerations for stabilization

• Shebang detection uses a subset of rustc, see docs(embedded): Note the shebang deviation #15173
• Config is only loaded from CARGO_HOME, like cargo install (Change config paths to only check CARGO_HOME for cargo-script #14749)
  • Unlike regular Cargo commands (relative to current_dir)
  • Unlike what was proposed in the RFC (relative to script)
  • This could end up being annoying for scripts in workspaces
• Target dir is built from a hash of the file literally passed in and does not account for any symlinks (parent directories or for the file), see Tracking Issue for cargo-script RFC 3424 #12207 (comment)

Unresolved Issues

• Should the manifest fields use an allowlist or a denylist (current)?
• Should escaping rules match package validation or cargo-new validation (current)?

See also the Pre-RFC for more discussion

Known Issues

• You can't run cargo foo.rs -Zsomething, only cargo -Zsomething cargo.rs (true for any global flag in Cargo) because anything after the script name is assumed to be an argument to the script, like third-party subcommands.

Future Extensions

No response

About tracking issues

Tracking issues are used to record the overall progress of implementation.
They are also used as hubs connecting to other relevant issues, e.g., bugs or open design questions.
A tracking issue is however not meant for large scale discussion, questions, or bug reports about a feature.
Instead, open a dedicated issue for the specific matter and add the relevant feature gate label.

[ChrisJefferson]

The RFC seems a bit unclear on if the filename must end with .rs or not?

If we (a) don't require .rs, and (b) don't require an explicit command line option, would that mean cargo runc myprog (misspelling run as runc) would be intepreted as "treat the runc executable as rust source and try and compile it, then run it"?

[epage]

The eRFC was intentionally very light on details as it was approving experimenting on the idea and not approving a near-final design. One of the things we'll be experimenting with is if there is a precedence scheme for cargo foo that works for us. I have some notes at epage/cargo-script-mvs#154 on how other tools deal with it.

[XOR-op]

In the current implementation, it looks like adding/renaming a function will trigger a whole re-compliation including all dependencies. Changing/Adding function signature is not rare in scripting. I wonder if this is expected and if this could be resolved.

[epage]

In #12268, the whole scheme is being removed. In future PRs, we'll being some of it back but yes, one of the thing I'll be changing is that the target dir should have a hash of the path, not the content. People change the content more than they change the location.