microsoft-rust-training

What this skill does

# Microsoft Rust Training

> Skill by [ara.so](https://ara.so) — Daily 2026 Skills collection.

A collection of seven structured Rust training books maintained by Microsoft, covering Rust from multiple entry points (C/C++, C#/Java, Python backgrounds) through deep dives on async, advanced patterns, type-level correctness, and engineering practices. Each book contains 15–16 chapters with Mermaid diagrams, editable Rust playgrounds, and exercises.

---

## Book Catalog

| Book | Level | Focus |
|------|-------|-------|
| `c-cpp-book` | 🟢 Bridge | Move semantics, RAII, FFI, embedded, no_std |
| `csharp-book` | 🟢 Bridge | C#/Java/Swift → ownership & type system |
| `python-book` | 🟢 Bridge | Dynamic → static typing, GIL-free concurrency |
| `async-book` | 🔵 Deep Dive | Tokio, streams, cancellation safety |
| `rust-patterns-book` | 🟡 Advanced | Pin, allocators, lock-free structures, unsafe |
| `type-driven-correctness-book` | 🟣 Expert | Type-state, phantom types, capability tokens |
| `engineering-book` | 🟤 Practices | Build scripts, cross-compilation, CI/CD, Miri |

---

## Installation & Setup

### Prerequisites

```bash
# Install Rust via rustup
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Install mdBook and Mermaid preprocessor
cargo install mdbook mdbook-mermaid
```

### Clone and Build

```bash
git clone https://github.com/microsoft/RustTraining.git
cd RustTraining

# Build all books into site/
cargo xtask build

# Serve all books locally at http://localhost:3000
cargo xtask serve

# Build for GitHub Pages deployment (outputs to docs/)
cargo xtask deploy

# Clean build artifacts
cargo xtask clean
```

### Serve a Single Book

```bash
cd c-cpp-book && mdbook serve --open     # http://localhost:3000
cd python-book && mdbook serve --open
cd async-book && mdbook serve --open
```

---

## Repository Structure

```
RustTraining/
├── c-cpp-book/
│   ├── book.toml
│   └── src/
│       ├── SUMMARY.md          # Table of contents
│       └── *.md                # Chapter files
├── csharp-book/
├── python-book/
├── async-book/
├── rust-patterns-book/
├── type-driven-correctness-book/
├── engineering-book/
├── xtask/                      # Build automation (cargo xtask)
│   └── src/main.rs
├── docs/                       # GitHub Pages output
├── site/                       # Local preview output
└── .github/workflows/
    └── pages.yml               # Auto-deploy on push to master
```

---

## mdBook Configuration (`book.toml`)

Each book contains a `book.toml`. Example configuration pattern:

```toml
[book]
title = "Async Rust"
authors = ["Microsoft"]
language = "en"
src = "src"

[build]
build-dir = "../site/async-book"

[preprocessor.mermaid]
command = "mdbook-mermaid"

[output.html]
default-theme = "navy"
preferred-dark-theme = "navy"
git-repository-url = "https://github.com/microsoft/RustTraining"
edit-url-template = "https://github.com/microsoft/RustTraining/edit/master/{path}"

[output.html.search]
enable = true
```

---

## Key Rust Concepts Covered by Book

### Bridge: Rust for C/C++ Programmers

**Ownership & Move Semantics**

```rust
// C++ has copy by default; Rust moves by default
fn take_ownership(s: String) {
    println!("{s}");
} // s is dropped here

fn main() {
    let s = String::from("hello");
    take_ownership(s);
    // println!("{s}"); // ERROR: s was moved
    
    // Use clone for explicit deep copy
    let s2 = String::from("world");
    let s3 = s2.clone();
    println!("{s2} {s3}"); // Both valid
}
```

**RAII — No Manual Memory Management**

```rust
use std::fs::File;
use std::io::{self, Write};

fn write_data(path: &str, data: &[u8]) -> io::Result<()> {
    let mut file = File::create(path)?; // Opens file
    file.write_all(data)?;
    Ok(())
} // file automatically closed here — no explicit close needed
```

**FFI Example**

```rust
// Calling C from Rust
extern "C" {
    fn abs(x: i32) -> i32;
}

fn main() {
    unsafe {
        println!("abs(-5) = {}", abs(-5));
    }
}
```

---

### Bridge: Rust for Python Programmers

**Static Typing with Type Inference**

```rust
// Python: x = [1, 2, 3]
// Rust infers the type from usage:
let mut numbers = Vec::new();
numbers.push(1_i32);
numbers.push(2);
numbers.push(3);

// Explicit when needed:
let numbers: Vec<i32> = vec![1, 2, 3];
```

**Error Handling (no exceptions)**

```rust
use std::num::ParseIntError;

fn double_number(s: &str) -> Result<i32, ParseIntError> {
    let n = s.trim().parse::<i32>()?; // ? propagates error
    Ok(n * 2)
}

fn main() {
    match double_number("5") {
        Ok(n) => println!("Doubled: {n}"),
        Err(e) => println!("Error: {e}"),
    }
}
```

**GIL-Free Concurrency**

```rust
use std::thread;
use std::sync::{Arc, Mutex};

fn main() {
    let counter = Arc::new(Mutex::new(0));
    let mut handles = vec![];

    for _ in 0..10 {
        let counter = Arc::clone(&counter);
        let handle = thread::spawn(move || {
            let mut num = counter.lock().unwrap();
            *num += 1;
        });
        handles.push(handle);
    }

    for handle in handles {
        handle.join().unwrap();
    }

    println!("Result: {}", *counter.lock().unwrap()); // 10
}
```

---

### Deep Dive: Async Rust

**Basic Async with Tokio**

```rust
use tokio::time::{sleep, Duration};

#[tokio::main]
async fn main() {
    let result = fetch_data().await;
    println!("{result}");
}

async fn fetch_data() -> String {
    sleep(Duration::from_millis(100)).await;
    "data loaded".to_string()
}
```

**Concurrent Tasks**

```rust
use tokio::task;

#[tokio::main]
async fn main() {
    let (a, b) = tokio::join!(
        task::spawn(async { expensive_computation(1).await }),
        task::spawn(async { expensive_computation(2).await }),
    );
    println!("{} {}", a.unwrap(), b.unwrap());
}

async fn expensive_computation(n: u64) -> u64 {
    tokio::time::sleep(std::time::Duration::from_millis(n * 100)).await;
    n * 42
}
```

**Cancellation-Safe Streams**

```rust
use tokio_stream::{self as stream, StreamExt};

#[tokio::main]
async fn main() {
    let mut s = stream::iter(vec![1, 2, 3, 4, 5]);
    while let Some(value) = s.next().await {
        println!("got {value}");
    }
}
```

---

### Advanced: Rust Patterns

**Type-Safe Builder Pattern**

```rust
#[derive(Debug)]
struct Config {
    host: String,
    port: u16,
    max_connections: usize,
}

struct ConfigBuilder {
    host: String,
    port: u16,
    max_connections: usize,
}

impl ConfigBuilder {
    fn new() -> Self {
        Self {
            host: "localhost".into(),
            port: 8080,
            max_connections: 100,
        }
    }
    fn host(mut self, h: impl Into<String>) -> Self { self.host = h.into(); self }
    fn port(mut self, p: u16) -> Self { self.port = p; self }
    fn max_connections(mut self, m: usize) -> Self { self.max_connections = m; self }
    fn build(self) -> Config {
        Config { host: self.host, port: self.port, max_connections: self.max_connections }
    }
}

fn main() {
    let config = ConfigBuilder::new()
        .host("0.0.0.0")
        .port(9090)
        .max_connections(500)
        .build();
    println!("{config:?}");
}
```

**Custom Allocator**

```rust
use std::alloc::{GlobalAlloc, Layout, System};
use std::sync::atomic::{AtomicUsize, Ordering};

static ALLOCATED: AtomicUsize = AtomicUsize::new(0);

struct TrackingAllocator;

unsafe impl GlobalAlloc for TrackingAllocator {
    unsafe fn alloc(&self, layout: Layout) -> *mut u8 {
        ALLOCATED.fetch_add(layout.size(), Ordering::Relaxed);
        System.alloc(layout)
    }
    unsafe fn dealloc(&self, ptr: *mut u8, layout: Layout) {
        ALLOCATED.fetch_sub(layout.size(), Ordering::Relaxed);
        System.dealloc(ptr, layout)
    }
}

#[global_allocator]
static A: TrackingAllocator = TrackingAllocator;

fn main() {
    let _v: Vec<u8> = vec![0u8; 1024];
    println!("Allocated: {} bytes", ALLOCATED.load(Ordering::Relaxed));
}
```

---

### Expert: Type-Driven Correctness

*