A Guide to the rustmax crate.

• Profiles. rustmax organizes crates into profiles, which correspond to common target environments and application types.
  • 🌎 Profile: rmx-profile-no-std
  • 🌎 Profile: rmx-profile-std
  • 🌎 Profile: rmx-profile-wasm
  • 🌎 Profile: rmx-profile-net
  • 🌎 Profile: rmx-profile-cli
  • 🌎 Profile: rmx-profile-build-script
  • 🌎 Profile: rmx-profile-proc-macro
  • 🌎 Profile: rmx-profile-full
  • 🌎 Profile: rmx-profile-max
  • 🌎 Profile: rmx-profile-max-nightly
• Ecosystem features. rustmax identifies Cargo features common across many crates.
  • ⛲ Feature: rmx-feature-no-std
  • ⛲ Feature: rmx-feature-std
  • ⛲ Feature: rmx-feature-default
  • ⛲ Feature: rmx-feature-more
  • ⛲ Feature: rmx-feature-derive
  • ⛲ Feature: rmx-feature-serde
  • ⛲ Feature: rmx-feature-backtrace
  • ⛲ Feature: rmx-feature-tokio
  • ⛲ Feature: rmx-feature-nightly
• Rust standard libraries. rustmax re-exports the standard Rust libraries for convenience.
  • 📙 Rustlib: rmx-rustlib-core
  • 📙 Rustlib: rmx-rustlib-alloc
  • 📙 Rustlib: rmx-rustlib-std
  • 📙 Rustlib: rmx-rustlib-proc_macro
• Using rustmax as a library
  • rustmax and cargo features
  • Crate reexports
  • Standard library reexports
  • The rustmax prelude
  • The extras module
  • Starter examples
  • Starting from a template
  • Known bugs
• rustmax crate API docs
  • Re-exports
  • Modules

Profiles

rustmax organizes crates into profiles, which correspond to common target environments and application types.

By default no profile is enabled and no crates are exported.

🌎 Profile: rmx-profile-no-std

This profile includes crates that do not require Rust std. It allows use of the Rust allocator, and enables allocator-related features of its crates. All crates in this profile are also in rmx-profile-std.

💡 This profile also enables rmx-feature-no-std.
💡 This profile also enables rmx-rustlib-core and rmx-rustlib-alloc.

Crates in rmx-profile-no-std

• ahash - A fast and DOS-resistent hash function, for use in HashMaps.
• anyhow - Flexible error handling.
• base64 - Base-64 encoding and decoding.
• bitflags - Types in which the bits are individually addressable.
• blake3 - The BLAKE3 cryptographic hash function.
• bytes - Abstractions for working with byte buffers: Bytes, Buf, and BufMut.
• cfg-if - A macro for writing conditional compilation as if / else blocks.
• chrono - Dates and time (legacy).
• crossbeam - Concurrency tools to supplement std::sync, including fast channels.
• derive_more - derive for more standard traits.
• extension-trait - A macro for defining extension methods to external types.
• futures - Abstractions for asynchronous programming.
• hex - Encoding and decoding hexadecimal strings.
• itertools - Additional methods for iterators.
• jiff - Dates and time.
• libc - Bindings to the C standard library.
• log - A simple logging framework.
• memchr - Fast byte search with SIMD acceleration.
• nom - An efficient parser combinator.
• num_bigint - Arbitrary-sized integers.
• num_enum - Conversions between numbers and enums.
• powerletters - Superscript and subscript Unicode text conversion.
• rand - Random number generators.
• rand_chacha - The ChaCha cryptographically-secure random number generators.
• rand_pcg - The PCG non-cryptographically-secure random number generators.
• semver - The software versioning standard used by Rust.
• serde - The standard Rust serialization framework.
• serde_json - JSON serialization / deserialization with serde.
• sha2 - The SHA2 cryptographic hash functions.
• toml - TOML serialization / deserialization with serde.

🌎 Profile: rmx-profile-std

This profile depends on the Rust standard library, and includes crates that require the Rust standard library, in addition to the crates provided by rmx-profile-no-std.

💡 This profile also enables rmx-feature-std.
💡 This profile also enables rmx-feature-default.
💡 This profile also enables rmx-feature-more.
💡 This profile also enables rmx-feature-derive.
💡 This profile also enables rmx-feature-serde.
💡 This profile also enables rmx-rustlib-core, rmx-rustlib-alloc, and rmx-rustlib-std.

Crates in rmx-profile-std

