Work In Progress

This book is still going through heavy edits. Pardon the dust.

What you will find here

This book is a compendium of Rust ecosystem examples, recipes, and links. It is intended to be everything you need for day-to-day Rust coding, in one place.

It quickly summarizes the basics of the language and often-used elements of the standard library.

It then focuses on cross-cutting concerns that affect most aspects of development e.g. error handling, error customization, configuration, p-debugging...

Concurrency, including asynchronous programming, is covered in details.

Next are tools, such as Cargo, Clippy, Rustfmt, as well as links and examples specific to programming domains such as CLI and Web development. The links section provides pointers to notable Rust websites, books, and code examples.

Who should read this book?

This book is intended both for new Rust programmers (to get an overview of the capabilities of the Rust ecosystem and pointers to other resources) and for experienced programmers (to find code examples and review best practices for common programming tasks).

Readers should have already some basic familiarity with Rust⮳ concepts. The Rust book⮳ is an excellent resource for complete beginners to get started with.

Why this book?

Per the curated list of Rust crates blessed.rs⮳, "the standard library in Rust is much smaller than in Python or Go, for example. Those languages come with "batteries included" support ... Rust, on the other hand, gets things like that from the crates.io ecosystem and the Cargo package manager. But with almost more than 100 thousand crates to choose from, a common complaint from new Rust developers is that they don't know where to start, which crates they ought to use, and which crates they ought to trust." There are (not yet) dominant frameworks or platforms like Rails, Django, Spring or Node in the Rust world.

This book intends to provide EXAMPLES to demonstrate the use of key Rust crates, examples which are absent from or scattered in the reference docs⮳, and hopes to become a "cheat sheet on steroid" for the Rust ecosystem (not just for the Rust language).

What other books should I consult?

The Rust cookbook⮳ demonstrate good practices to accomplish common programming tasks, using the crates of the Rust ecosystem. It focuses mainly on std and a few core crates. The Rust Cookbook is a collection of simple examples that demonstrate good practices to accomplish common programming tasks, using the crates of the Rust ecosystem.

Rust by Example⮳ is similar in concept - a collection of runnable examples - but not in scope, as it focuses solely on the Rust language and standard libraries.

Index of Examples

Accessibility

Screen Readers

Recipe	Crates	Categories
Make a user interface accessible to screen readers

Algorithms

Randomness

Recipe	Crates	Categories
Generate random numbers
Generate random numbers within a range
Generate random numbers with given distribution
Generate random values of a custom type
Create random passwords from a set of alphanumeric characters
Create random passwords from a set of user-defined characters

Sorting

Recipe	Crates	Categories
Sort a Vector of Integers
Sort a Vector of Floats
Sort a Vector of Structs

API Bindings

Python Interop

Recipe	Crates	Categories
Python Interop

Asynchronous

Async

Recipe	Crates	Categories
Basic Example
Differences with other languages
Which crate provides what?
Async runtimes

Async and Blocking

Recipe	Crates	Categories
Calling blocking code from async code
Tokio spawn_blocking
Using the rayon crate
Spawn a dedicated thread
Call async code from blocking code
Futures executor
Using the Tokio runtime directly

Async Channels

Recipe	Crates	Categories
OneShot
Multiple Producer, Single Consumer

Async Traits

Recipe	Crates	Categories
Async traits

Futures

Recipe	Crates	Categories
Selecting futures
Joining futures
Map, then, either, flatten

Streams

Recipe	Crates	Categories
Streams

Tokio

Recipe	Crates	Categories
Basics
Join
Spawning
IO
Graceful shutdown

Authentication

Basic Authentication

Recipe	Crates	Categories
Basic Authentication

Caching

LRU Caching

Recipe	Crates	Categories
LRU cache

Command Line Interface

ANSI Terminal

Recipe	Crates	Categories
ANSI Terminal
Printing colored text to the Terminal
Bold text in Terminal
Bold and colored text in terminal
Manipulate the cursor, style the output, handle input events

Arguments

Recipe	Crates	Categories
Using clap's builder API
Using clap's derive API
lexopt
pico-args

TUI

Recipe	Crates	Categories
Build complex TUI		{{hi:Command-line interface}}

User Interaction

Recipe	Crates	Categories
Ask for confirmation, selection, text input
Display progress bars and spinners	{{hi:indicatif}}

Command Line Utilities

Filesystem

Recipe	Crates	Categories
lsd
exa
broot
bat
open

Networking

Recipe	Crates	Categories
Networking tools: gping

Shells

Recipe	Crates	Categories
Shells and related utilities

Compilers

Cross Compilation

Recipe	Crates	Categories
Cross-compile for multiple target OSes and architectures

Faster Linking

Recipe	Crates	Categories
Faster linking
Alternative - Mold linker

Compilation Duration Reduction

Recipe	Crates	Categories
Use dynamic Linking
Compile incrementally
Measuring build times
Change optimization levels
Compilation duration reduction
Incremental computation

Compression

tar

Recipe	Crates	Categories
Decompress a tarball
Compress a directory into a tarball
Decompress a tarball while removing a prefix from the paths

Computer Vision

OpenCV

Recipe	Crates	Categories
Analyze images with Open CV

Shared State

Concurrent Data Structures

Recipe	Crates	Categories
Dashmap
Bounded Multi-producer Multi-consumer Queue
flurry

Shared State

