What is Rust Max?

Rust Max, also known by its crate name rmx, is a collection of crates, tools, and documentation for the Rust programming language.

Rust is a modern systems programming language that is extremely fast and does not crash. It is suitable for development of high-performance, low-level software as in operating systems, databases, and distributed systems; as well as cli, web, device, and application development.

Rust Max is a comprehensive guide to the Rust ecosystem for new and old Rust programmers, including a "batteries-included" supercrate of selected high-quality Rust libraries: rmx.

Rust Max is not an official Rust project.

Rust mastery awaits

• Step 1: Install Rust with rustup.
• Step 2: Learn Rust from The Rust Max Library.
• Step 3: Build programs with Rust crates.
• Step 4: Maintain programs with Rust tools.

Rust Max addons

todo

Easy Mode Rust

Starting a project

Updating dependencies in lockfile

cargo update

Updating dependencies in Cargo.toml

cargo upgrade

With no extra arguments cargo upgrade modifies Cargo.toml files such that the dependencies are set to their latest compatible versions. In this way it similar to cargo update but for manifests instead of lockfiles.

todo This command is from the cargo-edit package.

Upgrading dependencies across minor versions in Cargo.toml

cargo upgrade --incompatible

topics

• anyhow, thiserror

rustup Installation

Rust is installed with the rustup tool.

Linux, Mac OS, and Unixes

run the following in your shell then follow the onscreen instructions:

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

Windows for 64-bit x86_64

download and run rustup‑init.exe then follow the onscreen instructions.

Windows for 32-bit i686

download and run rustup‑init.exe then follow the onscreen instructions.

Rust Max: Crates

Rust Max: Tools

• Standard Rust tools: cargo rustc rustup rustdoc rustfmt clippy just mdbook bindgen miri
• Cargo plugins: cargo-edit cargo-clean-all cargo-deny cargo-license cargo-audit cargo-generate
• More Rust tools: clippy-control
• More tools: ripgrep tokei basic-http-server gist jaq jsonxf fd sd

todo say something here

Standard Rust tools

📦 cargo

The Rust build and packaging tool. It is the central tool in most Rust development workflows. It is part of every Rust toolchain, usually managed by rustup.

👁️ The cargo Book

📦 rustc

📦 rustup

📦 rustfmt

📦 mdbook

📦 bindgen

📦 miri

Cargo plugins

📦 cargo-edit

Extra cargo subcommands for editing Cargo.toml.

cargo install cargo-edit

🥡 crates.io Page
👁️ Source Repository

Installing cargo-edit provides two cargo subcommands:

• cargo upgrade
• cargo set-version

cargo add was once provided by cargo-edit but since Rust 1.62.0 is built into cargo itself.

📦 cargo-clean-all

📦 cargo-deny

📦 cargo-license

📦 cargo-audit

📦 cargo-generate

More Rust-specific tools

📦 clippy-control

More Rust tools

📦 ripgrep

📦 just

📦 tokei

📦 basic-http-server

📦 gist

📦 jaq

📦 jsonxf

📦 fd

📦 sd

The Rust Max Library

The Rust language and its ecosystem is documented in "books" (rendered with mdbook), and most of these links are to books.

Links with a bookmark icon, 🔖, are to particularly notable or useful chapters within a book.

The Rust language

• The Rust Programming Language (The Book)
• Rust By Example
• The Rust Reference
  • 🔖 Conditional compilation. Including which cfgs are set by rustc.
  • 🔖 Behavior considered undefined
• The Rustonomicon
• The Rust Edition Guide
• The Little Book of Rust Macros
• Rust API Guidelines
• Rust Unsafe Code Guidelines
• Rust Error Codes Index
• The Rust Unstable Book
• The Rust Style Guide
• Rust Release Notes

The Rust standard library

• std
  • 🔖 std::collections
  • 🔖 std::error
  • 🔖 std::ptr. Safety, undefined behavior, and "provenance".
  • 🔖 std::sync
  • 🔖 std::sync::atomic
• core
• alloc
• proc_macro

Standard Rust tools

• The cargo Book
  • 🔖 The manifest format
  • 🔖 Environment variables that affect the Cargo build process.
  • 🔖 Configuration format. Cargo has many interesting configuration options.
• The rustc Book
  • 🔖 The lint system and built-in lints
  • 🔖 Rust platform support tiers
• The rustup Book
• The rustdoc Book
• rustfmt (todo)
• The clippy Book
• The just Programmer's Manual
• The mdbook Book
• The bindgen User Guide
• miri (todo)

The Rust crate ecosystem

• The rand Book
• The proptest Book
• The serde Book
• The Rust Cookbook

Domain-specific Rust

• The Embedded Rust Book

The Rust Project internals

• Rust Project Goals
• Guide to rustc Development
• Standard Library Developers Guide
• Rust Forge
  • 🔖 Alternative Rust Installation Methods
• Rust RFCs

Rust Max Addons

The Rust Standard Library Revisited

The Rust Standard Library contains many important tools. Much of its documentation is excellent, but some, including the Tour of the Rust Standard Library, has bitrotted.

API docs

• std
• core
• alloc
• proc_macro

Rust standard library classics

Some of the Rust standard library documentation is excellent, with good overviews of systems programming topics generally.

• 🔖 std::collections
• 🔖 std::error
• 🔖 std::sync
• 🔖 std::sync::atomic

A (New) Tour of the Rust standard library

todo

The Rust Ecosystem

Rust resources

Error handling - anyhow and thiserror

Serialization - serde

Command line handling - clap

Derive all the things

Logging - log and env_logger

crate::env_logger::Builder::new()
    .filter_level(log::LevelFilter::Info)
    .parse_default_env()
    .init();

