Tutorial: Import Libraries of Rust Code with Crates.io
When you’re first getting started with Rust, you’ll eventually discover that there’s an all-important repository where users share their Rust code in modules — called “crates” — at crates.io. It’s Rust’s official package registry, which proudly informs visitor’s that they’ve now seen 1,397,892,571 downloads. (There’s over 29,187 to choose from.)
And fortunately, it’s really easy to import these libraries into your own Rust code…
Rust’s official “Getting Started” guide not only points visitors to the massive treasury of shared code modules at crates.io, but it also demonstrates how to install them with a package called, “Ferris Says.”
This will be my first encounter with Rust’s syntax for importing a library.
As I learned in my first week of Rust, even writing a simple “Hello World” program involves creating both the source file for the code itself plus a second manifest file. But the good news is that Rust’s cargo tool automatically creates that manifest file — and also helpfully includes a blank section where dependencies (like imported Rust libraries) can be added later.
And each library’s page at crates.io begins with the exact line of code to add into your manifest file to import it. In fact, to add it into your manifest, you don’t even have to type out the line of code. The icon to the right of the code lets you copy it straight into your buffer.
So I add the appropriate line into my manifest file Cargo.toml — then get ready to compile and run the new code.
The “Getting Started” guide also suggests replacing my old Hello World code…
|
1 2 3 |
fn main() { println!("Hello, world!"); } |
…with
|
1 2 3 4 5 6 7 8 9 10 11 |
use ferris_says::say; // from the previous step use std::io::{stdout, BufWriter}; fn main() { let stdout = stdout(); let out = b"Hello fellow Rustaceans!"; let width = 24; let mut writer = BufWriter::new(stdout.lock()); say(out, width, &mut writer).unwrap(); } |
One cut-and-paste later, I’m ready to go. So when I type cargo build to compile the code, I’m surprised how long it takes to add what seem to be very small changes. But then I realize cargo has taken this opportunity to update its internal index of files at crates.io. Several minutes go by as the cargo program tells me it’s still updating. I watch the ASCII art arrow move slowly across my screen…
But finally they’ve all been downloaded — and then compiled — so I can get back to the important business of printing out “Hello, world” with my newly-install Rust library.
And it works!
“You’re a Rustacean now!” explains the Getting Started guide. “Welcome! We’re so glad to have you.”
Exploring the Rust Libraries at Crates.io
Browsing through crates.io, I eventually discover that there’s a “categories” page that groups the downloadable libraries into 47 different categories. There’s a category with 532 algorithm crates, promising Rust implementations of core algorithms like sorting and searching, and 68 date and time crates “to manage the inherent complexity of dealing with the fourth dimension.”
Of course, that’s not the only place where you can import libraries. The official documentation for cargo reminds you that a library can just as easily come from a git repository, or even from subdirectories on your local file system. (And there’s fancy tricks for changing the dependencies depending on which platform is running the code.)
In fact, a GitHub repository named “rust-unofficial” also offers a curated collection of what it calls Awesome Rust, which includes links to libraries, development tools and even the code for entire applications.
But it turns out there’s another even easier way to play with crates. The top 100 most-downloaded crates are already pre-installed in the online “Rust Playground.” And this also gives you a chance to see what a manifest file looks like when it’s importing 100 different dependencies. In addition, it also includes all the libraries from “The Rust Cookbook,” which describes itself as “a collection of simple examples that demonstrate good practices to accomplish common programming tasks, using the crates of the Rust ecosystem.”
What I like about the “Cookbook” as a learning resource is it helpfully indicates which crates you’ll need for each example — and those two-color “badges” (with the crate names) link to detailed documentation.
Plus, working my way through the “Cookbook,” I also discovered there’s a much easier way to add dependencies to a manifest.
When you’re in the project’s directory (which has the Cargo.toml file), there’s a way to just use the command-line command cargo add and the library’s name.
> cargo add rand
Though ironically, this easier way of adding new dependencies to your manifest is only enabled after — adding a new dependency to your manifest. Specifically, you need to install the cargo-edit tool, whose webpage (on GitHub) describes it as “a utility for managing cargo dependencies from the command line.”
cargo-edit can also take several minutes to install — but then your Rust environment is fully equipped with a nice simple command for adding new crates from the command line.
> cargo install cargo-edit
> cargo add rand
And if you ever change your mind about a dependency, there’s also a way to cleanly remove it from your manifest altogether. Just replace “add” with “rm” in the command.
> cargo rm rand
And there’s also a third command. When you’re in a project’s directory, typing cargo upgrade will now check each of the project’s dependencies to see if there are newer versions available for any of them — and if so, will perform the necessary updates.
> cargo upgrade
These are tools are deceptively simple and incredibly powerful, giving you the flexibility to choose from tens of thousands of new code modules to add to the future Rust projects that await you.
So now the fun can really begin. Because once you know how to add one Rust library, you can start playing around with adding more!