conversions were done using https://github.com/pennae/nix-doc-munge
using (probably) rev f34e145 running
nix-doc-munge nixos/**/*.nix
nix-doc-munge --import nixos/**/*.nix
the tool ensures that only changes that could affect the generated
manual *but don't* are committed, other changes require manual review
and are discarded.
Upstream XMonad was using our xmonad patch file for their flake build to
support our nixos module. This would of course break the build upstream
if the version we patched and their master branch diverged. We
[discussed] that it'd make sense to upstream the environment var code.
In the process it seemed sensible to rename the NIX_GHC variable as
well, since it isn't really Nix-specific – it's just a way to set the
GHC binary to execute. This change has been [implemented] upstream in an
unreleased version of xmonad now – meaning we'll be able to drop the
xmonad patch soon!
This also clarifies the situation in nixpkgs a bit: NIX_GHC is easy to
confuse with the environment variable used in the ghcWithPackages
wrapper where it is used to set an alternative prefix for a GHC-wrapper
for applications trying to discover it via e.g. ghc-paths. It is an
implementation detail in this context, as it is in the case of the
xmonad module. Since they are different implementations doing different
things, different names also make sense.
[discussed]: 36d5761b3e
[implemented]: 23f36d7e23
the conversion procedure is simple:
- find all things that look like options, ie calls to either `mkOption`
or `lib.mkOption` that take an attrset. remember the attrset as the
option
- for all options, find a `description` attribute who's value is not a
call to `mdDoc` or `lib.mdDoc`
- textually convert the entire value of the attribute to MD with a few
simple regexes (the set from mdize-module.sh)
- if the change produced a change in the manual output, discard
- if the change kept the manual unchanged, add some text to the
description to make sure we've actually found an option. if the
manual changes this time, keep the converted description
this procedure converts 80% of nixos options to markdown. around 2000
options remain to be inspected, but most of those fail the "does not
change the manual output check": currently the MD conversion process
does not faithfully convert docbook tags like <code> and <package>, so
any option using such tags will not be converted at all.
Update the example config to show a working example for xmonad 0.17.0, which
added an argument to the `launch` function and adjusted the location of the
recompiled binary.
Commit 9a5b5d9fe8 added Haskell
dependencies (GHC and packages) to the xmonad binary's environment even
if xmonad had been preconfigured (via the "config" option). The intent
was to enable one-off recompiling using a local config file (e.g.
~/.config/xmonad/xmonad.hs), so the user can get quick feedback while
developing their config.
While this works, it may not be a common use-case, and it requires some
careful crafting in xmonad.hs itself. On top of that, it significantly
increases the size of the closure.
Given all that, commit b69d9d3c23 removed
GHC and packages from the binary's environment.
But there are still those among us who want to be able to recompile from
a preconfigured xmonad, so let's provide a way to opt-into configured
recompilation.
When 'services.xserver.windowManager.xmonad.config' is not null, the
restart feature won't work by default and is not desirable unless
specific care is made, as explained by the documentation.
I think it's reasonable to not include the haskell dependencies in the
environment by default. That reduces the size of my system by 2GB.
Without this patch merging options like
services.xserver.windowManager.xmonad.extraPackages
results in the evaluation error:
error: value is a list while a set was expected, at nixpkgs/lib/options.nix:77:23
With this patch we get the desired merging behaviour that just concatenates the
resulting package lists.
(cherry picked from commit 6e99f9fdec)
Co-Authored-By: Silvan Mosberger <contact@infinisil.com>
* nixos/xmonad: xmonad config w/ghc+xmessage
When the "config" option isn't set, we use xmonad-with-packages to
provide xmonad with runtime access to an isolated ghc, ensuring it can
recompile and exec a user's local config (e.g. $HOME/.xmonad/xmonad.hs)
regardless of which ghc (if any) is on PATH.
When the "config" option is set, however, we compile a configured xmonad
executable upfront (during nixos-rebuild), and prior to this commit, it
was not provided with runtime access to an isolated ghc.
As a result, with the "config" option set, it was not possible
to recompile and exec a user's local config unless there was a
compatible version of ghc on PATH with the necessary packages (xmonad,
xmonad-contrib, etc.) in its package database. Adding such a ghc to
environment.systemPackages, e.g.
(haskellPackages.ghcWithPackages (ps: with ps; [xmonad xmonad-contrib]))
is problematic because it adds both ghc and an unconfigured xmonad to
PATH, e.g.
$ ls -l $(which xmonad ghc)
lrwxrwxrwx ... /run/current-system/sw/bin/ghc -> /nix/store/...-ghc-8.10.2-with-packages/bin/ghc
lrwxrwxrwx ... /run/current-system/sw/bin/xmonad -> /nix/store/...-ghc-8.10.2-with-packages/bin/xmonad
Having the unconfigured xmonad on PATH is particularly bad because
restarting xmonad will dump the user into the unconfigured version, and
if no local config exists (e.g. in $HOME/.xmonad/xmonad.hs), they'll be
left in this unconfigured state.
In this commmit, we give the configured xmonad runtime access to ghc
like xmonad-with-packages does for the unconfigured version. The aim
is to allow the user to switch between the nixos module's config and a
local config (e.g. $HOME/.xmonad/xmonad.hs) at will, so they can try out
config changes without performing a nixos-rebuild.
Since the xmonad on PATH is the configured executable, there's no
danger a user could unwittingly restart into the unconfigured version,
and because xmonad will refuse to recompile when no local config
exists, there's no danger a user could unwittingly recompile into an
unconfigured version.
Given that a local config exists, the recompile/restart behavior depends
on two factors:
- which entry point is used
* 'XMonad.xmonad' (default)
* 'XMonad.launch' (recommended in "config" option description)
- what operation is triggered (i.e. via mod+q)
* `spawn "xmonad --recompile && xmonad --restart"` (default)
* `restart "xmonad" True`
* custom function
If the default 'XMonad.xmonad' entrypoint and default mod+q operation
are used, hitting mod+q will compile and exec the local config, which
will remain in use until next time the display manager is restarted.
If the entrypoint is changed to 'XMonad.launch' but mod+q left with its
default operation, hitting mod+q will have no visible effect. The logs
(as seen by running `journalctl --identifier xmonad --follow`) will show
an error,
X Error of failed request: BadAccess (attempt to access private resource denied)
which indicates that the shell was unable to start xmonad because
another window manager is already running (namely, the nixos-configured
xmonad).
https://wiki.haskell.org/Xmonad/Frequently_asked_questions#X_Error_of_failed_request:_BadAccess_.28attempt_to_access_private_resource_denied.29
Changing the mod+q operation to `restart "xmonad" True` (as recommended
in the "config" option's description) will allow a restart of the
nixos-configured xmonad to be triggeredy by hitting mod+q.
Finally, if the entrypoint is 'XMonad.launch', mod+q has been
bound to `restart "xmonad" True` and another key bound to a custom
recompile/restart function (e.g. `compileRestart` as shown in the
"config" option example), the user can switch between the nixos module's
config and their local config, with the custom key switching to the
local config and mod+q switching back.
* nixos/xmonad: refactor let binding
* nixos/xmonad: refactor (eliminate duplicate code)
* nixos/xmonad: install man pages
Prior to this commit, man pages were not installed if the "config"
option was set.
* nixos/xmonad: comment grammar fixups
* nixos/xmonad: writeStateToFile in example config
Calling writeStateToFile prior to recompiling and restarting allows
state (workspaces, etc.) to be preserved across the restart.
* nixos/xmonad: add ivanbrennan to maintainers
* nixos/xmonad: adjust compileRestart example
* nixos/xmonad: add missing import to example config
