Package and crate naming convention

help
1

I am new to Rust language, discovering the language last week, while trying to solve an issue with a PHP project I am working on.

I have been spending time reading "The Book", and blogs, particular the error handling done in Rust, rather different paradigm in the way of thinking, interesting none the less, just need time to get use to it.

I decided to look at packages structuring, and the like before starting to develop Rust packages (libraries and binaries), to ensure I don't make a fine mess of things. Considering I notice people mentioning that once packages are published to crates.io, you can't change package and crate names at all. Any added to crates.io is permanent, so care is required when publishing. Thus I decided to look up what is the naming convention used for packages, and crates (particular libraries), and the namespace the various Rust objects will live in.

I do see there is plenty discussion regarding the naming convention of structs, methods, functions, modules (interesting concept within a Rust file), yet hardly any concrete convention for crates and packages. Coming from a PHP environment, we have Packagist, which has a convention for naming the package and the starting namespace for the classes, and other bits, in that the package name starts with vendor (name/abbreviation), separator, followed by library/binary name (or abbreviation). The name space typically mirrors the package name, starting with vendor, , library name, and the class/interface/trait hierarchy following the second .

I would like to follow this naming scheme in rust to avoid naming clashes of crates, packages, and the structs/modules. The namespace would be "vendor::crate::...", which would match the crate and package name.

Yet, I am struggling to find the convention for naming packages and crates, I have come across confusing discussions about the use of hyphens "-" and underscores "_". Yet nothing official regarding this along with naming convention of packages and crates.

I appreciate any advice regarding the naming convention of packages, crates, and namespace.

1 Like
2

I have yet to see any discernible convention or system for creating crate names.

Is it not a bit premature, with only a one week looking into Rust, to be thinking of publishing crates to the world? Just because it is so easy to do does not mean we have to.

3

That is right. I recently posted my experiences on doing my first publication on crates.io. However, you can yank a version, marking it to not be used anymore. This is also explained in the Cargo Book in Publishing on crates.io.

AFAIK, there is no clear naming convention.

Also see https://rust-lang.github.io/api-guidelines/naming.html, where it currently says:

Crates: unclear

If you follow the link behind unclear, you'll get to Discussion #29 on the api-guidelines, where someone asks:

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?

Apparently, the document was then changed to reflect that there currently is no clear rule how to name crate names.

The namespace for crates is flat, i.e. anyone can publish a crate with any name directly in the top level namespace (on crates.io). However, it's also possible to use crates that are not on crates.io (e.g. which are downloaded from a different registry or found in a local path), or to change the name of an imported crate to a different name (see Renaming dependencies in Cargo.toml).

I personally dislike the flat hierarchy (considering that we do have domains as a unique namespace already), but that's how crates.io (and I think cargo) handles things. There may be some non-technical advantages, such as people having a motivation to develop things quickly to get a "cool" name reserved on crates.io. (Or just write a dummy package to reserve the name.)

What's important to keep in mind is that the namespace is really on a first-come-first-serve basis, and you have no guarantee that a crate with a good looking name is anything official or reliable. You'll have to do your own research before using any crates if you need to rely on them.

4

At some point, you may want to take the step to publish something. And to think about how to do it best, is a good thing to do. I started to wonder about the naming scheme at a very early stage too.

6

Thanks for the information, does help with the confused state of mind with naming of packages and crates.

7

Maybe Rust can still learn something from the PHP world :innocent:

8

Well I prefer having things done the correct acceptable way, than making a mess of the environment, without the ability to fix it later on. This is the reason why I asking about naming conventions so early.

Oh I have made a fine mess in the past, with other programming languages, and thus not repeat it with Rust. refactoring source code is not fine, to fix it to follow conventions.

9

Yes, and that's a good thing to do! :+1:

I guess there is less structure than you have expected in the naming of crates. It's basically a chaos.

However, you can/should still structure the inside of your crates in a reasonable way (e.g. using modules, submodules, etc., depending on the size of your project).

10

