Understand the Cargo basics to get started with your rust journey.
Table of contents
GitHub repo with all the code
Make sure to star/fork/watch it on GitHub.
What is Cargo?
Cargo is Rust’s build system and package manager. If you are familiar with
npm from the Node.Js ecosystem, you can think of cargo as something similar for the rust ecosystem.
What can Cargo do?
As you write complex rust programs with a lot of dependencies you need a tool to manage everything. You can't rely on
rustc compiler to compile and manage all your dependencies. With Cargo, you can manage multiple dependencies very efficiently.
Similarities between Cargo and npm
Cargo.tomlfor rust projects.
In npm, we install packages using
npm install packagesimilarly, in rust, we can install crates (packages are called crates in the rust ecosystem) using
cargo install crate
Cargo comes installed with Rust if you used the official installers.
To check your cargo version you can do:
If it does not show your cargo version, that would mean cargo is not installed properly in your system.
Creating a new project with Cargo
To create a new project we will do:
cargo new first_cargo_proj
This will create a new cargo project called first_cargo_proj:
The cargo projects are called packages. Think of a package as a collection of source files and a
Cargo.toml file that describes the package. (Like we have the
package.json in Node.Js projects).
The folder structure created by Cargo:
Note: If you create a new project outside a git repository it will come with the git configurations like
In the folder structure, we have:
src folder which will contain all the rust files. You can see the
Then we have the
What is the Cargo.toml file?
Cargo.toml is a manifest file. Which means it contains the description of the package. In rust, we use the TOML language for manifests. TOML stands for "Tom's Obvious Minimal Language". Checkout: https://toml.io
Understanding the Cargo.toml file
Now, let's look into the Cargo.toml file:
The first line,
[package], is a section heading that indicates that the following statements are configuring a package.
[package] section contains configurations Cargo needs to compile your program, like the name, version, and the edition of rust to use.
The last line
[dependencies] is the section which will contain all the dependencies of the package. These dependencies are called crates. You can browse these crates on https://crates.io
First, let's take a look at the
You can see rust generated a new Hello World program for us. Now, let's build and run this using Cargo.
To build the project you can do:
This will compile and build the project. Earlier we were doing it using
Now, if I check the directory I will find a new target folder:
And in the target folder, I have a new debug folder:
This folder contains the executable file to run the program. You can see the executable file here, it is called
first_cargo_proj.exe for windows).
NOTE: I have pushed the target folder in the repo just for reference. Ideally, it should not be pushed to git repos.
Now, I can run this executable file using:
You can see it worked! But there is a better way. You can just do:
This will build and run your project in one command.
Notice that this time we didn’t see output indicating that Cargo was compiling
first_cargo_proj. Cargo figured out that the files hadn’t changed, so it didn’t rebuild but just ran the binary (executable file).
One more thing, sometimes it can be the case that you do not want to build your project and just want to check the program for errors. This happens a lot, especially in big projects. For that you can do:
cargo check . This command quickly checks your code to make sure it compiles but doesn’t produce an executable. Plus you don't want to build your entire project when doing small changes to check if your code works. So, make sure to use this command.
Building your rust code for a release
Now, by default when you do
cargo build it will create a debug folder in the target folder which will have the executable. But, this is not the optimized version. It is for development and debugging purposes only.
To make a production build you should run
cargo build --release to compile with optimizations. The optimizations make your Rust code run faster, but turning them on lengthens the time it takes for your program to compile. Running this will make a release folder inside the target folder with the executable file:
Some interesting things to note
Cargo has an entire book written for it called "the cargo book".
With simple projects, Cargo doesn’t provide a lot of value over just using
rustc, but it will prove its worth as your programs become more intricate. Once programs grow to multiple files or need a dependency, it’s much easier to let Cargo coordinate the build.
TOML aims to be a minimal configuration file format that's easy to read due to obvious semantics.
There is a lot to learn about cargo. But as a beginner, this should suffice.