Tutorial: Rust Crate
published 01/12/2022 • 3m reading time • 302 viewsSo, you want to learn how to make a rust crate (library)? Well you came to the right place!
This Tutorial Requires you to have Rust and Cargo installed as well as some basic Rust knowledge. You will learn how to make a crate, add unit tests, documentation and finally publish to crates.io.
Setting Up
The first thing you need to do is create the Cargo project! You can do that by running the following command. This will make a new Cargo Library project.
cargo new --lib <PROJECT_NAME>
Now cd into the <PROJECT_NAME>
directory and launch your favorite text editor :P
The Package
Open the Cargo.toml
file, here we will configure the values description
and license
.
These values are needed to publish on crates.io.
For this example I will use GPL 3 for the license and “Example Crate” for the description.
The Cargo.toml
should now look something like this
[package]
name = "example_crate"
version = "0.1.0"
edition = "2021"
license = "GPL-3.0"
description = "Example Crate"
The Code
Now time to do some programming! yay
In this example I will make a very simple function to greet someone. You will be able to input for example “Darren” and it will output “Hello, Darren!”.
Here is the code I will use for my src/lib.rs
pub fn greet(name: &str) -> String {
format!("Hello, {}!", name)
}
Testing
So, we have the code, but we want to make sure everything is working before we publish it. To do this we will use Unit Texting! In this super simple example is not important but when you make bigger projects it becomes more difficult to make sure everything is working.
Here is the unit test I will use. It has two test cases for “Darren” and “Brenda”.
// Only build this code if testing
#[cfg(test)]
mod tests {
// Include the functions in the module tests is defined in
// This gives the tests access to all public functions in our example
use super::*;
// Define the tests
#[test]
fn test_greet_darren() {
assert_eq!(greet("Darren"), "Hello, Darren!")
}
#[test]
fn test_greet_brenda() {
assert_eq!(greet("Brenda"), "Hello, Brenda!")
}
}
Now running cargo test
should give us 2 passed tests!
Documentation
One crucial part to any good library is good documentation. Rust makes this super easy with Rustdoc. All you have to do is add a description and optional example. Then you can automagically generate a documentation page for your crate.
To add documentation to a function, struct, enum, or anything you use three slashes (///
) then some text in Markdown format.
You can add as many lines of this as you want. Code blocks in the doc string will be run as doc tests when running cargo test
So let’s add those docs! This will be the greet function now.
/// Greet someone by their name
///
/// Will prepend "Hello, "
/// and append "!" to the name
/// ## Example
/// ```rust
/// assert_eq!(greet("Darren"), "Hello, Darren!")
/// ```
pub fn greet(name: &str) -> String {
format!("Hello, {}!", name)
}
Lets try it
Now that we have our amazing crate, we should try it out! To do this I like to use examples.
First make a new folder named examples
in the crate root (Folder with Cargo.toml
).
Inside this folder make a test.rs
file. Add a main function and include the crate with use <PROJECT_NAME>::<function>
.
My example the test.rs file now has the following code
use example_crate::greet;
fn main() {
println!("{}", greet("Darren"));
}
To run this file use cargo run --example test
and If everything is working we can move on to publishing the crate!
Publishing
First go to crates.io and login with GitHub. Then go to https://crates.io/settings/tokens and create a new token. Now run this command to save the token cargo login <TOKEN>
.
To publish the package just use cargo publish
. Yay, you now have made a rust crate, tested it, added documentation and published it on crates.io.