Variable interpolation in Cargo.toml

1

Hi,

I ran into the following problem today. I have a Cargo.toml file, linking to docs.rs as a documentation link. It looks like this:

[package]
name = "my_lib"
version = "1.0.1"
documentation = "https://docs.rs/my_lib/1.0.1/"

The problem is that - on any update - I have to keep those two version strings in sync.

Would it make sense to allow interpolation in strings in Cargo.toml? As an example

[package]
name = "my_lib"
version = "1.0.1"
documentation = "https://docs.rs/my_lib/{$package.version}/"

Iā€™m aware that this leads down the road of Maven, but I think it is a reasonable motivating example. On the other hand, Iā€™m not sure how pervasive that problem is otherwise.

Another option would be to hand off such a task to tools like cargo-edit, but that would lead down the road of having an ever-expanding, de facto necessary toolchain, just to keep the core of the language.

1 Like
2

Maybe white-list the environment variables Cargo promises to make available, and use UNIX shell substitution syntax.

On a tangential note, Iā€™m not sure why we donā€™t just default documentation to "https://docs.rs/$NAME/$VERSION" at this point.

1 Like
3
4

Or just link to https://docs.rs/my_lib and it will redirect to the latest version. Letā€™s keep things simple.

6 Likes
5

That means that if you click on the documentation link in crate 1.0.1, it will send you to 2.0.whateverlatest. Thatā€™s very confusing and bad UX.

Reading the wrong version of the docs is a very common error.

2 Likes
6

IMO this seems like an issue for toml, not cargo. Adding this to cargo post-toml parsing would be a significant divergence from the standard, and having a specified standard was the reason we adopted toml.

2 Likes
7

Hand off the substitution task? Or just the redundant version bumps? I think the latter is totally reasonable, to have a tool that knows how to bump both a version and docs.rs in tandem, and it's not "de facto necessary" if it's just doing something you can still do manually.

8

There is already rusty-release and semantic-rs that bump the version of your crate. They could be modified to also update the documentation link.

2 Likes
9

One data point: in our project (Fuchsia) weā€™re struggling with how to point to generated IDL binding crates (the directory where the generated code goes is variable), and interpolation has come up as one possible solution. Iā€™m not saying itā€™s the best solution, but if this were to be adopted, we would find it useful.

10

I don't see how that would go against the TOML format. The spec itself includes strings as examples which are later subject to substitution. (not through values from the same file, I give you that). I still do not see how TOML would prohibit further interpretations of the values given in the file.

1 Like
11

It doesnā€™t violate the spec, but it does diverge from it. Substitutions ought happen during the parsing layer, not during the layer at which cargo operates. We are applying additional layers of syntactic significance to strings that donā€™t exist in the TOML format. Suppose toml does add substitutions like this, but using a different syntax. Now we have to support two redundant string interpolation formats.

12

Well, thatā€™s the danger of using a format marked as version 0.4.0 as the first big user. :slight_smile:

In that case, such a feature should be discussed with the relevant team before, but that shouldnā€™t factor into the discussion whether thatā€™s a desired feature or not for Cargo.

13

This topic was automatically closed 90 days after the last reply. New replies are no longer allowed.