Getting Started

Caution

gen is pre-release and its API is still changing.

gen is a set of small Nix libraries, and you can use any one of them on its own. This guide takes gen-graph, gives it four nodes, and asks two questions about them. You need a flake and ten lines of data. No nixpkgs input is required.

1. Add one library

   Every gen library is a flake that exports a .lib. gen-graph answers graph queries:

   flake.nix

   {
     inputs.gen-graph.url = "github:sini/gen-graph";
   
     outputs = { gen-graph, ... }:
       let
         graph = gen-graph.lib;
   
         myData = {                                        # (1)
           web = { deps = [ "api" ]; };
           api = { deps = [ "cache" "database" ]; };
           cache = { deps = [ "database" ]; };
           database = { deps = [ ]; };
         };
   
         g = {                                             # (2)
           edges = id: myData.${id}.deps or [ ];
           parent = id: myData.${id}.parent or null;
           nodes = builtins.attrNames myData;
           nodeData = id: myData.${id};
         };
       in
       {
         reachableFromWeb = graph.reachableFrom g "web";   # (3)
         roots = graph.roots g;
       };
   }

   1. myData is your own data. None of its field names mean anything to gen.
   2. g is an accessor record: four functions that tell gen-graph how to read your data. edges returns the nodes a node points to, parent returns its container, nodes lists every node and nodeData returns a node’s attributes.
   3. Each output is a query over g.

2. Ask it a question

   nix eval --json .#reachableFromWeb
   # ["api","cache","database"]
   
   nix eval --json .#roots
   # ["web"]

   web depends on the three listed nodes, directly or through other nodes. web is the only node that no other node points to.

What just happened

myData held the nodes, and its deps fields held the edges between them. g told gen-graph how to read both from data you already had. reachableFrom and roots are queries over that relation. gen-graph keeps no copy of the graph.

The rest of gen builds on the same model. Hosts, users and features are nodes, the relations between them are edges, and you get results by querying the graph.

Every gen library runs its test suite on every push under three evaluators: upstream Nix, Determinate Nix and Lix, each pinned to its latest release. See Trust.

Where to go next

Your First GraphMore queries, a second relation, and reading attributes back out.

Add gen to a FlakeUse one library, or wire the hub to build NixOS systems.

LibrariesEvery library and the features it provides.