Minor: Use "number" instead of "digit" when explaining Cargo's use of semver
Digit is technically incorrect here, as it would imply that Cargo treats 0.10.0 and 0.11.0 as semver compatible (because they have the same leftmost non-zero *digit*, even though they do not have the same leftmost non-zero *number*).
Update criterion
This updates the criterion dependency to the latest version. There aren't huge changes since 0.3.6, but there are some small changes such as slightly different console output, new flags, etc. The full changelog is at: https://github.com/bheisler/criterion.rs/blob/master/CHANGELOG.md
Digit is technically incorrect here, as it would imply that Cargo treats 0.10.0 and 0.11.0 as semver compatible (because they have the same leftmost non-zero *digit*, even though they do not have the same leftmost non-zero *number*).
Cargo tries to maintain the stability of every output it emits.
However, for things like `PackageId` and `SourceId` users should
see them as opaque strings. We generally don't change it but we
want to reserve the right to change when it is required.
docs(ref): Provide guidance on version requirements
### What does this PR try to resolve?
I've been dealing with these situations as either the package author, depending on such a package, or supporting users who run into problems that I figure documenting this guidance in a central place means I won't have to repeat myself as often and have to re-find all of the relevant links each time.
### How should we test and review this PR?
Alternatives to how this was documented
- Use a regular header. All of sections in this document are flat and its hard to see association between them. This also feels like its more on the level of the "note"s.
- Put this in a central Recommendations page. I think we should do something more for these when we have more (nothing else in my quick scan stood out as "recommendations" like this). At that point we can have a better idea of how it would work (much like the rule of 3 for generalizing code). I also suspect a "Recommendations" index might be better.
- Put this in the FAQ. This can easily be framed as a question and we put the `Cargo.lock` policy in there.
I left out talking about alternative proc-macro designs as I feel like treading new ground in community practices is out of the scope of this.
### Additional information
See also https://rust-lang.zulipchat.com/#narrow/stream/246057-t-cargo/topic/Version.20Requirements.20documentation
I've been dealing with these situations as either the package author,
depending on such a package, or supporting users who run into problems
that I figure documenting this guidance in a central place means I won't
have to repeat myself as often and have to re-find all of the relevant
links each time.
Alternatives to how this was documented
- Use a regular header. All of sections in this document are flat and
its hard to see association between them. This also feels like its
more on the level of the "note"s.
- Put this in a central Recommendations page. I think we should do
something more for these when we have more (nothing else in my quick
scan stood out as "recommendations" like this). At that point we can
have a better idea of how it would work (much like the rule of 3 for
generalizing code). I also suspect a "Recommendations" index might be
better.
- Put this in the FAQ. This can easily be framed as a question and we
put the `Cargo.lock` policy in there.
I left out talking about alternative proc-macro designs as I feel like
treading new ground in community practices is out of the scope of this.
See also https://rust-lang.zulipchat.com/#narrow/stream/246057-t-cargo/topic/Version.20Requirements.20documentation
Add READMEs for the credential helpers.
This adds some READMEs for these crates. These are pretty bare bones for now, but I suspect they may get extended in the future based on how we decide to deploy them.
Add some more documentation for Source download functions.
This adds a little more of a description to the download functions of the `Source` trait, since the behavior wasn't clear to me (and I often forget how these work).
Don't try to compile cargo-credential-gnome-secret on non-Linux platforms.
This is a followup on #11993 to put the same treatment for `cargo-credential-gnome-secret` so that it builds on non-Linux platforms, substituting the "unsupported" implementation in that case.
This will still fail on Linux platforms that don't have libsecret-1-dev installed. I'm not sure how to best treat that, since we do want an error to be generated if the user tries to run `cargo install cargo-credential-gnome-secret`, and they don't have libsecret installed.
fix(script): Be quiet on programmatic output
### What does this PR try to resolve?
This is a part of #12207
The goal is that we shouldn't interfere with end-user output when
"cargo script"s are used programmatically. The only way to detect this
is when piping. CI will also look like this.
My thought is that if someone does want to do `#!/usr/bin/env -S cargo -v`, it
should have a consistent meaning between local development
(`cargo run --manifest-path`) and "script mode" (`cargo`), so I
effectively added a new verbosity level in these cases. To get normal
output in all cases, add a `-v` like the tests do. Do `-vv` if you want
the normal `-v` mode. If you want it always quiet, do `--quiet`.
I want to see the default verbosity for interactive "script mode" a bit
quieter to the point that all normal output cargo makes is cleared before
running the built binary. I am holding off on that now as that could
tie into bigger conversations / refactors
(see https://rust-lang.zulipchat.com/#narrow/stream/246057-t-cargo/topic/Re-thinking.20cargo's.20output).
### How should we test and review this PR?
Initial writing of tests and refactors are split split out. The tests in the final commit will let you see what impact this had on behavior.
The goal is that we shouldn't interefere with end-user output when
"cargo script"s are used programmatically. The only way to detect this
is when piping. CI will also look like this.
My thought is that if someone does want to do `#!/usr/bin/env -S cargo -v`, it
should have a consistent meaning between local development
(`cargo run --manifest-path`) and "script mode" (`cargo`), so I
effectively added a new verbosity level in these cases. To get normal
output in all cases, add a `-v` like the tests do. Do `-vv` if you want
the normal `-v` mode. If you want it always quiet, do `--quiet`.
I want to see the default verbosity for interactive "script mode" a bit
quieter to the point that all normal output cargo makes is cleared before
running the built binary. I am holding off on that now as that could
tie into bigger conversations / refactors
(see https://rust-lang.zulipchat.com/#narrow/stream/246057-t-cargo/topic/Re-thinking.20cargo's.20output).
cargo script example needs nightly -Zscript feature
### What does this PR try to resolve?
Update cargo script example. Cargo script currently needs nightly `-Zscript` feature.
Without this change users will see:
```
error: running `./cargo_script.rs` requires `-Zscript`
```
cc https://github.com/rust-lang/cargo/issues/12207
### How should we test and review this PR?
I don't think any additional tests are needed. All existing tests for cargo script already use `-Zscript`.
### Additional information
Thanks for designing and implementing cargo script `@epage!`
fix(script): Process config relative to script, not CWD
### What does this PR try to resolve?
This is part of the work for #12207.
When you put in your path `foo.rs`:
```rust
#!/usr/bin/env cargo
fn main() {}
```
You expect it to build once and then repeatedly run the same version. However, `.cargo/config.toml` doesn't work like that (normally). It is an environment file, like `.env`, and is based on your current working directory. So if you run `foo.rs` from within a random project, it might rebuild due to RUSTFLAGS in `.cargo/config.toml`.
I had some concern about whether this current behavior is right or not and [noted this in the Pre-RFC](https://github.com/epage/cargo-script-mvs/blob/main/0000-cargo-script.md#unresolved-questions). This came up again while we were [discussing editions on zulip](https://rust-lang.zulipchat.com/#narrow/stream/246057-t-cargo/topic/cargo.20script.20and.20edition). In looking further into this, it turns out we already have precedence for this with `cargo install --path <path>`.
### How should we test and review this PR?
The second commit has the fix, the docs, and a change to a test (from the first commit) to show that the fix actually changed behavior.
-Znext-lockfile-bump: Don't suggest using -Z on stable
This changes the lockfile version 4 error to not suggest using `-Znext-lockfile-bump` on the stable channel. I fear this could be confusing to users when the real version 4 is stabilized, and the user is using a too old version of cargo. Instead this produces the same error message as any unknown version would produce, with a suggestion to update.
docs(unstable): Point stable-unstable docs to nightly docs
I ran into this in trying to find the "cargo script" docs. Unless its the rare case of `RUSTC_BOOTRAP=1 cargo +stable ...`, someone reading about features on `+nightly` likely would want to see the latest version of this document, so we should help people find it.
This is to avoid possible name collisions. For example, a user
creates a file called `.cargo/cache`, and then in the future
cargo wants to create a directory called `.cargo/cache/`, that
would collide with what the user specified. Restricting to `.toml`
extensions would avoid that since we won’t make a directory named
with a `.toml` extension.
fix: Allow embedded manifests in all commands
### What does this PR try to resolve?
This is a part of #12207.
One of the goals is for embedded manifests to be a first class citizen. If you have a script, you should be able to run tests on it, for example.
This expands the error check from just `Cargo.toml` to also single-file packages so you can use it in `--manifest-path`.
This, however, does mean that these *can* be used in places that likely won't work yet, like `cargo publish`.
### How should we test and review this PR?
By commit. We introduce tests for basic commands and then implement and refine the support for this.
### Additional information
Other information you want to mention in this PR, such as prior arts,
future extensions, an unresolved problem, or a TODO list.
