Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs(unstable): Update script documentation #12308

Merged
merged 1 commit into from
Jun 23, 2023
Merged

docs(unstable): Update script documentation #12308

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 9 additions & 8 deletions src/doc/src/reference/unstable.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1385,7 +1385,7 @@ Valid operations are the following:

Cargo can directly run `.rs` files as:
```console
$ cargo -Zscript file.rs
$ cargo +nightly -Zscript file.rs
```
where `file.rs` can be as simple as:
```rust
Expand Down Expand Up @@ -1423,6 +1423,9 @@ files), we are adding the concept of single-file packages which may contain an
embedded manifest. There is no required distinguishment for a single-file
`.rs` package from any other `.rs` file.

Single-file packages may be selected via `--manifest-path`, like
`cargo test --manifest-path foo.rs`. Unlike `Cargo.toml`, these files cannot be auto-discovered.

A single-file package may contain an embedded manifest. An embedded manifest
is stored using `TOML` in a markdown code-fence with `cargo` at the start of the
infostring inside a target-level doc-comment. It is an error to have multiple
Expand All @@ -1448,18 +1451,16 @@ Inferred / defaulted manifest fields:
later add support for including them in a workspace.
- `package.edition = <current>` to avoid always having to add an embedded
manifest at the cost of potentially breaking scripts on rust upgrades
- Warn when `edition` is unspecified. While with single-file packages this will be
silenced by default, users wanting stability are also likely to be using
other commands, like `cargo test` and will see it.
- Warn when `edition` is unspecified to raise awareness of this

Disallowed manifest fields:
- `[workspace]`, `[lib]`, `[[bin]]`, `[[example]]`, `[[test]]`, `[[bench]]`
- `package.workspace`, `package.build`, `package.links`, `package.autobins`, `package.autoexamples`, `package.autotests`, `package.autobenches`

As the primary role for these files is exploratory programming which has a high
edit-to-run ratio, building should be fast. Therefore `CARGO_TARGET_DIR` will
be shared between single-file packages to allow reusing intermediate build
artifacts.
The default `CARGO_TARGET_DIR` for single-file packages is at `$CARGO_HOME/target/<hash>`:
- Avoid conflicts from multiple single-file packages being in the same directory
- Avoid problems with the single-file package's parent directory being read-only
- Avoid cluttering the user's directory

The lockfile for single-file packages will be placed in `CARGO_TARGET_DIR`. In
the future, when workspaces are supported, that will allow a user to have a
Expand Down