From a4540a584d762b000b21cb7e61987c414eb72a1d Mon Sep 17 00:00:00 2001 From: tv Date: Sat, 14 Nov 2026 00:27:45 +0000 Subject: populate: layer populate below krops populate is a program of its own, with a Nix library, in pkgs/populate, which krops uses, and which doesn't use krops: - default.nix builds the program, with nix-build there or callPackage, as pkgs.populate-unwrapped. - lib is populate's Nix library: the types of sources and the POSIX types they use, evalSource, flakeFollows, hasGeneratedFlake, and derivesFlake, taking nixpkgs' lib. krops' lib takes them from there, so it provides them as before, and so does lib/types. pkgs.populate, the function from populate's arguments to a script running the program, is krops' own, in pkgs/krops/populate.nix, with checks.nix next to it. It takes the program as populate-unwrapped, which callPackage passes from the overlay; the flake, whose nixpkgs lacks it, passes its own. --- pkgs/populate/docs/design.md | 61 +++++++++++++++++++++++--------------------- 1 file changed, 32 insertions(+), 29 deletions(-) (limited to 'pkgs/populate/docs') diff --git a/pkgs/populate/docs/design.md b/pkgs/populate/docs/design.md index cf9d356..940ab5f 100644 --- a/pkgs/populate/docs/design.md +++ b/pkgs/populate/docs/design.md @@ -1,15 +1,16 @@ # Populate's design -Populate delivers sources to a target directory. It consists of two parts: +Populate delivers sources to a target directory. It consists of: -- Nix code, which turns populate's arguments into a command line: the - sources as `evalSource` returns them, as JSON, the target, and the - options. It checks the arguments during evaluation, so mistakes show - early. -- A program, which reads the sources and delivers them to the target its - command line names. It knows nothing about Nix expressions: whatever - produces sources as JSON can drive it. +- A program, which reads the sources as JSON and delivers them to the + target its command line names. It knows nothing about Nix expressions: + whatever produces sources as JSON can drive it. +- A Nix library, `lib`, with the types of sources, which describe how to + write them in Nix, and `evalSource`, which turns sources written so into + the JSON the program reads. +krops uses both: its `pkgs.populate` turns populate's arguments into a +command line, and checks them during evaluation, so mistakes show early. So there is one program for each version of populate, instead of a script for each set of arguments, and the program can be written in any language. This directory holds the program in Rust. Another implementation, e.g. in @@ -18,20 +19,22 @@ the same tests. ## Nix side -`default.nix` is `pkgs.populate`. Given populate's arguments, `{ backup ? -false, force ? false, prune ? false, source, target }`, it checks them with -`checks.nix`, and returns a script running the program with the sources as -JSON on file descriptor 3, so the commands populate runs keep standard -input. A target string goes to the program as it is. A target attribute -set, as `mkTarget` returns it, goes part by part, as options, with -`--local` or `--remote` as krops' lib's `isLocalTarget` decides during -evaluation, like the other functions of krops. The script puts the tools -populate runs in front of `PATH`, and depends on the store paths in the -sources, so building it builds them. `rustProgram` is the program, by -default built by `program.nix`. - -`writeDeploy` and the other functions of `pkgs.krops` use `pkgs.populate`, -so their arguments stay as they are. +`default.nix` builds the program: `nix-build` in this directory, or +`callPackage`, as krops' `pkgs.populate-unwrapped`. `lib/default.nix` is +the Nix library, taking nixpkgs' lib. + +krops' `pkgs.populate`, in its `pkgs/krops/populate.nix`, is populate's Nix +API there. Given populate's arguments, `{ backup ? false, force ? false, +prune ? false, source, target }`, it checks them with krops' +`pkgs/krops/checks.nix`, and returns a script running the program with the +sources as JSON on file descriptor 3, so the commands populate runs keep +standard input. A target string goes to the program as it is. A target +attribute set, as `mkTarget` returns it, goes part by part, as options, +with `--local` or `--remote` as krops' lib's `isLocalTarget` decides +during evaluation, like the other functions of krops. The script puts the +tools populate runs in front of `PATH`, and depends on the store paths in +the sources, so building it builds them. krops' `writeDeploy` and its +other functions use `pkgs.populate`, so their arguments stay as they are. ## Invocation @@ -99,13 +102,13 @@ doesn't go unnoticed. The sources carry no version: this is version 0, and a later version of populate that reads them differently will mark them. Store paths in the sources, e.g. of a `file` source that is a derivation, -must exist when the program runs. The script `default.nix` writes depends -on them. Something producing sources at run time has to build them first. +must exist when the program runs. The script krops' `pkgs.populate` +writes depends on them. Something producing sources at run time has to build them first. ## Checks -The program checks the sources and the target as `checks.nix` does, with -the same messages: +The program checks the sources and the target as krops' `checks.nix` does +during evaluation, with the same messages: - The target's host isn't empty, and neither it nor its user starts with `-`, so ssh can't take them for options. `checks.nix` doesn't check @@ -122,9 +125,9 @@ the same messages: since `evalSource` checks the types. Checks that depend on whether the target is local come on top, e.g. -refusing to copy flakes to remote targets using sudo. `checks.nix` does -that during evaluation too, where `default.nix` decides whether the target -is local. +refusing to copy flakes to remote targets using sudo. krops' `checks.nix` +does that during evaluation too, where `pkgs.populate` decides whether the +target is local. ## Output -- cgit v1.3.1