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
• CARGO_MANIFEST_PATH variable to replace CARGO_MANIFEST_DIR (feat: add CARGO_MANIFEST_PATH env variable #14404)
• 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 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
• 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.

[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

[Rustin170506]

Hi @epage, as a daily user of cargo-script, I really want to help advance and stabilize this feature. (Thank you all for working on this feature.) What can I do to help? Is there anything you would suggest for me to get started?

[epage]

@Rustin170506 any of the tasks in the task list without a PR is good for grabbing.

Some clarifications

Resolve symlinks in cargo ?

The use case for this is that we allow cargo Cargo.toml but putting a #! in Cargo.toml only works well if you symlink it into path with the name of the bin.

I had wondered if we should do just always resolve symlinks but that breaks some use cases. Instead, when determining whether its embedded or not and there is no extension, we should resolve it to see what the

Change config paths to only check CARGO_HOME

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

Lines 176 to 181 in 0461165

	// Treat `cargo foo.rs` like `cargo install --path foo` and re-evaluate the config based on the
	// location where the script resides, rather than the environment from where it's being run.
	let parent_path = manifest_path
	.parent()
	.expect("a file should always have a parent");
	gctx.reload_rooted_at(parent_path)?;

When we talked about this as a Cargo team, we decided this need to reload to cargo home, like cargo install does, to avoid downloading a script and being subject to spurious files in your ~/Downloads, at the cost of losing the config from your repo.

#14476

This might require an RFC but likely a trivial one

cargo pkgid support

This will be messy. We'll likely need to change SourceId to include the file name if it has an embedded manifest.

[Skgland]

One thing that occurred to me while just reading this is as you mention downloaded files :

Should cargo check for a Mark of the Web when running/building scripts on Wwindows/NTFS-drives?

[pirafrank]

One thing that occurred to me while just reading this is as you mention downloaded files :

Should cargo check for a Mark of the Web when running/building scripts on Wwindows/NTFS-drives?

I don't think so, but if it does, it should do it on macOS too, by checking additional file attributes.