• clap - Command line parsing.
• comrak - CommonMark and GitHub Flavored Markdown parser.
• env_logger - A basic logger to use with the log crate.
• flate2 - Deflate, gzip, and zlib compression and decompression.
• glob - Unix shell style pattern matching for paths.
• ignore - Directory traversal respecting gitignore rules.
• image - Image processing and manipulation.
• indicatif - Progress bars and spinners for CLI.
• json5 - JSON5, a superset of JSON with expanded syntax.
• notify - Cross-platform filesystem notifications.
• proptest - Testing over generated inputs, ala QuickCheck.
• rayon - Parallel iterators and other parallel processing tools.
• regex - Regular expressions.
• tempfile - Temporary files and directories.
• tera - A text template engine based on Jinja2.
• thiserror - Tools for defining custom error types.
• unicode-segmentation - Splitting strings on grapheme cluster, word, and sentence boundaries.
• walkdir - Efficient directory traversal.
• xshell - A Swiss-army knife for writing shell-style scripts in Rust.
• zip - Read and write ZIP archives.

🌎 Profile: rmx-profile-wasm

This profile is designed for WebAssembly (WASM) targets. It includes all crates from rmx-profile-no-std, plus additional crates that are compatible with WASM environments.

This profile uses WASM-specific variants of ecosystem features that exclude features incompatible with WASM environments, such as OS-specific threading APIs and file system operations that require native OS support.

💡 This profile also enables rmx-rustlib-core, rmx-rustlib-alloc, and rmx-rustlib-std.
💡 This profile also enables rmx-feature-std-wasm.
💡 This profile also enables rmx-feature-default-wasm.
💡 This profile also enables rmx-feature-more-wasm.
💡 This profile also enables rmx-feature-derive.
💡 This profile also enables rmx-feature-serde.

Crates in rmx-profile-wasm

All crates from rmx-profile-no-std, plus:

• clap - Command line parsing.
• comrak - CommonMark and GitHub Flavored Markdown parser.
• env_logger - A basic logger to use with the log crate.
• flate2 - Deflate, gzip, and zlib compression and decompression.
• glob - Unix shell style pattern matching for paths.
• json5 - JSON5, a superset of JSON with expanded syntax.
• rayon - Parallel iterators and other parallel processing tools.
• regex - Regular expressions.
• tempfile - Temporary files and directories.
• thiserror - Tools for defining custom error types.
• unicode-segmentation - Splitting strings on grapheme cluster, word, and sentence boundaries.
• walkdir - Efficient directory traversal.
• zip - Read and write ZIP archives.

Note: Some crates from rmx-profile-std are not included because they require native OS features unavailable in WASM environments: proptest, tera, xshell.

🌎 Profile: rmx-profile-net

Adds networking crates, including the tokio async runtime.

Not that this profile does not enable tokio features for other crates; to enable tokio features apply the rmx-feature-tokio feature.

💡 This profile also enables rmx-profile-std.

Crates in rmx-profile-net

• axum - Web application framework based on tokio.
• http - Shared definitions related to the HTTP protocol.
• hyper - HTTP, versions 1 and 2.
• mime - MIME media types.
• reqwest - Simple HTTP requests, synchronous and asynchronous.
• socket2 - Low-level network socket programming beyond std::net.
• tokio - An async task runtime and I/O library.
• tower - Service request/response abstraction (HTTP middleware) for tokio and axum.
• url - URL parsing and data structures.

🌎 Profile: rmx-profile-cli

Crates for building commandline interfaces.

💡 This profile also enables rmx-profile-std.

Crates in rmx-profile-cli

• ctrlc - Simple handling of Ctrl-C for CLI programs.
• termcolor - Cross-platform library for writing colored output to the terminal.
• rustyline - Command-line input reading with history.

🌎 Profile: rmx-profile-build-script

Crates for writing Rust build scripts.

💡 This profile also enables rmx-profile-std.

Crates in rmx-profile-build-script

• bindgen - Generate Rust bindings to C and C++ libraries.
• cc - A basic cross-platform C/C++ compiler driver.
• cxx - C++ bridge runtime support; paired with cxx_build.
• cxx-build - C++ bridge generator; paired with cxx.

🌎 Profile: rmx-profile-proc-macro

Crates for writing Rust procedural macros.

💡 This profile also enables rmx-profile-std.
💡 This profile also enables rmx-rustlib-proc_macro.

Crates in rmx-profile-proc-macro

• proc-macro2 - A preferred wrapper around the standard proc_macro crate.
• quote - The quote! macro for turning code blocks into source tokens.
• syn - A Rust parser used by procedural macros.

🌎 Profile: rmx-profile-full

This profile simply enables all previous profiles.

💡 This profile also enables rmx-profile-std.
💡 This profile also enables rmx-profile-net.
💡 This profile also enables rmx-profile-cli.
💡 This profile also enables rmx-profile-build-script.
💡 This profile also enables rmx-profile-proc-macro.

🌎 Profile: rmx-profile-max

