Modules and Crates

Default to the narrowest visibility (narrow-visibility)

Start private, then widen to pub(super), pub(crate), or pub only when an actual external consumer requires it.

// Good — restricted to the parent module
pub(super) static I8042_CONTROLLER:
    Once<SpinLock<I8042Controller, LocalIrqDisabled>> = Once::new();

pub(super) fn init() -> Result<(), I8042ControllerError> {
    // ...
}

// Bad — unnecessarily wide
pub static I8042_CONTROLLER: ...

See also: PR #2951 and #2605.

Qualify function calls with the parent module (qualified-fn-imports)

When importing a free function or a static/constant from another module, import the parent module and access the item through it (module::function(), module::CONSTANT). Do not import free functions or statics directly by name.

This convention is recommended by The Rust Programming Language and followed by the Rust compiler codebase. It serves two purposes:

1. The call site makes it clear that an imported item is being used, not a local one.
2. The module name provides context that complements the item name.

// Good — module-qualified function call
use ostd::irq;

let guard = irq::disable_local();

// Good — module-qualified static access
use ostd::mm::kspace;

let base = kspace::LINEAR_MAPPING_BASE_VADDR;

// Bad — bare function name; unclear origin at call site
use ostd::irq::disable_local;

let guard = disable_local();

// Bad — bare static name; could be mistaken for a local constant
use ostd::mm::kspace::LINEAR_MAPPING_BASE_VADDR;

let base = LINEAR_MAPPING_BASE_VADDR;

This rule applies to free functions and statics/constants. Types, traits, and enum variants should still be imported directly by name, following the standard Rust convention.

Use workspace dependencies (workspace-deps)

Always declare shared dependencies in the workspace [workspace.dependencies] table and reference them with .workspace = true in member crates.

# In the workspace root Cargo.toml
[workspace.dependencies]
ostd = { version = "0.17.0", path = "ostd" }
bitflags = "2.6"

# In a member crate's Cargo.toml
[dependencies]
ostd.workspace = true
bitflags.workspace = true