Recipe	Crates	Categories
Mutexes
Parking Lot
Atomics
arc-swap

Config

Configuration

Recipe	Crates	Categories
Configuration Management with Config
Configuration Management with Confy

Environment Variables

Recipe	Crates	Categories
Read environment variables from a .env file
Retrieve a single environment variable
Deserialize environment variables into type-safe structs

Cryptography

Encryption

Recipe	Crates	Categories
Salt and hash a password with PBKDF2

Hashing

Recipe	Crates	Categories
Calculate the SHA-256 digest of a file
Sign and verify a message with an HMAC digest
General Purpose Hashing
AEAD Encryption
RSA
Digital Signatures
Certificate Formats
TLS / SSL
Utilities

Password Hashing

Recipe	Crates	Categories
argon2
scrypt
bcrypt

Data Structures

Bitfield

Recipe	Crates	Categories
Define and operate on a type represented as a bitfield
Flagset

Maps

Recipe	Crates	Categories
Insertion-ordered map
Multimap
Slotmap

Stack-allocated Arrays

Recipe	Crates	Categories
arrayvec
smallvec
tinyvec

UUIDs

Recipe	Crates	Categories
Generate and parse UUIDs

Database Implementations

Databases

Recipe	Crates	Categories
Sled
SurrealDB		[] cat-database-implementations

Search

Recipe	Crates	Categories
Meilisearch
Tantivy

Date and Time

Duration

Recipe	Crates	Categories
Measure elapsed time
Perform checked date and time calculations
Convert a local time to another timezone

Parse

Recipe	Crates	Categories
Examine the date and time
Convert date to UNIX timestamp and vice versa
Display formatted date and time
Parse string into DateTime struct

Time

Recipe	Crates	Categories
Use the time crate

Cargo & Friends

Cargo

Recipe	Crates	Categories
Basic Cargo Usage
Cargo.toml and lock files

Crate Registries

Recipe	Crates	Categories
Crate Registries

Package Layout

Documentation

Badges

Recipe	Crates	Categories
Badges	Shield.io

Documentation

Recipe	Crates	Categories
Documenting your code
Module or crate-level documentation

mdbook

Recipe	Crates	Categories
mdBook
mdbook plugins
CD / CI
Rust playground

Formatting

Formatting

Recipe	Crates	Categories
Rustfmt
Rustfmt Configuration
Formatting attributes

Installation

Installation

Recipe	Crates	Categories
Rustup
Cargo install
Cargo binstall

rustup

Recipe	Crates	Categories
Key commands

Other

just

Recipe	Crates	Categories
Installation in a dev container
Example justfile

miri

Recipe	Crates	Categories
Miri
Miri installation

Other

Recipe	Crates	Categories
Background code checker
API search	roogle{{hi:roogle}}
Deployment on shuttle.rs	shuttle.rs
Binary minimizer
Code generators
Code verifier
Formal Methods

Versioning

Versioning

Recipe	Crates	Categories
Parse and increment a version string
Parse a complex version string
Check if given version is pre-release
Find the latest version satisfying given range
Check external command version for compatibility

Development Tools: Build Utils

Build Utils

Recipe	Crates	Categories
Compile and link statically to a bundled C library
Compile and link statically to a bundled C++ library
Compile a C library while setting custom defines

Development Tools: Cargo-Plugins

Auditing

Recipe	Crates	Categories
Audit Cargo.lock files for crates containing security vulnerabilities
Embded the exact crate versions in your Rust executable for auditability
List the license(s) of dependencies
cargo deny

Building

Recipe	Crates	Categories
cargo make
Devx
xshell: Making Rust a Better Bash

Code Formatting and Linting

Recipe	Crates	Categories
Format your code
Format
Lint your code
Fix compiler warnings
Check your code before committing it

Cross-Compiling

Recipe	Crates	Categories
Cross-compile using Zig as the linker

Maintaining

Recipe	Crates	Categories
Unused dependencies	udeps
Edit Cargo.toml
Find unused dependencies
cargo udeps
cargo machete
Detect dependencies that are out of date
Lint your crate API changes for semver violations
Manage the cargo cache

Performance

Recipe	Crates	Categories
Configure your Cargo project for maximum performance, fast compile times or minimal binary size
cargo hakari

Watching For Changes

Recipe	Crates	Categories
Cargo watch
Cargo limit

Writing

Recipe	Crates	Categories
Templates	Cargo Generate
Generate a Rust project from a template
Quickly open the crates.io or docs.rs page for the latest version of a crate

Development Tools: Debugging

Alternatives

Recipe	Crates	Categories
Older alternatives to tracing
log
slog
log4rs
env_logger
Other frameworks
OpenTelemetry
OpenObserve

Config Log

Recipe	Crates	Categories
Enable log levels per module
Use a custom environment variable to set up logging
Include a timestamp in log messages
Log messages to a custom location

Diagnostic Functions

Recipe	Crates	Categories
Get the type name of the pointed-to value

Log

Recipe	Crates	Categories
Log a debug message to the console
Log an error message to the console
Log to stdout instead of stderr
Log messages with a custom logger
Log to the Unix syslog

Tracing

Recipe	Crates	Categories
Tracing initialization
Basic tracing
Combine layers
Configure a custom event formatter
Events
Spans
Add tracing spans to functions
Related crates

Development Tools: FFI

Generate FFI Bindings

Recipe	Crates	Categories
bindgen
cbindgen
cxx		{{hi:No standard library}}

