Update config and environment variable docs.
Various updates to try to clarify and expand the documentation for config variables and environment variables.
Closes#4041Closes#7610Closes#7571Closes#5780Closes#5690
Stop ignoring .rs.bk files; rustfmt hasn't generated them in years
cargo currently generates a .gitignore file that ignores .rs.bk files,
historically because rustfmt would sometimes generate such files.
However, rustfmt and cargo fmt don't generate backup files by default
(only when requested), and even when requested, they generate .bk files,
not .rs.bk files (as of rustfmt commit
fad903fd14ad0df045dc574cac0717312860c380 in 2017). And nobody seems to
have noticed or complained since then, likely because rustfmt doesn't
generate backup files by default.
rustfmt also plans to deprecate the --backup option entirely, in rustfmt
2.0, and instead always rely on version control to track changes.
In addition, these types of ignores, just like ignores of editor backup
files, don't belong in .gitignore; they belong in people's personal
ignore files, such as `~/.config/git/ignore`. See
https://julien.danjou.info/properly-managing-your-gitignore/ for further
explanation of that.
Given all three of those factors, drop the code to add `**/*.rs.bk` to
.gitignore, and update tests accordingly.
cargo currently generates a .gitignore file that ignores .rs.bk files,
historically because rustfmt would sometimes generate such files.
However, rustfmt and cargo fmt don't generate backup files by default
(only when requested), and even when requested, they generate .bk files,
not .rs.bk files (as of rustfmt commit
fad903fd14ad0df045dc574cac0717312860c380 in 2017). And nobody seems to
have noticed or complained since then, likely because rustfmt doesn't
generate backup files by default.
rustfmt also plans to deprecate the --backup option entirely, in rustfmt
2.0, and instead always rely on version control to track changes.
In addition, these types of ignores, just like ignores of editor backup
files, don't belong in .gitignore; they belong in people's personal
ignore files, such as ~/.config/git/ignore. See
https://julien.danjou.info/properly-managing-your-gitignore/ for further
explanation of that.
Given all three of those factors, drop the code to add **/*.rs.bk to
.gitignore, and update tests accordingly.
Various contributing docs updates.
Various updates to the contributing docs for running tests, building docs, etc.
This also includes the commit from #7632, which for some reason azure is having trouble getting started.
Stabilize profile-overrides.
This stabilizes the profile-overrides feature. This was proposed in [RFC 2282](https://github.com/rust-lang/rfcs/pull/2282) and implemented in #5384. Tracking issue is https://github.com/rust-lang/rust/issues/48683.
This is intended to land in 1.41 which will reach the stable channel on Jan 30th.
This includes a new documentation chapter on profiles. See the ["Overrides" section](9c993a92ce/src/doc/src/reference/profiles.md (overrides)) in `profiles.md` file for details on what is being stabilized.
Note: The `config-profile` and `named-profiles` features are still unstable.
Closes#6214
**Concerns**
- There is some risk that `build-override` may be confusing with the [proposed future dedicated `build` profile](https://github.com/rust-lang/cargo/pull/6577). There is some more discussion about the differences at https://github.com/rust-lang/rust/issues/48683#issuecomment-445571286. I don't expect it to be a significant drawback. If we proceed later with a dedicated `build` profile, I think we can handle explaining the differences in the documentation. (The linked PR is designed to work with profile-overrides.)
- I don't anticipate any unexpected interactions with `config-profiles` or `named-profiles`.
- Some of the syntax like `"*"` or `build-override` may not be immediately obvious what it means without reading the documentation. Nobody suggested any alternatives, though.
- Configuring overrides for multiple packages is currently a pain, as you have to repeat the settings separately for each package. I propose that we can extend the syntax in the future to allow a comma-separated list of package names to alleviate this concern if it is deemed worthwhile.
- The user may not know which packages to override, particularly for some dependencies that are split across multiple crates. I think, since this is an advanced feature, the user will likely be comfortable with using things like `cargo tree` to understand what needs to be overridden. There is [some discussion](https://github.com/rust-lang/rust/issues/48683#issuecomment-473356415) in the tracking issue about automatically including a package's dependencies, but this is somewhat complex.
- There is some possibly confusing interaction with the test/bench profile. Because dependencies are always built with the dev/release profiles, overridding test/bench usually does not have an effect (unless specifying a workspace member that is being tested/benched). Overriding test/bench was previously prohibited, but was relaxed when named profiles were added.
- We may want to allow overriding the `panic`, `lto`, and `rpath` settings in the future. I can imagine a case where someone has a large workspace, and wants to override those settings for just one package in the workspace. They are currently not allowed because it doesn't make sense to change those settings for rlibs, and `panic` usually needs to be in sync for the whole profile.
- There are some strange interactions with `dylib` crates detailed in https://github.com/rust-lang/rust/issues/64319. A fix was attempted, but later reverted. Since `dylib` crates are rare (this mostly applied to `libstd`), and a workaround was implemented for `build-std` (it no longer builds a dylib), I'm not too worried about this.
- The interaction with `share-generics` can be quite confusing (see https://github.com/rust-lang/rust/issues/63484). I added a section in the docs that tries to address this concern. It's also possible future versions of `rustc` may handle this better.
- The new documentation duplicates some of the information in the rustc book. I think it's fine, as there are subtle differences, and it avoids needing to flip back and forth between the two books to learn what the settings do.
Remove dep_targets.
This is just some code cleanup. The `dep_targets` method has been replaced by `unit_deps`, which doesn't force the creation of a new Vec.
vendor: don't use canonical path in .cargo/config
Use the user-specified path as-is, so it remains relative if specified as relative.
Should also address Windows path canonicalization issues.
Resolves issue #7316
Minor testsuite organization.
I sometimes get a little lost when looking for the right module for tests. This adds a brief comment to each one explaining what it is. This also includes a few renamed modules, and a few tests have been placed in a location that makes a little more sense to me. There shouldn't be any functional changes here.
- Move `build_lib` into `build`. It seemed a little strange to have these tests floating in a separate file.
- Rename `build_auth` to `git_auth`.
- Rename `small_fd_limits` to `git_gc`.
- Rename `resolve` to `minimal_versions`.
- Rename `overrides` to `replace`.
- Pull out `paths` overrides tests into a separate file.
Use the user-specified path as-is, so it remains relative if specified as relative.
Should also address Windows path canonicalization issues.
Resolves issue #7316
Add value OUT_DIR to build-script-executed JSON message
The target audience here is IDE authors, who can use this feature to
better support crates which generate code to OUT_DIR
Update documentation for custom target dependencies.
Closes#7613.
The old documentation was wrong, and hasn't worked for some time. It needs to be the file stem (see issue for discussion).
I also added a test, since I couldn't find any. It was remarkably awkward to add the test without build-std, so I just added it to a build-std test.
Document private items for binary crates by default
I suggested this change in default behavior [a long time ago](https://github.com/rust-lang/cargo/issues/1520#issuecomment-135215284) and [a year ago again](https://github.com/rust-lang/cargo/issues/1520#issuecomment-420616261). Both time, everyone seemed to agree that this is a good idea, so I thought I could just implement it.
This PR already changed the default behavior, but there are a few things we should talk about/I should do before merging:
- [x] ~~Do we *really* want this changed default behavior? If not, *why* not?~~ -> [yip](https://github.com/rust-lang/cargo/pull/7593#issuecomment-556482199)
- [x] Is changing this default behavior OK regarding backwards compatibility? -> [apparently](https://github.com/rust-lang/cargo/pull/7593#issuecomment-556482199)
- [x] ~~We should also probably add a `--document-only-public-items` flag or something like that if we change the default behavior. Otherwise users have no way to not document private items for binary crates. Right?~~ -> [We can do it later](https://github.com/rust-lang/cargo/pull/7593#issuecomment-557152039)
- [x] I should probably add some tests for this new behavior -> I did
- [ ] I don't like that I added `rustdoc_document_private_items` to `CompileOptions`, but this was the sanest way I could think of without rewriting a whole lot. Is this OK or how else would one do it? The flag would belong to `DocOptions`. But `compile` does not have access to that. Any ideas? Btw: If we also add `--document-only-private-items`, I would change the type from `bool` to `Option<bool>`.
Stabilize install-upgrade.
Tracking issue: #6797
This stabilizes the install-upgrade feature, which causes `cargo install` to reinstall a package if it appears to be out of date, or exit cleanly if it is up-to-date.
There are no changes from `-Zinstall-upgrade`. See [the old unstable docs](6a7f505a18/src/doc/src/reference/unstable.md (install-upgrade)) for a refresher on the details of what it does.
This also stabilizes the following changes:
- `--version` no longer allows an implicit version requirement like `1.2`. It must be either contain all 3 components (like `1.2.3`) or use a requirement operator (like `^1.2`). This has been a warning for a very long time, and is now changed to a hard error.
- Added `--no-track` to disable install tracking.
**Motivation**
I just personally prefer this behavior, and it has been requested a few times in the past. I've been using it locally, and haven't run into any issues. If this goes into 1.41, then it will release on Jan 30, about 10 months since it was added in #6798.
**Concerns**
Regarding some of the concerns I had:
- Is it tracking the correct set of information?
I'm satisfied with the current set. It also tracks, but does not use, the version of rustc and the version specified in the `--version` flag, in case we ever want to use that in the future. It is also designed to be backwards and forwards compatible, so more information can be added in the future. I think the current set strikes a good balance of tracking the really important things, without causing unnecessary rebuilds.
- Method to upgrade all outdated packages?
This can always be added as a new flag or command in the future, and shouldn't block stabilization.
- Should `--no-track` be kept? Does it work correctly?
I kept it. It's not too hard to support, and nobody said anything (other than maybe using a less confusing name).
- Should this be the default? Should there be a way to use the old behavior?
I like it as the default, and don't see a real need for the old behavior. I think we could always bring back the old behavior with a flag in the future, but I would like to avoid it for simplicity. There is also the workaround of `which foo || cargo install foo`.
Closes#6797.
Closes#6727.
Closes#6485.
Closes#2082.
Turn the new lock file format on by default
This commit enables the support added in #7070 by default. This means
that gradually over time all `Cargo.lock` files will be migrated to the
new format. Cargo shipped with Rust 1.38.0 supports this new lock file
format, so any project using Rust 1.38.0 or above will converge quickly
onto the new lock file format and continue working.
The main benefit of the new format is to be more friendly to git merge
conflicts. Information is deduplicated throughout the lock file to avoid
verbose `depedencies` lists and the `checksum` data is all listed inline
with `[[package]]`. This has been deployed with rust-lang/rust for some
time now and it subjectively at least seems to have greatly reduced the
amount of bouncing that happens for touching `Cargo.lock`.
Ignore file lock errors if unsupported, on Windows
Not all file systems support file locking; WSL’s network file system doesn’t seem to, and I don’t think other network file systems will, either (though I haven’t checked them). ERROR_INVALID_FUNCTION is Windows’ equivalent to Unix’s ENOTSUP and Linux’s ENOSYS which are checked just above.
Fixes#7511.
Add hack for fwdansi change.
This is a hack to fix a test failing on CI.
The issue is that fwdansi 1.1 was published with a change on how it processes reset codes. I have filed https://github.com/kennytm/fwdansi/issues/2 with some details on some of the issues.
This is just a workaround to get the test to pass. I'm not too happy with it, but other choices seemed less than ideal. Am happy to consider them, though:
- Remove fwdansi, and give up supporting color on Win 7/8, old 10.
- Change `Shell` so that it knows whether or not the console supports ANSI, and only use fwdansi when necessary. This means Win 10 would stop using fwdansi, but 7/8 would continue to use it. It is a little awkward – I think it would have to call wincolor::set_virtual_terminal_processing and see if it succeeds.
- Wait for a change to fwdansi to make resets more transparent.
I am very tempted by the first choice. rustc's color output has been broken on win 7/8 for a long time, and only a very small number of people have complained. I have spent way too much time dealing with something I think nobody really uses.
cc @kennytm
Not all file systems support file locking; WSL’s network file system
doesn’t seem to, and I don’t think other network file systems will,
either (though I haven’t checked them). ERROR_INVALID_FUNCTION is
Windows’ equivalent to Unix’s ENOTSUP and Linux’s ENOSYS which are
checked just above.
Fixes#7511.
Remove "cargo login" from user input when asking for login token.
Hey all!
This is my first time contributing to open source, but I realized that I could help some people out and make a quick change. 😄
When running cargo login, I was told to `please visit https://crates.io/me and paste the API Token below`. However, me on autopilot accidentally pasted the whole `cargo login $APITOKEN` string on the website into `cargo login` and it took me almost 30 minutes to figure out why I couldn't publish a package.
I thought it would be useful to automatically remove `cargo login` from the token, just in case someone makes the brain dead mistake like me.
Hope I can get some good feedback on this, have a great one! ❤️
Fix all Clippy suggestions (but not add it to CI 🙃)
This PR adds a `clippy` job to the Azure Pipelines CI.
In addition to adding the job, I made sure to fix all the lints in all the packages.
I'm new to Rust, so please check my code modifications extra carefully 😂
