Added documentation for the configuration discovery of cargo install to the man pages

[jofas]

Fixes #11660.

[rustbot]

r? @ehuss

(rustbot has picked a reviewer for you, use r? to override)

[weihanglo]

You've written something pleasing to read! Thank you! However, this is probably a breaking change for someone depending on old cargo uninstall behaviour. Could we split this PR into two, so we can approve cargo install part and discuss the other half afterward?

BTW, I think we may want to first warn the user who depends on the behaviour of implicit config discovery in cargo uninstall. After a transition period, we can then turn the warning into an error.

[jofas]

However, this is probably a breaking change for someone depending on old cargo uninstall behaviour. Could we split this PR into two, so we can approve cargo install part and discuss the other half afterward?

Of course. Never contributed to a project that can't make a breaking change, release a new version and call it a day 😅.

I'll split the breaking changes and make a new PR. Maybe we could use that PR to also tackle the fact that install starts configuration discovery at $CARGO_HOME/config.toml, whereas I think it would be more natural to anchor configuration discovery at $CARGO_HOME/config.toml, not start it, like you already pointed out in the issue:

cargo/src/bin/cargo/commands/install.rs

Lines 93 to 94 in efd3733

	// TODO: Consider calling set_search_stop_path(home).
	config.reload_rooted_at(config.home().clone().into_path_unlocked())?;

---

BTW, I think we may want to first warn the user who depends on the behaviour of implicit config discovery in cargo uninstall. After a transition period, we can then turn the warning into an error.

Can you point me to a location in the source where cargo already has such a warning? Then I could create a PR for the warning as well (of course only if that is something you'd want).

[weihanglo]

Can you point me to a location in the source where cargo already has such a warning? Then I could create a PR for the warning as well (of course only if that is something you'd want).

You'll find them by searching “hard error” or “transition period” in this repository, such as:

cargo/src/cargo/ops/cargo_package.rs

Lines 299 to 306 in 65cab34

	ws.config().shell().warn(&format!(
	"license-file `{}` does not appear to exist{}.\n\
	Please update the license-file setting in the manifest at `{}`\n\
	This may become a hard error in the future.",
	license_path.display(),
	rel_msg,
	pkg.manifest_path().display()
	))?;

[weihanglo]

Looks pretty good! Thanks for the update :)

[weihanglo]

@bors r+

[bors]

📌 Commit eaf055f has been approved by weihanglo

It is now in the queue for this repository.

[bors]

⌛ Testing commit eaf055f with merge e578c67...

[weihanglo]

BTW, @jofas could you squash these commits so that we won't have things added and removed making the history confusing? No problem if you're unable to do that.

[jofas]

Sure, I can squash the commits into a single one. Can you stop bors from merging?

[weihanglo]

@bors r-

[weihanglo]

BTW, if the bot detects more commits being pushed, it will cancel the merge automatically.

[jofas]

Thanks, good to know. I squashed the commits.

[weihanglo]

Thanks a lot!

@bors r+

[bors]

📌 Commit e011901 has been approved by weihanglo

It is now in the queue for this repository.

[bors]

⌛ Testing commit e011901 with merge 447ccb4...

[bors]

☀️ Test successful - checks-actions
Approved by: weihanglo
Pushing 447ccb4 to master...