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

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 -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

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 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 tools

🌞 clippy-control

Non-Rust tools for Rust

🌞 mold

A high-performance linker that significantly speeds up Rust builds on Linux.

rustmax install-tool mold

👁️ Source Repository

Linking is one of the most time-consuming stages of a Rust build, and it has to be redone every time you test your program. On Linux the mold linker is faster than the default linker.

Setting up mold manually requires configuring .cargo/config.toml and ensuring the linker is properly installed, but the Rust Max CLI tool handles this setup automatically.

More general developer tools

🌞 ripgrep

🌞 just

A simple and suprisingly useful command runner with make-like syntax.

cargo install just

🌞 crates.io Page
👁️ Source Repository

Almost every project has a handful of commands the developer(s) uses frequently. Put these in a justfile so the menu of commands for this project is always obvious, which can be extra helpful after years away from a project.

just runs commands listed in a file named justfile. The justfile lives your project's root directory, and is configured with a make-like syntax:

default:
    just --list

install-tools:
    cargo install mdbook
    cargo install mdbook-yapp

clean: doc-clean
    cargo clean

doc-clean:
    rm -rf out

It's a simple idea, but suprisingly useful. And don't worry that it looks like a Makefile — it is much more fun and sensible in use than make.

When you come back to a project and see there's a justfile you know to run just --list and you'll immediately see what was on the previous maintainer's mind.

$ just --list
Available recipes:
    build
    check
    clean
    default
    doc-book
    doc-build
    doc-clean
    doc-crates
    install-tools
    lint
    maint-audit
    maint-duplicates
    maint-lock-minimum-versions # useful prior to running `cargo audit`
    maint-outdated
    maint-upgrade
    prebuild
    publish
    publish-dry
    replace-version old new
    test
    test-min-version-build

$ just build
   Compiling rustmax-cli v0.0.5 (…/rustmax/crates/rustmax-cli)
   …

🌞 tokei

🌞 basic-http-server

🌞 gist

🌞 jaq

🌞 jsonxf

🌞 fd

🌞 sd

🌞 dust

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 standard library

Standard Rust tools

The Rust crate ecosystem

Domain-specific Rust

The Rust Project internals

The Rust Max CLI

To install:

cargo install rustmax-cli --locked

The Rust Max CLI provides a number of small tools that help manage a Rust development environment, Rust tools, and Rust projects.

  • Print Rust sytem status
  • Install the mold linker
  • Install all Rust Max tools
  • Create a Rust Max project from template
  • Build the Rust Max documentation
  • Run all lint-style checks
  • Emit opinionated rustfmt.toml
  • Emit opinionated deny.toml
  • Emit opinionated clippy-control.toml

Rust Max understands your rustup toolchain status, Rust Max tools installed via cargo, and other tools like the mold linker.

$ rustmax status
... todo ...

Set up the mold linker

Linking is one of the most time-consuming stages of a Rust build, and it has to be redone every time you test your program.

On Linux the mold linker is faster than the the default linker. Setting it up manually is not difficult, but just hard enough that I have to look it up every time.

The Rust Max CLI tool can do it instead:

rustmax install-tool mold

Use rustfmt::skip

Sometimes exact formatting is important to make code beautiful. Don't be afraid annotate with #[rustfmt::skip].

Use Option with ?

The ? operator works with Option to early-return on None, making option-heavy code much cleaner.

#![allow(unused)]
fn main() {
fn find_user_email(id: u32) -> Option<String> {
    let user = database.find_user(id)?;  // Return None if user not found
    let profile = user.get_profile()?;   // Return None if no profile
    let email = profile.email?;          // Return None if no email
    Some(email)
}
}

An alternative to match or if let statements, ? lets you chain operations that might fail, automatically propagating None up the call stack.

Put common development commands in a justfile

Almost every project has a handful of commands the developer(s) uses frequently. Put these in a justfile so the menu of commands for this project is always obvious, which can be extra helpful after years away from a project.

just runs commands listed in a file named justfile. The justfile lives your project's root directory, and is configured with a make-like syntax:

default:
    just --list

install-tools:
    cargo install mdbook
    cargo install mdbook-yapp

clean: doc-clean
    cargo clean

doc-clean:
    rm -rf out

It's a simple idea, but suprisingly useful. And don't worry that it looks like a Makefile — it is much more fun and sensible in use than make.

When you come back to a project and see there's a justfile you know to run just --list and you'll immediately see what was on the previous maintainer's mind.

$ just --list
Available recipes:
    build
    check
    clean
    default
    doc-book
    doc-build
    doc-clean
    doc-crates
    install-tools
    lint
    maint-audit
    maint-duplicates
    maint-lock-minimum-versions # useful prior to running `cargo audit`
    maint-outdated
    maint-upgrade
    prebuild
    publish
    publish-dry
    replace-version old new
    test
    test-min-version-build

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

Rust standard library classics

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

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

Tools

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.

External Rust Resources

These are not part of Rust Max.

Must know URLS 🤯

Tier 1 - looks good 👍

Tier 2 - unvetted 😒

todo

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