So, I've published my first Rust crate.
This post is a brief summary of my experience going through the process. There is no TLDR, because the whole post a TLDR, essentially.😛
- The dev process is super smooth with tests that just work out of the box and require zero additional configuration.
- There are official guidelines documenting the API design best practices.
- Doc comments can (and should) include example code snippets that also serve as additional tests for your crate's public API.
- The process of publishing is well-documented.
- Documentation is automatically generated for every published crate by docs.rs.
- The release ritual can be automated with
- Need to keep a lot of things in mind to make sure your crate has great interoperability with the existing Rust ecosystem, e.g. because of the orphan rule the users of your crate won't be able to implement the traits defined in
serdefor the types from your crate, so you have to decide which ones it makes sense to implement and provide that implementation yourself.
It is currently not possible to specify that a certain version of a crate implementing some
cargo-*subcommand must be installed when working on my crate. It's quite limiting, especially coming from JS where you can explicitly declare a cli package as a dependency of your own package and use it in build scripts, etc.
- Where should I put the main documentation for my crate? Should it be
//!doc comment in
src/lib.rs? Eventually, I ended up placing the crate documentation in
cargo-readmeto extract it into
README.mdwhenever I publish a new release. It's cool that it's possible, but it's also an additional build step I have to care about. Don't know how people solve it usually, so please comment if you have a better workflow.
Use clippy with a config, as annoying as you can still handle. Mine is:
#![warn(clippy::all, clippy::pedantic, clippy::nursery, clippy::cargo)]
cargo-releaseand setup pre-release hooks and replacements.
cargo-readmefor extracting the crate documentation from
README.md, thus avoiding duplicating it manually.
Coming from a JS background and only recently starting dabbling in Rust I'd say the overall experience working on a Rust library is far more enjoyable than what you are going through authoring an npm package.
This is, mostly, because the language itself comes with a bigger part of the tooling that you need to be productive. I really appreciate things like the built-in testing framework and excellent workflow around crate's documentation. At the same time, it doesn't feel like the
cargo ecosystem is fully matured yet, and certain things I'm used to having accessible in
npm world are missing (or maybe I'm just not aware of the alternatives).
Anyways, I'd be happy to read your take on how to setup and maintain a crate in the comments, let me know what you think.