Implement support for base paths (RFC 3529)

[dpaoliello]

RFC: rust-lang/rfcs#3529
Tracking Issue: #14355

Introduce a table of path "bases" in Cargo configuration files that can be used
to prefix the path of path dependencies and patch entries.

This feature will not support declaring path bases in manifest files to avoid
additional design complexity, though this may be added in the future.

Motivation

As a project grows in size, it becomes necessary to split it into smaller
sub-projects, architected into layers with well-defined boundaries.

One way to enforce these boundaries is to use different Git repos (aka
"multi-repo"). Cargo has good support for multi-repo projects using either git
dependencies, or developers can use private registries if they want to
explicitly publish code or need to preprocess their sub-projects (e.g.,
generating code) before they can be consumed.

If all of the code is kept in a single Git repo (aka "mono-repo"), then these
boundaries must be enforced a different way: either leveraging tooling during
the build to check layering, or requiring that sub-projects explicitly publish
and consume from some intermediate directory. Cargo has poor support for
mono-repos: the only viable mechanism is path dependencies, but these require
relative paths (which makes refactoring and moving sub-projects very difficult)
and don't work at all if the mono-repo requires publishing and consuming from an
intermediate directory (as this may very per host, or per target being built).

This RFC proposes a mechanism to specify path bases in config.toml files which
can be used to prepend path dependencies. This allows mono-repos to specify
dependencies relative to their root directory, which allows the consuming
project to be moved freely (no relative paths to update) and a simple
find-and-replace to handle a producing project being moved. Additionally, a
host-specific or target-specific intermediate directory may be specified as a
base, allowing code to be consumed from there using path dependencies.

Implementation Details

• Adds support in path dependencies and patch table.
• Validates base path names conform to RFC.
• Adds workspace built-in path base.
• Adds support for cargo add (via --base option).
• Adds documentation to the reference.

[rustbot]

Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @ehuss (or someone else) soon.

Please see the contribution instructions for more information. Namely, in order to ensure the minimum review times lag, PR authors and assigned reviewers should ensure that the review label (S-waiting-on-review and S-waiting-on-author) stays updated, invoking these commands when appropriate:

• @rustbot author: the review is finished, PR author should check the comments and take action accordingly
• @rustbot review: the author is ready for a review, this PR will be queued again in the reviewer's queue

[epage]

Blocked on rust-lang/rfcs#3529

(doing this just to make it obvious in tandem with the draft status)

[dpaoliello]

FYI, there appears to be a bug where, if a workspace has a path dependency with a base, then the member using that workspace dependency still sees the path relative to the workspace Cargo.toml rather than as-written - I'm currently looking into a fix.

[bors]

☔ The latest upstream changes (presumably #13080) made this pull request unmergeable. Please resolve the merge conflicts.

[bors]

☔ The latest upstream changes (presumably #13296) made this pull request unmergeable. Please resolve the merge conflicts.

[dpaoliello]

Question for reviewers: should I remove the documentation (either for the feature itself or for cargo add), or just mention that it is currently unstable?

[epage]

CLI flags should have (unstable). All other documentation should live on https://doc.rust-lang.org/cargo/reference/unstable.html until stabilized.

[epage]

I might not get to this for a few days. Something that might be helpful is to split the core feature PR from cargo add. Keeping the PRs smaller will make them easier to review (there are times where I have a PR that is just adding the unstable feature flag and a placeholder location in the docs) and cargo add support for things tends to be a feature in of itself.

[dpaoliello]

I might not get to this for a few days. Something that might be helpful is to split the core feature PR from cargo add. Keeping the PRs smaller will make them easier to review (there are times where I have a PR that is just adding the unstable feature flag and a placeholder location in the docs) and cargo add support for things tends to be a feature in of itself.

Fair enough: I'll convert this to a draft and then split it into chunks.

[dpaoliello]

Splitting this PR into a series of smaller PRs