[Pre-RFC] Resolve support for hyphens in crate names

[jminer]

When I was naming a couple crates (not on crates.io yet), I first used hyphens to separate words because I think they look a little better than underscores.

I tried using extern crate crate-name, got a compile error, and had to do multiple Google searches to find the right syntax. Even if it was added to the beginner tutorial, it would be fairly easy to forget by the time you end up using a crate with a hyphen. When I found out the special syntax needed for crates with hyphens, I renamed the crates to use underscores.

I think the complications of having crate names not be identifiers or of using fuzzy matching outweigh their benefits.

[DanielKeep]

So thus far, the opinions on this are roughly summarised as:

• Hyphens in crate names are bad, something should be done about them: 5.
• Hyphens in crate names are pretty: 2.

Just to note: this is not to denigrate anyone’s opinion. It’s just that no one who said they liked how hyphens looked commented on the practical problems they cause. Again, literally the only defense of hyphens in the abstract is that they look nice.

As for expressed opinions on possible solutions…

• Forbid them: 2.
• Nothing, just recommend against them: 1.
• Not stated: 4.
• N/A: 1.

I hardly feel this is a good sample size. I was hoping to get some feedback to maybe help guide which specific proposal to go with, but I think that would be premature. I’m going to post this to the Reddit later today, and see if I can’t get some more input on this.

At present, I’m leaning toward a more well-defined fuzzy matching, where crate names are canonicalised into identifiers by replacing all punctuation symbols with underscores and continuing to forbid non-ASCII letter and digit codepoints. The idea being that symbols that Rust is unlikely to ever support in identifiers get turned into underscores, whilst letters and digits that might be allowed in future don’t.

[oderwat]

I think hypens should be removed and forbidden. I also think that this should be changed quickly before there are even more crates with hypens in the name. People are used to rewrite a lot of code every some days at the moment. Later on that would be even more of a pain to do. Using hypens also looks a bit like simulating namespaces to me: rustc-something?

[phaylon]

There is also an aesthetic reason I’m generally against the hyphens: If you have to use extern "..." as "...", it mixes hyphen-fixes with actual renames. Though it’s not a big one, it just bugs me a bit.

That being said, has it been proposed to just give extern crate an identifier and a quoted string form, with the latter having a simplifier? Examples:

// loads foo_bar as foo_bar
extern crate foo_bar;

// loads foo-bar as foo_bar
extern crate "foo-bar"

// loads foo_bar-sys as foo_bar_sys
extern crate "foo_bar-sys";

This could probably be extended to other characters, like the above mentioned dot:

// loads windows.data.pdf.lib as windows_data_pdf_lib
extern crate "windows.data.pdf.lib";

Though at that point, I’d expect the deciding factor will be what cargo can support for crate identifiers. At least the dot seems semantically important there.

[nstoddard]

I agree that dashes are prettier than underscores, but I think we should keep crate names consistent with identifiers - we should forbid dashes entirely. I’m against anything like fuzzy matching, because it seems like a hack and it adds needless complexity to the language. Forbidding dashes will result in some churn, but I think it’s preferable to the alternatives.

[retep998]

I’m in favor of getting rid of hyphens on the condition that I can use namespaces on crates.io. If I can turn something-sys into winapi/something then I will be happy (with some bikeshedding over winapi vs winsdk vs wsdk vs win32 vs win vs windows. Gah, I’ll just start a poll when you guys decide to add namespaces and get rid of hyphens).

[michaelsproul]

+1 for forbidding hyphens entirely. I think we should all just use underscores and accept the minor aesthetic burden.

For a typical chunk of Rust code, we already have the following names:

• Source code repository name - can contain hyphens.
• Cargo package name - as declared in Cargo.toml and used on crates.io.
• Crate name(s) - should be identifiers.

I think unifying these names for simple packages is desirable. Bubbling up the crate name makes the most sense, and is least surprising for users.

[mikedilger]

+1 to treat crate names as identifiers and forbid hyphens. Lets take the pain now rather than live in pain forever.

[aidancully]

I’d also advocate just removing hyphens and requiring underscores, at least for 1.0. Post-1.0, new facilities (like namespaces) could be added, and restrictions on names can be loosened if it’s determined that they are too tight, but it’d be impossible to tighten the symbol-naming restrictions post-1.0 in a backwards-compatible way. So the safe path forward seems (to me) to be using the more-restrictive option until the less-restrictive option gets more fully fleshed out.

For whatever it’s worth, I also prefer hyphens to underscores aesthetically, and I also like the ability to rename crates on import, so the status-quo isn’t that bad, for me. BUT I also feel like the current design is not that future-proof (if something like namespaces get folded in, in particular), so rather than have 1.0 block on getting the right design right now, I’d like to see the current behavior stripped to its future-proof essence, so that a better facility could be added even after 1.0 (if that’s how long it takes to design).

[Marius]

For esthetic reasons I prefer dashes in file names, however I agree that having crate names as valid Rust identifiers is a strong reason to disallow them. For Rust adoption in the enterprise we should add namespaces at some point and it will remove namespace as an use case for dashes.

