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
• 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
• Resolve symlinks in cargo <foo>?
• 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
• cargo pkgid support
• Remove doc-comment support
• Remove hack from feat(embedded): Hack in code fence support  #12681, relying on rustc support for new syntax
• Allow newlines before code fence
• Harden code fence parser
• cargo add / cargo rm support
• cargo clippy support
• cargo fmt support
• cargo fix support
• rust-analyzer support
  • Add shebang support for "cargo script" rust-analyzer#15318

Deferred / non-blocking:

• 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

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

Issues: Z-script Nightly: cargo script

More design updates and exploration can be found at: https://github.com/epage/cargo-script-mvs/blob/main/0000-cargo-script.md

This is an experimental feature to add unstable support for single-file packages in cargo so we can explore the design and resolve questions with an implementation to collect feedback on.

Note: third-party support

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

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

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.

[azzamsa]

Worked like like a charm. Thank you!

[heaths]

I've written a couple rust scripts now in cases where I need more consistent, programmatic control than a (more often easier) shell script could provide in a few cases e.g., parsing TOML without acquisition of additional tools.

In those cases, however, it's incredibly useful to write the source in an editor e.g., VSCode + rust-analyzer to have the benefits of an LSP, linting etc. To that end, neither front matter supported now allow for that because of syntax errors:

```cargo
[package]
edition = "2021"
```

Or:

---
[package]
edition = "2021"
---

Unless the eventual idea is that all tools including rustc, rust-analyzer, etc., support - even just ignore - this front matter section, writing scripts in an editor is impossible. At leat you have to comment it out and, if you have dependencies, need a Cargo.toml. From the current tracking items, it seems solving the latter is on the radar, but it'd be great to consider solving the former. As of now, it seems the idea is to not support commands, depending on what "Remove doc-comment support" means exactly.

Given the use of code fences in the first case above (though it seems the second case is the way forward, yes?), couldn't cargo support triple slashes e.g.,

#!/usr/bin/env -S cargo +nightly -Zscript
/// ```cargo
/// [package]
/// edition = "2021"
/// ```

fn main() {
    todo!()
}

At least until dependency resolution is sorted, this would support opening scripts in an editor using an LSP.

[epage]

The plan is to add the syntax to the Rust language. An RFC exists for this. Once one more T-lang team member checks a box, FCP will start.

[jcbhmr]

is there a way to use features or other cfg stuff when using cargo +nightly -Zscript ./hello_world.rs? like if I have this:

#!/usr/bin/env -S cargo +nightly -Zscript
```cargo
[features]
hi = []
```
fn main() {
  #[cfg(feature = "hi")]
  println!("hi");
  println!("hello world");
}

how would I run it with the --features=hi flag?

jcbhmr@PIG2016:~/Documents/test343$ ./hello_world.rs --features=hi
warning: `package.edition` is unspecified, defaulting to `2021`
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.07s
     Running `/home/jcbhmr/.cargo/target/aa/3b09aa9f783bc3/debug/hello_world --features=hi`
hello world
jcbhmr@PIG2016:~/Documents/test343$ cargo +nightly -Zscript --features=hi ./hello_world.rs
error: unexpected argument '--features' found

Usage: cargo [+toolchain] [OPTIONS] [COMMAND]
       cargo [+toolchain] [OPTIONS] -Zscript <MANIFEST_RS> [ARGS]...

For more information, try '--help'.

☝️ particularly the cargo +nightly -Zscript --features=hi ./hello_world.rs one; that one i really hoped would work

i looked at the env var list https://doc.rust-lang.org/cargo/reference/environment-variables.html and couldn't find a Ctrl+F match for "feature" that would let me do like CARGO_FEATURES=hi ./hello_world.rs either 🤷‍♀️

if there is a way, how would I use it in the shebang? like

#!/usr/bin/env -S cargo +nightly -Zscript --features=hi
```cargo
[features]
hi = []
```
fn main() {
  #[cfg(feature = "hi")]
  println!("hi");
  println!("hello world");
}

---

EDIT UPDATE

I found a way! ...but it doesn't seem to work with #! shebang. 😢

cargo +nightly -Zscript run --features=hi --manifest-path ./hello_world.rs # ✅
cargo +nightly -Zscript run --features=hi --manifest-path ./hello_world.rs pos1 --flag1 # ❌
cargo +nightly -Zscript run --features=hi --manifest-path ./hello_world.rs -- pos1 --flag1 # ✅
./hello_world.rs # ✅
./hello_world.rs pos1 --flag1 # ❌
./hello_world.rs -- pos1 --flag1 # ✅

you need something like this which i haven't found a way to do yet:

#!/usr/bin/env -S cargo +nightly -Zscript run --features=hi --manifest-path $THE_FILE --
```cargo
[features]
hi = []
```
fn main() {
  #[cfg(feature = "hi")]
  println!("hi");
  println!("hello world");
}

./hello_world.rs pos1 --flag1 # the dream lol

[epage]

Yes, cargo scripts are meant to work with any cargo command, so cargo run works.

What is your use case for wanting this on the shebang? My assumption is if you want it when you run it should be a default feature and likely if you use features, you're use case is likely big enough for a multi-file package.

[beckend]

How would one maintain the dependencies?
How would you import a module from foo.rs?

[epage]

Could you clarify what you mean by "maintain dependencies"? In general, we expect tooling to manage embedded manifests like regular ones.

As for importing a foo.rs, that is broken right now when dependencies are used due to a hack we use to get dependencies working. You would mod foo; just like from a main.rs. However, that would be discouraged as the point of these is to be single file. If you need to mod something, why not have a full package?

[beckend]

"maintain dependencies"
Can I do:

once_cell = { workspace = true, default-features = false }

Can I use cargo update?

I would disagree on the limitation of not having the ability to use a module, to be able to externalize some code and import that module makes it much cleaner. I mean why is is necessary to impose this limitation, if there are difficulties implementing this, okay fine, but it's not necessary.

[epage]

cargo update should already work.

workspace = true does not work yet because workspace support is out of scope for the initial release.

cargo add will be supported on release. Support is waiting on the syntax RFC being approved.

As for mod, I did not say it wouldn't be supported. I said it would be discouraged. Its still not clear why you'd use an embedded manifest over Cargo.toml if you are using external files. A large point of these is to be single file for easy sharing and there are features we are explicitly not supporting, like build.rs.

[dmyTRUEk]

I see almost no discussion around release/optimized mode (except "This is under discussion in the RFC" (above) and merged commit adding "option to generate release mode profile") which I find pretty important, so I want to express my view on this subject:

While manually setting all parameters in the [profile.dev] section to be the same as in release mode or just using the "option to generate release mode profile" kinda does that, I don't think this is an optimal solution.

Adding --release and -r flags looks to me like a much more solid solution to the problem. Or perhaps maybe even add support for arbitrary profiles (using --profile), same as for the usual cargo run, for maximum flexibility.

This allows users to iterate much faster when developing or experimenting with a script, while not compromising performance when the script is done, and all of this is just by simply adding or removing the --release flag to the shebang, unlike the current solution, where you have to manually edit all of the desired flags in "Cargo.toml part" of the script.

[epage]

Rather than dividing the conversation, I'd recommend focusing it at rust-lang/rfcs#3502 (comment)

[surban]

How is this supposed to work on Windows?

Will rustup extend PATHEXT upon installation and associate .rs files with cargo?

In this case all Rust source files would become executable, which is confusing, especially when using Windows Explorer.

I think it might be better to use a separate extension, for example .rsc for Rust SCript, to ensure that the experience on Windows will not lack behind.

[bjorn3]

How does python handle this on Windows? They don't use a separate extension for executable and non-executable files either.

[surban]

How does python handle this on Windows? They don't use a separate extension for executable and non-executable files either.

True, but it doesn't mean we have to follow them if we can do better.

[Rudxain]

How does python handle this[...]?

All *.py files are executable, scripts and modules alike. So I would be hesitant to suggest taking inspiration from Py, but I'm unsure if there's a better alternative than simply using a different file-ext.

MS should definitely add shebang (and magic-numbers) support to Windows! It's overdue since many years ago

[epage]

This might be a better conversation on the relevant section in the RFC: https://github.com/epage/rfcs/blob/script/text/3502-cargo-script.md#file-association-on-windows

[surban]

This might be a better conversation on the relevant section in the RFC: https://github.com/epage/rfcs/blob/script/text/3502-cargo-script.md#file-association-on-windows

I sent you a PR.

[surban]

MS should definitely add shebang (and magic-numbers) support to Windows! It's overdue since many years ago

They won't do that because it does not make sense on Windows, since the interpreter can be in an installation-dependent place and is not necessarily found in PATH. The Windows mechanism is not inherently bad, just different from UNIX.

[programmerjake]

MS should definitely add shebang (and magic-numbers) support to Windows! It's overdue since many years ago

They won't do that because it does not make sense on Windows, since the interpreter can be in an installation-dependent place and is not necessarily found in PATH. The Windows mechanism is not inherently bad, just different from UNIX.

well, magic number support can look for a file starting with #!/usr/bin/env cargo and send that to wherever cargo is installed, no shebang support needed

[istudyatuni]

Please stop, many people watching for progress, not for discussion