Possibly. Just now I don't see I will ever create anything that is generally useful to anyone else.

Also I doubt I could craft it to the standard I expect of others in their published crates :frowning:

I would not discourage wondering about it.

11

For a "standalone" crate, you can pretty much name it whatever. If you're releasing a crate that's strongly tied to another one, it's common to use the main crate's name as a prefix, see for example all the tokio-* crates at https://crates.io/search?q=tokio, or serde-* crates at https://crates.io/search?q=serde.

The underscore/hyphen situation is a little unfortunate, imo. Both are commonly used as separators in crate names, and even the Rust book mixes them up, using underscores in one bit of example code and hyphens in another. Cargo differentiates between the two, so trying to depend on serde-json is an error, as is trying to depend on actix_web, so sometimes you'll know which crate you need but get the separator wrong. Not a big deal, but feels like an unnecessary annoyance.

1 Like
12

I was a bit worried before I published my first crate (refid). On the other hand: There is no guarantee for any of the published crates to fulfill any quality standard. (Edit: Not true, there may be some crates that are referenced in the official docs or statements regarding quality standards by the publishers, of course.) I don't want to argue in favor of publishing half-baked stuff, but at some point I had to give it a try :grin:. And I published it despite some critical feedback on whether my idea was a reasonable thing to do in Rust. I still like it's there, and I can use it now or post references to the docs on docs.rs in that matter.

I mean… other people publish stub packages just to reserve a cool sounding or short name, right? And a lot of people publish their experiments on GitHub. I think the problem here isn't rooted in being experimental, but in the flat namespace that also made me feel a bit "guilty" for taking a 5 character name in the "global Rust-World namespace" and occupying it FOREVER :scream_cat:

13

Reading the train of posts related to Discussion #29, it seems recently the Rust maintainers have agreed on the use of underscore is the way to go. Just not official mentioned in "The Book", yet!. Hopefully soon, for the sake of other new people arriving at Rust.

14

One other thing you should definitely keep in mind when publishing crates is to use the right versioning scheme. I guess it's no strict rule though:

These are only guidelines, and not necessarily hard-and-fast rules that all projects will obey.

Note that a major change is already denoted by raising the leftmost non-zero number. This confused me a bit at first, e.g. 0.1.1 to 0.2.0 is a major change, but 1.1.1 to 1.2.0 is a minor change. (0.2.0 to 1.0.0 is a major change, of course.)

This reduces the chance of breaking code due to an update.

15

I seem what you mean. I think i follow my own convention of prefixing al my packages with a vendor identifier (something similar to the GitHub account name), followed by project name, then if needed separate libraries, using the underscore "_" separator.

And of course survive the mine field of mixed separator use both in package names, and the crate names within. :laughing:

16

Lucky that I am already very much used to versioning scheme, so entrench in the Linux community since appearing on the scene. :+1:

17

These days I see more people using a hyphen than an underscore.

1 Like
18

That seems legit (to me).

But you should be aware that other people might use the same prefix without your consent. Maybe if you are a holder of a registered trademark, you could request to take such other crates down, which highjack your prefix, but that might involve going through a lot of hassle.

I personally would like to have my personal namespace on crates.io, but it's not going to happen. Or is there any policy disallowing other people to use any prefix? The policies of crates.io currently state the following:

The Law

For issues such as DMCA violations, trademark and copyright infringement, Crates.io will respect Mozilla Legal’s decisions with regards to content that is hosted.

19

I got it. Something like:

zicog™_funky_functionality

Can we have unicode in crate names?

I'm an underscore kind of guy.

Having made that decision I can post-justify it by saying that the hyphen is the subtraction operator in Rust. That is why we use underscores in identifiers. So why not just be consistent and use underscores in create names.

20

:joy:

21

That makes sense to use underscore both in the language for identifiers, and for crates names (essentially are identifiers in a sense).

Perhaps package names could be kebab style, to match the usual file naming convention of applications and libraries, especially on Linux file systems. Considering Discussion #29 really is concerned is about crate names, particular for crates.io.