Crate tvix_eval

source ·
Expand description

tvix-eval implements the evaluation of the Nix programming language in Tvix.

It is designed to allow users to use Nix as a versatile language for different use-cases.

This module exports the high-level functions and types needed for evaluating Nix code and interacting with the language’s data structures.

Nix has several language features that make use of impurities (such as reading from the NIX_PATH environment variable, or interacting with files). These features are optional and the API of this crate exposes functionality for controlling how they work.



  • This module implements the builtins exposed in the Nix language.
  • chunk 🔒
  • compiler 🔒
    This module implements a compiler for compiling the rnix AST representation to Tvix bytecode.
  • errors 🔒
  • This module implements generator logic for the VM. Generators are functions used during evaluation which can suspend their execution during their control flow, and request that the VM do something.
  • io 🔒
    Interface for injecting I/O-related functionality into tvix-eval.
  • Implements traits for things that wish to observe internal state changes of tvix-eval.
  • opcode 🔒
    This module implements the instruction set running on the abstract machine implemented by tvix.
  • pretty_ast 🔒
    Pretty-printed format for the rnix AST representation.
  • source 🔒
    This module contains utilities for dealing with the codemap that needs to be carried across different compiler instantiations in an evaluation.
  • spans 🔒
    Utilities for dealing with span tracking in the compiler and in error reporting.
  • systems 🔒
  • upvalues 🔒
    This module encapsulates some logic for upvalue handling, which is relevant to both thunks (delayed computations for lazy-evaluation) as well as closures (lambdas that capture variables from the surrounding scope).
  • value 🔒
    This module implements the backing representation of runtime values in the Nix language.
  • vm 🔒
    This module implements the abstract/virtual machine that runs Tvix bytecode.
  • warnings 🔒
    Implements warnings that are emitted in cases where code passed to Tvix exhibits problems that the user could address.


  • This module provides macros which are used in the implementation of the VM for the implementation of repetitive operations. This macro simplifies the implementation of arithmetic operations, correctly handling the behaviour on different pairings of number types.
  • This macro simplifies the implementation of comparison operations.


  • Represents a single built-in function which directly executes Rust code that operates on a Nix value.
  • Describes what input types are allowed when coercing a Value to a string
  • Represents the result of compiling a piece of Nix code. If compilation was successful, the resulting bytecode can be passed to the VM.
  • Dummy implementation of EvalIO, can be used in contexts where IO is not available but code should “pretend” that it is.
  • An Evaluation represents how a piece of Nix code is evaluated. It can be instantiated and configured directly, or it can be accessed through the various simplified helper methods available below.
  • Builder for building an Evaluation.
  • Result of evaluating a piece of Nix code. If evaluation succeeded, a value will be present (and potentially some warnings!). If evaluation failed, errors will be present.
  • Nix context strings representation in Tvix. This tracks a set of different kinds of string dependencies that we can come across during manipulation of our language primitives, mostly strings. There’s some simple algebra of context strings and how they propagate w.r.t. primitive operations, e.g. concatenation, interpolation and other string operations.
  • Nix string values
  • Tracks all source code in a Tvix evaluation for accurate error reporting.
  • Implementation of EvalIO that simply uses the equivalent standard library functions, i.e. does local file-IO.



  • Represents all possible filesystem interactions that exist in the Nix language, and that need to be executed somehow.


  • Internal helper function for common parsing & compilation logic between the public functions.
  • Prepare the full set of globals available in evaluated code. These are constructed from the set of builtins supplied by the caller, which are made available globally under the builtins identifier.

Type Aliases§

  • The map of globally available functions and other values that should implicitly be resolvable in the global scope.