Should I start a separate RFC for namespaces or has this already been discussed and decided upon?

[drewm1980]

+1 for forbidding dashes to stay consistent with identifiers. When I was learning Cargo I got the false impression that hyphens were a de-facto standard, and then got totally tripped up on where to use a dash vs. an underscore in the repo name, the .toml name, the name in the import statement, etc… This is part of the reason I have referred to the module system as non-obvious in some other threads. New users should not have to think about this; they should just see that everyone is using underscores everywhere, follow that, and have things “just work”.

Keep in mind that the vast majority of Rust code has never been written, most Rust users have not even tried Rust yet, and most of the code out there now will be broken before 1.0 anyway.

@retep998, thanks for being so gracious about this proposal; I hope it is both fixed AND you get a convient migration path!

[riccieri]

What about repurposing using the #[link] attribute (or creating a new one, if that’s confusing) to set the crate name (and presumably allowing dots too), instead of having special syntax for this?

#[link(name = "windows.data.pdf.lib")]
extern crate windows_pdf;

[lfairy]

@DanielKeep are you still working on this?

I very much support this proposal, and would be happy to pick up where you left off.

[DanielKeep]

I’m partway through writing up the revised version, taking the comments into account.

The hard part is… looks around I really want hyphens to stay on in some form, but I can’t reconcile that with the overwhelming “only idents everywhere” position that is, logically, the most reasonable: no rule to have it explain is better than any rule that has to be explained.

At this point, I’m just going to have to just lie in the bed I made and work out how in the hell to transition retep’s twenty zillionty hyphenated packages.

I might leave the door open by writing it up as “no hyphens anywhere at all… at least until after 1.0”.

[tomjakubowski]

I would favor using hyphens in package names but simply having a convention, perhaps enforced by Cargo by default, that hyphenated package names produce underscored crate names.

You can already name the “lib” crate name for a package to whatever you want, I believe.

[lfairy]

I would favor using hyphens in package names but simply having a convention, perhaps enforced by Cargo by default, that hyphenated package names produce underscored crate names.

You can already name the “lib” crate name for a package to whatever you want, I believe.

I think we can implement that as a lint in rustc, actually.

Something like this:

warning: crate names with hyphens ("foo-bar") are awkward to use, #[warn(hyphenated_names)] on by default
help: consider renaming the crate with #![crate_name="foo_bar"]

[tomjakubowski]

That’s one idea! The help might be better if it were more Cargo-oriented, since the preferred way to specify a Cargo crate (not package name) is to use [lib] name = "whatever".

Like this:

[package]

name = "iron-fizzbuzz-middleware"
version = "0.0.1"
authors = ["Tom Jakubowski <tom@crystae.net>"]

[lib]
name = "iron_fizzbuzz_middleware" # or even "fizzbuzz_middleware", to use pseudo package namespacing

[lfairy]

EDIT: See better proposal below

Of course! Would something like this:

warning: crate names with hyphens ("foo-bar") are awkward to use, #[warn(hyphenated_names)] on by default
help: consider renaming the crate in your Cargo.toml:
    [lib]
    name = "foo_bar"
help: alternatively, add #![crate_name="foo_bar"] to the crate root

work for you? It’s hard to explain the whole fix without bloating the message too much; I think it can be tweaked more.

I want to keep it as a rustc lint, because:

1. Hyphenated names are awkward in general, not just with Cargo-ified libraries;

2. If the user really wants a hyphenated crate name, they can silence the warning using the existing infrastructure (#[allow] or -A). I don’t think there’s a good way to silence Cargo warnings (feel free to correct me on this).

Actually it would be nice if rustc detected if it was being called by Cargo or not, and gave an appropriate suggestion based on that. Maybe an environment variable or something. But I’m not sure whether that’s worth the extra complexity in the compiler.

[lfairy]

The more I think about it, the more I’m convinced that we should just have Cargo warn unconditionally on hyphenated crate (not package) names. Someone along the line will need to rename the crate anyway; better it be the maintainer, not the user.

People who don’t use Cargo will miss out on the warning, but I think we can live with that.

---

EDIT: Okay, I think I’ve got it down to a concrete proposal:

1. If a user invokes cargo new with a hyphenated name, and the --bin option is not present, automatically apply the Jakubowski renaming trick on the crate name (not the package name).

   • Rationale: Hyphenated names are bad for library crates, but for executables it doesn’t matter.

2. If an existing (library) package has a hyphenated crate name (not the package name), Cargo should warn every time the package is built. The warning should include a short explanation of the problem, plus a snippet that the user can paste right into their Cargo.toml.

3. On crates.io, reject any new uploads which would warn under part 2. This change can come after a grace period, so that everyone has a chance to be warned in Cargo first.

@alexcrichton @DanielKeep @retep998 @tomjakubowski @everyone-else Does this sound reasonable to you all?

[nightpool]

I came into this thread expecting to be completely against it (I’m a big believer in aesthetics) but these proposals sound eminently reasonable to me. I’d prefer if we could use hyphenated identifiers of course, but that’s a much bigger change :​D