Async I/O - tokio

Managing Rust toolchains

Procedural macros

Rust build scripts

todo topics

• cargo add
• cargo update
• cargo upgrade
• lockfiles

How Do I … in Rust?

Discovery

… find a crate for a given purpose?

… find the latest version of a crate?

Project organization

… organize a Rust workspace?

Conveniences

… define "extension" methods on a type in another crate?

… guarantee a trait is object-safe?

static_assertions::assert_obj_safe!(MyTrait);

Error handling and debugging

… handle errors simply and correctly?

… structure errors in a public API?

… set up basic logging?

Collections

… create a fast HashMap?

… convert from slices to fixed-length arrays?

Numerics

… convert between numeric types ideomatically?

… perform math ideomatically?

… convert between ints and bytes?

Encoding, serialization, parsing

… serialize to and from JSON?

… decide what format to use with serde?

Time

… parse and render standard time formats?

Random numbers

… generate a strong random number?

… generate a strong random number from a seed?

… generate a fast random number from a seed?

Cryptography

… calculate a cryptographic content hash?

Parallelism and Concurrency

… initialize a global value?

todo LazyLock, OnceLock, and Once.

… send messages to/from async code?

todo futures::channels

Asynchronous I/O

… set up the tokio event loop?

… stub an unwritten async fn?

Networking and web

… make a synchronous HTTP request?

… configure a basic HTTP server?

Text / unicode

Terminal / CLI

… set up a simple CLI parser with subcommands?

… display colors in the terminal?

… read line-based input from the terminal?

System / OS

… read environment variables?

… work with a temporary file?

… work with multiple files in a temporary directory?

Testing

… create a custom test harness?

… create a custom table-based test harness?

Build scripts

… write build scripts ideomatically?

… link to a native static library?

… compile and link a C source file?

FFI / interop

… create Rust bindings to a C/C++ program?

Procedural macros

let else

topics

• justfiles
• time - jiff vs chrono vs time
• xtask and xshell
• project organization
• extension_trait
• global initialization - lazy_static vs once_cell vs std
  • lazy_static -> LazyLock
  • lazy_static can be used with a spin lock
  • OnceLock is in std
• error handling
• ideomatic casting
• ideomatic math

The Rust Max Radar

This is where we collect crates and tools of interest, but that are not yet part of Rust Max.

Crates

• backtrace-on-stack-overflow. Nice missing feature, but code looks underdeveloped.
• bitvec. Operate directly on bits.
• boringtun. WireGuard.
• comrak. Markdown parser.
• console, dialoguer, and indicatif. Pretty terminals.
• criterion. Advanced benchmarking.
• dashmap. Concurrent hash map.
• datatest-stable Data-driven tests.
• dotenv.
• derive-new Derive the new function.
• ena. The union find algorithm.
• encoding, charset, codepage, oem_cp, icu_normalizer, detone. Text encoding.
• enum-iterator. Iterate over variants.
• eyre. Sophisticated error handling.
• flate2.
• fnv or some other non-ahash fast hash
• hashbrown. Hash maps with no-std.
• home
• ignore. Like walkdir but obeys .gitignore.
• include_dir.
• indexmap
• libm. Useful for no-std.
• memchr
• memmap
• ndarray
• nix
• notify. File system notification.
• num.
• num-traits
• ordered-float
• parking_lot Non-poisoning mutexes, etc.
• petgraph
• ratatui. Seriously cool CLIs.
• rangetools
• rustls. TLS.
• rustversion
• rust-embed. Embedding of file system resources into binaries, with hot-reloading during development.
• scopeguard. Like defer.
• smallvec. The "small vector" optimization. There may be better / newer options.
• sqlx.
• tar.
• tungstenite. WebSockets.
• stacker. Manually-growable call stacks.
• time. Another time crate.
• tracing.
• tracing-subscriber.
• tracing-tracy.
• unicode-xid.
• xdg

Tools

• cargo-duplicates
• cargo-hack
• cargo-outdated
• rust-analyzer

Wanted

• SHA3
• gRPC
• wasm crates and tools, wasm-bindgen, stdweb
• threadpool
• zip, gzip
• parser generator (pest?)
• alternative to bitflags
• gui stuff
  • winit, wgpu vs glow, morphorm, css, iced vs egui
• i18n
• QUIC - either quinn or quiche
• HTTP3
• markdown
• csv
• small string, smartstring
• rational numbers
• fixed-point, decimal numbers, rust-decimal

Replacements

• num_cpu -> std::thread::available_parallelism

Graveyard

These projects were once useful or notable, but are now deprecated by others.

• lazy_static. Use std::sync::LazyLock.
• once_cell. Use std::sync::OnceLock.

External Rust Resources

These are not part of Rust Max.

Must know URLS 🤯

• rust-lang.org
• std.rs
• docs.rs
• crates.io
• rustup.org
• play.rust-lang.org

Tier 1 - looks good 👍

• Rust Language Cheat Sheet. This looks awesome.
• Rust Component History. rustup toolchain status. Look here to figure out if your nightly toolchain had component build failures.
• The Little Book of Rust Books
• "Can I Use _?"

Tier 2 - unvetted 😒

• Rust String Conversions Cheat Sheet
• Rust Iterator Cheat Sheet
• Rust Container Cheet Sheet
• Lib.rs
• Secure Rust Guidelines.
• List of security-related projects
• Tour of Rust's standard library traits
• Another Container Cheet Sheet

todo

• rust-lang.org
• play.rust-lang.org
• rustup.org
• crates.io
• std.rs
• docs.rs
• query.rs
• social and forums
• releases.rs