Module compiler

This module implements a compiler for compiling the rnix AST representation to Tvix bytecode.

A note on unwrap(): This module contains a lot of calls to unwrap() or expect(...) on data structures returned by rnix. The reason for this is that rnix uses the same data structures to represent broken and correct ASTs, so all typed AST variants have the ability to represent an incorrect node.

However, at the time that the AST is passed to the compiler we have verified that rnix considers the code to be correct, so all variants are fulfilled. In cases where the invariant is guaranteed by the code in this module, debug_assert! has been used to catch mistakes early during development.

Modules

• bindings 🔒
  This module implements compiler logic related to name/value binding definitions (that is, attribute sets and let-expressions).
• import 🔒
  This module implements the Nix language’s import feature, which is exposed as a builtin in the Nix language.
• optimiser 🔒
  Helper functions for extending the compiler with more linter-like functionality while compiling (i.e. smarter warnings).
• scope 🔒
  This module implements the scope-tracking logic of the Tvix compiler.

Structs

• CompilationOutput
  Represents the result of compiling a piece of Nix code. If compilation was successful, the resulting bytecode can be passed to the VM.
• Compiler
• LambdaCtx 🔒
  Represents the lambda currently being compiled.

Enums

• TrackedFormal 🔒
  When compiling functions with an argument attribute set destructuring pattern, we need to do multiple passes over the declared formal arguments when setting up their local bindings (similarly to let … in expressions and recursive attribute sets. For this purpose, this struct is used to represent the two kinds of formal arguments:

Constants

• GLOBAL_BUILTINS 🔒
  Set of builtins that (if they exist) should be made available in the global scope, meaning that they can be accessed not just through builtins.<name>, but directly as <name>. This is not configurable, it is based on what Nix 2.3 exposed.

Functions

• compile
• compile_src_builtin 🔒
  Create a delayed source-only builtin compilation, for a builtin which is written in Nix code.
• expr_static_attr_str 🔒
  Convert the provided ast::Attr into a statically known string if possible.
• expr_static_str 🔒
  Convert a non-dynamic string expression to a string if possible.
• prepare_globals
  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

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