fork/home-manager

git clone https://git.julia.blue/fork/home-manager

Robert Helgessonlib: add functions to create DAGs from lists28614ed7

master
10.8 KiB283 linesraw
1[[ch-writing-modules]]
2== Writing Home Manager Modules
3:writing-nixos-modules: https://nixos.org/nixos/manual/index.html#sec-writing-modules
4
5The module system in Home Manager is based entirely on the NixOS module system so we will here only highlight aspects that are specific for Home Manager. For information about the module system as such please refer to the {writing-nixos-modules}[Writing NixOS Modules] chapter of the NixOS manual.
6
7[[sec-option-types]]
8=== Option Types
9:wikipedia-dag: https://en.wikipedia.org/w/index.php?title=Directed_acyclic_graph&oldid=939656095
10:gvariant-description: https://docs.gtk.org/glib/struct.Variant.html#description
11
12Overall the basic option types are the same in Home Manager as NixOS. A few Home Manager options, however, make use of custom types that are worth describing in more detail. These are the option types `dagOf` and `gvariant` that are used, for example, by <<opt-programs.ssh.matchBlocks>> and <<opt-dconf.settings>>.
13
14[[sec-option-types-dag]]`hm.types.dagOf`::
15Options of this type have attribute sets as values where each member is a node in a {wikipedia-dag}[directed acyclic graph] (DAG). This allows the attribute set entries to express dependency relations among themselves. This can, for example, be used to control the order of match blocks in a OpenSSH client configuration or the order of activation script blocks in <<opt-home.activation>>.
16+
17A number of functions are provided to create DAG nodes. The functions are shown below with examples using an option `foo.bar`  of type `hm.types.dagOf types.int`.
18+
19--
20[[sec-option-types-dag-entryAnywhere]]`hm.dag.entryAnywhere (value: T) : DagEntry<T>`:::
21Indicates that `value` can be placed anywhere within the DAG. This is also the default for plain attribute set entries, that is
22+
23[source,nix]
24----
25foo.bar = {
26  a = hm.dag.entryAnywhere 0;
27}
28----
29+
30and
31+
32[source,nix]
33----
34foo.bar = {
35  a = 0;
36}
37----
38+
39are equivalent.
40+
41[[sec-option-types-dag-entryAfter]]`hm.dag.entryAfter (afters: list string) (value: T) : DagEntry<T>` :::
42Indicates that `value` must be placed _after_ each of the attribute names in the given list. For example
43+
44[source,nix]
45----
46foo.bar = {
47  a = 0;
48  b = hm.dag.entryAfter [ "a" ] 1;
49}
50----
51+
52would place `b` after `a` in the graph.
53+
54[[sec-option-types-dag-entryBefore]]`hm.dag.entryBefore (befores: list string) (value: T) : DagEntry<T>` :::
55Indicates that `value` must be placed _before_ each of the attribute names in the given list. For example
56+
57[source,nix]
58----
59foo.bar = {
60  b = hm.dag.entryBefore [ "a" ] 1;
61  a = 0;
62}
63----
64+
65would place `b` before `a` in the graph.
66+
67[[sec-option-types-dag-entryBetween]]`hm.dag.entryBetween (befores: list string) (afters: list string) (value: T) : DagEntry<T>` :::
68Indicates that `value` must be placed _before_ the attribute names in the first list and _after_ the attribute names in the second list. For example
69+
70[source,nix]
71----
72foo.bar = {
73  a = 0;
74  c = hm.dag.entryBetween [ "b" ] [ "a" ] 2;
75  b = 1;
76}
77----
78+
79would place `c` before `b` and after `a` in the graph.
80--
81+
82There are also a set of functions that generate a DAG from a list.
83These are convenient when you just want to have a linear list of DAG entries,
84without having to manually enter the relationship between each entry.
85Each of these functions take a `tag` as argument and the DAG entries will be named `${tag}-${index}`.
86
87[[sec-option-types-dag-entriesAnywhere]]`hm.dag.entriesAnywhere (tag: string) (values: [T]) : Dag<T>`:::
88Creates a DAG with the given values with each entry labeled using the given tag. For example
89+
90[source,nix]
91foo.bar = hm.dag.entriesAnywhere "a" [ 0 1 ];
92+
93is equivalent to
94+
95[source,nix]
96----
97foo.bar = {
98  a-0 = 0;
99  a-1 = hm.dag.entryAfter [ "a-0" ] 1;
100}
101----
102+
103[[sec-option-types-dag-entriesAfter]]`hm.dag.entriesAfter (tag: string) (afters: list string) (values: [T]) : Dag<T>`:::
104Creates a DAG with the given values with each entry labeled using the given tag.
105The list of values are placed are placed _after_ each of the attribute names in `afters`.
106For example
107+
108[source,nix]
109foo.bar =
110  { b = 0; }
111  // hm.dag.entriesAfter "a" [ "b" ] [ 1 2 ];
112+
113is equivalent to
114+
115[source,nix]
116----
117foo.bar = {
118  b = 0;
119  a-0 = hm.dag.entryAfter [ "b" ] 1;
120  a-1 = hm.dag.entryAfter [ "a-0" ] 2;
121}
122----
123+
124[[sec-option-types-dag-entriesBefore]]`hm.dag.entriesBefore (tag: string) (befores: list string) (values: [T]) : Dag<T>`:::
125Creates a DAG with the given values with each entry labeled using the given tag.
126The list of values are placed _before_ each of the attribute names in `befores`.
127For example
128+
129[source,nix]
130foo.bar =
131  { b = 0; }
132  // hm.dag.entriesBefore "a" [ "b" ] [ 1 2 ];
133+
134is equivalent to
135+
136[source,nix]
137----
138foo.bar = {
139  b = 0;
140  a-0 = 1;
141  a-1 = hm.dag.entryBetween [ "b" ] [ "a-0" ] 2;
142}
143----
144+
145[[sec-option-types-dag-entriesBetween]]`hm.dag.entriesBetween (tag: string) (befores: list string) (afters: list string) (values: [T]) : Dag<T>`:::
146Creates a DAG with the given values with each entry labeled using the given tag.
147The list of values are placed _before_ each of the attribute names in `befores`
148and _after_ each of the attribute names in `afters`.
149For example
150+
151[source,nix]
152foo.bar =
153  { b = 0; c = 3; }
154  // hm.dag.entriesBetween "a" [ "b" ] [ "c" ] [ 1 2 ];
155+
156is equivalent to
157+
158[source,nix]
159----
160foo.bar = {
161  b = 0;
162  c = 3;
163  a-0 = hm.dag.entryAfter [ "c" ] 1;
164  a-1 = hm.dag.entryBetween [ "b" ] [ "a-0" ] 2;
165}
166----
167
168[[sec-option-types-gvariant]]`hm.types.gvariant`::
169This type is useful for options representing {gvariant-description}[GVariant] values. The type accepts all primitive GVariant types as well as arrays, tuples, ``maybe'' types, and dictionaries.
170+
171Some Nix values are automatically coerced to matching GVariant value but the GVariant model is richer so you may need to use one of the provided constructor functions. Examples assume an option `foo.bar`  of type `hm.types.gvariant`.
172+
173[[sec-option-types-gvariant-mkBoolean]]`hm.gvariant.mkBoolean (v: bool)`:::
174Takes a Nix value `v` to a GVariant `boolean` value (GVariant format string `b`). Note, Nix booleans are automatically coerced using this function. That is,
175+
176[source,nix]
177----
178foo.bar = hm.gvariant.mkBoolean true;
179----
180+
181is equivalent to
182+
183[source,nix]
184----
185foo.bar = true;
186----
187[[sec-option-types-gvariant-mkString]]`hm.gvariant.mkString (v: string)`:::
188Takes a Nix value `v` to a GVariant `string` value (GVariant format string `s`). Note, Nix strings are automatically coerced using this function. That is,
189+
190[source,nix]
191----
192foo.bar = hm.gvariant.mkString "a string";
193----
194+
195is equivalent to
196+
197[source,nix]
198----
199foo.bar = "a string";
200----
201[[sec-option-types-gvariant-mkObjectpath]]`hm.gvariant.mkObjectpath (v: string)`:::
202Takes a Nix value `v` to a GVariant `objectpath` value (GVariant format string `o`).
203[[sec-option-types-gvariant-mkUchar]]`hm.gvariant.mkUchar (v: string)`:::
204Takes a Nix value `v` to a GVariant `uchar` value (GVariant format string `y`).
205[[sec-option-types-gvariant-mkInt16]]`hm.gvariant.mkInt16 (v: int)`:::
206Takes a Nix value `v` to a GVariant `int16` value (GVariant format string `n`).
207[[sec-option-types-gvariant-mkUint16]]`hm.gvariant.mkUint16 (v: int)`:::
208Takes a Nix value `v` to a GVariant `uint16` value (GVariant format string `q`).
209[[sec-option-types-gvariant-mkInt32]]`hm.gvariant.mkInt32 (v: int)`:::
210Takes a Nix value `v` to a GVariant `int32` value (GVariant format string `i`). Note, Nix integers are automatically coerced using this function. That is,
211+
212[source,nix]
213----
214foo.bar = hm.gvariant.mkInt32 7;
215----
216+
217is equivalent to
218+
219[source,nix]
220----
221foo.bar = 7;
222----
223[[sec-option-types-gvariant-mkUint32]]`hm.gvariant.mkUint32 (v: int)`:::
224Takes a Nix value `v` to a GVariant `uint32` value (GVariant format string `u`).
225[[sec-option-types-gvariant-mkInt64]]`hm.gvariant.mkInt64 (v: int)`:::
226Takes a Nix value `v` to a GVariant `int64` value (GVariant format string `x`).
227[[sec-option-types-gvariant-mkUint64]]`hm.gvariant.mkUint64 (v: int)`:::
228Takes a Nix value `v` to a GVariant `uint64` value (GVariant format string `t`).
229[[sec-option-types-gvariant-mkDouble]]`hm.gvariant.mkDouble (v: double)`:::
230Takes a Nix value `v` to a GVariant `double` value (GVariant format string `d`). Note, Nix floats are automatically coerced using this function. That is,
231+
232[source,nix]
233----
234foo.bar = hm.gvariant.mkDouble 3.14;
235----
236+
237is equivalent to
238+
239[source,nix]
240----
241foo.bar = 3.14;
242----
243+
244[[sec-option-types-gvariant-mkArray]]`hm.gvariant.mkArray type elements`:::
245Builds a GVariant array containing the given list of elements, where each element is a GVariant value of the given type (GVariant format string `a${type}`). The `type` value can be constructed using
246+
247--
248- `hm.gvariant.type.string` (GVariant format string `s`)
249- `hm.gvariant.type.boolean` (GVariant format string `b`)
250- `hm.gvariant.type.uchar` (GVariant format string `y`)
251- `hm.gvariant.type.int16` (GVariant format string `n`)
252- `hm.gvariant.type.uint16` (GVariant format string `q`)
253- `hm.gvariant.type.int32` (GVariant format string `i`)
254- `hm.gvariant.type.uint32` (GVariant format string `u`)
255- `hm.gvariant.type.int64` (GVariant format string `x`)
256- `hm.gvariant.type.uint64` (GVariant format string `t`)
257- `hm.gvariant.type.double` (GVariant format string `d`)
258- `hm.gvariant.type.variant` (GVariant format string `v`)
259- `hm.gvariant.type.arrayOf type` (GVariant format string `a${type}`)
260- `hm.gvariant.type.maybeOf type` (GVariant format string `m${type}`)
261- `hm.gvariant.type.tupleOf types` (GVariant format string `(${lib.concatStrings types})`)
262- `hm.gvariant.type.dictionaryEntryOf [keyType valueType]` (GVariant format string `{${keyType}${valueType}}`)
263--
264+
265where `type` and `types` are themselves a type and list of types, respectively.
266+
267[[sec-option-types-gvariant-mkEmptyArray]]`hm.gvariant.mkEmptyArray type`:::
268An alias of <<sec-option-types-gvariant-mkArray,`hm.gvariant.mkArray type []`>>.
269+
270[[sec-option-types-gvariant-mkNothing]]`hm.gvariant.mkNothing type`:::
271Builds a GVariant maybe value (GVariant format string `m${type}`) whose (non-existent) element is of the given type. The `type` value is constructed as described for the <<sec-option-types-gvariant-mkArray,`mkArray`>> function above.
272+
273[[sec-option-types-gvariant-mkJust]]`hm.gvariant.mkJust element`:::
274Builds a GVariant maybe value (GVariant format string `m${element.type}`) containing the given GVariant element.
275+
276[[sec-option-types-gvariant-mkTuple]]`hm.gvariant.mkTuple elements`:::
277Builds a GVariant tuple containing the given list of elements, where each element is a GVariant value.
278+
279[[sec-option-types-gvariant-mkVariant]]`hm.gvariant.mkVariant element`:::
280Builds a GVariant variant (GVariant format string `v`) which contains the value of a GVariant element.
281+
282[[sec-option-types-gvariant-mkDictionaryEntry]]`hm.gvariant.mkDictionaryEntry [key value]`:::
283Builds a GVariant dictionary entry containing the given list of elements (GVariant format string `{${key.type}${value.type}}`), where each element is a GVariant value.