lazy_static

lazy_static is a small procedural macro crate that lets Rust programs declare static values whose initialization requires runtime code — heap allocations, function calls, or anything that isn’t a const expression. Before std::sync::LazyLock stabilized in the standard library, this was the standard way to build globally-accessible, once-initialized data such as compiled regexes, parsed configuration, or lookup tables, and it remains one of the most widely depended-upon crates in the Rust ecosystem.

Under the hood, each static ref NAME: TYPE = EXPR; declaration expands into a hidden marker type plus a Deref implementation that triggers the expression’s evaluation exactly once, on first access, backed by std::sync::Once (or the spin crate in no_std environments via the spin_no_std feature). The result behaves like an ordinary &'static TYPE reference everywhere it’s used.

What You Get

• The lazy_static! macro for declaring one or more lazily-initialized statics in a single block, with support for visibility modifiers, doc comments, and attributes
• Thread-safe, exactly-once initialization backed by std::sync::Once, so concurrent first access from multiple threads is race-free
• A no_std-compatible code path (spin_no_std feature) that swaps the std::sync::Once implementation for the spin crate’s spinlock-based Once, for embedded or kernel-level targets
• A public lazy_static::initialize() function to force eager initialization at a controlled point instead of waiting for first access
• Zero runtime dependencies in the default configuration — pure core/std, no external crates required

Common Use Cases

• Compiling a Regex once at first use instead of recompiling it on every function call
• Building a static lookup table, HashMap, or Vec that requires heap allocation and can’t be expressed as a const
• Caching the result of an expensive one-time computation (e.g. parsing an embedded config or computing a derived constant) behind a global reference
• Sharing a single initialized instance of a type across an application without threading it through every function signature

Under The Hood

Architecture — The crate implements a macro-based lazy-initialization pattern. src/lib.rs defines the public lazy_static! macro (built on top of an internal __lazy_static_internal! macro) that generates, for each declared static, a unique marker struct implementing Deref<Target = TYPE>; the first call to deref() evaluates the user’s expression and stores it, and every subsequent call returns a reference to the already-computed value. The actual storage and once-only-execution logic lives behind a __lazy_static_create! macro whose implementation is swapped at compile time between src/inline_lazy.rs (default) and src/core_lazy.rs (the spin_no_std feature), letting the same public macro surface target both hosted std environments and no_std embedded targets.

Tech Stack — Pure Rust with a #![no_std] core crate; the only dependency is the optional spin crate (v0.9.8, default-features off, once feature) gated behind the spin_no_std feature flag. Dev-dependencies are doc-comment (to doctest the README’s code samples) and trybuild (for compile-fail/UI testing). There’s no build script and no external tooling beyond Cargo; MSRV is pinned at Rust 1.40.0 and verified in CI via a GitHub Actions workflow.

Code Quality — tests/test.rs exercises basic declarations, doc-comment/attribute passthrough, cross-referencing statics from separate lazy_static! blocks, unsafe-expression initialization, and array/box element types, all under #![deny(warnings)]. tests/no_std.rs verifies the spin_no_std path compiles and runs correctly. Notably, tests/ui.rs plus the tests/compile_fail/ fixtures use trybuild to assert that common misuse — referencing a private static from another module, incorrect visibility restrictions — fails to compile with the expected diagnostic, which is a strong quality signal for a macro crate whose main risk surface is macro-expansion misuse rather than runtime logic.

API Design — The public API is a single macro requiring only use lazy_static::lazy_static; and a static ref NAME: TYPE = EXPR; line per value — effectively zero boilerplate. Visibility, doc comments, and other attributes thread through unmodified, and the resulting static is used exactly like a normal &TYPE reference thanks to the transparent Deref implementation. The crate’s own documentation is unusually candid for a mature, maintenance-mode crate: lib.rs includes a dedicated “Standard library” section that shows the equivalent std::sync::LazyLock-based code and points new users toward the stdlib alternative where it’s available.