Core Concepts

gen is a set of Nix libraries for building configuration frameworks. It stores a configuration as a graph, groups settings into reusable features, gives every part a stable identity, and computes only what a reader asks for. This section explains each idea on its own page. Every page sets up its own small example, so you can start on any of them.

The ideas, in reading order

page	the idea in one sentence
Your Configuration as a Graph	Hosts, users and features are nodes. Their relations are labelled edges, and you ask questions by following labels.
Reusable Features	A feature is a named bundle of configuration that any host can use, and features can include each other.
Stable Identity for Everything	Every node gets an identity computed from its definition, so equal things are recognised as equal.
An Enhanced Module Type System	Options have types, definitions merge by priority, and gen records which file set every value.
Automatic Argument Injection	A module asks for the values it needs, such as the host it configures, and gen passes them in.
Rules That Add Relationships	Rules decide which relations hold, and each relation that holds becomes an edge.
Values Computed on Demand	A node’s values are computed when something reads them, from the node and its neighbours.
Rebuilding Only What Changed	After an edit, gen reuses what did not change and gives the same result as a full run.
Which Tool for Which Job	A goal-by-goal guide to the mechanisms above.

flowchart LR
  G["Graph"] --> F["Features"]
  F --> I["Identity"]
  I --> T["Typed modules"]
  T --> A["Argument injection"]
  A --> R["Rules"]
  R --> D["On-demand values"]
  D --> N["Incremental rebuild"]

Words used throughout

• A node is one thing in your configuration: a host, a user, a service, a feature.
• An edge connects two nodes and carries a label, such as user or feature.
• A kind declares the shape of a node: its options and their types. A registry holds the nodes of one kind.
• An aspect is gen’s name for a feature: a named bundle of configuration.
• A class is the target a piece of configuration is written for, such as nixos. A framework can declare any class it needs.
• A rule states that a relation holds when some facts hold and others do not.

gen declares none of these words for your domain. A framework built on gen brings its own kinds, such as host or service, and gen supplies the machinery around them. The terminology page defines every other term.

Taking the libraries

Each idea is provided by a small library, and each library can be used on its own as a flake input. The examples in this section bind all of them at once through the hub:

gen = inputs.gen.lib.mkGenLibs { };   # gen.graph, gen.merge, gen.aspects, ...

Libraries lists which library provides which feature, and Getting Started shows one library taken alone.

Where the ideas come from

Each page ends with a short paragraph on the research behind its mechanism, with a link to our reading of the paper. The papers section has the full list.