From 3e906060a88a6929c40b7170e73e7adf9e84a8a8 Mon Sep 17 00:00:00 2001 From: Jan Tojnar Date: Sat, 6 May 2023 16:03:18 +0200 Subject: [PATCH 1/7] docs: Add inline anchors for direct linking to GVariant types --- docs/writing-modules.adoc | 38 +++++++++++++++++++------------------- 1 file changed, 19 insertions(+), 19 deletions(-) diff --git a/docs/writing-modules.adoc b/docs/writing-modules.adoc index d8d69e82..a0fcc3a3 100644 --- a/docs/writing-modules.adoc +++ b/docs/writing-modules.adoc @@ -77,12 +77,12 @@ foo.bar = { + would place `c` before `b` and after `a` in the graph. -`hm.types.gvariant`:: +[[sec-option-types-gvariant]]`hm.types.gvariant`:: This type is useful for options representing {gvariant-description}[GVariant] values. The type accepts all primitive GVariant types as well as arrays and tuples. Dictionaries are not currently supported. + To create a GVariant value you can use a number of provided functions. Examples assume an option `foo.bar` of type `hm.types.gvariant`. + -`hm.gvariant.mkBoolean (v: bool)`::: +[[sec-option-types-gvariant-mkBoolean]]`hm.gvariant.mkBoolean (v: bool)`::: Takes a Nix value `v` to a GVariant `boolean` value. Note, Nix booleans are automatically coerced using this function. That is, + [source,nix] @@ -96,7 +96,7 @@ is equivalent to ---- foo.bar = true; ---- -`hm.gvariant.mkString (v: string)`::: +[[sec-option-types-gvariant-mkString]]`hm.gvariant.mkString (v: string)`::: Takes a Nix value `v` to a GVariant `string` value. Note, Nix strings are automatically coerced using this function. That is, + [source,nix] @@ -110,15 +110,15 @@ is equivalent to ---- foo.bar = "a string"; ---- -`hm.gvariant.mkObjectpath (v: string)`::: +[[sec-option-types-gvariant-mkObjectpath]]`hm.gvariant.mkObjectpath (v: string)`::: Takes a Nix value `v` to a GVariant `objectpath` value. -`hm.gvariant.mkUchar (v: string)`::: +[[sec-option-types-gvariant-mkUchar]]`hm.gvariant.mkUchar (v: string)`::: Takes a Nix value `v` to a GVariant `uchar` value. -`hm.gvariant.mkInt16 (v: int)`::: +[[sec-option-types-gvariant-mkInt16]]`hm.gvariant.mkInt16 (v: int)`::: Takes a Nix value `v` to a GVariant `int16` value. -`hm.gvariant.mkUint16 (v: int)`::: +[[sec-option-types-gvariant-mkUint16]]`hm.gvariant.mkUint16 (v: int)`::: Takes a Nix value `v` to a GVariant `uint16` value. -`hm.gvariant.mkInt32 (v: int)`::: +[[sec-option-types-gvariant-mkInt32]]`hm.gvariant.mkInt32 (v: int)`::: Takes a Nix value `v` to a GVariant `int32` value. Note, Nix integers are automatically coerced using this function. That is, + [source,nix] @@ -132,13 +132,13 @@ is equivalent to ---- foo.bar = 7; ---- -`hm.gvariant.mkUint32 (v: int)`::: +[[sec-option-types-gvariant-mkUint32]]`hm.gvariant.mkUint32 (v: int)`::: Takes a Nix value `v` to a GVariant `uint32` value. -`hm.gvariant.mkInt64 (v: int)`::: +[[sec-option-types-gvariant-mkInt64]]`hm.gvariant.mkInt64 (v: int)`::: Takes a Nix value `v` to a GVariant `int64` value. -`hm.gvariant.mkUint64 (v: int)`::: +[[sec-option-types-gvariant-mkUint64]]`hm.gvariant.mkUint64 (v: int)`::: Takes a Nix value `v` to a GVariant `uint64` value. -`hm.gvariant.mkDouble (v: double)`::: +[[sec-option-types-gvariant-mkDouble]]`hm.gvariant.mkDouble (v: double)`::: Takes a Nix value `v` to a GVariant `double` value. Note, Nix floats are automatically coerced using this function. That is, + [source,nix] @@ -153,7 +153,7 @@ is equivalent to foo.bar = 3.14; ---- + -`hm.gvariant.mkArray type elements`::: +[[sec-option-types-gvariant-mkArray]]`hm.gvariant.mkArray type elements`::: Builds a GVariant array containing the given list of elements, where each element is a GVariant value of the given type. The `type` value can be constructed using + -- @@ -176,20 +176,20 @@ Builds a GVariant array containing the given list of elements, where each elemen + where `type` and `types` are themselves a type and list of types, respectively. + -`hm.gvariant.mkEmptyArray type`::: +[[sec-option-types-gvariant-mkEmptyArray]]`hm.gvariant.mkEmptyArray type`::: An alias of `hm.gvariant.mkArray type []`. + -`hm.gvariant.mkNothing type`::: +[[sec-option-types-gvariant-mkNothing]]`hm.gvariant.mkNothing type`::: Builds a GVariant maybe value whose (non-existent) element is of the given type. The `type` value is constructed as described for the `mkArray` function above. + -`hm.gvariant.mkJust element`::: +[[sec-option-types-gvariant-mkJust]]`hm.gvariant.mkJust element`::: Builds a GVariant maybe value containing the given GVariant element. + -`hm.gvariant.mkTuple elements`::: +[[sec-option-types-gvariant-mkTuple]]`hm.gvariant.mkTuple elements`::: Builds a GVariant tuple containing the given list of elements, where each element is a GVariant value. + -`hm.gvariant.mkVariant element`::: +[[sec-option-types-gvariant-mkVariant]]`hm.gvariant.mkVariant element`::: Builds a GVariant variant which contains the value of a GVariant element. + -`hm.gvariant.mkDictionaryEntry elements`::: +[[sec-option-types-gvariant-mkDictionaryEntry]]`hm.gvariant.mkDictionaryEntry elements`::: Builds a GVariant dictionary entry containing the given list of elements, where each element is a GVariant value. From 81d5b220cde5860b529e87fdc3aae55718c24030 Mon Sep 17 00:00:00 2001 From: Jan Tojnar Date: Sat, 6 May 2023 16:07:05 +0200 Subject: [PATCH 2/7] docs: Fix broken GVariant docs link --- docs/writing-modules.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/writing-modules.adoc b/docs/writing-modules.adoc index a0fcc3a3..8a6c932d 100644 --- a/docs/writing-modules.adoc +++ b/docs/writing-modules.adoc @@ -7,7 +7,7 @@ The module system in Home Manager is based entirely on the NixOS module system s [[sec-option-types]] === Option Types :wikipedia-dag: https://en.wikipedia.org/w/index.php?title=Directed_acyclic_graph&oldid=939656095 -:gvariant-description: https://developer.gnome.org/glib/stable/glib-GVariant.html#glib-GVariant.description +:gvariant-description: https://docs.gtk.org/glib/struct.Variant.html#description Overall 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 <> and <>. From cfa5c2869b535e5e83dac6b04745f673c591e0d2 Mon Sep 17 00:00:00 2001 From: Jan Tojnar Date: Sat, 6 May 2023 16:16:47 +0200 Subject: [PATCH 3/7] docs: GVariant dictionaries are already supported The support for dictionaries were introduced in 864ff685fe6443101a0a8f3950d21bcb4330e56a. --- docs/writing-modules.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/writing-modules.adoc b/docs/writing-modules.adoc index 8a6c932d..b502c17c 100644 --- a/docs/writing-modules.adoc +++ b/docs/writing-modules.adoc @@ -78,7 +78,7 @@ foo.bar = { would place `c` before `b` and after `a` in the graph. [[sec-option-types-gvariant]]`hm.types.gvariant`:: -This type is useful for options representing {gvariant-description}[GVariant] values. The type accepts all primitive GVariant types as well as arrays and tuples. Dictionaries are not currently supported. +This 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. + To create a GVariant value you can use a number of provided functions. Examples assume an option `foo.bar` of type `hm.types.gvariant`. + From a0ddb8af40bee08737170b167e04ab608215d8de Mon Sep 17 00:00:00 2001 From: Jan Tojnar Date: Sat, 6 May 2023 16:23:08 +0200 Subject: [PATCH 4/7] docs: Mention GVariant auto-coercion at the top --- docs/writing-modules.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/writing-modules.adoc b/docs/writing-modules.adoc index b502c17c..482bc770 100644 --- a/docs/writing-modules.adoc +++ b/docs/writing-modules.adoc @@ -80,7 +80,7 @@ would place `c` before `b` and after `a` in the graph. [[sec-option-types-gvariant]]`hm.types.gvariant`:: This 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. + -To create a GVariant value you can use a number of provided functions. Examples assume an option `foo.bar` of type `hm.types.gvariant`. +Some 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`. + [[sec-option-types-gvariant-mkBoolean]]`hm.gvariant.mkBoolean (v: bool)`::: Takes a Nix value `v` to a GVariant `boolean` value. Note, Nix booleans are automatically coerced using this function. That is, From 13d666dd68d18dd20760662b78e885559f90991d Mon Sep 17 00:00:00 2001 From: Jan Tojnar Date: Sat, 6 May 2023 17:12:41 +0200 Subject: [PATCH 5/7] docs: Mention GVariant format strings --- docs/writing-modules.adoc | 64 +++++++++++++++++++-------------------- 1 file changed, 32 insertions(+), 32 deletions(-) diff --git a/docs/writing-modules.adoc b/docs/writing-modules.adoc index 482bc770..648434dd 100644 --- a/docs/writing-modules.adoc +++ b/docs/writing-modules.adoc @@ -83,7 +83,7 @@ This type is useful for options representing {gvariant-description}[GVariant] va Some 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`. + [[sec-option-types-gvariant-mkBoolean]]`hm.gvariant.mkBoolean (v: bool)`::: -Takes a Nix value `v` to a GVariant `boolean` value. Note, Nix booleans are automatically coerced using this function. That is, +Takes a Nix value `v` to a GVariant `boolean` value (GVariant format string `b`). Note, Nix booleans are automatically coerced using this function. That is, + [source,nix] ---- @@ -97,7 +97,7 @@ is equivalent to foo.bar = true; ---- [[sec-option-types-gvariant-mkString]]`hm.gvariant.mkString (v: string)`::: -Takes a Nix value `v` to a GVariant `string` value. Note, Nix strings are automatically coerced using this function. That is, +Takes a Nix value `v` to a GVariant `string` value (GVariant format string `s`). Note, Nix strings are automatically coerced using this function. That is, + [source,nix] ---- @@ -111,15 +111,15 @@ is equivalent to foo.bar = "a string"; ---- [[sec-option-types-gvariant-mkObjectpath]]`hm.gvariant.mkObjectpath (v: string)`::: -Takes a Nix value `v` to a GVariant `objectpath` value. +Takes a Nix value `v` to a GVariant `objectpath` value (GVariant format string `o`). [[sec-option-types-gvariant-mkUchar]]`hm.gvariant.mkUchar (v: string)`::: -Takes a Nix value `v` to a GVariant `uchar` value. +Takes a Nix value `v` to a GVariant `uchar` value (GVariant format string `y`). [[sec-option-types-gvariant-mkInt16]]`hm.gvariant.mkInt16 (v: int)`::: -Takes a Nix value `v` to a GVariant `int16` value. +Takes a Nix value `v` to a GVariant `int16` value (GVariant format string `n`). [[sec-option-types-gvariant-mkUint16]]`hm.gvariant.mkUint16 (v: int)`::: -Takes a Nix value `v` to a GVariant `uint16` value. +Takes a Nix value `v` to a GVariant `uint16` value (GVariant format string `q`). [[sec-option-types-gvariant-mkInt32]]`hm.gvariant.mkInt32 (v: int)`::: -Takes a Nix value `v` to a GVariant `int32` value. Note, Nix integers are automatically coerced using this function. That is, +Takes a Nix value `v` to a GVariant `int32` value (GVariant format string `i`). Note, Nix integers are automatically coerced using this function. That is, + [source,nix] ---- @@ -133,13 +133,13 @@ is equivalent to foo.bar = 7; ---- [[sec-option-types-gvariant-mkUint32]]`hm.gvariant.mkUint32 (v: int)`::: -Takes a Nix value `v` to a GVariant `uint32` value. +Takes a Nix value `v` to a GVariant `uint32` value (GVariant format string `u`). [[sec-option-types-gvariant-mkInt64]]`hm.gvariant.mkInt64 (v: int)`::: -Takes a Nix value `v` to a GVariant `int64` value. +Takes a Nix value `v` to a GVariant `int64` value (GVariant format string `x`). [[sec-option-types-gvariant-mkUint64]]`hm.gvariant.mkUint64 (v: int)`::: -Takes a Nix value `v` to a GVariant `uint64` value. +Takes a Nix value `v` to a GVariant `uint64` value (GVariant format string `t`). [[sec-option-types-gvariant-mkDouble]]`hm.gvariant.mkDouble (v: double)`::: -Takes a Nix value `v` to a GVariant `double` value. Note, Nix floats are automatically coerced using this function. That is, +Takes a Nix value `v` to a GVariant `double` value (GVariant format string `d`). Note, Nix floats are automatically coerced using this function. That is, + [source,nix] ---- @@ -154,24 +154,24 @@ foo.bar = 3.14; ---- + [[sec-option-types-gvariant-mkArray]]`hm.gvariant.mkArray type elements`::: -Builds a GVariant array containing the given list of elements, where each element is a GVariant value of the given type. The `type` value can be constructed using +Builds 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 + -- -- `hm.gvariant.type.string` -- `hm.gvariant.type.boolean` -- `hm.gvariant.type.uchar` -- `hm.gvariant.type.int16` -- `hm.gvariant.type.uint16` -- `hm.gvariant.type.int32` -- `hm.gvariant.type.uint32` -- `hm.gvariant.type.int64` -- `hm.gvariant.type.uint64` -- `hm.gvariant.type.double` -- `hm.gvariant.type.variant` -- `hm.gvariant.type.arrayOf type` -- `hm.gvariant.type.maybeOf type` -- `hm.gvariant.type.tupleOf types` -- `hm.gvariant.type.dictionaryEntryOf types` +- `hm.gvariant.type.string` (GVariant format string `s`) +- `hm.gvariant.type.boolean` (GVariant format string `b`) +- `hm.gvariant.type.uchar` (GVariant format string `y`) +- `hm.gvariant.type.int16` (GVariant format string `n`) +- `hm.gvariant.type.uint16` (GVariant format string `q`) +- `hm.gvariant.type.int32` (GVariant format string `i`) +- `hm.gvariant.type.uint32` (GVariant format string `u`) +- `hm.gvariant.type.int64` (GVariant format string `x`) +- `hm.gvariant.type.uint64` (GVariant format string `t`) +- `hm.gvariant.type.double` (GVariant format string `d`) +- `hm.gvariant.type.variant` (GVariant format string `v`) +- `hm.gvariant.type.arrayOf type` (GVariant format string `a${type}`) +- `hm.gvariant.type.maybeOf type` (GVariant format string `m${type}`) +- `hm.gvariant.type.tupleOf types` (GVariant format string `(${lib.concatStrings types})`) +- `hm.gvariant.type.dictionaryEntryOf [keyType valueType]` (GVariant format string `{${keyType}${valueType}}`) -- + where `type` and `types` are themselves a type and list of types, respectively. @@ -180,16 +180,16 @@ where `type` and `types` are themselves a type and list of types, respectively. An alias of `hm.gvariant.mkArray type []`. + [[sec-option-types-gvariant-mkNothing]]`hm.gvariant.mkNothing type`::: -Builds a GVariant maybe value whose (non-existent) element is of the given type. The `type` value is constructed as described for the `mkArray` function above. +Builds 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 `mkArray` function above. + [[sec-option-types-gvariant-mkJust]]`hm.gvariant.mkJust element`::: -Builds a GVariant maybe value containing the given GVariant element. +Builds a GVariant maybe value (GVariant format string `m${element.type}`) containing the given GVariant element. + [[sec-option-types-gvariant-mkTuple]]`hm.gvariant.mkTuple elements`::: Builds a GVariant tuple containing the given list of elements, where each element is a GVariant value. + [[sec-option-types-gvariant-mkVariant]]`hm.gvariant.mkVariant element`::: -Builds a GVariant variant which contains the value of a GVariant element. +Builds a GVariant variant (GVariant format string `v`) which contains the value of a GVariant element. + -[[sec-option-types-gvariant-mkDictionaryEntry]]`hm.gvariant.mkDictionaryEntry elements`::: -Builds a GVariant dictionary entry containing the given list of elements, where each element is a GVariant value. +[[sec-option-types-gvariant-mkDictionaryEntry]]`hm.gvariant.mkDictionaryEntry [key value]`::: +Builds a GVariant dictionary entry containing the given list of elements (GVariant format string `{${key.type}${value.type}}`), where each element is a GVariant value. From ea29b1a8d1e2717581f4db852ad6647fc03bd00d Mon Sep 17 00:00:00 2001 From: Jan Tojnar Date: Sat, 6 May 2023 16:13:39 +0200 Subject: [PATCH 6/7] docs: Add GVariant cross-references --- docs/writing-modules.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/writing-modules.adoc b/docs/writing-modules.adoc index 648434dd..7f0e79cd 100644 --- a/docs/writing-modules.adoc +++ b/docs/writing-modules.adoc @@ -177,10 +177,10 @@ Builds a GVariant array containing the given list of elements, where each elemen where `type` and `types` are themselves a type and list of types, respectively. + [[sec-option-types-gvariant-mkEmptyArray]]`hm.gvariant.mkEmptyArray type`::: -An alias of `hm.gvariant.mkArray type []`. +An alias of <>. + [[sec-option-types-gvariant-mkNothing]]`hm.gvariant.mkNothing type`::: -Builds 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 `mkArray` function above. +Builds 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 <> function above. + [[sec-option-types-gvariant-mkJust]]`hm.gvariant.mkJust element`::: Builds a GVariant maybe value (GVariant format string `m${element.type}`) containing the given GVariant element. From 0b4ec66640ad5a1aa912a2ae7643f9756e71b4a7 Mon Sep 17 00:00:00 2001 From: Jan Tojnar Date: Sat, 6 May 2023 17:26:35 +0200 Subject: [PATCH 7/7] dconf: Warn about strict typing of options This is a frequent surprise to users. --- modules/misc/dconf.nix | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/modules/misc/dconf.nix b/modules/misc/dconf.nix index f1ce38d3..8aa8e8d8 100644 --- a/modules/misc/dconf.nix +++ b/modules/misc/dconf.nix @@ -59,6 +59,17 @@ in { ''; description = '' Settings to write to the dconf configuration system. + + Note that the database is strongly-typed so you need to use the same types + as described in the GSettings schema. For example, if an option is of type + uint32 (u), you need to wrap the number + using the lib.hm.gvariant.mkUint32 constructor. + Otherwise, since Nix integers are implicitly coerced to int32 + (i), it would get stored in the database as such, and GSettings + might be confused when loading the setting. + + You might want to use dconf2nix + to convert dconf database dumps into compatible Nix expression. ''; }; };