From 7613fd12ecf837317f2752deb29572fecc5a6114 Mon Sep 17 00:00:00 2001 From: Robert Helgesson Date: Tue, 21 Apr 2020 01:02:20 +0200 Subject: [PATCH] doc: document `dagOf` and `gvariant` types --- doc/manual.xml | 1 + doc/writing-modules.adoc | 180 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 181 insertions(+) create mode 100644 doc/writing-modules.adoc diff --git a/doc/manual.xml b/doc/manual.xml index 8ff81308b..9b32826eb 100644 --- a/doc/manual.xml +++ b/doc/manual.xml @@ -26,6 +26,7 @@ + Configuration Options diff --git a/doc/writing-modules.adoc b/doc/writing-modules.adoc new file mode 100644 index 000000000..41678c30d --- /dev/null +++ b/doc/writing-modules.adoc @@ -0,0 +1,180 @@ +[[ch-writing-modules]] +== Writing Home Manager Modules +:writing-nixos-modules: https://nixos.org/nixos/manual/index.html#sec-writing-modules + +The 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. + +[[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 + +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 <>. + +`hm.types.dagOf`:: +Options 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 <>. ++ +A 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`. ++ +`hm.dag.entryAnywhere (value: T)`::: +Indicates that `value` can be placed anywhere within the DAG. This is also the default for plain attribute set entries, that is ++ +[source,nix] +---- +foo.bar = { + a = hm.dag.entryAnywhere 0; +} +---- ++ +and ++ +[source,nix] +---- +foo.bar = { + a = 0; +} +---- ++ +are equivalent. ++ +`hm.dag.entryAfter (afters: list string) (value: T)`::: +Indicates that `value` must be placed _after_ each of the attribute names in the given list. For example ++ +[source,nix] +---- +foo.bar = { + a = 0; + b = hm.dag.entryAfter [ "a" ] 1; +} +---- ++ +would place `b` after `a` in the graph. ++ +`hm.dag.entryBefore (befores: list string) (value: T)`::: +Indicates that `value` must be placed _before_ each of the attribute names in the given list. For example ++ +[source,nix] +---- +foo.bar = { + b = hm.dag.entryBefore [ "a" ] 1; + a = 0; +} +---- ++ +would place `b` before `a` in the graph. ++ +`hm.dag.entryBetween (befores: list string) (afters: list string) (value: T)`::: +Indicates that `value` must be placed _before_ the attribute names in the first list and _after_ the attribute names in the second list. For example ++ +[source,nix] +---- +foo.bar = { + a = 0; + c = hm.dag.entryBetween [ "b" ] [ "a" ] 2; + b = 1; +} +---- ++ +would place `c` before `b` and after `a` in the graph. + +`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)`::: +Takes a Nix value `v` to a GVariant `boolean` value. Note, Nix booleans are automatically coerced using this function. That is, ++ +[source,nix] +---- +foo.bar = hm.gvariant.mkBoolean true; +---- ++ +is equivalent to ++ +[source,nix] +---- +foo.bar = true; +---- +`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] +---- +foo.bar = hm.gvariant.mkString "a string"; +---- ++ +is equivalent to ++ +[source,nix] +---- +foo.bar = "a string"; +---- +`hm.gvariant.mkObjectpath (v: string)`::: +Takes a Nix value `v` to a GVariant `objectpath` value. +`hm.gvariant.mkUchar (v: string)`::: +Takes a Nix value `v` to a GVariant `uchar` value. +`hm.gvariant.mkInt16 (v: int)`::: +Takes a Nix value `v` to a GVariant `int16` value. +`hm.gvariant.mkUint16 (v: int)`::: +Takes a Nix value `v` to a GVariant `uint16` value. +`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] +---- +foo.bar = hm.gvariant.mkInt32 7; +---- ++ +is equivalent to ++ +[source,nix] +---- +foo.bar = 7; +---- +`hm.gvariant.mkUint32 (v: int)`::: +Takes a Nix value `v` to a GVariant `uint32` value. +`hm.gvariant.mkInt64 (v: int)`::: +Takes a Nix value `v` to a GVariant `int64` value. +`hm.gvariant.mkUint64 (v: int)`::: +Takes a Nix value `v` to a GVariant `uint64` value. +`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] +---- +foo.bar = hm.gvariant.mkDouble 3.14; +---- ++ +is equivalent to ++ +[source,nix] +---- +foo.bar = 3.14; +---- ++ +`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 ++ +-- +- `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.arrayOf type` +- `hm.gvariant.type.tupleOf types` +-- ++ +where `type` and `types` are themselve a type and list of types, respectively. ++ +`hm.gvariant.mkEmptyArray type`::: +An alias of `hm.gvariant.mkArray type []`. ++ +`hm.gvariant.mkTuple elements`::: +Builds a GVariant tuple containing the given list of elements, where each element is a GVariant value.