weechat: 2.1 -> 2.2; improve package configuration

This aims to make the `weechat` package even more configurable. It
allows to specify scripts and commands using the `configure` function
inside a `weechat.override` expression.

The package can be configured like this:

```
with import <nixpkgs> { };
weechat.override {
  plugins = { availablePlugins, ... }: {
    plugins = builtins.attrValues availablePlugins;

    init = ''
      /set foo bar
      /server add freenode chat.freenode.org
    '';

    scripts = [ "/path/to/script.py" ];
  };
}
```

All commands are passed to `weechat --run-command "/set foo bar;/server ..."`.

The `plugins' attribute is not necessarily required anymore, if it's
sufficient to add `init' commands, the `plugins' will be
`builtins.attrValues availablePlugins' by default.

Additionally the result contains `weechat` and `weechat-headless`
(introduced in WeeChat 2.1) now.

1 files changed, 51 insertions, 0 deletions

diff --git a/doc/package-notes.xml b/doc/package-notes.xml
index c2aef8937b06..1f088e8aaa0e 100644
--- a/doc/package-notes.xml
+++ b/doc/package-notes.xml
@@ -671,6 +671,8 @@ overrides = super: self: rec {
     plugins = with availablePlugins; [ python perl ];
   }
 }</programlisting>
+    If the <literal>configure</literal> function returns an attrset without the <literal>plugins</literal>
+    attribute, <literal>availablePlugins</literal> will be used automatically.
   </para>
 
   <para>
@@ -704,6 +706,55 @@ overrides = super: self: rec {
 }; }
 </programlisting>
   </para>
+  <para>
+    WeeChat allows to set defaults on startup using the <literal>--run-command</literal>.
+    The <literal>configure</literal> method can be used to pass commands to the program:
+<programlisting>weechat.override {
+  configure = { availablePlugins, ... }: {
+    init = ''
+      /set foo bar
+      /server add freenode chat.freenode.org
+    '';
+  };
+}</programlisting>
+    Further values can be added to the list of commands when running
+    <literal>weechat --run-command "your-commands"</literal>.
+  </para>
+  <para>
+    Additionally it's possible to specify scripts to be loaded when starting <literal>weechat</literal>.
+    These will be loaded before the commands from <literal>init</literal>:
+<programlisting>weechat.override {
+  configure = { availablePlugins, ... }: {
+    scripts = with pkgs.weechatScripts; [
+      weechat-xmpp weechat-matrix-bridge wee-slack
+    ];
+    init = ''
+      /set plugins.var.python.jabber.key "val"
+    '':
+  };
+}</programlisting>
+  </para>
+  <para>
+    In <literal>nixpkgs</literal> there's a subpackage which contains derivations for
+    WeeChat scripts. Such derivations expect a <literal>passthru.scripts</literal> attribute
+    which contains a list of all scripts inside the store path. Furthermore all scripts
+    have to live in <literal>$out/share</literal>. An exemplary derivation looks like this:
+<programlisting>{ stdenv, fetchurl }:
+
+stdenv.mkDerivation {
+  name = "exemplary-weechat-script";
+  src = fetchurl {
+    url = "https://scripts.tld/your-scripts.tar.gz";
+    sha256 = "...";
+  };
+  passthru.scripts = [ "foo.py" "bar.lua" ];
+  installPhase = ''
+    mkdir $out/share
+    cp foo.py $out/share
+    cp bar.lua $out/share
+  '';
+}</programlisting>
+  </para>
  </section>
  <section xml:id="sec-citrix">
   <title>Citrix Receiver</title>