From 951f81c0cc39cd0e8fa2575d708aa5eadd3e1dce Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?J=C3=B6rg=20Thalheim?= <Mic92@users.noreply.github.com>
Date: Wed, 2 Nov 2022 08:03:22 +0100
Subject: [PATCH] nixos/systemd-unit-options: document correct wantedBy default
 for user units (#199007)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Until this commit, the documentation suggested `multi-user.target`
as `wantedBy` for all services.
Since `multi-user.target` is not available for user services,
propose a different default for those in the documentation.

Co-authored-by: Naïm Favier <n@monade.li>
Co-authored-by: Florian Warzecha <liketechnik@disroot.org>
---
 nixos/lib/systemd-unit-options.nix | 28 ++++++++++++++--------------
 1 file changed, 14 insertions(+), 14 deletions(-)

diff --git a/nixos/lib/systemd-unit-options.nix b/nixos/lib/systemd-unit-options.nix
index 79c01921781..44f26572a23 100644
--- a/nixos/lib/systemd-unit-options.nix
+++ b/nixos/lib/systemd-unit-options.nix
@@ -68,10 +68,9 @@ in rec {
       default = [];
       type = types.listOf unitNameType;
       description = lib.mdDoc ''
-        Units that require (i.e. depend on and need to go down with)
-        this unit. The discussion under `wantedBy`
-        applies here as well: inverse `.requires`
-        symlinks are established.
+        Units that require (i.e. depend on and need to go down with) this unit.
+        As discussed in the `wantedBy` option description this also creates
+        `.requires` symlinks automatically.
       '';
     };
 
@@ -79,16 +78,17 @@ in rec {
       default = [];
       type = types.listOf unitNameType;
       description = lib.mdDoc ''
-        Units that want (i.e. depend on) this unit. The standard way
-        to make a unit start by default at boot is to set this option
-        to `[ "multi-user.target" ]`. That's despite
-        the fact that the systemd.unit(5) manpage says this option
-        goes in the `[Install]` section that controls
-        the behaviour of `systemctl enable`. Since
-        such a process is stateful and thus contrary to the design of
-        NixOS, setting this option instead causes the equivalent
-        inverse `.wants` symlink to be present,
-        establishing the same desired relationship in a stateless way.
+        Units that want (i.e. depend on) this unit. The default method for
+        starting a unit by default at boot time is to set this option to
+        '["multi-user.target"]' for system services. Likewise for user units
+        (`systemd.user.<name>.*`) set it to `["default.target"]` to make a unit
+        start by default when the user `<name>` logs on.
+
+        This option creates a `.wants` symlink in the given target that exists
+        statelessly without the need for running `systemctl enable`.
+        The in systemd.unit(5) manpage described `[Install]` section however is
+        not supported because it is a stateful process that does not fit well
+        into the NixOS design.
       '';
     };