Creating a Project with Cargo
Let's create a new project using Cargo and look at how it differs from our original "Hello, world!" project. Navigate back to your project
directory (or wherever you decided to store your code). Then, on any operating system, run the following:
cd ~/project
cargo new hello_cargo
cd hello_cargo
The first command creates a new directory and project called hello_cargo. We've named our project hello_cargo, and Cargo creates its files in a directory of the same name.
Go into the hello_cargo
directory and list the files. You'll see that Cargo has generated two files and one directory for us: a Cargo.toml
file and a src
directory with a main.rs
file inside.
It has also initialized a new Git repository along with a .gitignore file. Git files won't be generated if you run cargo new
within an existing Git repository; you can override this behavior by using cargo new --vcs=git
.
Note: Git is a common version control system. You can change cargo new
to use a different version control system or no version control system by using the --vcs
flag. Run cargo new --help
to see the available options.
Open Cargo.toml
in your text editor of choice. It should look similar to the code in Listing 1-2.
Filename: Cargo.toml
[package]
name = "hello_cargo"
version = "0.1.0"
edition = "2021"
[dependencies]
Listing 1-2: Contents of Cargo.toml
generated by cargo new
This file is in the TOML (Tom's Obvious, Minimal Language) format, which is Cargo's configuration format.
The first line, [package]
, is a section heading that indicates that the following statements are configuring a package. As we add more information to this file, we'll add other sections.
The next three lines set the configuration information Cargo needs to compile your program: the name, the version, and the edition of Rust to use. We'll talk about the edition
key in Appendix E.
The last line, [dependencies]
, is the start of a section for you to list any of your project's dependencies. In Rust, packages of code are referred to as crates. We won't need any other crates for this project, but we will in the first project in Chapter 2, so we'll use this dependencies section then.
Now open src/main.rs
and take a look:
Filename: src/main.rs
fn main() {
println!("Hello, world!");
}
Cargo has generated a "Hello, world!" program for you, just like the one we wrote in Listing 1-1! So far, the differences between our project and the project Cargo generated are that Cargo placed the code in the src
directory and we have a Cargo.toml
configuration file in the top directory.
Cargo expects your source files to live inside the src
directory. The top-level project directory is just for README files, license information, configuration files, and anything else not related to your code. Using Cargo helps you organize your projects. There's a place for everything, and everything is in its place.
If you started a project that doesn't use Cargo, as we did with the "Hello, world!" project, you can convert it to a project that does use Cargo. Move the project code into the src
directory and create an appropriate Cargo.toml
file.