[Rust Guide] 1.3. Rust Cargo

1.3.0. Review

At the end of the 1.2. Basic Understanding of Rust and Printing "Hello World" article, it was mentioned that only small, simple Rust projects are suitable for compilation using rustc, while large projects require Cargo. This article provides a detailed introduction to Cargo.

1.3.1. What is Cargo

Cargo is Rust's build system and package manager. Its functions include building code, downloading dependent libraries, building these libraries...

Cargo is installed automatically when installing Rust. To check if Cargo is correctly installed: enter the command cargo --version in the terminal

1.3.2. Creating Projects with Cargo

Projects created in RustRover automatically configure Cargo, and you can see a file called Cargo.toml in the left project structure.

For non-RustRover users, you can configure Cargo in the terminal:

• Copy the folder path where you want Cargo to be located, open terminal, enter command cd desired_path
• Then enter command cargo new desired_project_name to create the project
• Open this path in your IDE, the project will be under the Cargo project name folder you created

The final project structure should look like this:

PS: Some IDEs won't have the target folder and Cargo.lock file - they appear only after the first compilation

Project structure analysis:

• src is the abbreviation for Source Code, this folder stores your code

• .gitignore indicates that a Git repository has been initialized when creating this project. You can also use other VCS (Version Control System) or not use VCS at all - just add --vcs for configuration when creating the project (the cargo new desired_project_name step)

• The content of Cargo.toml will be explained below

1.3.3. Cargo.toml

The .toml (Tom's Obvious, Minimal Language) format is Cargo's configuration file format

Its content is as follows:

Content analysis:

• [package] is a section header, indicating that the content below is used to configure the package

  • name specifies the project name
  • version specifies the project version
  • authors specifies the project authors, optional and not present here. If present, the format should be: authors = ["your_name <[e-mail]>"]
  • edition specifies the Rust version being used

• [dependencies] is another section header, the content below is used to configure dependencies. It lists the project's dependencies. If there are no dependencies, it's empty below.

PS: In Rust, code packages (libraries) are called crates

1.3.4. Project Structure Format

• All source code should be in the src directory
• Cargo.toml should be in the top-level directory
• The top-level directory can contain: README, licenses, configuration files, and other files unrelated to source code

1.3.5. Converting Non-Cargo Projects to Use Cargo

• Move source code to the src directory
• Create Cargo.toml and fill in the configuration based on the source code

1.3.6. Building Cargo Projects

• Copy the folder path where the Cargo project is located, open terminal, enter command cd Cargo_project_path

• Enter command cargo build. This command creates an executable file. On Windows, its path is target\debug\your_Cargo_project_name.exe; on Linux/MacOS, its path is target/debug/your_Cargo_project_name

• Execute this executable file, first ensure you've completed step one. For Windows, enter .\target\debug\your_Cargo_project_name.exe in terminal; for Linux/MacOS, enter ./target/debug/your_Cargo_project_name in terminal

• Running cargo build for the first time will generate a cargo.lock file in the top-level directory

1.3.7. Cargo.lock

cargo.lock is generated after the project's first compilation (some IDEs automatically generate it before the first compilation). Its content is as follows:

This file's purpose is to track the exact versions of project dependencies. As the comment in this file states, you should not and are not recommended to manually modify this file.

1.3.8. Running Cargo Projects

• Copy the folder path where the Cargo project is located, open terminal, enter command cd Cargo_project_path
• Enter command cargo run

cargo run is actually a two-step operation—compile code + execute result. It first generates an executable file, then runs this executable file. If it has compiled successfully before and the source code hasn't changed, it will directly run the executable file.

1.3.9. Code Checking

The purpose of cargo check is to check code to ensure it can compile successfully, but it doesn't produce an executable file. cargo check is much faster than cargo build. When writing code, you can repeatedly use cargo check to improve efficiency.

Usage:

• Copy the folder path where the Cargo project is located, open terminal, enter command cd Cargo_project_path
• Enter command cargo check

1.3.10. Building for Release

The cargo build command is used for development (debugging). When you've finished writing code and want to release it, you should use cargo build --release, the release build command, instead of cargo build. Comparing the two, the former takes longer to compile code, but the code runs faster. The executable file generated by the former will be in target/release instead of target/debug.