From 0b4ec66640ad5a1aa912a2ae7643f9756e71b4a7 Mon Sep 17 00:00:00 2001
From: Jan Tojnar <jtojnar@gmail.com>
Date: Sat, 6 May 2023 17:26:35 +0200
Subject: [PATCH] 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.
+          </para><para>
+          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
+          <literal>uint32</literal> (<literal>u</literal>), you need to wrap the number
+          using the <literal>lib.hm.gvariant.mkUint32</literal> constructor.
+          Otherwise, since Nix integers are implicitly coerced to <literal>int32</literal>
+          (<literal>i</literal>), it would get stored in the database as such, and GSettings
+          might be confused when loading the setting.
+          </para><para>
+          You might want to use <link xlink:href="https://github.com/gvolpe/dconf2nix">dconf2nix</link>
+          to convert dconf database dumps into compatible Nix expression.
         '';
       };
     };