Add mdman for generating man pages.
This introduces a new utility called `mdman` that converts a markdown-formatted document to a man page. This replaces asciidoctor, with the intent to make it easier to contribute, easier to have consistent formatting across platforms, and easier to generate plain-text documents for use on Windows (for #8456). This also includes a number of formatting fixes.
There is some documentation in the `mdman/doc` directory explaining how to use it, and the docs in `src/doc/README.md` have been updated (this explains the structure of the files). The Makefile has been replaced with a simple shell script.
CI has been updated to verify the checked-in docs are up-to-date. Perhaps in the future, these can be generated automatically (perhaps by `build.rs`?), but since that requires a bit of build system work (like upstream rust), this is deferred till later.
cargo login: make login message less ambiguous
The previous message
"please visit https://crates.io/me and paste the API Token below"
Had me waiting for a token to appear in the command line which I would then paste into the website.
Rephrase to
"please paste the api token found on https://crates.io/me below"
to clarify where to paste from and where to paste to.
The previous message
"please visit https://crates.io/me and paste the API Token below"
Had me waiting for a token to appear in the command line which I would then paste into the website.
Rephrase to
"please paste the api token found on https://crates.io/me below"
to clarify where to paste from and where to paste to.
Fix O0 build scripts by default without `[profile.release]`
This fixes an issue where #8500 didn't quite work as expected, since it
only worked if a crate had a `[profile.release]` section.
Emphasize git dependency version locking behavior.
Added a section in `src/doc/src/reference/specifying-dependencies.md` clarifying Cargo's version locking behavior when adding `git` dependencies:
```
Once a `git` dependency has been added, Cargo will lock that dependency to the
latest commit at the time. New commits will not be pulled down automatically
once the lock is in place. However, they can be pulled down manually with
`cargo update`.
```
Resolves#8555
Update lock file encodings on changes
This commit alters Cargo's lockfile encoding update strategy from its
previous incarnation. Previously Cargo had two versions, one for new
lock files and one for old lock files. Each of these versions were
different and would affect how Cargo manages lock file updates. The
intention was that we'd roll out defaults to new lock files first and
then later to preexisting lock files. This requires two separate
changes, though, and it's not necessarily clear when to start updating
old lock files. Additionally when old lock files were opted in it would
break builds using `--locked` if they simply updated Cargo because Cargo
would would want to bring the lock file versions forward.
The purpose of this change is to solve these issues. The new strategy
for updating a lock file's encoding is to simply preserve what's already
existing on the filesystem until we actually decide to write out a new
lock file. When Cargo updates a lock file on-disk then it will, at that
time, update the lock file encoding to whatever the current default is.
This means that there's only one version number to keep track of (the
default for encoding). Cargo will always preserve the preexisting
encoding unless another change is required to the lock file.
Fix sporadic lto test failures.
These tests can fail because the order of the messages is not deterministic. The two `foo` jobs start in parallel, so the order can be swapped. Results in an error like:
```
---- lto::test_profile stdout ----
running `/home/runner/work/cargo/cargo/target/debug/cargo test -v`
thread 'lto::test_profile' panicked at '
Expected: execs
but: differences:
6 - |[RUNNING] `rustc --crate-name foo [..]--crate-type lib --emit=dep-info,metadata,link -Cembed-bitcode=no[..]|
+ | Running `rustc --crate-name foo --edition=2018 src/lib.rs --error-format=json --json=diagnostic-rendered-ansi --emit=dep-info,link -C lto=thin -C debuginfo=2 --test -C metadata=af771ad588185fac -C extra-filename=-af771ad588185fac --out-dir /home/runner/work/cargo/cargo/target/cit/t1080/foo/target/debug/deps -L dependency=/home/runner/work/cargo/cargo/target/cit/t1080/foo/target/debug/deps --extern bar=/home/runner/work/cargo/cargo/target/cit/t1080/foo/target/debug/deps/libbar-398704963dd4e38b.rlib`|
7 - |[RUNNING] `rustc --crate-name foo [..]--emit=dep-info,link -C lto=thin [..]--test[..]|
+ | Running `rustc --crate-name foo --edition=2018 src/lib.rs --error-format=json --json=diagnostic-rendered-ansi --crate-type lib --emit=dep-info,metadata,link -Cembed-bitcode=no -C debuginfo=2 -C metadata=1e8f5d385f4ffeb6 -C extra-filename=-1e8f5d385f4ffeb6 --out-dir /home/runner/work/cargo/cargo/target/cit/t1080/foo/target/debug/deps -L dependency=/home/runner/work/cargo/cargo/target/cit/t1080/foo/target/debug/deps --extern bar=/home/runner/work/cargo/cargo/target/cit/t1080/foo/target/debug/deps/libbar-398704963dd4e38b.rmeta`|
```
The failure rate is pretty small (depends heavily on the hardware).
Flag git http errors as maybe spurious
This showed up in #8544 with an error message of "stream ended at an
unexpected time; class=Http" which sounds like a spurious error.
Termination of a network connection can happen at any time! For now try
to assist in that error by adding another class of error to the list of
maybe spurious errors.
This commit alters Cargo's lockfile encoding update strategy from its
previous incarnation. Previously Cargo had two versions, one for new
lock files and one for old lock files. Each of these versions were
different and would affect how Cargo manages lock file updates. The
intention was that we'd roll out defaults to new lock files first and
then later to preexisting lock files. This requires two separate
changes, though, and it's not necessarily clear when to start updating
old lock files. Additionally when old lock files were opted in it would
break builds using `--locked` if they simply updated Cargo because Cargo
would would want to bring the lock file versions forward.
The purpose of this change is to solve these issues. The new strategy
for updating a lock file's encoding is to simply preserve what's already
existing on the filesystem until we actually decide to write out a new
lock file. When Cargo updates a lock file on-disk then it will, at that
time, update the lock file encoding to whatever the current default is.
This means that there's only one version number to keep track of (the
default for encoding). Cargo will always preserve the preexisting
encoding unless another change is required to the lock file.
Display builtin aliases with `cargo --list`
As stated in #8486 it would help to the discovery of the
builtin aliases the facto of printing them with the
`cargo --list` command.
- Extracted the builtin aliases currently implemented to a
separated `const`.
- Make all of the functions that interact with these aliases
point to that function.
- Refactored the `list_commands` fn in order to include with the
builtin and external commands, the builtin aliases that come with
cargo by default.
- Added a test that checks that the aliases that currently
are builtin with cargo are indeed being printed with the rest
of the commands when `cargo --list` is called.
The output on my machine looks like this:
```
$ cargo --list
Installed Commands:
b alias: build
bench Execute all benchmarks of a local package
build Compile a local package and all of its dependencies
c alias: check
check Check a local package and all of its dependencies for errors
clean Remove artifacts that cargo has generated in the past
doc Build a package's documentation
fetch Fetch dependencies of a package from the network
fix Automatically fix lint warnings reported by rustc
generate-lockfile Generate the lockfile for a package
git-checkout This subcommand has been removed
init Create a new cargo package in an existing directory
install Install a Rust binary. Default location is $HOME/.cargo/bin
locate-project Print a JSON representation of a Cargo.toml file's location
login Save an api token from the registry locally. If token is not specified, it will be read from stdin.
metadata Output the resolved dependencies of a package, the concrete used versions including overrides, in machine-readable format
new Create a new cargo package at <path>
owner Manage the owners of a crate on the registry
package Assemble the local package into a distributable tarball
pkgid Print a fully qualified package specification
publish Upload a package to the registry
r alias: run
read-manifest Print a JSON representation of a Cargo.toml manifest.
run Run a binary or example of the local package
rustc Compile a package, and pass extra options to the compiler
rustdoc Build a package's documentation, using specified custom flags.
search Search packages in crates.io
t alias: test
test Execute all unit and integration tests and build examples of a local package
tree Display a tree visualization of a dependency graph
uninstall Remove a Rust binary
update Update dependencies as recorded in the local lock file
vendor Vendor all dependencies for a project locally
verify-project Check correctness of crate manifest
version Show version information
yank Remove a pushed crate from the index
clippy
clippy
clippy
clippy
flamegraph
fmt
fmt
fmt
fmt
miri
miri
miri
miri
outdated
tree
```
As discussed with @ehuss the `BTreeSet` enforces `Ord` therefore, the aliases get mixed with the commands since they're passed through the same function.
It can be refactored to appear separately, but, the code will be more spread and now it's all in just one file (which I believe is easier to maintain and review).
Closes#8486
As @ehuss correctly suggested, we could just declare
in one `const` structure for every builtin alias the
following: `(alias, aliased_command, description)`.
Therefore, the suggestion has been applied and the
`BUILTIN_ALIASES` const has been refactored.
Also, the `builtin_aliases_execs` now parses the
`BUILTIN_ALIASES` const searching for a
"possible alias command" returning an option with the
previous info structure or `None`.
Check manifest for requiring nonexistent features
Fixes#4854: Examples requiring a nonexistent feature should be an error
Thanks @lukaslueg with his https://github.com/rust-lang/cargo/pull/4874 for the inspiration!
This showed up in #8544 with an error message of "stream ended at an
unexpected time; class=Http" which sounds like a spurious error.
Termination of a network connection can happen at any time! For now try
to assist in that error by adding another class of error to the list of
maybe spurious errors.
Clarify test name filter usage
I set aside the description of the usage example in the top description section and added a more concise example in the example section at the bottom of the man page. I also changed the wording of the usage example up top a bit to be more search-friendly since "filter" is a common keyword to search for.
Resolves#8282
Set aside description of the usage example in the top description section and added a more consise example in the example section at the bottom of the man page.
Revert Cargo Book changes for default edition
On #8543 it was introduced a change on the Cargo Book docs
where it was incorrectly stated that the default edition for
the Cargo Manifest was `2018` when indeed, as @ehuss correctly stated
in https://github.com/rust-lang/cargo/pull/8543#issuecomment-663769077
it is not.
Therefore, as @Eh2406 asked for, I made the PR reverting this changes
and leaving the Cargo Book docs as they were before.
On #8543 it was introduced a change on the Cargo Book docs
where it was incorrectly stated that the default edition for
the Cargo Manifest was `2018` when indeed, as @ehuss correctly stated
in https://github.com/rust-lang/cargo/pull/8543#issuecomment-663769077
it is not.
Therefore, as @Eh2406 asked for, I made the PR reverting this changes
and leaving the Cargo Book docs as they were before.
Prepare for not defaulting to master branch for git deps
This PR is the "equivalent" of https://github.com/rust-lang/cargo/pull/8503 for the nightly channel of Rust (the master branch of Cargo). The purpose of this change is to fix the breakage from https://github.com/rust-lang/cargo/pull/8364 but to still pave a path forward to enabling the feature added in https://github.com/rust-lang/cargo/pull/8364, namely reinterpreting dependency directives without a `branch` directive as depending on `HEAD` insead of depending on `master`.
This is a series of commits which implements a few mitigation strategies, but they're all adding up into a larger plan to roll out this change with, ideally, no breaking changes for those "reasonably" keeping up with Rust. The changes here are:
* Cargo still internally differentiates between `DefaultBranch` and `Branch("master")`, so it knows what you wrote in the manifest. These two, however, hash and equate together so everything in Cargo considers them equivalent.
* Cargo will now issue a warning whenever it fetches a repository pinned to `DefaultBranch` and the branch's `master` branch doesn't actually match `HEAD`. This avenue of breakage didn't arise but I added it here for completionism about not having to deal with breakage from this change again.
* Cargo has now implemented a new future lockfile format. Internally this is dubbed "v3". The changes in this format is that it will have a `version` marker at the top of the file as well as encoding git dependencies different. Today `DefaultBranch` and `Branch("master")` encode the same way, but in the future they will encode differently.
* Cargo now has a warning where if you have a mixture of `DefaultBranch` and `Branch("master")` in your build. The intention here is to get everyone on one or the other so the transition to the new lock file format can go smoothly.
With all of these pieces in place the intention is that there is no breakage from #8364 as well. Additionally projects that *would* break will receive warnings. (note that projects "broken" today, those we've got issues for, will likely not get warnings, but that's because it was accidental we broke them). The long-term plan is to let this bake for quite some time, and then as part of the same change land an update to the new lock file format as well as "fixing" `SourceId` to consider these two directives different. When this change happens we should have guaranteed, for all currently active projects, they're either only using `branch = "master"` or no directive at all. We can therefore unambiguosly read the previous `Cargo.lock` to transition it into a new `Cargo.lock` which will either have `?branch=master` or nothing.
I'm not sure how long this will need to bake for because unfortunately version changes to `Cargo.lock` cannot be taken lightly. We haven't even bumped the default format for old lock files to `V2` yet, they're still on `V1`. Hopefully in getting this in early-ish, though, we can at least get the ball rolling.
Closes#8468
Include `+` for crates.io feature requirements in the Cargo Book section on features
This change was introduced in commit 5f842f7 of rust-lang/crates.io but was not subsequently added to the Cargo Book.
