Naming convention for crates

[dtolnay]

The current guideline says "snake_case (but prefer single word)." Is this still the case? Why do new high-profile crates like tokio-core use kebab case?

[dtolnay]

I still think it shouldn't matter. rust-lang/cargo#2775

[chris-morgan]

Two things are being conflated here: crates and packages.

A crate is the unit of compilation and that which you import into your code; its name must be a Rust identifier, and is conventionally unspecified, allowing it to determined automatically (from the package name with - changed to _, for library crates).

A package is the directory containing Cargo.toml, which could include a lib crate, multiple bin crates, examples, tests, &c. It is their naming convention that is unclear—though there are certain strong subconventions like *-sys. (The history of hyphens versus underscores is not particularly well documented; yet I say that kebab-case was the preferred convention the last time this was discussed; snake_case has gained in popularity because no declaration was made at that time of one particular form as preferred.)

[dumindu]

Rust having workspaces, crates and mod/ modules.

1. Why we need another layer / packages?
2. Personally, I think "packages" naming is quite bad because crates are packages in Rust v1? Correct me if I am wrong.

[Enet4]

The concept of package does exist as a separate concept from crate. And many packages have more than one crate. I don't think we're in a great position to change the names at this point.

[dumindu]

I'm quite aware that now we can't change the naming but I am trying to understand why we need another layer. Ex. Previously https://github.com/rust-lang/rust/tree/master/src was a workspace and std crates separation was consistent and visible in the source. Any reason behind the changes and using some Python code? Ex. In real world projects also can't handle all only using Rust?

PS. About the content in https://doc.rust-lang.org/cargo/appendix/glossary.html -> Package, Package manager, Project

Cargo is the package manager within the Rust ecosystem.

But it downloads crates from crates.io.

Project: Another name for a package.

Bit confusing!

[BurntSushi]

why we need another layer

The layer already exists.

[cheako]

This is confusing, I'm looking to run cargo new on a polar perlin noise loop... Well actually polar OpenSimplex noise loop. The loop is optional as I can't find /polar perlin noise .*/ that's not loop.

What should I type, should I just make up some silly name or acronym so it's one word?

[chris-morgan]

@cheako That’s not the type of naming convention that’s being spoken about here. You could call it polar-opensimplex-noise-loop if you wanted to if that’s not taken, or some other silly name, or whatever you like. What’s being talked about here is matters like whether you should use _ or -; that you should shun -rs suffixes and rust- prefixes; the convention of -sys suffixes; and any other conventions like foo being accompanied by foo-macros and foo-shared crates where necessary.

[dlee13]

I'm still confused. Should my new rust project use snake_case or kebab-case?

[BurntSushi]

Personally, I have always, and continue to use, kebab case for crate names.

[dumindu]

With reference the discussion had in r/rust/,

Even though snake_case is the initial convention on crates and file names, even the official docs uses kebab-case on crate names and in some examples, both snake_case and kebab-case have been mixed while naming files.

example:

• https://doc.rust-lang.org/book/ch07-01-packages-and-crates.html
• https://doc.rust-lang.org/cargo/guide/project-layout.html

In general, Rust tends to use UpperCamelCase for "type-level" constructs (types and traits) and snake_case for "value-level" constructs.
_ https://rust-lang.github.io/api-guidelines/naming.html

To reduce confusions and to make docs and code more consistent, I think better promote snake_case instead kebab-case, at least on official docs.

And this issue is already 3 years old :)

[daira]

Given that -s in the package name are going to be changed to _s anyway in the code by default, why would you use anything other than snake_case for package names? It's not as though - has any semantic significance; it's just a pointless source of variation.

[jocutajar]

I like your point, except: "-" is a word separator, while "_" is not, at least for the most obvious web search engines, apparently. So if you're concerned about SEO ranking and linking and those weird things, dash is preferable. Ambitious projects may seek better SE visibility. On the other hand, we have other tools to search the code so sticking to snake_case there is fine. I would have preferred if this wasn't the case. Same package and crate name, either way, dash way, under way, dotnet way... but same. It bugs me time and again to spell it out differently in Cargo.toml and in .rs. But I'm just a mortal and this is not the biggest hurdle after all. I named my co-crates with a dash, as I perceived it the standard: samotop, samotop-delivery, samotop-this-and-that. Imagine if IDE tooling could figure out exactly the crate you are referring to from the code and add the latest version to Cargo.toml. The transformations complicate it somewhat.

[dumindu]

OMG! should language conventions consider about SEO optimization as well? 🤦 And some languages use PascalCase for modules.

What I think is we should promote correct & more consistent conventions and https://crates.io to search crates :)

[jocutajar]

correct & more consistent conventions

Perhaps that's all I wanted to say. I wish there was a clear convention. But there wasn't and now we have a mess. God has nothing to do with it :)

[Ryder17z]

