From cc785d16d4d2ef0a13660addd73aa88d34034f22 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christina=20S=C3=B8rensen?= Date: Thu, 5 Sep 2024 09:39:42 +0200 Subject: [PATCH] docs: improve readme with explanation, usage MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Christina Sørensen --- README.md | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/README.md b/README.md index 6c8e9d4..ef2a9fa 100644 --- a/README.md +++ b/README.md @@ -20,3 +20,32 @@ weather`](https://guix.gnu.org/manual/en/html_node/Invoking-guix-weather.html). [![License: EUPL-1.2](https://img.shields.io/badge/licence-EUPL--1.2-blue)](https://commission.europa.eu/content/european-union-public-licence_en) + +## How It Works + +The basic idea is that we construct a set of all requisites to build the +top-level of a NixOS configuration, and then query Nix cache(s) for the narinfo. +By doing this in a high concurrency, parallel task runner (i.e. tokio async +runtime), and only querying the headers for status codes, we can reach +impressive speeds, typically around 45~ network time. + +One of the biggest limiting factors regarding speed is building the +`config.system.toplevel`, and finding the necessary requisites with `nix-store`. +Caching the requisites is a future goal, so that we only have to build the +`toplevel`, and then match against its derivation in cache, which should cut +down the nix part of the runtime by ~80%. + +## Usage + +> **Note** +> Currently, `nix-weather` only has first-class support for flakes. + +General usage would be like this: + +```bash +nix-weather --name myhost --config ~/git/my-nixos-config +``` + +Here, we specify the name of the host, as specified at the flake output +`nixosConfiguration`, and a path to the NixOS configuration flake. +