Tracking Issue for path-bases

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.

Auto merge of #14360 - dpaoliello:basepath1, r=epage

Implement path-bases (RFC 3529) 2/n: `cargo add` support

Auto merge of #14427 - dpaoliello:add, r=epage

Implement path-bases (RFC 3529) 2/n: `cargo add` support

@dpaoliello

@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?

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.

@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? 🤨

@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" }

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").

I'd love to see home or user_home as a built-in path base. I already reported an existing use case for that here: #12874

I don't really understand the reason for package or current-dir. Isn't that the same as just not using a path-base? I think that might just lead to confusion.

Navigation Menu

Repository navigation

Tracking Issue for path-bases #14355

Summary

Changes from RFC

Unresolved Issues

Future Extensions

About tracking issues

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

Usage

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Tracking Issue for path-bases #14355

Description

Summary

Changes from RFC

Unresolved Issues

Future Extensions

About tracking issues

Activity

Sajjon commented on Jan 4, 2025

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

Usage

dpaoliello commented on Jan 6, 2025

Sajjon commented on Jan 6, 2025

dpaoliello commented on Jan 6, 2025

Sajjon commented on Jan 6, 2025

Wasabi375 commented on Nov 13, 2025

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

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