How should we use libraries written by others (choosing from the multitude of libraries available at https://crates.io) in our project? Cargo makes this very easy.
Suppose we want to use both the log and the mac library in the monsters project. log is a simple logging framework that gives us a number of macros such as info!, warn!, and trace! to log information messages. mac is a collection of useful macros, maintained by Jonathan Reem.
To get these libraries, we edit our Cargo.toml configuration file and add a [dependencies] section when it isn't already present. Beneath it, we specify the versions of the libraries we want to use:
[dependencies] log = "0.3" mac = "*"
A * denotes that any version is OK, and the most recent version will be installed.
If the library is not available at the crates.io repository, but only at GitHub, add a [dependencies.libname] section and refer to it with its complete URL for the Git property. For example, if your library depends on the gtk crate available at GitHub, add this to your Cargo.toml:
[dependencies.gtk] git = "https://github.com/rust-gnome/gtk"
You can also refer to an abc library that still sits on your machine by including its path:
[dependencies.abc] path = "path/to/abc"
The string value in the [dependencies] section (here "0.3") follows the rules of semantic versioning, which are quite versatile (see https://en.wikipedia.org/wiki/Software_versioning); some examples include these:
1.* means all versions >= 1.0.0 but < 2.0.0
1.2.* means all versions >= 1.2.0 but < 1.3.0
= 1.2.3 means exactly that version
>= 1.2.3 means bigger than or equal to that version
>1.2.3 means bigger than that version
^1.2.3 means all versions starting from 1.2.3 but < 2.0.0
^0 means all versions starting from 0.0.0 but < 1.0.0
~1.2.3 means all versions starting from 1.2.3 but < 1.3.0
For other details, see http://doc.crates.io/crates-io.html.
Save the file and, in the monsters folder, issue this command:
cargo build
Cargo will take care of locally installing and compiling the libraries:
It will also automatically update the Cargo.lock file to register the installed versions of the libraries, so that subsequent project builds will always use the same versions (here log v0.3.1 and mac v0.0.1). If you later want to update to the most recent version of a library, for example, for the log library, do a cargo update -p log, or a cargo update to update all libraries. This will download the latest crate versions for those crates indicated with version *. If you want a higher version for a crate, change its version number in Cargo.toml.
The cargo check command can also be useful; your project's code is checked by the compiler, but no executable code is generated.
Start using the libraries by importing their crates in the code:
#[macro_use] extern crate log; extern crate mac;
The #[macro_use] attribute allows the use of macros defined in the external crate (see the next section). Then we can, for example, use the info! macro from the log crate as follows:
info!("Gathering information from monster {:?}", zmb1);