Help new users understand the unintuitive crate name -> Rust namespace mapping for hyphenated names

[Timmmm]

Problem

An annoying papercut with Rust is crate names containing hyphens, e.g. aho-carosick.

It has been a number of years since I learned this, but at some point I knew that you accessed crate members based on the crate name:

use crate_name::foo;

but I did not know that crate names with hyphens were automatically converted to underscores. I know it sounds obvious if you already know it, but really - this is not obvious, nor is it easy to search for a solution.

Even worse if lib.name is set (see also #6827)

I think Cargo (and crates.io, but I guess that's out of scope here) could do more to help:

Proposed Solution

1. When you create a new crate via cargo init with a crate name containing hyphens, warn that it may be confusing to new users because the crate name doesn't match the crate name. This could be a one-time or few-time warning, so as not to annoy people. See also Ask for confirmation of certain crate data on first publish #8883
2. When you cargo add aho-carosick, note that you will need to use aho_carosick in code. Ditto on few-time warnings. Currently it actually warns in the opposite direction which is kind of silly: warning: translating regex_syntax to regex-syntax.
3. crates.io should list the command as cargo add aho_carosick not cargo add aho-carosick. Both work but the former makes it more obvious how to use the code.

It's going to be really easy for seasoned Rust developers (including me, now) to dismiss this as trivial and obvious. Trust me it wasn't when I was learning, and I'm sure it isn't for many other people.

[epage]

For (1) and (3), as mentioned at #2775 (comment), these make the use of underscores the preferred solution for package names and the Cargo team is not ready at this time to weigh in on making - or _ the preferred case.

Note that this problem isn't just about translating - to _ but users can also override the namespace using lib.name (see also #6827).

Quoting from #2775 (comment)

Another issue brought up in this thread that is indirectly related to the problem at hand which is translating dependency names to Rust namespaces. We now have docs.rs and if packages provide examples, that should help clarify things. For further improvement, I'd recommend creating an issue against rust-lang/rust for trying to detect when - is used in a root namespace and suggest changing it to _.

(emphasis added)

[epage]

2. When you cargo add aho-carosick, note that you will need to use aho_carosick in code. Ditto on few-time warnings. Currently it actually warns in the opposite direction which is kind of silly: warning: translating regex_syntax to regex-syntax.

Quoting from #2775 (comment)

I think its at least worth exploring (in a separate space as noted above) My main is balancing is being too helpful and being noisy in our output. Its not always about one particular message but what principle we apply for preventing "add a message" gradually turning into 10 messages being added. We've talked about git-like advice which can be disabled in config. It'd help if we had a stable way of setting config on the command-line for easy copy/paste disabling of advice.

[epage]

Trust me it wasn't when I was learning, and I'm sure it isn't for many other people.

What was your background before Rust?

I know at least Python has this problem and I wouldn't be surprised if most other packaging systems have it. That doesn't mean we can't improve on them but looking for more context to understand the problem.

[Timmmm]

What was your background before Rust?

Mostly C++, some Java, Python, Typescript, etc. They all have wildly different approaches to this problem so none of it really helped. I don't think "the namespace name is the crate name with - converted to _" is a common enough idiom for any prior experience to help. But also I agree that we shouldn't rely on new users being familiar with other languages that do the same surprising thing.

users can also override the namespace using lib.name

True, but I expect that is extremely rare and probably not worth worrying about. This doesn't have to be perfect in every case in order to be useful & better.

[Timmmm]

Cargo team is not ready at this time to weigh in on making - or _ the preferred case.

For (1) I don't think a warning about potential confusion crosses that line?

Btw it doesn't feel very nice for my proposals to be unilaterally crossed out. 🙁 Do I edit it back? I think it's better etiquette to stick to comments until there is agreement, or add a new section at the top of the original one with "original issue:", or to add attributed comments.

Anyway I would say (2) is probably the biggest improvement and also easiest and least controversial - I'm happy to contribute a PR if people want?

[epage]

Mostly C++, some Java, Python, Typescript, etc. They all have wildly different approaches to this problem so none of it really helped. I don't think "the namespace name is the crate name with - converted to _" is a common enough idiom for any prior experience to help. But also I agree that we shouldn't rely on new users being familiar with other languages that do the same surprising thing.

At least C++ and Python do not support - in namespaces. At least Python does allow - in package names. Python also has an issue like lib.name in that the package name can be different than the namespace (directory in the source). C++ is too scattered on packaging systems to say much.

Examples

• grephene-pydantic / from graphene_pydantic import PydanticObjectType, see https://pypi.org/project/graphene-pydantic/ (found via random search)
• Its been a while but I remember some CamelCased package names when the namespace is snake_case. There might have even been a case where a Py prefix was removed

For (1) I don't think a warning about potential confusion crosses that line?

Generally people treat "warnings are bad" and they exert subtle pressure to change behavior.

Btw it doesn't feel very nice for my proposals to be unilaterally crossed out. 🙁 Do I edit it back? I think it's better etiquette to stick to comments until there is agreement, or add a new section at the top of the original one with "original issue:", or to add attributed comments.

Sorry, no intent to give offense. I was trying to clarify the state of things to streamline the conversation. If I wait for "agreement", the question is also among whom and what is needed for that? Waiting in those kind of scenarios can make things too open ended to ever be closed out.

I crossed them out from my knowledge of the state of the Cargo team and from what behavior those suggestions would drive which runs counter to the state of the Cargo team.

Anyway I would say (2) is probably the biggest improvement and also easiest and least controversial - I'm happy to contribute a PR if people want?

Note that we generally encourage waiting for Issues to be Accepted before moving forward, see https://doc.crates.io/contrib/process/working-on-cargo.html#before-hacking-on-cargo

While this item is less controversial, it doesn't mean its an automatic acceptance and I've mentioned a concern and a way to mitigate it but it requries more design work, see #15887 (comment)