Development Tools: Procedural Macro-Helpers

Compile Macros

Recipe	Crates	Categories
Watt

Tools

Recipe	Crates	Categories
cargo expand

Write Proc Macros

Recipe	Crates	Categories
Parse Rust source code
paste
quote
proc-macro2
darling

Development Tools: Profiling

Assembly

Recipe	Crates	Categories
Inspect the generated assembly

Benchmarking

Recipe	Crates	Categories
cargo flamegraph
Criterion
Divan
Hyperfine

Memory

Recipe	Crates	Categories
Profile heap memory

Development Tools: Testing

Fuzzing

Recipe	Crates	Categories
afl

Testing

Recipe	Crates	Categories
Test your code with cargo test
Emit a custom message
cargo nextest
Approx
Snapshot testing
Code coverage

Email

Send Emails

Recipe	Crates	Categories
Send an email

Embedded

Embassy

Recipe	Crates	Categories
Embassy

Emulators

Emulators

Recipe	Crates	Categories
emulators

Encoding

Complex

Recipe	Crates	Categories
Serialize and deserialize unstructured JSON
Deserialize a TOML configuration file
Read and write integers in little-endian byte order

CSV

Recipe	Crates	Categories
Read CSV records
Read CSV records with different delimiter
Filter CSV records matching a predicate
Handle invalid CSV data with Serde
Serialize records to CSV
Serialize records to CSV using Serde
Transform one CSV column

Serde

Recipe	Crates	Categories
JSON
serde-json
monostate
serde-ignored

Strings

Recipe	Crates	Categories
Percent-encode a string
Encode a string as application/x-www-form-urlencoded
Encode and decode hex
Encode and decode base64

Typecasts

Recipe	Crates	Categories
bytemuck
zerocopy

External FFI Bindings

External FFI Bindings

Recipe	Crates	Categories
ffi

Filesystem

cwd

Recipe	Crates	Categories
Get the current working directory

dir

Recipe	Crates	Categories
File names that have been modified in the last 24 hours
Find loops for a given path
Recursively find duplicate file names
Recursively find all files with given predicate
Traverse directories while skipping dotfiles
Recursively calculate file sizes at given depth
Find all png files recursively
Find all files with given pattern ignoring filename case

File Watching

Recipe	Crates	Categories
Watch files or directories and execute a function when they change

Ignore

Recipe	Crates	Categories
Walk the filesystem while respecting ignore files

Read & Write Files

Recipe	Crates	Categories
Read lines of strings from a file
Avoid writing and reading from a same file
Access a file randomly using a memory map

Tempfiles and Directories

Recipe	Crates	Categories
Create temporary files or temporary directories

User Directories

Recipe	Crates	Categories
Get platform-specific locations for configuration, cache, and other data with dirs
Get platform-specific locations for configuration, cache, and other data with directories

Finance

Quant

Recipe	Crates	Categories
RustQuant

Game Development

Game Development

Recipe	Crates	Categories
Game development

Game Engines

Game Engines

Recipe	Crates	Categories
bevy
fyrox
ggez
macroquad
glam

Graphics

Webgpu

Recipe	Crates	Categories
wgpu

GUI

2D Renderers

Recipe	Crates	Categories
femtovg
skia-safe
vello
vger
webrender

Clipboard

Recipe	Crates	Categories
arboard

File Dialogs

Recipe	Crates	Categories
rfd

GTK

Recipe	Crates	Categories
gtk4
relm4

Immediate Mode Gui

Recipe	Crates	Categories
eGUI

Other GUI

Recipe	Crates	Categories
xilem
slint
GPUI
druid

Retained-mode GUI

Recipe	Crates	Categories
iced
floem

Text Layout

Recipe	Crates	Categories
cosmic-text
parley

UI Layout

Recipe	Crates	Categories
taffy
morphorm

Web-based GUI

Recipe	Crates	Categories
Tauri
dioxus

Window Creation

Recipe	Crates	Categories
winit
tao

Hardware Support

Processor

Recipe	Crates	Categories
Get the number of logical cpu cores

Internationalization

Internationalization

Recipe	Crates	Categories
internationalization

Localization

Localization

Recipe	Crates	Categories
Localization

Mathematics

Additional Numeric Types

Recipe	Crates	Categories
Abstracting over different number types
Big integers
Big decimal
Sortable Floats

Complex Numbers

Recipe	Crates	Categories
Creating complex numbers
Adding complex numbers
Mathematical functions on complex numbers

Linear Algebra

Recipe	Crates	Categories
Vector Norm
Adding matrices
Multiplying matrices
Multiply a scalar with a vector with a matrix
Invert matrix
Vector comparison
(De)-Serialize a Matrix

Statistics

Recipe	Crates	Categories
Computing standard deviation
Measures of central tendency
Standard deviation

Trigonometry

Recipe	Crates	Categories
Calculating the side length of a triangle
Verifying tan is equal to sin divided by cos
Distance between two points on the Earth

Memory Management

Global Static

Recipe	Crates	Categories
Declare lazily evaluated constant

Lazy Initialization

Recipe	Crates	Categories
std
once_cell
lazy_static

Multimedia Audio

Audio

Recipe	Crates	Categories
Audio

Multimedia Encoding

Encoding

Recipe	Crates	Categories
Multimedia encoding

Multimedia Images

Images

Recipe	Crates	Categories
Images

