From 141efa9562674d0728805633e8b6dda3e87cc41f Mon Sep 17 00:00:00 2001 From: David Arnold Date: Tue, 6 Apr 2021 20:45:01 -0500 Subject: [PATCH 1/7] checkpoint --- API.md | 164 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 164 insertions(+) create mode 100644 API.md diff --git a/API.md b/API.md new file mode 100644 index 000000000..cdf5b83e0 --- /dev/null +++ b/API.md @@ -0,0 +1,164 @@ +# DevOS 2.0 + +- We want to be a god ecosystem citizen, therefore we want to rebase on [`gytis/flake-utils-plus`](https://github.com/gytis-ivaskevicius/flake-utils-plus). +- `gytis/flake-utils-plus` is designed to be incorporated in upstream flake-utils. As the name suggests, it wraps and extends `flake-utils` for nixos related use cases. +- `devos-lib` shall be another layer that wraps `flakes-utils-plus` and adds accoustomed devos amentities, such as: + - automagic importers, for pure convenience, but without prescribing a particular folder layout (that is something for devos templates to achieve). + - additional configuration generators, such as for `deploy-rs` or `home-manager` or other future integrations (eg. mobile nixos, etc) that we want to offer as a convenience. + - other amentities (tbd) + + + +## Importers + +Importers declutter the top level flake. The goal is to have a bunch of lines that read like a very clean table of contents: + +```nix + concept1 = ./concept1; + concept2 = ./concept2; + concept3 = { "..." = "..."; }; + concept4 = []; +``` +It seems important to enable dual use (importing files or declaring inline), in order to allow people to generate user +flakes that put emphasis on different aspects of using devos lib (by sheer looking on the folder hierarchy). + +Some context about importers, and how we might want them to behave: + + - https://github.com/gytis-ivaskevicius/flake-utils-plus/issues/8 + - https://github.com/blaggacao/devos/blob/5d80663bcd3f65cc95fd965b49becc7b24ebf9d4/lib/devos/importer.nix + + +## Config Generators + +Configuration Generators generate configurations for particular entities. In practice and for now, + +- a [nixosConfigurationsGenerator](https://github.com/gytis-ivaskevicius/flake-utils-plus/blob/51cb739c9c9c2258bc70747eb7bc22975ae244bd/systemFlake.nix#L61-L64) creates nixosConfigurations, +- based on which a [deployConfigurationsGenerator](https://github.com/blaggacao/devos/blob/5d80663bcd3f65cc95fd965b49becc7b24ebf9d4/lib/devos/configGenerators.nix#L14-L25) generates deploy-rs configurations & +- a [hmConfigurationsGenerator](https://github.com/blaggacao/devos/blob/5d80663bcd3f65cc95fd965b49becc7b24ebf9d4/lib/devos/configGenerators.nix#L34-L45) generates home manager configurations. + +See also: https://github.com/gytis-ivaskevicius/flake-utils-plus/issues/10 + + +## API + +The devos-lib onion: + +- `builtins` +- `numtide/flake-utils` +- `gytis/flake-utils-plus` +- `divnix/devos` (the lib) + +While flake-utils-plus exports a generic [`utils.systemFlake`](https://github.com/gytis-ivaskevicius/flake-utils-plus/blob/51cb739c9c9c2258bc70747eb7bc22975ae244bd/flake.nix#L37) user function +and is restricted from including dependencies, devos-lib should export a `devos.systemFlake` kwithout such restrictions and that can include +additional (eventually third-party mediated) generatros, such as `deploy-rs`, while implementing a strict superset of +`utils.systemFlake` api and, on the other hand, a `devos.mkFlake` with importer amenities included and a slightly different api for convenience. + +Such function would have the following top level API + +```nix +# devos.systemFlake +{ +# adopt flake-utils-plus, file upstream issues where discussion is needed + self +, defaultSystem ? "x86_64-linux" +, supportedSystems ? flake-utils.lib.defaultSystems +, name # or inputs, see: https://github.com/gytis-ivaskevicius/flake-utils-plus/issues/12 +, nixosConfigurations ? { } +, nixosProfiles ? { NAME = { + system = "..."; + channelName = "..."; + extraArgs = { }; + modules = [ ]; + };} +, channels ? { + input = "..."; + overlaysBuilder = channels: [ (final: prev: { })]; + config = { }; + patches = [ ]; + } +, channelsConfig ? { } +, sharedModules ? [ ] +, sharedOverlays ? [ ] +, nixosSpecialArgs ? { } + +, hmConfigurations ? { } +, hmProfiles ? { NAME = { + modules = [ ]; + extraArgs = { }; + # what else makes sense, here? + };} + +, deployConfigurations ? { } + +, ... # passed through +} +``` + +```nix +# devos.mkFlake' +{ + self +, defaultSystem ? "x86_64-linux" +, supportedSystems ? flake-utils.lib.defaultSystems +, name # or inputs, see: https://github.com/gytis-ivaskevicius/flake-utils-plus/issues/12 +, nixosConfigurations ? { } # escape hatch +, hmConfigurations ? { } # escape hatch +, deployConfigurations ? { } # escape hatch +, channels ? { + input = "..."; + overlaysBuilder = channels: [ (final: prev: { })]; + config = { }; + patches = [ ]; + } +, channelsConfig ? { } +, sharedModules ? [ ] +, sharedOverlays ? [ ] + +, nixosModules ? [ ] +, nixosProfiles ? [ ] +, nixosUserProfiles ? [ ] +, nixosSpecialArgs ? [ ] +, hmModules ? [ ] +, hmProfiles ? [ ] +, hmSpecialArgs ? { } + + + # TODO + , suites + , hosts + +} +``` + +```nix +# devos.mkFlake +{ + self +, defaultSystem ? "x86_64-linux" +, supportedSystems ? flake-utils.lib.defaultSystems +, name # or inputs, see: https://github.com/gytis-ivaskevicius/flake-utils-plus/issues/12 +, nixosConfigurations ? { } # escape hatch +, hmConfigurations ? { } # escape hatch +, deployConfigurations ? { } # escape hatch +, channels ? { + input = "..."; + overlaysBuilder = channels: [ (final: prev: { })]; + config = { }; + patches = [ ]; + } +, channelsConfig ? { } +, sharedModules ? [ ] +, sharedOverlays ? [ ] + +, nixosModules ? ./modules +, nixosProfiles ? ./profiles +, nixosUserProfiles ? ./users +, nixosSpecialArgs ? { } +, hmModules ? ./users/modules +, hmProfiles ? ./users/profiles +, hmSpecialArgs ? { } + +, hosts ? ./hosts +, suites ? ./suites +} +``` From f1ed2de91607c2d87677c6d87529eb0e75e1d80d Mon Sep 17 00:00:00 2001 From: David Arnold Date: Tue, 6 Apr 2021 21:48:05 -0500 Subject: [PATCH 2/7] some updates --- API.md | 43 +++++++++++++++++++++++-------------------- 1 file changed, 23 insertions(+), 20 deletions(-) diff --git a/API.md b/API.md index cdf5b83e0..c5c88d1bb 100644 --- a/API.md +++ b/API.md @@ -63,8 +63,8 @@ Such function would have the following top level API , defaultSystem ? "x86_64-linux" , supportedSystems ? flake-utils.lib.defaultSystems , name # or inputs, see: https://github.com/gytis-ivaskevicius/flake-utils-plus/issues/12 -, nixosConfigurations ? { } -, nixosProfiles ? { NAME = { +, nixosConfigurations ? { } # https://github.com/gytis-ivaskevicius/flake-utils-plus/issues/14 +, nixosHosts ? { NAME = { # https://github.com/gytis-ivaskevicius/flake-utils-plus/issues/16 system = "..."; channelName = "..."; extraArgs = { }; @@ -79,7 +79,7 @@ Such function would have the following top level API , channelsConfig ? { } , sharedModules ? [ ] , sharedOverlays ? [ ] -, nixosSpecialArgs ? { } +, nixosSpecialArgs ? { } # https://github.com/gytis-ivaskevicius/flake-utils-plus/issues/13#issuecomment-814512835 , hmConfigurations ? { } , hmProfiles ? { NAME = { @@ -101,9 +101,9 @@ Such function would have the following top level API , defaultSystem ? "x86_64-linux" , supportedSystems ? flake-utils.lib.defaultSystems , name # or inputs, see: https://github.com/gytis-ivaskevicius/flake-utils-plus/issues/12 -, nixosConfigurations ? { } # escape hatch -, hmConfigurations ? { } # escape hatch -, deployConfigurations ? { } # escape hatch +, nixosConfigurations ? { } # escape hatch / https://github.com/gytis-ivaskevicius/flake-utils-plus/issues/14 +, hmConfigurations ? { } # escape hatch / https://github.com/gytis-ivaskevicius/flake-utils-plus/issues/14 +, deployConfigurations ? { } # escape hatch / https://github.com/gytis-ivaskevicius/flake-utils-plus/issues/14 , channels ? { input = "..."; overlaysBuilder = channels: [ (final: prev: { })]; @@ -117,16 +117,19 @@ Such function would have the following top level API , nixosModules ? [ ] , nixosProfiles ? [ ] , nixosUserProfiles ? [ ] -, nixosSpecialArgs ? [ ] +, nixosSpecialArgs ? { } # https://github.com/gytis-ivaskevicius/flake-utils-plus/issues/13#issuecomment-814512835 +, nixosHosts ? { NAME = { # https://github.com/gytis-ivaskevicius/flake-utils-plus/issues/16 + system = "..."; + channelName = "..."; + extraArgs = { }; + modules = [ ]; + };} +, nixosSuites = { }; , hmModules ? [ ] , hmProfiles ? [ ] , hmSpecialArgs ? { } - - - # TODO - , suites - , hosts - +, hmSuites = { }; +, ... # passed through } ``` @@ -137,12 +140,12 @@ Such function would have the following top level API , defaultSystem ? "x86_64-linux" , supportedSystems ? flake-utils.lib.defaultSystems , name # or inputs, see: https://github.com/gytis-ivaskevicius/flake-utils-plus/issues/12 -, nixosConfigurations ? { } # escape hatch -, hmConfigurations ? { } # escape hatch -, deployConfigurations ? { } # escape hatch +, nixosConfigurations ? { } # escape hatch / https://github.com/gytis-ivaskevicius/flake-utils-plus/issues/14 +, hmConfigurations ? { } # escape hatch / https://github.com/gytis-ivaskevicius/flake-utils-plus/issues/14 +, deployConfigurations ? { } # escape hatch / https://github.com/gytis-ivaskevicius/flake-utils-plus/issues/14 , channels ? { input = "..."; - overlaysBuilder = channels: [ (final: prev: { })]; + overlaysBuilder = channels: [ (final: prev: { })]; # TODO: do we want another interface here? Also: how to handle module backports? config = { }; patches = [ ]; } @@ -153,12 +156,12 @@ Such function would have the following top level API , nixosModules ? ./modules , nixosProfiles ? ./profiles , nixosUserProfiles ? ./users -, nixosSpecialArgs ? { } +, nixosSpecialArgs ? { } # https://github.com/gytis-ivaskevicius/flake-utils-plus/issues/13#issuecomment-814512835 +, nixosHosts ? ./hosts , hmModules ? ./users/modules , hmProfiles ? ./users/profiles , hmSpecialArgs ? { } - -, hosts ? ./hosts , suites ? ./suites +, ... # passed through } ``` From 7b93e33961d44f1238a3dd98a7579f62d2a54c24 Mon Sep 17 00:00:00 2001 From: David Arnold Date: Tue, 6 Apr 2021 22:07:30 -0500 Subject: [PATCH 3/7] oversight from previous commit --- API.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/API.md b/API.md index c5c88d1bb..3eac60f1f 100644 --- a/API.md +++ b/API.md @@ -158,10 +158,11 @@ Such function would have the following top level API , nixosUserProfiles ? ./users , nixosSpecialArgs ? { } # https://github.com/gytis-ivaskevicius/flake-utils-plus/issues/13#issuecomment-814512835 , nixosHosts ? ./hosts +, nixosSuites = ./suites; , hmModules ? ./users/modules , hmProfiles ? ./users/profiles +, hmSuites = ./users/suites; , hmSpecialArgs ? { } -, suites ? ./suites , ... # passed through } ``` From 68927e123b8e1cf2bd0108fcce1f54541852a599 Mon Sep 17 00:00:00 2001 From: David Arnold Date: Tue, 6 Apr 2021 22:43:16 -0500 Subject: [PATCH 4/7] cluster options by config generator subsystem, ditch nixosUserProfiles - nixosUserProfiles is a bit clashing with hm modules, we might want to just combine them into nixosProfiles, and make a distinction on a template - ditch mkFlake' since its only raison d'etre was to showcase what importers would do to things. --- API.md | 63 +++++++++++++--------------------------------------------- 1 file changed, 14 insertions(+), 49 deletions(-) diff --git a/API.md b/API.md index 3eac60f1f..2a1e07fa7 100644 --- a/API.md +++ b/API.md @@ -94,45 +94,6 @@ Such function would have the following top level API } ``` -```nix -# devos.mkFlake' -{ - self -, defaultSystem ? "x86_64-linux" -, supportedSystems ? flake-utils.lib.defaultSystems -, name # or inputs, see: https://github.com/gytis-ivaskevicius/flake-utils-plus/issues/12 -, nixosConfigurations ? { } # escape hatch / https://github.com/gytis-ivaskevicius/flake-utils-plus/issues/14 -, hmConfigurations ? { } # escape hatch / https://github.com/gytis-ivaskevicius/flake-utils-plus/issues/14 -, deployConfigurations ? { } # escape hatch / https://github.com/gytis-ivaskevicius/flake-utils-plus/issues/14 -, channels ? { - input = "..."; - overlaysBuilder = channels: [ (final: prev: { })]; - config = { }; - patches = [ ]; - } -, channelsConfig ? { } -, sharedModules ? [ ] -, sharedOverlays ? [ ] - -, nixosModules ? [ ] -, nixosProfiles ? [ ] -, nixosUserProfiles ? [ ] -, nixosSpecialArgs ? { } # https://github.com/gytis-ivaskevicius/flake-utils-plus/issues/13#issuecomment-814512835 -, nixosHosts ? { NAME = { # https://github.com/gytis-ivaskevicius/flake-utils-plus/issues/16 - system = "..."; - channelName = "..."; - extraArgs = { }; - modules = [ ]; - };} -, nixosSuites = { }; -, hmModules ? [ ] -, hmProfiles ? [ ] -, hmSpecialArgs ? { } -, hmSuites = { }; -, ... # passed through -} -``` - ```nix # devos.mkFlake { @@ -153,16 +114,20 @@ Such function would have the following top level API , sharedModules ? [ ] , sharedOverlays ? [ ] -, nixosModules ? ./modules -, nixosProfiles ? ./profiles -, nixosUserProfiles ? ./users -, nixosSpecialArgs ? { } # https://github.com/gytis-ivaskevicius/flake-utils-plus/issues/13#issuecomment-814512835 -, nixosHosts ? ./hosts -, nixosSuites = ./suites; -, hmModules ? ./users/modules -, hmProfiles ? ./users/profiles -, hmSuites = ./users/suites; -, hmSpecialArgs ? { } +# allow setting thos ine a variety of (polished ways) +# like suites = { one = {}; two = {};}; instead of ./suites +, nixos ? { + modules = ./modules; + profiles = ./profiles; + specialArgs = { }; # https://github.com/gytis-ivaskevicius/flake-utils-plus/issues/13#issuecomment-814512835 + hosts = ./hosts; + suites = ./suites; +, hm ? { + modules = ./users/modules; + profiles = ./users/profiles; + specialArgs = { }; + suites = ./users/suites; + } , ... # passed through } ``` From 4f69777c5670391636ce0553db9a53c841a042c4 Mon Sep 17 00:00:00 2001 From: David Arnold Date: Wed, 7 Apr 2021 10:29:06 -0500 Subject: [PATCH 5/7] Agreement in principle reach on how to deal with escape hatches upstream --- API.md | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) diff --git a/API.md b/API.md index 2a1e07fa7..0816dfb62 100644 --- a/API.md +++ b/API.md @@ -63,7 +63,6 @@ Such function would have the following top level API , defaultSystem ? "x86_64-linux" , supportedSystems ? flake-utils.lib.defaultSystems , name # or inputs, see: https://github.com/gytis-ivaskevicius/flake-utils-plus/issues/12 -, nixosConfigurations ? { } # https://github.com/gytis-ivaskevicius/flake-utils-plus/issues/14 , nixosHosts ? { NAME = { # https://github.com/gytis-ivaskevicius/flake-utils-plus/issues/16 system = "..."; channelName = "..."; @@ -90,8 +89,7 @@ Such function would have the following top level API , deployConfigurations ? { } -, ... # passed through -} +, ... # passed through / https://github.com/gytis-ivaskevicius/flake-utils-plus/issues/14} ``` ```nix @@ -101,9 +99,6 @@ Such function would have the following top level API , defaultSystem ? "x86_64-linux" , supportedSystems ? flake-utils.lib.defaultSystems , name # or inputs, see: https://github.com/gytis-ivaskevicius/flake-utils-plus/issues/12 -, nixosConfigurations ? { } # escape hatch / https://github.com/gytis-ivaskevicius/flake-utils-plus/issues/14 -, hmConfigurations ? { } # escape hatch / https://github.com/gytis-ivaskevicius/flake-utils-plus/issues/14 -, deployConfigurations ? { } # escape hatch / https://github.com/gytis-ivaskevicius/flake-utils-plus/issues/14 , channels ? { input = "..."; overlaysBuilder = channels: [ (final: prev: { })]; # TODO: do we want another interface here? Also: how to handle module backports? From 7153c920fe36a3208e8ebdbf030bcc5fc68e91b6 Mon Sep 17 00:00:00 2001 From: David Arnold Date: Wed, 7 Apr 2021 12:55:30 -0500 Subject: [PATCH 6/7] Split it further --- API.md | 47 +++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 43 insertions(+), 4 deletions(-) diff --git a/API.md b/API.md index 0816dfb62..dbfd1e0b8 100644 --- a/API.md +++ b/API.md @@ -49,11 +49,11 @@ The devos-lib onion: - `divnix/devos` (the lib) While flake-utils-plus exports a generic [`utils.systemFlake`](https://github.com/gytis-ivaskevicius/flake-utils-plus/blob/51cb739c9c9c2258bc70747eb7bc22975ae244bd/flake.nix#L37) user function -and is restricted from including dependencies, devos-lib should export a `devos.systemFlake` kwithout such restrictions and that can include +and is restricted from including dependencies, devos-lib should export a `devos.systemFlake` without such restrictions and that can include additional (eventually third-party mediated) generatros, such as `deploy-rs`, while implementing a strict superset of `utils.systemFlake` api and, on the other hand, a `devos.mkFlake` with importer amenities included and a slightly different api for convenience. -Such function would have the following top level API +### `devos.systemFlake` ```nix # devos.systemFlake @@ -92,6 +92,36 @@ Such function would have the following top level API , ... # passed through / https://github.com/gytis-ivaskevicius/flake-utils-plus/issues/14} ``` +### `devos.mkFlake` + +This is all about importer amentities over `devos.systemFlake`. + +For example people should be able to define either paths or functions as arguments. +Also we might consider special (import !only!) magic like reducing: + +```nix +{ + nixos = { + modules = ./modules; + profiles = ./profiles; + specialArgs = { }; # https://github.com/gytis-ivaskevicius/flake-utils-plus/issues/13#issuecomment-814512835 + hosts = ./hosts; + suites = ./suites; + }; +} +``` + +to + +```nix +{ + nixos = ./os; # with default fallback folder naming scheme +} +``` + +#### Part 1: Passthrough API from `devos.systemFlake` + +We should not change the api here, but rather seek upstream amendmend. ```nix # devos.mkFlake { @@ -106,10 +136,20 @@ Such function would have the following top level API patches = [ ]; } , channelsConfig ? { } +# TODO: two dimensions: +# - shared vs. "per-host" +# - external (consuming other devos flakes) vs internal , sharedModules ? [ ] , sharedOverlays ? [ ] +, ... # passed through +} +``` -# allow setting thos ine a variety of (polished ways) +#### Part 2: Devos NixOS/hm/... configuration API +```nix +# devos.mkFlake +{ +# allow setting those in a variety of (polished ways) # like suites = { one = {}; two = {};}; instead of ./suites , nixos ? { modules = ./modules; @@ -123,6 +163,5 @@ Such function would have the following top level API specialArgs = { }; suites = ./users/suites; } -, ... # passed through } ``` From 0f656a8ec7be5c174b12f3c2068df0c866241dc0 Mon Sep 17 00:00:00 2001 From: Timothy DeHerrera Date: Sun, 18 Apr 2021 19:24:31 -0600 Subject: [PATCH 7/7] fix typo which has dual effect of increasing modesty :smile: --- API.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/API.md b/API.md index dbfd1e0b8..3c734ef14 100644 --- a/API.md +++ b/API.md @@ -1,6 +1,6 @@ # DevOS 2.0 -- We want to be a god ecosystem citizen, therefore we want to rebase on [`gytis/flake-utils-plus`](https://github.com/gytis-ivaskevicius/flake-utils-plus). +- We want to be a good ecosystem citizen, therefore we want to rebase on [`gytis/flake-utils-plus`](https://github.com/gytis-ivaskevicius/flake-utils-plus). - `gytis/flake-utils-plus` is designed to be incorporated in upstream flake-utils. As the name suggests, it wraps and extends `flake-utils` for nixos related use cases. - `devos-lib` shall be another layer that wraps `flakes-utils-plus` and adds accoustomed devos amentities, such as: - automagic importers, for pure convenience, but without prescribing a particular folder layout (that is something for devos templates to achieve).