I Published my First Crate to crates.io

In the last week I published my first rust crate to crates.io. The crate idea was a result of another collaborative project I am working on with an awesome group at the Recurse Center.

I’m so happy I got around to actually publishing a crate, if nothing else to realize how easy it was! There is of course a lot of things I would like to improve about it, both feature set wise and in the public API. But if there is anything I need to learn it is to say “good enough for now”, and I managed to this time.

The Crate

The crate is called mesh-rand and is meant to evolve into a suite for sampling all kinds of random distributions on the surface or in the volume of a 3D mesh. At the moment the only feature available is to generate random uniform points on the surface, but I hope to get around to adding more soon.

The idea came from the need in the original project to generate a 3d point cloud to represent a 3d mesh. In the case of a high poly model one easy way is to just use the verticie data, but this does not work for models that contain large triangles. I looked around for a while online, but couldn’t find a library that seemed to do what we need, and so decided to build the feature separately to be able to publish it as a crate.

What I Learned

The process of publishing was surprisingly smooth! I just followed the instructions here. The largest part was going through the rust API guidelines (still have a couple of points that could for sure be improved upon).

I’m really happy I managed to find a project with a very small scope, to get my feet wet and not have to many decisions to make when going through the process of publishing.

Doc Examples

I learned a bit about doc comment code examples. Within a doc comment code block, lines can be excluded from the doc, but included in the doc tests, by adding a # to the beginning of doc lines:

///```
/// let a = 5;
/// # assert_eq!(a, 5);
///```

This both allows for adding assertions that are not visible in the examples as above, but also makes it possible to use the question mark operator inside examples by wrapping them like this:

///```
/// # fn main() -> Result<(), Box<dyn std::error::Error>> {
/// ... your code here ...
/// # Ok(())
/// # }
///```

One feeling I went away with is that there really should exist a macro crate for defining more ergonomic rust doc examples. Why not auto-generate the above wrapper, and as a bonus not have to worry about including “///” at the beginning of each line by doing this:

doc_example! {
    //code here, syntax highlighted and all!
}

Maybe even a way of referencing the entirety or parts of test methods? Would love to hear your thoughts on this.

Un-answered Questions

How can I in a nice way support both f32 and f64 types in a library? I did look at the num_traits crate Float type, but the problem is that I’m using a dependency that only accepts a handful of numeric primitives (f32, f64, i32 etc.). One solution would be a feature flag that defines a Float type, but that seems weird. Another idea is through some sort of build step, but it just seems like there should be a better way of doing this.
How to choose input/output types in the best way possible? The distributions in the library needs mesh data. Right now I opted for a arbitrary way of representing this using rust primitives, as it seemed the most flexible for the caller. I did start to research what other crates exist that have mesh types defined - in the hope of realizing they were all using some common format. Not the case. Adding all these other crates as a dependency just to implement “from” methods feels bad. Maybe behind feature flags? But there would be so many…

Next steps

Would like to implement poisson disc sampling on mesh surfaces using some combination/variant of these methods: