Tracking Issue for path-bases

[dpaoliello]

Summary

RFC: #3529
Original issue: #9855
Documentation: https://doc.rust-lang.org/nightly/cargo/reference/unstable.html#path-bases
Implementation:

• Implement path-bases (RFC 3529) 1/n: path dep and patch support #14360
• Implement path-bases (RFC 3529) 2/n: cargo [add|remove|update] support #14427
• 3/n [patch] table in config support

Introduce shared base directories in Cargo configuration files that in turn enable base-relative path dependencies.

Changes from RFC

• base naming was switched to package / registry naming rules, meaning we support unicode instead of just ASCII (Implement path-bases (RFC 3529) 1/n: path dep and patch support #14360)

Unresolved Issues

• How should each layer (config, eventually manifest) layer? Section-wide, per-field? We should have tests to confirm the approach we have
• Can we switch our existing "make dep paths absolute" to build on top of this? (Implement path-bases (RFC 3529) 1/n: path dep and patch support #14360)
• What exact names we should use for the table (path-bases) and field names (base)?
• What other built-in base paths could be useful?
  • package or current-dir for the directory of the current project?
  • home or user_home for the user's home directory?
  • sysroot for the current rustc sysroot?
• Do we actually want to support the [patch] table? Adding support for [patch] in config files greatly complicates the implementation
• Should base = "workspace" work with implicit workspaces?

Future Extensions

• Add support for declaring path bases in the manifest
  • Motivating example: You have a Git dependency that has a path dependency to one of its submodules. It would be nice if the Git dependency could use a path base to point to the submodule, but currently this is broken as the configuration file in that git dependency is never loaded. See https://blog.rust-lang.org/inside-rust/2024/08/15/this-development-cycle-in-cargo-1.81.html#path-bases
• Path bases relative to other path bases
• Path dependency with just a base
• Git dependencies

About tracking issues

Tracking issues are used to record the overall progress of implementation.
They are also used as hubs connecting to other relevant issues, e.g., bugs or open design questions.
A tracking issue is however not meant for large scale discussion, questions, or bug reports about a feature.
Instead, open a dedicated issue for the specific matter and add the relevant feature gate label.

[Sajjon]

@dpaoliello this makes it possible to shorten the chars needed when specifying paths in workspaces, which is a great feature.

But even better a feature would be to be able to declare paths like constants, once and reuse them everywhere. Has this been pitched / discussed? I understand this is a tracking issue for path-bases specifically, so sorry to hijack this issue, but what I propose is related to the problem which this tries to solve: better ergonomics for my-crate = { path = "../my-crate" } config.

Imagine many crates (30+) in a single workspace, where I would like to group some crates together on filesystem by use of folders. We note that this is ofc opaque to cargo, but filesystem grouping is still good for IDE exploration and git.

Project root:

crates/
    core/
        utils/
            Cargo.toml
            src/
                lib.rs
        error/
            Cargo.toml
            src/
                lib.rs
    clients/
        http/
            Cargo.toml
            src/
                lib.rs
        database
            Cargo.toml
            src/
                lib.rs
    really_huge_structure/
        logic/
            foo/
                Cargo.toml
                src/
                    lib.rs
            bar/
                Cargo.toml
                src/
                    lib.rs
        models/
            foo/
                Cargo.toml
                src/
                    lib.rs
            bar/
                Cargo.toml
                src/
                    lib.rs
Cargo.toml
README.md

many many crates omitted, very simplified!

I now have to specify the path foo-logic = { path = "../crates/really_huge_structure/logic/foo" } many times whenever it is references in the 30 other crates. path-bases could give me a variable for crates/really_huge_structure, right?

But even better would be:

Declaration in Cargo.toml in root (the workspace toml)

PATH_FOO_LOGIC = "../crates/really_huge_structure/logic/foo"

Usage

In some workspace crates toml
foo-logic = { path = "$PATH_FOO_LOGIC }

Or can a path-base be a full path? If so I guess this feature gives me what I want? And/or can a path-base reference another path base?

[dpaoliello]

Or can a path-base be a full path? If so I guess this feature gives me what I want? And/or can a path-base reference another path base?

Path base can be either relative or absolute. Note that relative paths are relative to the declaring config.toml, which makes it convenient for scenarios like yours where there is a common parent directory.

In .cargo/config.toml:

[path-bases]
core = "../crates/core"
clients = "../crates/clients"
logic = "../crates/really_huge_structure/logic"
models = "../crates/really_huge_structure/models"

Which makes the cargo.toml quite nice:

foo-logic = { path = "foo", base = "logic" }

That all said, I think a workspace may be better suited for your scenario than relying on path base.

[Sajjon]

@dpaoliello cool! Im using workspaces, but I don't think I can use workspace = true for one of my crates in my workspace, can I? 🤨

[dpaoliello]

@dpaoliello cool! Im using workspaces, but I don't think I can use workspace = true for one of my crates in my workspace, can I? 🤨

Yep, it's a bit verbose since you have to repeat everything, but you can list each of the workspace members as a path dependency in the workspace and then inherit those in the member manifests.

[workspace]
members = [
    "crates/really_huge_structure/logic/foo",
    ...
]

[workspace.dependencies]
foo-logic = { path = "crates/really_huge_structure/logic/foo" }

[Sajjon]

Thank you! That is fantastic! I thought to try it first, but then I deemed it as silly, but it is way better than repeating a "core" crate many many times with path also being different (for nested crates at different directory "depths").