Multimedia Video

Video

Recipe	Crates	Categories
Video

Network Programming

Reverse Proxy

Recipe	Crates	Categories
Rathole
ngrok
nginx
Pingora

Server

Recipe	Crates	Categories
Listen on unused port TCP/IP
Listen on unused port TCP/IP
Perform asynchronous I/O operations on storage devices
glommio

No alloc

No alloc

Recipe	Crates	Categories
No alloc

OS: FreeBSD APIs

FreeBSD

Recipe	Crates	Categories
FreeBSD

OS: Linux APIs

Linux

Recipe	Crates	Categories
Linux

OS: macOS APIs

macOS

Recipe	Crates	Categories
macOS

OS: Unix APIs

Unix

Recipe	Crates	Categories
rustix		{{hi:Unix APIs}}
nix		{{hi:Unix APIs}}

OS: Windows APIs

Windows

Recipe	Crates	Categories
Integrate with Windows APIs
winapi

Parser Implementations

Parser Implementations

Recipe	Crates	Categories
JavaScript

Parsing

Parsing

Recipe	Crates	Categories
Nom
Pest
Tree sitter

Rendering: Data Formats

Data Formats

Recipe	Crates	Categories
Data formats

Rendering Engine

Rendering Engines

Recipe	Crates	Categories
Render

Rendering: Graphics APIs

Graphics APIs

Recipe	Crates	Categories
Graphics

Rust Patterns

Design Patterns

Recipe	Crates	Categories
Abstract factory
dyn-clone
Lens

Error Customization

Recipe	Crates	Categories
Anyhow
thisError
miette
color-eyre

Error Handling

Recipe	Crates	Categories
Handle errors correctly in main
Irrecoverable panics
Recoverable errors with Result
unwrap_or_else
A Shortcut for propagating errors: the ? Operator
Avoid discarding errors during error conversions
Obtain backtrace of complex error scenarios

Functional Programming

Recipe	Crates	Categories
Compose iterators with itertools

Rust Idioms

Recipe	Crates	Categories
Rust idioms

Science Geo

Geo

Recipe	Crates	Categories
Geoscience

Science Neuroscience

Neuro

Recipe	Crates	Categories
Neuroscience

Science Robotics

Robotics

Recipe	Crates	Categories
Robotics	robotics.rs

Useful Robotics Tools And Libs

Recipe	Crates	Categories
Open CV
zenoh
Open Rust Robotics
bonsai-bt

Simulation

Simulation

Recipe	Crates	Categories
Simulation

Template Engine

Tera

Recipe	Crates	Categories
Create HTML files from a template

tinytemplate

Recipe	Crates	Categories
tinytemplate

Text Editors

IDEs

Recipe	Crates	Categories
VS Code	VS Code
IntelliJ Rust
Zed
Helix Editor

Text Processing

Regex

Recipe	Crates	Categories
Verify and extract login from an email address
Extract a list of unique #Hashtags from a text
Extract phone numbers from text
Filter a log file by matching multiple regular expressions
Replace all occurrences of one text pattern with another pattern.

String Concat

String Parsing

Recipe	Crates	Categories
Collect Unicode Graphemes
Implement the FromStr trait for a custom struct

Value Formatting

Value Formatting

Recipe	Crates	Categories
Value formatting

Virtualization

Virtualization

Recipe	Crates	Categories
Virtualization

Visualization

Visualization

Recipe	Crates	Categories
Visualization

Wasm

Others

Yew

Recipe	Crates	Categories
Yew

Web Programming: HTTP Client

APIs

Recipe	Crates	Categories
Query the GitHub API
Check if an API resource exists
Create and delete Gist with GitHub API
Consume a paginated RESTful API
Handle a rate-limited API

Download

Recipe	Crates	Categories
Download a file to a temporary directory
Make a partial download with HTTP range headers
POST a file to paste-rs

HTTP Clients

Recipe	Crates	Categories
reqwest
ureq
hyper

Requests

Recipe	Crates	Categories
Make a HTTP GET request
Set custom headers and URL parameters for a REST request
Async

Web Pr: HTTP Server

actix

Recipe	Crates	Categories
Actix

axum

Recipe	Crates	Categories
Axum

Batteries-included frameworks

CORS

Recipe	Crates	Categories
CORS

GraphQL

gRPC

hyper

Middleware

Recipe	Crates	Categories
Tower
Tower HTTP
Alternatives

Other Frameworks

Recipe	Crates	Categories
Rocket
Leptos

Static Website Generators

Recipe	Crates	Categories
Static website generator - Zola
Zola themes

Web-Programming Websocket

Websocket

Recipe	Crates	Categories
Low-level
General Purpose

Contributing

API Documentation

Development Editing

Dev Container Docker

Dev Environment Setup

Optional Preprocessors

Publication

Repo Structure

Topics of Interest

Language

Attributes

Closures

Control Flow

Enums

Functions

Generics

Iterators

Lifetimes

Macros

Main

Match

Modules

Ownership Borrowing

Rust Install

Simple Data Types

Slices

Structs

Traits

Trait Objects

Variables and Constants

Links

Blogs, Podcasts, Meetups

Books

Companies

Example Code

Learning

Links

Rust Cheatsheets

Architecture

Architecture

Cloud

AWS

Rust-native Cloud Development

Serverless

Recipe	Crates	Categories
Implement serverless computing with Rust
Use the dapr distributed runtime with Rust

