Expand description
Describe Nix configuration with ordinary Rust structs, enums and functions.
Nix is a language used to describe configuration and software builds. Rusix turns Rust values into Nix expressions; Nix evaluates those expressions later. Rust code can also describe references and calls without reading their results.
Start with config for a local configuration tree. Nested structs become
nested named fields in Nix. Use IntoConfig and IntoRusixValue derives
for reusable types, interop to reuse existing packages and functions, and
nixos::NixosModule to combine configuration for NixOS. NixOS combines
modules and checks configurable fields, called options, during evaluation.
compile generates Nix source from a Rust description. With the default
evaluation feature, NixSession can
evaluate the generated source in an offline, disposable Nix store. Compilation
does not launch Nix; evaluation never builds packages or activates a system.
Disable default features to use authoring and compilation without the evaluator.
Evaluation supports Linux; the fixture executable requires dev-cli.
Re-exports§
pub use compiler::Generated;pub use compiler::RenderOptions;pub use compiler::SourceSpan;pub use compiler::compile;pub use compiler::compile_with_options;pub use diagnostic::Diagnostic;pub use diagnostic::DiagnosticKind;pub use diagnostic::DiagnosticOrigin;pub use diagnostic::OriginRole;pub use diagnostic::Provenance;
Modules§
- compiler
- Compile deferred Rust descriptions into Nix source and inspection syntax. Generate Nix source from Rust configuration and evaluate it in isolation.
- diagnostic
- Explain compilation and Nix evaluation failures in terms of Rust source.
Diagnostickeeps the useful reason, contributing source locations and original Nix output. Consumers can inspect these fields without parsing Nix error text themselves. - interop
- Refer to existing Nix packages, functions and configuration from Rust.
- ir
- Semantic IR construction and inspection for compiler/backend implementations. Semantic representation of deferred Nix computations and their Rust origins.
- nixos
- Describe and combine NixOS system configuration from Rust.
- package
- Describe recurring nixpkgs package operations without evaluating them in Rust. nixpkgs supplies build environments, dependencies and builders; these helpers construct expressions using the values supplied by the package or module caller.
- prelude
- Common typed authoring interfaces; raw interop and backend access require explicit imports. Common interfaces for typed package and configuration authoring.
Macros§
- nix_
record - Build a Nix attribute set from named values using a concise macro. An attribute set is Nix’s collection of named fields, like a Rust record or map. Values can mix Rust literals with packages and expressions that Nix will evaluate later; the macro does not evaluate them or convert them to strings.
- nix_
text - Build text containing values that Nix will evaluate later.
This resembles named Rust formatting, but returns a
crate::Expr<String>rather than a RustString. Each hole usesToNixTextand Nix’sbuiltins.toString, so a hole can contain a Rust literal, a symbolic option reference or a package.
Structs§
- Config
- A group of settings that one component contributes to configuration.
For example, it can define
services.example.enableandservices.example.port. Values may be concrete Rust literals or expressions that Nix will evaluate later; constructing Config does not run Nix. - Evaluation
- The JSON-compatible result of evaluating a Nix expression. It includes Nix’s original diagnostic output for inspection. A package or function cannot necessarily be serialized directly; select suitable data such as a package’s name before requesting JSON output.
- Expr
- An expression that Nix will evaluate later, with an expected Rust result type.
- NixSession
- A temporary workspace for asking Nix to evaluate generated expressions.
- Rusix
Value - Data ready to be placed inside a Rusix configuration tree.
It can contain named fields, ordered lists, literals and expressions that Nix
will evaluate later. Use this as the result of a custom
IntoRusixValueimplementation; it is not evaluated Nix data or raw Nix source. Ordinary derived values can useIntoRusixValue::try_into_nix_valuedirectly without handling this intermediate representation. - Validation
Error - A configuration-description error found by Rust before Nix evaluation. It identifies the Rust operation and explains why its description cannot be compiled. NixOS option type errors are checked later by NixOS instead.
Traits§
- Config
Value - A supported value that can be used directly in a derived configuration field,
Config::set_dynamicor a Nix call. Built-in Rust literals, supportedExprtypes and Nix references implement this trait. It is sealed, so users cannot add implementations. For your own configuration types, derive or implementcrate::IntoRusixValueinstead. - Into
Config - Convert a complete Rust configuration component into a group of settings.
The component defines where its fields belong: a root with a
servicesfield, for example, defines paths starting withservices. Reusable nested values usecrate::IntoRusixValueand let their parent choose placement. - Into
Rusix Value - Convert a Rust value into data Rusix can use inside a configuration tree. A nested value defines its fields, while its parent determines where they appear. For example, the same endpoint type can be nested under several services without containing a global option path.
Attribute Macros§
- args
- Generate typed accessors for values in a Nix function’s named arguments. Nixpkgs package functions commonly receive an attribute set of dependencies and feature choices. This macro describes the fields an adapter needs. Accessors construct Nix expressions; they do not read argument values in Rust.
- config
- Turn an inline Rust module’s local types into Nix configuration values.
Nested structs become nested Nix attribute sets: collections of named fields.
Mark a root struct with
#[rusix(root)]so it can be added to anixos::NixosModule. NixOS will combine that contribution with other modules. The macro describes values; it does not evaluate Nix or declare option types. - options
- Generate typed accessors for final NixOS configuration values. NixOS combines configuration supplied by many modules. These accessors refer to the resulting values, so other modules’ overrides still affect dependent expressions. Rust constructs references; it never reads the final values. This declares dependencies, not NixOS options or their actual types.
Derive Macros§
- Into
Config - Convert a reusable Rust struct into a complete group of configuration settings.
Nested fields determine Nix paths: a
servicesfield containing anexamplefield places that value underservices.example. The derive implements bothIntoConfigandIntoRusixValue, so the type can also be nested in a parent. It does not evaluate Nix or declare which NixOS options exist. - Into
Rusix Value - Convert a reusable Rust type into a nested configuration value.
Named structs become named Nix fields, a single-field newtype delegates to
its inner value, and unit enums become strings such as
"readOnly"forReadOnly. The parent determines where the value appears in configuration.