I like your point, except: "-" is a word separator, while "_" is not, at least for the most obvious web search engines

Which is backwards compared to how it should be. Most applications replace spaces with underscores when required, not dash.
(I apologize for throwing this comment in here a year later.)

[seancfoley]

When it comes to the English language (and many other languages), using "_" is backwards. The hyphen "-" has long been used as a word separator. The underscore was never used as a word separator until compute computer programmers started doing it in code. You'll never find it in a book or an article.

Search engines use language as their primary input, and programmers lean towards using common language to name their projects, which is why so many have been using "-" to name their crates.

So, jocutar has a good point, the highest level naming constructs should better be modeled after common language. Using "_" is backwards from that perspective.

[camsteffen]

A naming convention has already been accepted in RFC 430. The fact that it has not been followed is an issue. But, in my opinion, removing the convention altogether is not merited.

[e-ivkov]

I think it is better to remove unclear part in the rust docs if the RFC 430 was already accepted.

[Kinrany]

RFC 430 specifies a naming convention for crates, but not for packages. See also this comment about the difference between the two.

As far as I understand, package names lie in the domain of Cargo and not the Rust language proper, so it kinda makes sense that language API guidelines wouldn't mention packages at all.

But it also makes sense to disambiguate. In addition to changing the "unclear" part to "snake_case", we could add a link to a Cargo doc that clarifies the difference between crates and packages and documents the naming convention for packages (or states that none exists yet).

Rust Book - Chapter 7.1 - Packages and Crates is another possible target for the link, but I'm not sure if referencing the book in the specifications and guidelines is something we do.

[peter-lyons-kehl]

Could we clarify naming of procedural macro crates? Like xyz_derive for crates containing proc_macro_derive macros only, and xyz_macros for crates containing other (or proc_macro_derive and other) macros?

[tarcieri]

Semi-related to this discussion: it doesn't seem possible to change the separator once a crate has been published, which is unfortunate: rust-lang/crates.io#728

[Kinrany]

Silver lining: using - for packages and _ for crates would help disambiguate them and raise awareness of the difference between the two, if documented appropriately.

[dumindu]

What is the difference between packages (you mention) and crates in Rust ecosystem?

[Kinrany]

Packages are units of package management handled by cargo, and crates are units of compilation handled by rustc: https://doc.rust-lang.org/stable/book/ch07-01-packages-and-crates.html

[dumindu]

What's wrong with workspaces?
https://doc.rust-lang.org/cargo/reference/workspaces.html

[fibo]

We can use both.
I am new to Rust: for example I am trying godot-rust and I am creating my first hello world with

cargo init --lib hello_godot-rust

it is fine to use both - and _ where it makes sense.

[dumindu]

As I know hello_godot-rust converts to hello_godot_rust. So, in future you can't use hello-godot-rust or hello_godot_rust or hello-godot_rust. So better stick with one convention.

[cheako]

It wouldn't surprise me if both could be published on creats.io.

[PivitParkour94]

I hate to add to a discussion that seems close to finalised, but when creating a new rust project, the folder name where the parent level Cargo.toml, src and target directories go, is that what we refer to as the "package"?

If so, should that be kebab or snake cased?

The reason I ask is because when making a CLI tool in rust, when you run cargo build, you get an executable named whatever your package name is, which seems weird to be anything other than kebab-case (of course not all rust projects are CLI tools. just my two cents)

[peter9477]

Is that actually quite true? I think the Cargo.toml [package] section has a name field that is what is really used for the executable name (among other things probably), and that's the actual package name regardless of the folder name, if I correctly understood how it works.

[nematsakis]

the folder name where the parent level Cargo.toml, src and target directories go, is that what we refer to as the "package"?

Correct. Packages are a cargo concept (see the Cargo Book Glossary). Sometimes the term "project" is used informally in documentation as well. The Rust language/compiler doesn't know about packages, only crates.

In 2022, this issue is more than a bit confusing, because the title is "Naming convention for crates" but seems to be discussing the naming conventions for packages. RFC-0430 states that the naming convention for crates is snake_case with a preference for single words.

As a complete Rust novice, it seems like the only sensible options for cargo package naming conventions is kebab-case or lower_snake_case. Starting from these, I find the following conventions attractive:

• package names should be kebab-case
• src/main.rs should be the crate root for a binary with the package name
• src/lib.rs should be the crate root for a library with the package name converted to snake_case by replacing hyphens with underscores

I'd be very curious to see the data from crates.io on how many packages follow various candidate conventions, both in terms of raw counts and also by some reasonable measure of community popularity.

Finally, FWIW the book is recommending snake_case for crates in its "Hello, Cargo!" example.

[nematsakis]

I'd be very curious to see the data from crates.io on how many packages follow various candidate conventions, both in terms of raw counts and also by some reasonable measure of community popularity.