Containers

Containers

Cross Platform

Crux

Recipe	Crates	Categories
Develop across platforms with Crux

Data Processing

CSV

Dataframes

Recipe	Crates	Categories
Manipulate data in a tabular format

Data Engineering

Recipe	Crates	Categories
Develop data analytics applications that process columnar data with Arrow
Query in-memory data with datafusion
Databend
Arrow
Datafusion

Data Visualization

Devops

CD/CI

Dependency Management

DevOps

Github Actions

Git Hooks

Release Automation

GPU

GPU

Recipe	Crates	Categories
rust-gpu

Scripting

rhai

Recipe	Crates	Categories
Embed Rust scripting in your application

Written in Rust

Development Tools

Others

Python Tools

Recipe	Crates	Categories
rustpython
pyOxidizer
Ruff
uv

Standard Library

Asref

Recipe	Crates
AsRef

Cow

Recipe	Crates
Convert Cow to &str
Convert Cow to String

Derive

Recipe	Crates
Automatically implement common traits using the derive attribute
Automatically implement additional traits using derive_more

Hashmaps

Recipe	Crates
Hashmaps

Option

Recipe	Crates
Option
Adapters for working with references
Extracting the value contained in Option
Combinators

Result

Recipe	Crates
Result

Smart Pointers

Recipe	Crates
Box
Rc
RefCell

Strings

Recipe	Crates
String type
Placeholders
String concatenation

Vectors

Recipe	Crates
Vec

Call for contributions

This book is in its early days. Contributions, from small edits to whole chapters, are most welcome.

It is also intended to be easy for (new) Rust programmers to contribute to and get involved with the Rust community.

Feel free to submit an issue or a pull request to the repo⮳. Draft pages are kept in this folder⮳. An informal (and very long) list of subjects we would like to cover is kept in the topics of interest⮳ page.

Embedded examples should be ideally runnable on the Rust playground⮳ or at least directly copy-pasteable into Rust code.

This book's long-term goal is the coverage of the 'most commonly used' Rust crates, as defined by blessed.rs⮳, the most downloaded libraries in crates.io⮳, and 'high quality crates' per lib.rs⮳ statistics⮳. Review key crates⮳ for topic ideas.

Unless you explicitly state otherwise, any contribution you intentionally submit for inclusion in this book shall be licensed under the same terms than the rest of the book, without any additional restrictions or conditions.

Please read CONTRIBUTING.md for more details.

See also

Topics of interest

• Async
• CD / CI
• Macros
• AWS and other Cloud services
• Advanced data structures
• Basic and advanced TCP/IP networking
• More database examples, including object databases, graph databases, BonsaiDB
• Zip files and other archives
• Authentication / authorization: OAuth2, LDAP/AD, DNS lookups
• FLTK
• GPU processing, CUDA
• Machine learning, Tensorflow
• Raft Consensus library
• Network file systems
• Statistics, math
• Crypto, SSL, SSH, other public key encryption, X.509, RusTLS
• Sound, graphics
• Games
• Search engines
• Buffer pools, garbage collection, or other reference-counted examples
• IPv6 address processing
• Cloud stuff: LB, status reporting (Vigil), routing, orchestration, containers
• Version control: libgit2: clone, change branches, create commits, push, pull
• High-performance computing: OpenMP, etc.
• Social media APIs
• Personal file sharing: OwnCloud, etc.

Repo structure

• The repo contains a book, which markdown sources are in the src folder.
• After the book is built using mdbook⮳, the resulting HTML and Javascript are found in book/html.
• The intermediate (processed) Markdown is in book/markdown. The mdbook⮳ configuration is in book.toml; the templates and assets are in theme and static respectively.
• The Rust code is organized as a cargo⮳ workspace:
  • Examples that are embedded in the book are found in deps/tests and deps/examples. These are mostly single, short .rs files. The deps/Cargo.toml list all dependencies used by the embedded examples. Use cargo add <crate> -F <feature> while in the deps folder to add more as required. deps/build.rs creates the Skpetic tests that validate all embedded examples.
  • Additional examples that are too long or complex to be inserted in the book itself will be added under xmpl.
  • tools contains utilities that e.g. generate the sitemap file and organize links.
• The Dev Container and Docker (Compose) configuration files are found in .devcontainer.

Development Environment Setup

Using VS Code

Clone the repo⮳ and open the folder in VS Code⮳. Edit .devcontainer/.env if needed. VS Code should prompt you to open the code in a docker⮳ container, which installs mdbook⮳ and rust tooling automatically. Make sure you have previously installed

• Dev Container extension⮳
• Docker Desktop]⮳ (or at least the Docker engine).

Note that opening the code folder in VS Code may take a little while the first time around.

Other

If you are not using VS Code, install the Dev Container CLI⮳ or simply install the required tools on your local machine:

sudo apt-get update # or equivalent for other distros
# sudo apt-get install fzf # optional
# sudo apt-get mold clang # if using
rustup update
rustup component add clippy
cargo install cargo-nextest
cargo install mdbook
cargo install just
cargo install mdbook_linkcheck
cargo install mdbook-utils
# for cargo +nightly fmt
rustup toolchain install nightly
rustup component add rustfmt --toolchain nightly

You may need sudo apt-get install libsqlite3-dev on WSL.

Review .devcontainer/Dockerfile for other dependencies.

Book Editing and Example Code Development

