docs/src/configurations: init

yunfachi · yunfachi · commit e68313331c6b · 2024-10-01T11:14:00.000+03:00
diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts
@@ -73,6 +73,13 @@ function themeConfigEnglish() {return {
           { text: "Examples", link: "/hosts/examples" }
         ],
       },
+      {
+        text: "Configurations (flakes)",
+        items: [
+          { text: "Introduction", link: "/configurations/introduction" },
+          { text: "Structure", link: "/configurations/structure" }
+        ],
+      },
       {
         text: "Rices",
         items: [
@@ -115,7 +122,7 @@ function themeConfigRussian() {return {
           { text: "Вступление в модули NixOS", link: "/ru/modules/introduction-nixos" },
           { text: "Вступление", link: "/ru/modules/introduction" },
           { text: "Структура", link: "/ru/modules/structure" },
-          { text: "Примеры", link: "/ru/modules/examples" }
+          { text: "Примеры", link: "/ru/modules/examples" },
         ],
       },
       {
@@ -129,15 +136,22 @@ function themeConfigRussian() {return {
         items: [
           { text: "Вступление", link: "/ru/hosts/introduction" },
           { text: "Структура", link: "/ru/hosts/structure" },
-          { text: "Примеры", link: "/ru/hosts/examples" }
+          { text: "Примеры", link: "/ru/hosts/examples" },
+        ],
+      },
+      {
+        text: "Конфигурации (флейки)",
+        items: [
+          { text: "Вступление", link: "/ru/configurations/introduction" },
+          { text: "Структура", link: "/ru/configurations/structure" },
         ],
       },
       {
         text: "Райсы",
         items: [
           { text: "Вступление", link: "/ru/rices/introduction" },
           { text: "Структура", link: "/ru/rices/structure" },
-          { text: "Примеры", link: "/ru/rices/examples" }
+          { text: "Примеры", link: "/ru/rices/examples" },
         ],
       },
       { text: "Реальные конфигурации", link: "/real-configurations" },
diff --git a/docs/src/configurations/introduction.md b/docs/src/configurations/introduction.md
@@ -0,0 +1,49 @@
+# Introduction to Denix Configurations (Flakes) {#introduction}
+The `delib.configurations` function is used to create lists of `nixosConfigurations` and `homeConfigurations` for flakes.
+
+In addition to all hosts, it also adds combinations of each host with every **non-`inheritanceOnly`** rice, which allows for quickly switching between rice configurations without editing the code. For example, if the "desktop" host is set to use the "light" rice, executing the following command:
+
+```sh
+nixos-rebuild switch --flake .#desktop --use-remote-sudo
+```
+
+will use the "desktop" host with the "light" rice. However, if you need to quickly switch to another rice, for example, "dark" you can run the following command:
+
+```sh
+nixos-rebuild switch --flake .#desktop-dark --use-remote-sudo
+```
+
+In this case, the host remains "desktop", but the rice changes to "dark".
+
+It is important to note that when switching rice in this way, only the value of the `${myConfigName}.rice` option changes, while the value of `${myConfigName}.hosts.${hostName}.rice` remains the same.
+
+## Principle of Configuration List Generation {#principle}
+The configuration list is generated based on the following principle:
+
+- `{hostName}` - where `hostName` is the name of any host.
+- `{hostName}-{riceName}` - where `hostName` is the name of any host, and `riceName` is the name of any rice where `inheritanceOnly` is `false`.
+
+If `isHomeManager` from the [function arguments](/configurations/structure#function-arguments) is equal to `true`, then a prefix of `{homeManagerUser}@` is added to all configurations in the list.
+
+## Example {#example}
+An example of a flake's `outputs` for `nixosConfigurations` and `homeConfigurations`:
+
+```nix
+outputs = {denix, nixpkgs, ...} @ inputs: let
+  mkConfigurations = isHomeManager:
+    denix.lib.configurations rec {
+      homeManagerNixpkgs = nixpkgs;
+      homeManagerUser = "sjohn";
+      inherit isHomeManager;
+
+      paths = [./hosts ./modules ./rices];
+
+      specialArgs = {
+        inherit inputs isHomeManager homeManagerUser;
+      };
+    };
+in {
+  nixosConfigurations = mkConfigurations false;
+  homeConfigurations = mkConfigurations true;
+}
+```
diff --git a/docs/src/configurations/structure.md b/docs/src/configurations/structure.md
@@ -0,0 +1,31 @@
+# Structure {#structure}
+
+## Function Arguments {#function-arguments}
+- `myconfigName` (string): the category for all Denix module options, hosts, and rices. Default is `myconfig`; changes are not recommended.
+- `denixLibName` (string): the name of the Denix library in `specialArgs` (`{denixLibName, ...}: denixLibName.module { ... }`). Default is `delib`; changes are not recommended.
+- `homeManagerNixpkgs` (nixpkgs): used in the `pkgs` attribute of the `home-manager.lib.homeManagerConfiguration` function in the format: `homeManagerNixpkgs.legacyPackages.${host :: homeManagerSystem}`. By default, it takes `nixpkgs` from the flake.
+- `homeManagerUser` (string): the username, used in `home-manager.users.${homeManagerUser}` and for generating the Home Manager configuration list.
+- `isHomeManager` (boolean): indicates whether to create a configuration list for Home Manager or for NixOS.
+- `paths` (listOf string): paths to be imported; add hosts, rices, and modules here. Default is `[]`.
+- `exclude` (listOf string): paths to be excluded from importing. Default is `[]`.
+- `recursive` (boolean): determines whether to recursively search for paths to import. Default is `true`.
+- `specialArgs` (attrset): `specialArgs` to be passed to `lib.nixosSystem` and `home-manager.lib.homeManagerConfiguration`. Default is `{}`.
+- **EXPERIMENTAL** `extraModules` (list): default is `[]`.
+- **EXPERIMENTAL** `mkConfigurationsSystemExtraModule` (attrset): a module used in the internal NixOS configuration that receives the list of hosts and rices to generate the configuration list. Default is `{nixpkgs.hostPlatform = "x86_64-linux";}`.
+
+## Pseudocode {#pseudocode}
+```nix
+delib.configurations {
+  myconfigName = "myconfig";
+  denixLibName = "delib";
+  homeManagerNixpkgs = inputs.nixpkgs;
+  homeManagerUser = "";
+  isHomeManager = true;
+  paths = [./modules ./hosts ./rices];
+  exclude = [./modules/deprecated];
+  recursive = true;
+  specialArgs = {
+    inherit inputs;
+    isHomeManager = true;
+  };
+}
diff --git a/docs/src/modules/structure.md b/docs/src/modules/structure.md
@@ -1,5 +1,5 @@
 # Structure {#structure}
-This section uses the variables `myconfigName`, `isHomeManager`, and `homeManagerUser`, so it's recommended to first review the corresponding subsection: [delib.system Function Arguments](/TODO).
+This section uses the variables `myconfigName`, `isHomeManager`, and `homeManagerUser`, so it's recommended to first review the corresponding subsection: [delib.configurations Function Arguments](/configurations/structure#function-arguments).
 
 ## Function Arguments {#function-arguments}
 - `name`{#function-arguments-name}: string. It is recommended that it matches the parent path of the module's `enable` option, such as `"programs.example"`, since the `cfg` argument depends on this path.
diff --git a/docs/src/rices/introduction.md b/docs/src/rices/introduction.md
@@ -6,7 +6,7 @@ The term "rice" in slang refers to system settings, usually related to appearanc
 However, rices are not mandatory: to avoid using them, simply do not add the options `${myconfigName}.rices` and `${myconfigName}.rice`, and do not use the `delib.rice` function.
 
 ## Inheritance {#inheritance}
-A rice can inherit all configurations of another rice via the `inherits` attribute. Additionally, you can set `inheritanceOnly = true;`, which will hide the rice from being generated in [`delib.system`](/TODO), leaving it only for inheritance.
+A rice can inherit all configurations of another rice via the `inherits` attribute. Additionally, you can set `inheritanceOnly = true;`, which will hide the rice from being generated in [`delib.configurations`](/configurations/introduction), leaving it only for inheritance.
 
 Example of three rices, where the first two inherit all configurations from the "rounded" rice:
 
diff --git a/docs/src/rices/structure.md b/docs/src/rices/structure.md
@@ -3,7 +3,7 @@
 ## Function Arguments {#function-arguments}
 - `name`: a string representing the rice name.
 - `inherits`: a list of strings - the names of rices whose configurations will be inherited by the current rice.  
-- `inheritanceOnly`: a boolean value that determines whether this rice will be added to the [list of systems generated for each host and rice](/TODO), or if it is only used for inheritance.
+- `inheritanceOnly`: a boolean value that determines whether this rice will be added to the [list of systems generated for each host and rice](/configurations/introduction), or if it is only used for inheritance.
 - `myconfig`: sets its value to `config.${myconfigName}` if `config.${myconfigName}.rice` matches the current rice.
 - `nixos`: sets its value to `config` if `isHomeManager` is `false` and `config.${myconfigName}.rice` matches the current rice.
 - `home`: sets its value to `config` if `isHomeManager` is `true` and `config.${myconfigName}.rice` matches the current rice. Otherwise, if `config.${myconfigName}.rice` matches the current rice, sets its value to `config.home-manager.users.${homeManagerUser}`.
diff --git a/docs/src/ru/configurations/introduction.md b/docs/src/ru/configurations/introduction.md
@@ -0,0 +1,49 @@
+# Введение в конфигурации Denix (флейки) {#introduction}
+Функция `delib.configurations` используется для создания списков `nixosConfigurations` и `homeConfigurations` для флейков.
+
+Помимо всех хостов, она также добавляет комбинации каждого хоста с каждым **не `inheritanceOnly`** райсом, что позволяет быстро переключаться между райсами без редактирования кода. Например, если у хоста "desktop" задан райс "light", то при выполнении следующей команды:
+
+```sh
+nixos-rebuild switch --flake .#desktop --use-remote-sudo
+```
+
+будет использован хост "desktop" с райсом "light". Однако, если необходимо быстро переключиться на другой райс, например, на "dark", можно выполнить следующую команду:
+
+```sh
+nixos-rebuild switch --flake .#desktop-dark --use-remote-sudo
+```
+
+В этом случае хост останется "desktop", но райс изменится на "dark".
+
+Важно отметить, что при смене райса таким образом меняется только значение опции `${myConfigName}.rice`, при этом значение `${myconfigName}.hosts.${hostName}.rice` остаётся прежним.
+
+## Принцип генерации списка конфигураций {#principle}
+Список конфигураций генерируется по следующему принципу:
+
+- `{hostName}` - где `hostName` - имя любого хоста.
+- `{hostName}-{riceName}` - где `hostName` - имя любого хоста, а `riceName` - имя любого райса, у которого `inheritanceOnly` равно `false`.
+
+Если `isHomeManager` из [аргументов функции](/ru/configurations/structure#function-arguments) равен `true`, то ко всем конфигурациям в списке добавляется префикс` {homeManagerUser}@`.
+
+## Пример {#example}
+Пример `outputs` флейка для `nixosConfigurations` и `homeConfigurations`:
+
+```nix
+outputs = {denix, nixpkgs, ...} @ inputs: let
+  mkConfigurations = isHomeManager:
+    denix.lib.configurations rec {
+      homeManagerNixpkgs = nixpkgs;
+      homeManagerUser = "sjohn";
+      inherit isHomeManager;
+
+      paths = [./hosts ./modules ./rices];
+
+      specialArgs = {
+        inherit inputs isHomeManager homeManagerUser;
+      };
+    };
+in {
+  nixosConfigurations = mkConfigurations false;
+  homeConfigurations = mkConfigurations true;
+}
+```
diff --git a/docs/src/ru/configurations/structure.md b/docs/src/ru/configurations/structure.md
@@ -0,0 +1,32 @@
+# Структура {#structure}
+
+## Аргументы функции {#function-arguments}
+- `myconfigName` (string): категория для всех опций модулей Denix, хостов и райсов. По умолчанию `myconfig`; изменять не рекомендуется.
+- `denixLibName` (string): имя библиотеки Denix в `specialArgs` (`{denixLibName, ...}: denixLibName.module { ... }`). По умолчанию `delib`; изменять не рекомендуется.
+- `homeManagerNixpkgs` (nixpkgs): используется в атрибуте `pkgs` функции `home-manager.lib.homeManagerConfiguration` в формате: `homeManagerNixpkgs.legacyPackages.${host :: homeManagerSystem}`. По умолчанию берется `nixpkgs` из флейка.
+- `homeManagerUser` (string): имя пользователя, используется в `home-manager.users.${homeManagerUser}` и для генерации списка конфигураций Home Manager.
+- `isHomeManager` (boolean): указывает, создавать ли список конфигураций для Home Manager или для NixOS.
+- `paths` (listOf string): пути, которые будут импортированы; добавьте сюда хосты, райсы и модули. По умолчанию `[]`.
+- `exclude` (listOf string): пути, которые будут исключены из импортирования. По умолчанию `[]`.
+- `recursive` (boolean): определяет, следует ли рекурсивно искать пути для импортирования. По умолчанию `true`.
+- `specialArgs` (attrset): `specialArgs`, которые будут переданы в `lib.nixosSystem` и `home-manager.lib.homeManagerConfiguration`. По умолчанию `{}`.
+- **EXPERIMENTAL** `extraModules` (list): по умолчанию `[]`.
+- **EXPERIMENTAL** `mkConfigurationsSystemExtraModule` (attrset): модуль, используемый во внутренней конфигурации NixOS, который получает список хостов и райсов для генерации списка конфигураций. По умолчанию `{nixpkgs.hostPlatform = "x86_64-linux";}`.
+
+## Псевдокод {#pseudocode}
+```nix
+delib.configurations {
+  myconfigName = "myconfig";
+  denixLibName = "delib";
+  homeManagerNixpkgs = inputs.nixpkgs;
+  homeManagerUser = "";
+  isHomeManager = true;
+  paths = [./modules ./hosts ./rices];
+  exclude = [./modules/deprecated];
+  recursive = true;
+  specialArgs = {
+    inherit inputs;
+    isHomeManager = true;
+  };
+}
+```
diff --git a/docs/src/ru/modules/structure.md b/docs/src/ru/modules/structure.md
@@ -1,5 +1,5 @@
 # Структура {#structure}
-В этом разделе будут использованы переменные `myconfigName`, `isHomeManager` и `homeManagerUser`, поэтому рекомендуется предварительно ознакомиться с соответствующим подразделом: [Аргументы delib.system](/TODO).
+В этом разделе будут использованы переменные `myconfigName`, `isHomeManager` и `homeManagerUser`, поэтому рекомендуется предварительно ознакомиться с соответствующим подразделом: [Аргументы delib.configurations](/ru/configurations/structure#function-arguments).
 
 ## Аргументы функции {#function-arguments}
 - `name`{#function-arguments-name}: строка. Рекомендуется, чтобы она совпадала с родительским путём опции `enable` модуля, например, `"programs.example"`, так как передаваемый аргумент `cfg` зависит именно от этого пути.
diff --git a/docs/src/ru/rices/introduction.md b/docs/src/ru/rices/introduction.md
@@ -6,7 +6,7 @@
 При этом райсы не являются обязательными - если вы не хотите их использовать, просто не добавляйте опции `${myconfigName}.rices` и `${myconfigName}.rice`, а также не вызывайте функцию `delib.rice`.
 
 ## Наследование {#inheritance}
-Райс может наследовать все конфигурации другого райса через атрибут `inherits`. Кроме того, можно установить `inheritanceOnly = true;`, чтобы скрыть райс от генерации в [`delib.system`](/TODO), оставив его только для наследования.
+Райс может наследовать все конфигурации другого райса через атрибут `inherits`. Кроме того, можно установить `inheritanceOnly = true;`, чтобы скрыть райс от генерации в [`delib.configurations`](/ru/configurations/introduction), оставив его только для наследования.
 
 Пример трех райсов, где первые два наследуют все конфигурации райса "rounded":
 
diff --git a/docs/src/ru/rices/structure.md b/docs/src/ru/rices/structure.md
@@ -3,7 +3,7 @@
 ## Аргументы функции {#function-arguments}
 - `name`: строка, представляющая имя райса.
 - `inherits`: список строк - имена райсов, чьи конфигурации будут унаследованы текущим райсом.
-- `inheritanceOnly`: булевое значение (`true` или `false`), которое определяет, будет ли этот райс добавлен в [список систем, сгенерированный для каждого хоста и райса](/TODO), или же он используется только для наследования.
+- `inheritanceOnly`: булевое значение (`true` или `false`), которое определяет, будет ли этот райс добавлен в [список систем, сгенерированный для каждого хоста и райса](/ru/configurations/introduction), или же он используется только для наследования.
 - `myconfig`: устанавливает её значение в `config.${myconfigName}`, если `config.${myconfigName}.rice` соответствует текущему райсу.
 - `nixos`: устанавливает её значение в `config`, если `isHomeManager` равен `false` и `config.${myconfigName}.rice` соответствует текущему райсу.
 - `home`: устанавливает её значение в `config`, если `isHomeManager` равен `true` и `config.${myconfigName}.rice` соответствует текущему райсу. В противном случае, если `config.${myconfigName}.rice` соответствует текущему райсу, устанавливает её значение в `config.home-manager.users.${homeManagerUser}`.
