From 004e6a172ef0a88255ba3952783f6e3c13df19c0 Mon Sep 17 00:00:00 2001 From: Ed Page Date: Fri, 23 Jun 2023 14:20:00 -0500 Subject: [PATCH] docs(unstable): Update script documentation See #12207 for what all is merged thatt his is trying to cover. --- src/doc/src/reference/unstable.md | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/src/doc/src/reference/unstable.md b/src/doc/src/reference/unstable.md index 31afa2133bc..01f6319d1e2 100644 --- a/src/doc/src/reference/unstable.md +++ b/src/doc/src/reference/unstable.md @@ -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 @@ -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 @@ -1448,18 +1451,16 @@ Inferred / defaulted manifest fields: later add support for including them in a workspace. - `package.edition = ` 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/`: +- 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