Apologies for quoting myself, but I think collecting data on current usage is a key next step. This is a classic bike shed topic that can lead to endless discussions of what individuals prefer, but data from the community will go far to ground those discussions. For example, I just looked at my own project's crate and found 21% of dependencies use lower_snake_case, 16% use kebab-case, and 63% avoid hyphens or underscores. What does this look like across the open-source tree writ large?

Also, while a straightforward analysis would simply look at underscores vs. hyphens (and I guess mixed), there are some cases where hyphens are used more as a namespace delimiter (e.g tokio-*) than a simple word delimiter. There might be a case to use a different convention in this instance. I'm not sure what a good heuristic for detecting these would be—probably multiple packages maintained by the same entity with the same prefix. Or alternately, just ask your local friendly LLM. 😀

[thehappycheese]

I arrived at this page from https://rust-lang.github.io/api-guidelines/naming.html#casing-conforms-to-rfc-430-c-case which still says unclear. But as @nematsakis pointed out RFC-0430 says crates should be snake_case, and since 'crate' and 'package' are often interchangeable for simple projects, I conclude that the standard for a packages is lower_snake_case

[package]
name="my_lower_snake_case_package" # this is both the crate name and package name for basic rust projects

[nematsakis]

As it says in the documentation you linked, the naming convention for crates is unclear. Crates and packages are distinct entities and there are arguments both ways for them sharing a convention and also having distinct naming conventions. Everyone is free to name their crates how they want and have opinions on what the convention should be, but an individual can't conclude what the convention is on their own.

I think the best path forward here would be for some enterprising individual to collect the arguments in favor and against each of the reasonable options, collect some real-world data on the actual practices for public crates on crates.io, and put forth an RFC laying out the issues and recommending a proposed convention. That would be how the community would conclude what the convention is.

[jocutajar]

I'm probably not the right guy to do the whole dance as I have no idea, but how about this RFC sketch:

• New PACKAGE names (if not single word) must be snake_case (like the CRATE names)
• Existing (pre RFC) PACKAGE names with a dash and with an underscore are equivalent (you can refer to tokio-core as tokio_core)
• Tooling should initially warn and later error on kebab-cased names

Steps to get there:

• Scan registries (crates.io and perhaps also private ones?) to identify any conflicts between snake_cased and kebab-cased packages. Work with the owners to resolve. Heck, this should not happen, anyway, right? tokio-core and tokio_core to be different packages with distinct owners? That would be misleading.
• Index kebab-case as snake_case in registries, prevent conflicting names. For backward compatibility, registries shall offer both variants if present for probably a long time in the index until a major registry API version change.
• Treat kebab-case and and snake_case packages as identical in dependency tree. Converge to snake_case.
• Deny new kebab-case package registrations in registries
• Warn about kebab-case during package publishing (in cli, registry or both)
• Warn about kebab-case dependencies during build in current edition
• Error about kebab-case dependencies during build in next edition

Or we may as well accept the status quo. It's not that bad, really. Just strange, considering how well defined everything else about Rust seems to be.

[Enet4]

Wouldn't this require all crate owners using dash as a namespace separator (e.g. tokio-*, aws-sdk-*, dicom-* and many others) to give it up for new crates, leading to a mixture of packages on crates.io with a dash and others with an underscore?

[nematsakis]

Deny new kebab-case package registrations in registries
Error about kebab-case dependencies during build in next edition

This is vastly over-scoping this issue. A naming convention is just that, a convention, not a mandate. There are definitely good reasons for crates.io to not allow packages whose names differ only by hyphen/underscores, but that is not the same as forcing all packages to rename themselves.

[jocutajar]

require all crate owners using dash as a namespace separator ... to give it up for new crates

Yes, if that's the consensus. Ideally, this would be transparent to users with gentle push (warnings) to update their Cargo.toml.

vastly over-scoping this issue

The convention has already been established - kebab-case package names are OK now. This RFC would gradually change that and bring everyone on the same page with snake_case, if that's what people want to do. And that's quite involved, to do it nicely, I agree. So if the RFC fails, we know we should stick to the status quo, right?

[braxtons12]

FWIW as someone who is "just in the community" I think this is a mostly-reasonable approach.

I don't agree that forcing package authors to converge universally on snake_case or kebab-case is the correct route, but the general spirit of this, i.e. "pick one, make them mean the same thing in package registries and etc., maybe give a warning if using a convention that isn't 'THE convention'", is pretty reasonable.

I think there has also been a lot of "talking past each other" going on historically in this discussion, more or less summed up as:

• "crates use snake_case, isn't this decided?"
• "crates aren't packages tho"
• repeat xN

which is due to the common (mis)conception that crate/package/library/project/etc are all synonymous

SO I think step zero in whatever process is adopted for this should be thoroughly clarifying the difference between a crate, package, and cargo workspace in the documentation, community (as much as possible/reasonable), etc., otherwise this will just create more confusion (or be ignored entirely)