Rust

Rust programming language

Start #

Install #

For Windows go to Rust install page and download the installer. For Unix systems install by downloading the rustup utility:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

This will install rust in $HOME/.cargo/bin or %USERPROFILE%\.cargo\bin.

# Uninstall Rust
rustup self uninstall

# Update Rust
rustup update

# Validate installation
rustc --version
cargo --version
rustdoc --version

Toolchain #

The installation tool rustup installs itself and three core tools: rustc, rustdoc and cargo. Rust is designed to be built and executed using cargo (it wraps the other two).

rustc #

The compiler, it takes .rs files and produces native executables.

1
fn main(){
2
  println! ("Hello World");
3
}

rustc main.rs
./main

rustdoc #

The HTML documentation generator from doc comments (/// for items and //! for modules/crates) into ./doc/ directory.

rustdoc src/lib.rs

1
/// Adds two numbers and returns the result.
2
///
3
/// Returns `a + b` as an `i32`.
4
pub fn add(a: i32, b: i32) -> i32 {
5
  a + b
6
}

rustdoc src/lib.rs

cargo #

Build system and package manager. Used to create projects, resolve dependencies, compile and execute Rust.

new #

Create a new cargo project.

cargo new my_project   # To create a binary project (default)
cargo new my_lib --lib # To create a library project

1
my_project/
2
├── Cargo.toml      # Manifest: name, version, dependencies
3
├── cargo.lock      # Locked dependency versions for build
4
├── src/
5
│   └── main.rs     # Entry point (lib.rs for libraries)
6
└── target/         # Build artifacts (generated on build)

check #

Check if the project code will compile.

cargo check

build #

Compile a project with all its dependencies. (invokes rustc with flags)

cargo build                # Debug build  → target/debug/
cargo build --release      # Optimized    → target/release/

Resolves Cargo.toml crates and updates the Cargo.lock file, then invokes rustc with a set of flags placing the output in target/<profile>.

run #

Build and then execute the resulting binary (invokes rustc with flags and executes).

cargo run            # Build + run (default dev build profile)

cargo run --release        # Build + run (release profile)
cargo test                 # Build + run with test profile (runs all tests)
cargo bench                # Build + run with bench profile (runs all benchmarks)

doc #

Create the HTML documentation (invokes rustdoc).

cargo doc --open           # Build docs and open in browser
cargo doc --no-deps        # Only generate your crate docs, skip dependencies

crates #

Dependencies are defined in Cargo.toml and fetched from crates.io.

cargo install dependency_name        # Install crate globally into ~/.cargo/bin
cargo install --list                 # Display globally installed crates
cargo uninstall dependency_name      # Uninstall crate globally
cargo add dependency_name            # Fetch and add latest version to project
cargo update -p dependency_name      # Update crate to latest compatible ver
cargo remove dependency_name         # Remove crate from project

cargo update                                 # Update all dependencies within semver constraints
cargo clean                                  # Remove all build artifacts and dependency builds
cargo add dependency_name@1.0                # Add specific crate version
cargo add dependency_name --features derive  # Add with feature flags
cargo add --dev dependency_name              # Add crate as a dev dependency
cargo add --build dependency_name
cargo tree                                   # Full dependency tree with versions
cargo tree -i dependency_name                # Reverse: who pulls in dependency_name?
cargo tree --duplicates                      # Find multiple versions of the same crate
cargo search dependency_name                 # Search for specific crate
cargo outdated                               # Check for outdated crates (requires cargo-outdated)
cargo audit                                  # Audit crates against CVEs (requires cargo-audit)

Cargo.toml #

The manifest declares package metadata, dependencies, targets, features and build configuration.

Metadata #

The mimimum required fields are name, version and edition:

1
[package]
2
name = "my_project"
3
version = "0.1.0"
4
edition = "2024"

1
[package]
2
name         = "my_project"                   # crates.io name (required, must be unique)
3
version      = "0.1.0"                        # semver (required)
4
edition      = "2024"                         # Rust edition: 2015, 2018, 2021, 2024
5
authors      = ["Name <me@example.com>"]      # Author name and email
6
description  = "A short blurb"                # Required for publishing to crates.io
7
license      = "MIT"                          # SPDX expression
8
repository   = "https://github.com/user/repo" # Git repository
9
readme       = "README.md"                    # Readme file
10
keywords     = ["cli", "parser"]              # Max 5, for crates.io search
11
categories   = ["command-line-utilities"]     # creates.io package category
12
rust-version = "1.75"                         # Minimum Supported Rust Version (MSRV)

Dependencies #

Dependencies must have a context and a semver requirement. They can be fetched from crates.io, a git repo or a local path. They can have specific feature flags enabled.

Context #

1. [dependencies] is what src/ imports. Ships in the final binary or library. e.g. serde, tokio, clap, anyhow.
2. [dev-dependencies] is what tests/, benches/, examples/, and #[cfg(test)] blocks use. Stripped from the published crate. e.g. criterion, proptest, mockall, assert_cmd.
3. [build-dependencies] is what build.rs uses to do code generation, native compilation, or linker setup before your crate is built. Never touched by src/. e.g. cc, bindgen, prost-build.

1
[dependencies]            # Used by src and release artifacts.
2
dependency_name = "1.0"
3
[dev-dependencies]        # Used only by src for test, bench and example artifacts.
4
dependency_name = "1.0"
5
[build-dependencies]      # Not used by artifacts, used by buils.rs at compile time.
6
dependency_name = "1.0"

Semver #

All dependencies require a semver requirement string. Cargo updates dependencies only within the range specified by the semver string, by default jumps between major versions 1.x -> 2.x have to be added explicitly with cargo add.

1
# Plain semver string are implicitly caret-prefixed
2
dep_name = "0"                    # >=0.0.0, <1.0.0
3
dep_name = "1"                    # >=1.0.0, <2.0.0
4
dep_name = "~1"                   # >=1.0.0, <2.0.0
5
dep_name = "1.*"                  # >=1.0.0, <2.0.0
6
dep_name = "1.2"                  # >=1.2.0, <2.0.0
7
dep_name = "1.2.3"                # >=1.2.3, <2.0.0
8
# For 0.x minor instead of major bumb is breaking
9
dep_name = "0.0"                  # >=0.0.0, <0.1.0
10
dep_name = "0.5"                  # >=0.5.0, <0.6.0
11
dep_name = "0.5.3"                # >=0.5.3, <0.6.0
12
dep_name = "~1.2"                 # >=1.2.0, <1.3.0
13
dep_name = "1.2.*"                # >=1.2.0, <1.3.0
14
# For 0.0.x patch instead of minor bumb is breaking
15
dep_name = "0.0.0"                # >=0.0.0, <0.0.1
16
dep_name = "0.0.5"                # >=0.0.5, <0.0.6
17
dep_name = "~1.2.3"               # >=1.2.3, <1.2.4
18
# Wildcards are best avoided
19
dep_name = "*"                    # Any version - blocked by crates.io
20
# Comparisons are more loose
21
dep_name = ">=1.2.3"              # At least 1.2.3, no upper bound
22
dep_name = ">1.2.3"               # Greater than 1.2.3, no upper bound
23
dep_name = "<1.2.3"               # Less than 1.2.3, no lower bound
24
dep_name = "<=1.2.3"              # At most 1.2.3, no lower bound
25
dep_name = "=1.2.3"               # Exactly 1.2.3, disables updates
26
dep_name = ">=1.2, <1.5"          # 1.2.0 to 1.4.x
27
dep_name = ">1.0, <=1.4.5"        # 0.x.x to 1.4.5
28
# Pre-releases are outside the normal range, this means that "<1"
29
# does not include 0.0.1-beta even though technically it is lower
30
dep_name = "1.0.0-beta.2"         # Opt into 1.0.0-beta line
31
dep_name = ">=1.0.0-alpha"        # Opt into 1.0.0 pre-releases and stable forward
32
# Inline table explicit form
33
# This notation is used to add features, optional, path, git and other options
34
dep_name = { version = "1", features = ["full"], optional=true }

Source #

We can specify the source from which we fetch the crates.

1
[dependencies]
2
dep_name = "1"                                                                        # Fetched from crates.io (default)
3
dep_name = { version = "1", path = "../my_utils"}                                     # Fetched from local path
4
dep_name = { version = "1", git = "https://github.com/usr/repo", branch = "main"}     # Fetched from git repo branch
5
dep_name = { version = "1", git = "https://github.com/usr/repo", rev = "abc123"}      # Fetched from git repo commit
6
dep_name = { version = "1", optional = true}                                          # Fetched async only when enabled by a feature

Feature #

Feature are opt-in compile flags that toggle extra code paths or pull optional dependencies.

1
[dependencies]
2
json_dependency = { version = "1", optional = true }
3
async_dependency = { version = "1", optional = true }
4
[features]
5
default = ["json"]                 # Always enabled (unless --no-default-features is set)
6
json = ["dep:json_dependency"]     # If json is enabled it pulls json_dependency
7
async = ["dep:async_dependency"]   # If async is enabled it pulls async_dependency
8
full = ["json, async"]             # If full is enabled it enables json and async

cargo build --no-default-features
cargo build --features async
cargo build --features json
cargo build --features full
cargo build --all-features

Profile #

You can override one of the compiler build profiles or create a custom one. This is mainly used to fine tune the release artifacts build process.

1
[profile.release]
2
opt-level = 3      # 0 to 3 levels of optimization
3
lto = "fat"        # Link-time optimizations - off, thin, fat
4
codegen-units = 1  # Lower equals better optimizations and slower compile
5
strip = "symbols"  # Strip debug symbols
6
panic = "abort"    # Smaller binary with no unwinding

Target #

The target is auto-detected by cargo but you can declare it explicitly. Note the double brackets since toml will treat it as an array of tables (a crate can produce multiple artifacts).

1
[[bin]]
2
name = "cli"              # Build as cli artifact from cli.rs
3
path = "src/bin/cli.rs"
4
[[example]]               # Build demo from examples/demo.rs
5
name = "demo"
6
[[bench]]                 # Build bench from benches/perf.rs
7
name = "perf"
8
harness = false           # Also disable, nightly built-in bench harness

Workspace #

Some projects contain multiple crates, in this case the root cargo.toml can act as a workspace root file so that all members share a single cargo.lock file and target/ directory. This improves build speeds and the project structure.

1
[workspace]
2
members  = ["app", "core", "utils"]
3
resolver = "2"                                       # Default in edition 2021+
4
[workspace.dependencies]                             # Shared dependencies, defined once
5
serde = "1.0"
6
tokio = { version = "1.0", features = ["full"] }

Then each member crate just inherits:

1
[dependencies]
2
serde = { workspace = true, features = ["derive"] }
3
tokio = { workspace = true }

Fundamentals #

Variables #

Variables are named storage locations that map a symbolic name to a value in memory, the name is replaced with the memory location at compile time. Declared with let, immutable by default; opt into mutability with mut.

1
fn main(){
2
  let x = 2;
3
  println! ("x = {}", x);
4
  let mut y = 2;
5
  y = 3;
6
  println! ("y = {}", y);
7
}

Shadowing #

Rebinding a variable name with a new let shadows the previous binding. Unlike mut, shadowing creates a fresh binding and therefore can change the type.

1
rustfn main() {
2
    let x = "5";                         // &str
3
    let x = x.parse::<i32>().unwrap();   // Shadowing the string into i32
4
    let x = x + 1;                       // i32, value = 6
5
    println!("x = {}", x);
6
}

Constants #

Use const to declare a compile-time constant. Constants must be annotated, their values must be a constant expression and they conventionally use SCREAMING_SNAKE_CASE. They are inlined when used, meaning they don’t necessarily have a fixed memory address.

1
rustconst MAX_USERS: u32 = 100_000;

Use static to declare a value with a fixed memory address. They are usually used to define the global state of the program, creating a mutable static requires an unsafe memory access point.

1
ruststatic APP_NAME: &str = "my-app";

Data Types #

Rust is statically typed, data types must be known at compile time. The type can be inferred or explicitly annotated with a colon. Variables can be declared without a value as long as they are annotated (however they must be initialized before being read).

1
fn main() {
2
  let _int: i32 = 42;
3
  println! ("Int = {}", _int);
4
  let _float: f64 = 3.141;
5
  let _boolean: bool = true;
6
  let _character: char = 'R';
7
  let _tuple: (i32, f64, char, bool) = (42, 3.141, 'R', true);
8
  let _unit_tuple: () = ();
9
  let _array: [i32; 5] = [1, 2, 3, 4, 5];
10
}

Data types can be broadly subdivided into scalar and compound data types.

Integers #

Signed go from $-(2^{n-1})$ to $2^{n-1}-1$. Unsigned go from $0$ to $2^n-1$. Signed are stored using two’s complement representation.

The primary use for isize/usize is indexing collections. Literals accept _ as a visual separator and type suffixes: Hex as 0xff, octal as 0o77, binary as 0b11110000 or byte as b'A' (u8 only). Dev and test artifacts include an overflow panic check, however release artifacts wrap overflows via two’s complement.

Overflow #

In debug (dev, test) normal arithmetic operators + - * / will panic when overflown but silently wrap in release (releease, bench). If you expect overflow to happen you can explicitly handle it by calling an overflow method and the intended arithmetic operator (_add, _sub, _mul, _div, _neg, _rem, _pow, _shl, _shr, etc.).

1
fn main() {
2
    let max_u8 = u8::MAX;
3
    let wrapped = max_u8.wrapping_add(1);
4
    println!("Wrapped: {}", wrapped);  // Outputs Wrapped: 0
5
}

Scalar #

Compound #

Casting #

Rust never coerces between types implicitly, type casting is usually done explicitly with as. This defaults to truncating or wrapping on narrowing conversions (e.g i32 -> i8).

1
fn main() {
2
    let a: i32 = 5;
3
    let b: f64 = 2.5;
4
    let sum = a as f64 + b;    // 7.5
5
    println!("{}", sum);
6
}

For safe, fallible conversions use TryFrom and TryInto, for lossless conversions use From and Into.

Comments #

Single-line comments use double forward slash while multi-line comments use a comment block:

1
fn main() {
2
  // This is a single-line comment
3
  /* This is a multi-line
4
     comment
5
  */
6
}

Functions #

Functions organize code into reusable units. main() is the entry point of every Rust program. Declared with fn, followed by name, parameters with explicit types, optional return type, and a body. The convention is to use snake_case for the function name and parameters.

1
fn function_name(arg1:type, arg2:type,...) -> ReturnType{
2
  // Body1
3
}

Statement, Expression #

A function’s body consists of statements and or expressions. Statements perform an action and return a unit touple (meaning no value), they end with a ;. Expressions evaluate to a value they return, they have no trailing ;.

1
fn main() {
2
    let x = 5;            // statement does not return a value (simply binds to 5)
3
    let y = { x + 1 };    // the expression (x+1) does evaluates to a value (6)
4
    println!("{}", y);
5
}

Return Single #

You can annotate a function’s return type with -> and return a value explicitly with return or implicitly by ending the function’s body with an expression.

1
fn sum(x: i16, y: i16) -> i16 {
2
    x + y // no `;` so it implicitly returns this expression's value
3
}
4

5
fn abs(x: i32) -> i32 {
6
    if x < 0 { return -x; } // early explicit return
7
    x
8
}
9

10
fn main() {
11
    println!("{}", sum(2, 3));   // 5
12
    println!("{}", abs(-7));     // 7
13
}

Return Multiple #

To return multiple values at the same time we can use a tuple and then destructure it at the call site.

1
fn min_max(a: i32, b: i32) -> (i32, i32) {
2
    if a < b { (a, b) } else { (b, a) }
3
}
4

5
fn main() {
6
    let (lo, hi) = min_max(7, 3);
7
    println!("lo={}, hi={}", lo, hi);   // lo=3, hi=7
8
}

Control Flow #

Control flow tools allow us to execute code based on certain conditions or execute repeating code.

If - Else #

We use if to conditionally execute code based on an explicit boolean condition (Rust does not coerce integers, options or similar into truthy-falsy).

For mutually exclusive blocks we can use if - else expressions and for multiple non-overlapping conditions we can use if - else if expressions. if expression branches that implicitly return a value of the same data type can be assigned into a variable.

1
fn main() {
2
  let a = 10;
3
  if a == 10 {
4
    println!("a is 10");
5
  } else {
6
    println!("a is not 10");
7
  }
8

9
  let grade = 67;
10
  let letter = if grade > 90 { 'A' }
11
                else if grade > 80 { 'B' }
12
                else if grade > 70 { 'C' }
13
                else if grade > 60 { 'D' }
14
                else { 'F' };
15
  println!("Grade: {}", letter);
16
}

Match #

match is an alternative to if - else if expression branches that compare a value against a pattern and return a value, match branches must be exhaustive meaning that they cover every possible value. The pattern can be a literal (0), an OR pipe pattern (1|2), a range (3..=9) or any (_).

1
fn main() {
2
  let n = 3;
3
  let label = match n {
4
      0       => "zero",
5
      1 | 2   => "small",
6
      3..=9   => "medium",
7
      _       => "large",
8
  };
9
  println!("{}", label);
10
}

Loops #

We can repeatidly execute a block of code with a loop (infinite), while (condition-driven) or a for (iterator-driven) loop method.

Loop #

Runs until it encounters a break, else it runs indefinitely. You can pass a value to break in order to return it from the loop.

1
fn main() {
2
  let mut a = 5;
3
  let final_a = loop {
4
    a -= 1;
5
    if a == 2 { break a; }
6
  };
7
  println!("Loop result = {}", final_a);  // 2
8
}

While #

Runs until a condition goes from true to false.

1
fn main() {
2
  let mut b = 5;
3
  while b > 2 {
4
    b -= 1;
5
    println!("b = {}", b); // 5,4,3
6
  }
7
}

For #

Runs until it finishes iterating over the elements of a collection. A for loop can be considered a while loop with a counter but it is optimized for this use case.

1
fn main() {
2
  for i in 0..3   { println!("{}", i); }   // 0, 1, 2
3
  for i in 0..=3  { println!("{}", i); }   // 0, 1, 2, 3
4
  let values = [1, 2, 3, 4];
5
  for v in &values {
6
    println!("value = {}", v);   // 1,2,3,4
7
  }
8
}

Break, Continue, Labels #

To exit the innermost loop use break. To skip the next iteration use continue. To target a specific loop within nested loops you can add a label to it 'loop_name:.

1
fn main() {
2
    'outer: for i in 0..5 {
3
        for j in 0..5 {
4
            if i * j > 6 { break 'outer; }
5
            println!("{}, {}", i, j);
6
        }
7
    }
8
}

Questions #

Does this compile? If not, why and how to correct?

1
fn main() {
2
  let a=2;
3
  let b=3.0;
4
  println!("Sum of a and b = {}", a+b);
5
}

You have an array of 4 floats, implement find_mean()

1
fn main() {
2
  let ar = [2.5, 3.0, 4.5, 2.0];
3
  println!("Mean of ar = {}", find_mean(ar));
4
}

1
fn find_mean(ar: [f64; 4]) -> f64 {
2
 let mut sum = 0.0;
3
 for v in ar.iter() { sum += v; }
4
 sum / ar.len() as f64
5
}

Write down the output of this program

1
fn main() {
2
  let mut a:i8 = 125;
3
  a = a+3;
4
  println!("a={}", a);
5
}

State if true or false:

1. f32 is the default for floats = false, it is f64
2. Doing let a = 5; the data type of x is i8 = false, it is i32
3. Floats are compound data types = false, it is scalar
4. Statements do not produce a result = true, statements evaluate to ().
5. What is shadowing = rebinding an existing name, creates a fresh bind

Ownership #

Structs #

Packages #

Errors #

Generics #

Files #

Text #

Concurrency #

Input-Output #

Terminals #

Signals #

Databases #

Networks #

Unsafe #

Foreign #

Embedded #

Web #

Rhai #

Egui #

GUI libary for rust that runs natively or on the web, also available as a libary on many game engines. It is a very simple, easy to use GUI library. It uses the Eframe framework meaning it supports Linux, Mac, Windows, Android and Web.

1
ui.heading("My egui Application");
2
ui.horizontal(|ui| {
3
    ui.label("Your name: ");
4
    ui.text_edit_singleline(&mut name);
5
});
6
ui.add(egui::Slider::new(&mut age, 0..=120).text("age"));
7
if ui.button("Increment").clicked() {
8
    age += 1;
9
}
10
ui.label(format!("Hello '{name}', age {age}"));
11
ui.image(egui::include_image!("ferris.png"));

https://docs.rs/egui.