repository·main·Indexed 19 days ago
https://github.com/nix-community/haumeaA filesystem-based module system for Nix that maps directory structures into attribute sets. Haumea provides automatic imports, visibility rules via underscore prefixes, and hierarchical references using self, super, and root. It includes a flexible API for loading files via custom loaders and matchers (supporting Nix, JSON, TOML, and regex), as well as transformers like hoistAttrs and hoistLists to manipulate the resulting attribute tree.
Haumea provides several core benefits for Nix developers:
import ./path/to/file.nix statements by automatically loading files into an attribute set.self, super, and root to facilitate self-referencing, fixed points, and hierarchical access.loader or manipulate the resulting tree using a transformer.Haumea is a filesystem-based module system for Nix. Unlike NixOS modules, Haumea functions more like the module systems found in traditional programming languages, providing support for file hierarchies and visibility.
Its primary function is to map a directory of Nix files into a structured attribute set, where the directory structure is preserved in the resulting attribute tree.
Haumea automatically converts a directory tree of .nix files into a nested attribute set. By default, the resulting attribute set mirrors the file hierarchy.
Files prefixed with __ (e.g., __internal.nix) or located in directories like _utils/ are handled according to visibility rules (though the specific mapping for these prefixes is part of the internal module logic), allowing you to organize code without manual imports.
# Example mapping:
# From:
# ├─ foo/
# │ ├─ bar.nix
# │ ├─ baz.nix
# │ └─ __internal.nix
# ├─ bar.nix
# └─ _utils/
# └─ foo.nix
# To:
{
foo = {
bar = <...>;
baz = <...>;
};
bar = <...>;
}Matchers allow Haumea to load non-Nix files by defining how to identify a file and how to parse it. Matchers are used with the loader option of the load function.
When Haumea evaluates a file, it passes the filename to the matches function. The filename is processed by removing up to two preceding underscores (_). For example:
bar.nix becomes bar.nixfoo/__bar.nix becomes bar.nixThe loader function in a matcher works identically to a standard loader function passed to load. It receives the standard context ({ self, super, root, ... }) and the Path to the file.
When using matchers, the resulting attribute name in the loaded set is the filename with its last extension removed.
foo.nix $\rightarrow$ foobar/_foo.nix $\rightarrow$ foobaz/foo $\rightarrow$ foofar.bar.baz $\rightarrow$ far.barWhen a file loaded by load is a function, Haumea automatically passes three reserved arguments to it:
self: Represents the current file's own attribute set (the result of the function's own evaluation).super: Represents the attribute set of the directory containing the current file.root: Represents the entire attribute set produced by the load call at the src root.If foo/bar.nix contains:
{ self, super, root }: {
a = 42;
b = self.a * 2;
}self.a will be 42.self.b will be 84.super will contain the other files in the foo/ directory (e.g., bar, baz, and __internal files).root will contain the full structure of the src directory.{
self, super, root
}: {
a = 42;
b = self.a * 2;
}Haumea follows semantic versioning. Because breaking changes can occur on the main branch at any time, it is highly recommended to pin your Haumea dependency to a specific version tag to ensure build stability and prevent unexpected breakage in your environment.
You can find a list of all available stable versions on the GitHub releases page.
You can quickly scaffold a new Nix library project using the Haumea template. This generates a flake.nix and other necessary files in your current directory.
To initialize in the current directory:
nix flake init -t github:nix-community/haumeaTo initialize in a new directory:
nix flake new <dir> -t github:nix-community/haumeanix flake init -t github:nix-community/haumeahaumea.lib attribute. Use this attribute to access the core API when building your Nix expressions.To verify your library, you can use haumea.lib.loadEvalTests (which behaves similarly to load) to define tests. You can execute these checks using the standard Nix command:
nix flake checknix flake checkIf you do not want to use the full template, you can simply add Haumea as a flake input in your existing flake.nix. It is recommended to pin Haumea to a specific tag to avoid breaking changes from the main branch.
inputs.haumea.url = "github:nix-community/haumea/v0.2.2";Use loaders.path when you simply need the filesystem path of a file without actually importing or evaluating its contents.
Type: `{ ... } -> Path -> Path`