Type just⮳ (a tool similar to make⮳) in your favorite shell to lists all commonly used recipes during book editing and example code development.

Use just serve to preview the book by serving it locally on http://localhost:3000⮳.

To add or edit the book, simply update or add a .md file in the appropriate src⮳ subfolder, then add a link in SUMMARY.md⮳.

• Add Rust code examples under deps/tests⮳.
  • Make sure to format your code (just fmtall or cargo +nightly fmt --all), check it compiles (just buildall or cargo build --all-targets), lint it (just clippyall or cargo clippy --all-targets), and test it (just testall or cargo test --test <name> for an individual example). You may also cargo run --example <name>.
  • Include your code example in the Markdown via {{# include /path/to/file.rs}} within pairs of triple backticks.
• You may write very short examples directly in the Markdown (but they won't be be formatted / linted automatically).
• rust language code blocks in the Markdown will automatically get a play button, which will execute the code in the Rust Playground⮳ and display the output just below the code block. Adding the mdbook-runnable attribute forces the play button to be displayed when ignore⮳ is set.
• The Rust playground only supports the top 100 most downloaded libraries and libraries used by the Rust Cookbook. noplayground⮳ removes the play button if a code block does not work on the playground.
• Example projects that are too complex to be inserted in the book itself (e.g. that include multiple modules) should be added as separate folders below xmpl. Use cargo new or cargo init to create packages as usual. Insert a link to the appropriate GitHub page in the markdown.

Verify the markdown is properly rendered using just serve or mdbook serve --open. Pushing a commit to the main branch on GitHub will trigger a GitHub Action workflow that checks formatting / linting, builds / tests all examples, then deploys the book to GitHub Pages.

Dev Container and Docker

The development target of the multi-stage .devcontainer\Dockerfile is used by .devcontainer/devcontainer.json to install mdbook⮳ and rust tooling.

If you don't want to use Dev Container, use the following from the project's root directory to manually build the docker⮳ image and run it.

docker build --file .devcontainer/Dockerfile --target development --tag rust_howto_dev --build-arg RUST_IMAGE_LABEL=1.75.0-slim-bookworm --build-arg MDBOOK_VERSION=0.4.36 .
docker run --rm --detach --name rust_howto_dev1 --volume $(pwd):/code rust_howto_dev
docker exec -it rust_howto_dev1 bash

To cache the crate and the target folders from run to run, add

--mount type=volume,src=rust_howto_cargo_crate_cache,dst=/usr/local/cargo/registry/
--mount type=volume,src=rust_howto_cargo_target_cache,dst=/cargo-target-rust_howto/

To connect to the (host OS) docker engine from within the container, add

--mount type=bind,src=/var/run/docker.sock,dst=/var/run/docker-host.sock

Docker Compose

Test the docker compose setup used during developement (which Dev Container runs) with:

cd ./.devcontainer
docker compose build # uses compose.yaml and compose.override.yaml
docker compose up -d
# or simply
docker compose up --build -d

Deployment to GitHub Pages

The continuous integration worflow is found under .github.

Test the docker compose setup used during CI using:

cd ./.devcontainer
docker compose -f compose.yaml -f compose-ci.yaml build
docker compose -f compose.yaml -f compose-ci.yaml run book # or simply docker compose -f compose.yaml -f compose-ci.yaml up

It uses the ci target in .devcontainer/Dockerfile.

To test the docker⮳ image manually, use

docker build --file .devcontainer/Dockerfile --target ci --tag rust_howto_ci --build-arg RUST_IMAGE_LABEL=1.75.0-slim-bookworm --build-arg MDBOOK_VERSION=0.4.36 .
docker run -it --rm --name rust_howto_ci1 --volume $(pwd)/book:/code/book rust_howto_ci bash

Related Stackoverflow question⮳

Push image to Docker Hub

From the project root folder, use the following to build and push the development image:

docker build --file .devcontainer/Dockerfile --target development --tag johncd/rust_howto_dev:latest --build-arg RUST_IMAGE_LABEL=1.75.0-slim-bookworm --build-arg MDBOOK_VERSION=0.4.36 .
# or docker tag rust_howto_dev johncd/rust_howto_dev:latest
docker login
# or docker login -u "user" -p "password" docker.io
docker push johncd/rust_howto_dev:latest

Use the following to build and push the CI image:

docker build --file .devcontainer/Dockerfile --target ci --tag johncd/rust_howto_ci --build-arg RUST_IMAGE_LABEL=1.75.0-slim-bookworm --build-arg MDBOOK_VERSION=0.4.36 .
docker login
docker push johncd/rust_howto_ci:latest

Optional pre-processors

• mdbook-linkcheck⮳ is a backend for mdbook⮳ that will check links. Install with cargo install mdbook-linkcheck. Uncomment the related section in book.toml.
• mdbook-hide⮳ hides chapters under construction. Install with cargo install mdbook-hide. Uncomment the related section in book.toml. To mark a chapter as hidden, add the following comment anywhere in the Markdown file. It is better to have it at the top of the file for clarity.

<!--hidden-->

• mdbook-keeper⮳. Install with

cargo install mdbook_keeper --git https://github.com/tfpk/mdbook_keeper.git

Generate the docs.rs Documentation

Use just doc to generate the documentation for docs.rs.

cargo doc --open does not seem to work when running from a Dev Container in VS Code; the script that opens URLs into an external browser (see $ echo $BROWSER) does not handle raw HTML. Use python3 -m http.server 9000 or live server to serve the files instead. See the doc recipe in justfile⮳.

Using a Dev Container feature

Alternatively, use the "Desktop lite" Dev Container feature⮳ to install a light GUI manager. Add the following to devcontainer.json:

"features": {
    "ghcr.io/devcontainers/features/desktop-lite:1": {}
},
"forwardPorts": [
    6080
],
"portsAttributes": {
    "6080": {
        "label": "desktop"
    }
},

and the following to the Dockerfile⮳

RUN apt-get update && export DEBIAN_FRONTEND=noninteractive && apt-get install -y firefox-esr

Optionally apt-get install xdg-utils to check that Firefox is the default for text/html:

xdg-mime query default text/html
# or for more details:
XDG_UTILS_DEBUG_LEVEL=2 xdg-mime query default text/html

xdg-settings --list
xdg-settings get default-web-browser

Point your browser to http://localhost:6080 and use vscode as the password. Open the HTML file of your choice with:

xdg-open /cargo-target-rust_howto/target/doc/deps/index.html

Other methods to preview the documentation HTML

• Add the target directory e.g. /cargo-target-rust_howto/target to the VS Code Explorer view (File > Add Folder to Workspace...), then right-click the /cargo-target-rust_howto/target/doc folder in the VS Code Explorer view and select Download... or use VS Code's built-in Simple Browser command.
• Or install the Live Server or MS Live Preview VS Code extensions.

Publish to crates.io

The publish folder contains a placeholder crate, so that the book could be located when searching on crates.io.

• Go to crates.io, sign in, and create an API token in Account Settings > API Tokens.
• Use cargo login to save the token in $CARGO_HOME/credentials.toml.
• cd publish; cargo build; cargo clippy; cargo run; cargo doc; cargo package
• Review the packaging output in /cargo-target-rust_howto/target/package.
• When ready, cargo publish --dry-run; cargo publish

Rust language

Rust is a modern programming language that offers high performance, reliability, and productivity. It is designed to prevent common errors such as memory leaks, data races, and null pointer dereferences, by enforcing strict rules at compile time. Rust also supports powerful features such as generics, traits, macros, and concurrency, making it suitable for a wide range of applications.

Rust prefers snake case for variables and functions, so a method would be called read_str instead of readStr. For structs, traits and enums, camel case (or Pascal case) is used, for example HttpClient.

Rust Installation

Install Rust⮳

Key Steps

• Install Rustup⮳

On WSL / Unix:

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

• Check whether you have Rust installed correctly

rustc --version
cargo --version

• Open the documentation, if needed

rustup doc

• Create a new project

cargo new hello_world
cd hello_world
code . # open VS Code (or your favorite editor) and edit the code as you wish

• Build / run the code.

cargo check # check if the code can compile
cargo build # compile
cargo run # run the executable

cargo run builds the code if cargo build has not been invoked before or the code has changed.

Main function

use std::fs::File;
use std::io::Read;

use anyhow::anyhow;
use anyhow::Result;

fn read_uptime() -> Result<u64> {
    let mut uptime = String::new();
    File::open("/proc/uptime")?.read_to_string(&mut uptime)?;

    Ok(uptime
        .split('.')
        .next()
        .ok_or(anyhow!("Cannot parse uptime data"))?
        .parse()?)
}

fn main() {
    match read_uptime() {
        Ok(uptime) => println!("uptime: {} seconds", uptime),
        Err(err) => eprintln!("error: {}", err),
    };
}

Async Main Function

use anyhow::Result;

#[tokio::main]
async fn main() -> Result<()> {
    println!("I'm async!");
    Ok(())
}

Simple Data Types

• Integers: i8⮳, i16⮳, i32⮳, i64⮳, i128⮳, isize⮳
• Unsigned: u8⮳, u16⮳, u32⮳, u128⮳, usize⮳
  • usize⮳ and isize⮳ are 32 or 64 bits, depending on the architecture of the computer.
• Floating point: f32⮳, f64⮳
• Boolean: bool⮳: true, false
• Char: let z: char = 'ℤ'; Unicode
• Tuples: let tup: (i32, f64, u8) = (500, 6.4, 1);
  • Access via let five_hundred = x.0;
  • Destructuring via let (x, y, z) = tup;
• Arrays: let a: [i32; 5] = [1, 2, 3, 4, 5]; allocated on the stack. access via let first = a[0];
  • A vector is a similar collection type provided by the standard library that is allowed to grow or shrink in size
• Unit (aka void): ()
• Type aliases: type Kilometers = i32;

Overflow handling

• Wrap in all modes with the wrapping_* methods, such as wrapping_add⮳.
• Return the std::option::Option::None⮳ value if there is overflow with the checked_* methods.
• Return the value and a boolean indicating whether there was overflow with the overflowing_* methods.
• Saturate at the value’s minimum or maximum values with the saturating_* methods.

Variables and Constants

fn main() {
    // `const` is set to a constant expression; the type must be annotated
    const THREE_HOURS_IN_SECONDS: u32 = 60 * 60 * 3;

    let apples = 5; // immutable variable

    let mut guess = String::new(); // mutable variable
}

Shadowing

#![allow(unused)]
fn main() {
    let x = 5; // x is immutable

    let x = x + 1; // redefines x
    println!("{x}");

    let x = "example"; // the type can change
    println!("{x}");
}

Destructuring

#![allow(unused)]
fn main() {
    // destructuring tuples
    let (_x, _y, _z) = (1, 2, 3);

    // destructuring structs
    struct Point {
        x: i32,
        y: i32,
    }

    let p = Point { x: 0, y: 7 };
    let Point { x: _a, y: _b } = p; // a = 0, b = 7
    let Point { x, y } = p; // simpler
    let _ = (x, y);
}

Starting the name of a variable with an underscore silences unused variable warnings.

Ownership and Borrowing

Ownership

• No garbage collector. Ownership instead.
• Each value in Rust has an owner.
• There can only be one owner at a time.

#![allow(unused)]
fn main() {
    let s1 = String::from("hello"); // On the heap
    let _s2 = s1; // s1 was MOVED into s2 - NOT a shallow copy - Rust
                  // invalidates s1 ERROR println!("
                  // {}, world!", s1);
}

When the owner goes out of scope, the value will be dropped.

#![allow(unused)]
fn main() {
    {
        let _s = String::from("hello");
    } // variable out of scope - Rust calls `drop`

    // ERROR println!("{}", s);

}

Rust will never automatically create “deep” copies of your data. Use std::clone::Clone⮳

fn main() {
    let s2 = String::from("hello");
    let _s3 = s2.clone();
    // `clone` deeply copies the heap data of the `String`,
    // not just the stack data
}

If a type implements the std::marker::Copy⮳ trait (stack-only, fixed-size values, like integers, floats, and tuples thereof), variables that use it do not move, but rather are trivially copied, making them still valid after assignment to another variable.

#![allow(unused)]
fn main() {
    let x = 5; // Integer
    let y = x; // No MOVE

    println!("x = {}, y = {}", x, y); // OK

}

Borrowing

Passing a variable to a function will move or copy, just as assignment does. To avoid passing a value along, borrow the value:

fn main() {
    let s1 = String::from("hello");

    let _len = calculate_length(&s1); // pass an immutable reference to s1

    fn calculate_length(s: &str) -> usize {
        s.len()
    } // Here, s goes out of scope. But because it does not have
      // ownership of what it refers to, s1 is not dropped.
}

Mutable reference

fn change(some_string: &mut String) {
    // note the `&mut`
    some_string.push_str(", world");
}

fn main() {
    let mut s = String::from("hello"); // note the `mut`
    change(&mut s);
}

If you have a mutable reference to a value, you can have no other simultaneous references to that value! Functions like a read/write lock.

Slices

Slices

#![allow(unused)]
fn main() {
    let s = String::from("hello world");

    let hello: &str = &s[0..5]; // or &s[..5];
    let world = &s[6..11]; // or &s[6..];

    println!("{}", hello);
    println!("{}", world);
}

Functions

fn foo(x: i32, unit_label: char) -> i32 {
    let y = {
        let z = 3;
        x + z // expression at the end of a block - no semi-colon
    };

    println!("The value of y is: {y}{unit_label}");
    y // returns y - no semi-colon
}

fn main() {
    println!("{}", foo(1, 'm'));
}

The unit type () (void in some languages) is the default return type when no type is given for a function. It could be omitted: fn log(message: &str) { ... }

Generic functions

fn generic<T>(_t: T) {
    println!("got t");
}

// Explicitly specified type parameter `char` to `generic()`.
// Note the turbofish notation ::<>

fn main() {
    generic::<char>('a');
}

use std::fmt::Display;

fn generic<T: ?Sized + Display>(t: &T) {
    // By default, generic functions will work only on types that have a
    // known size at compile time. Use ?Sized to relax that. t must be
    // some kind of pointer: &, Rc, Box...
    println!("{}", t);
}

fn main() {
    let s = String::from("hello");
    generic(&s[..]);
}

Function pointers

fn add_one(x: i32) -> i32 {
    x + 1
}

fn do_twice(f: fn(i32) -> i32, arg: i32) -> i32 {
    // function pointer
    f(arg) + f(arg)
}

fn main() {
    println!("{}", do_twice(add_one, 1));
}

Diverging functions

Diverging functions never return.

fn foo() -> ! {
    // ! is the Never type
    panic!("This call never returns.");
}

fn main() {
    println!("Will panic");
    foo();
}

Control Flow

If else

#![allow(unused)]
fn main() {
    let number = 3;
    let result = if number < 5 {
        // condition must return a bool; `if` is an expression
        println!("condition was true");
        5
    } else {
        println!("condition was false");
        6
    };
    println!("{}", result);
}

Also else if <cond> { ... }

Loop

#![allow(unused)]
fn main() {
    let mut counter = 0;

    let result = loop {
        counter += 1;

        if counter == 10 {
            break counter * 2;
            // `continue` and loop labels also exist:
            // https://doc.rust-lang.org/book/ch03-05-control-flow.html
        }
    };
    println!("{}", result);
}

While

#![allow(unused)]
fn main() {
    let mut number = 5;
    while number != 0 {
        println!("{number}!");
        number -= 1;
    }
}

For

#![allow(unused)]
fn main() {
    let a = [10, 20, 30, 40, 50];

    for element in a {
        println!("the value is: {element}");
    }

    // Range - generates all numbers in sequence
    // starting from one number and ending before another number.
    for number in (1..4).rev() {
        // reverse enumeration
        println!("{number}!");
    }
}

Structs