Skip to content

Latest commit

 

History

History
executable file
·
100 lines (73 loc) · 4.97 KB

a4.cargo,crates_and_basic_project_structure.md

File metadata and controls

executable file
·
100 lines (73 loc) · 4.97 KB
Raw

title: Cargo, Crates and Basic Project Structure

Cargo

Cargo is Rust’s built-in package manager and the build system. It can be used to,

  • Create a new project: cargo new
  • Create a new project in an existing directory: cargo init
  • Build the project: cargo build
  • Run the project: cargo run
  • Update project dependencies: cargo update
  • Run tests: cargo test
  • Run benchmarks: cargo bench
  • Generate the project documentation via rustdoc: cargo doc
  • Analyze the project to see it has any errors, without building it: cargo check

In addition, there are cargo commands to publish the project as a crate/ package to Rust's official crate registry, crates.io.

💡 We need to get an API token from crates.io to publish a crate to it. The API token can be found in the Account Settings page, after login to that site. We will discuss more about this under code organization with crates.

  • Login to crates.io with the API token: cargo login
  • Make the local crate uploadable to crates.io: cargo package
  • Upload the crate to crates.io: cargo publish
  • Install a Rust binary: cargo install
  • Uninstall a Rust binary: cargo uninstall

Crate

A crate is a package, which can be shared via crates.io. A crate can produce an executable or a library. In other words, it can be a binary crate or a library crate.

  1. cargo new crate_name --bin or cargo new crate_name: Produces an executable
  2. cargo new crate_name --lib: Produces a library

The first one generates,

├── Cargo.toml
└── src
    └── main.rs

and the second one generates,

├── Cargo.toml
└── src
    └── lib.rs
  • Cargo.toml(capital c) is the configuration file which contains all of the metadata that Cargo needs to compile your project.
  • src folder is the place to store the source code.
  • Each crate has an implicit crate root/ entry point. main.rs is the crate root for a binary crate and lib.rs is the crate root for a library crate.

💡 When we build a binary crate via cargo build or cargo run, the executable file will be stored in the target/debug/ folder. But when building it via cargo build --release for a release it will be stored in the target/release/ folder. The release builds are applying more optimizations while compiling the code, to make the code run faster. But it takes more compile time.

Project Structure

This is how Cargo documentation describes about the recommended project layout,

.
├── Cargo.toml
├── Cargo.lock
├── src
│   ├── main.rs
│   ├── lib.rs
│   └── bin
│       └── another_executable.rs
├── tests
│   └── some_integration_tests.rs
├── benches
│   └── simple_bench.rs
└── examples
    └── simple_example.rs
  • The source code goes in the src directory.
    • The default executable file is src/main.rs.
    • The default library file is src/lib.rs.
    • Other executables can be placed in src/bin/*.rs.
  • Integration tests go in the tests directory (unit tests go in each file they're testing).
  • Benchmarks go in the benches directory.
  • Examples go in the examples directory.

Rust Editions

After the initial release in 2015, according to the feedback got from user communities, the Rust team was focusing to increase the productivity of the language and the ecosystem. After 3 years of hard work in 2018, a new Rust edition was released with new features, simplified syntax and better tooling. We call it Rust 2018 edition.

To keep the promise of supporting backward compatibility, the new edition = "2018" configuration was added to the Cargo.toml file. For new projects, the cargo new command adds this configuration by default. So, you don't need to care. But on legacy crates, if you can not see any edition configuration, Cargo will consider it as a Rust 2015 edition crate.

Before going to the next...

  • The .cargo/bin directory of your home directory is the default location of Rust binaries. Not only the official binaries like rustup, rustc, cargo, rustfmt, rustdoc, rls and also the binaries you can install via cargo install command, will be stored in this directory.

  • Even though the initial convention for naming crates and file names is using the snake_case, some crate developers are using kebab-case on both crates and file names. To make your code more consistent, use the initial convention snake_case; especially on file names.

  • Create an executable crate via cargo new command and run it via cargo run.

  • Create a library crate via cargo new command and run cargo test.