rustmax with all features (that don't require nightly).

💡 This profile also enables rmx-profile-full.
💡 This profile also enables rmx-feature-derive.
💡 This profile also enables rmx-feature-serde.
💡 This profile also enables rmx-feature-backtrace.
💡 This profile also enables rmx-feature-tokio.

🌎 Profile: rmx-profile-max-nightly

rustmax with all features (including nightly).

💡 This profile also enables rmx-profile-max.
💡 This profile also enables rmx-feature-nightly.

Ecosystem features

rustmax identifies Cargo features common across many crates.

⛲ Feature: rmx-feature-no-std

This feature is enabled by rmx-profile-no-std. It does not typically need to be set manually.

It enables few features, particularly enabling allocator support for no-std crates that can be compiled without.

⛲ Feature: rmx-feature-std

This feature is enabled by rmx-profile-std. It does not typically need to be set manually.

It enables the "std" feature of crates and other default features that require the standard library.

⛲ Feature: rmx-feature-std-wasm

This feature is enabled by rmx-profile-wasm. It does not typically need to be set manually.

Similar to rmx-feature-std, but excludes features that are incompatible with WebAssembly targets, such as those requiring threading or OS-specific APIs.

⛲ Feature: rmx-feature-default

This feature is enabled by rmx-profile-std. It does not typically need to be set manually.

It enables the "default" feature of crates.

⛲ Feature: rmx-feature-default-wasm

This feature is enabled by rmx-profile-wasm. It does not typically need to be set manually.

Similar to rmx-feature-default, but uses WASM-compatible default features where necessary.

⛲ Feature: rmx-feature-more

This feature is enabled by rmx-profile-std. It does not typically need to be set manually.

This activates extra crate features for convenience that the crates themselves do not typically activate by default.

⛲ Feature: rmx-feature-more-wasm

This feature is enabled by rmx-profile-wasm. It does not typically need to be set manually.

Similar to rmx-feature-more, but excludes features that are incompatible with WebAssembly targets, such as blocking I/O and threading.

⛲ Feature: rmx-feature-derive

Enables derive macros of crates where it is optional, typically with a feature named "derive".

⛲ Feature: rmx-feature-serde

Enables serde support for crates where it is optional, typically with a feature named "serde".

⛲ Feature: rmx-feature-backtrace

Enables backtrace support for crates where it is optional, typically with a feature named "backtrace".

This feature is necessary for backtrace support in anyhow.

This feature also enables rmx-feature-std.

⛲ Feature: rmx-feature-tokio

Enables tokio support for crates where it is optional, typically with a feature named "tokio".

⛲Feature: rmx-feature-nightly

Enables features that only compile with the Rust [nightly compiler], typically with a feature named "nightly".

Rust standard libraries

rustmax re-exports the standard Rust libraries for convenience. These features enable reexports of the corresponding standard library crates as modules within rustmax.

📙 Rustlib: rmx-rustlib-core

Reexports the core library. Enabled by rmx-profile-no-std and all profiles that include it.

📙 Rustlib: rmx-rustlib-alloc

Reexports the alloc library. Enabled by rmx-profile-no-std and all profiles that include it.

📙 Rustlib: rmx-rustlib-std

Reexports the std library. Enabled by rmx-profile-std and all profiles that include it.

📙 Rustlib: rmx-rustlib-proc_macro

Reexports the proc_macro library. Enabled by rmx-profile-proc-macro.

Using rustmax as a library.

In your manifest Cargo.toml:

[dependencies]
rmx.package = "rustmax"
rmx.version = "0.0.7"
rmx.features = [
  "rmx-profile-max",
]

Or if using a workspace, in your workspace Cargo.toml

[dependencies]
rmx.version = "0.0.7"
rmx.features = [
  "rmx-profile-max",
]

And in your crate's Cargo.toml

[dependencies]
rmx.workspace = true

rustmax and cargo features

todo

The main way of configuring the rustmax crates is by enabling the appropriate profile cargo features.

rustmax enables no features by default, and reexports no crates; but for most uses people will want to enable rmx-profile-std. This feature augments the Rust std library with crates that are widely used with a variety of Rust programs, as well as minor helpers missing from the standard library.

[dependencies]
rmx.package = "rustmax"
rmx.version = "0.0.7"
rmx.features = [
  "rmx-profile-max",
]

Crate reexports

The crates of rustmax are all reexported as modules from the rustmax crate.

# use rustmax as rmx;
use rmx::rand::Rng;

These modules should generally behave the same as the corresponding crates, with exceptions noted in "Known Bugs". These modules have have rustmax-specific module-level documentation, with a short description and motivation, an example, and relevant links, including to the original crate-level documentation.

These modules are only defined when their crate is configured through cargo features like rmx-profile-std.

The rustmax prelude

The extras module

Known bugs

• serde derive only works if the serde crate is an explicit dependency.
• derive_more derives only works if the derive_more crate is an explicit dependency.