diff options
author | rnhmjoj <rnhmjoj@inventati.org> | 2020-01-09 22:28:42 +0100 |
---|---|---|
committer | rnhmjoj <rnhmjoj@inventati.org> | 2020-02-02 12:00:51 +0100 |
commit | ef9a029700babd9b26a1f452dd97c1defd31ebed (patch) | |
tree | c4104517ef62310726fc9bf912d99faae0673316 /doc/builders/packages | |
parent | 4e155430ab76627f8bb29f584c4d43e499d2b1d9 (diff) |
doc: document new urxvt plugin system
Diffstat (limited to 'doc/builders/packages')
-rw-r--r-- | doc/builders/packages/index.xml | 1 | ||||
-rw-r--r-- | doc/builders/packages/urxvt.xml | 101 |
2 files changed, 102 insertions, 0 deletions
diff --git a/doc/builders/packages/index.xml b/doc/builders/packages/index.xml index 9f3f58a8d9031..4e109bd1c5994 100644 --- a/doc/builders/packages/index.xml +++ b/doc/builders/packages/index.xml @@ -18,6 +18,7 @@ <xi:include href="opengl.xml" /> <xi:include href="shell-helpers.xml" /> <xi:include href="steam.xml" /> + <xi:include href="urxvt.xml" /> <xi:include href="weechat.xml" /> <xi:include href="xorg.xml" /> </chapter> diff --git a/doc/builders/packages/urxvt.xml b/doc/builders/packages/urxvt.xml new file mode 100644 index 0000000000000..f85680cecc402 --- /dev/null +++ b/doc/builders/packages/urxvt.xml @@ -0,0 +1,101 @@ +<section xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xml:id="sec-urxvt"> + <title>Urxvt</title> + + <para> + Urxvt, also known as rxvt-unicode, is a highly customizable terminal emulator. + </para> + + <section xml:id="sec-urxvt-conf"> + + <title>Configuring urxvt</title> + + <para> + In <literal>nixpkgs</literal>, urxvt is provided by the package + <literal>rxvt-unicode</literal>. It can be configured to include your choice + of plugins, reducing its closure size from the default configuration which + includes all available plugins. To make use of this functionality, use an + overlay or directly install an expression that overrides its configuration, + such as + <programlisting>rxvt-unicode.override { configure = { availablePlugins, ... }: { + plugins = with availablePlugins; [ perls resize-font vtwheel ]; + } +}</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> + In order to add plugins but also keep all default plugins installed, it is + possible to use the following method: + <programlisting>rxvt-unicode.override { configure = { availablePlugins, ... }: { + plugins = (builtins.attrValues availablePlugins) ++ [ custom-plugin ]; + }; +}</programlisting> + </para> + + <para> + To get a list of all the plugins available, open the Nix REPL and run + <programlisting>$ nix repl +:l <nixpkgs> +map (p: p.name) pkgs.rxvt-unicode.plugins + </programlisting> + Alternatively, if your shell is bash or zsh and have completion enabled, + simply type <literal>nixpkgs.rxvt-unicode.plugins.<tab></literal>. + </para> + + <para> + In addition to <literal>plugins</literal> the options + <literal>extraDeps</literal> and <literal>perlDeps</literal> can be used + to install extra packages. + <literal>extraDeps</literal> can be used, for example, to provide + <literal>xsel</literal> (a clipboard manager) to the clipboard plugin, + without installing it globally: + <programlisting>rxvt-unicode.override { configure = { availablePlugins, ... }: { + pluginsDeps = [ xsel ]; + } +}</programlisting> + + <literal>perlDeps</literal> is a handy way to provide Perl packages to + your custom plugins (in <literal>$HOME/.urxvt/ext</literal>). For example, + if you need <literal>AnyEvent</literal> you can do: + <programlisting>rxvt-unicode.override { configure = { availablePlugins, ... }: { + perlDeps = with perlPackages; [ AnyEvent ]; + } +}</programlisting> + </para> + + </section> + + <section xml:id="sec-urxvt-pkg"> + + <title>Packaging urxvt plugins</title> + + <para> + Urxvt plugins resides in + <literal>pkgs/applications/misc/rxvt-unicode-plugins</literal>. + To add a new plugin create an expression in a subdirectory and add the + package to the set in + <literal>pkgs/applications/misc/rxvt-unicode-plugins/default.nix</literal>. + </para> + + <para> + A plugin can be any kind of derivation, the only requirement is that it + should always install perl scripts in <literal>$out/lib/urxvt/perl</literal>. + Look for existing plugins for examples. + </para> + + <para> + If the plugin is itself a perl package that needs to be imported from + other plugins or scripts, add the following passthrough: + <programlisting>passthru.perlPackages = [ "self" ]; +</programlisting> + This will make the urxvt wrapper pick up the dependency and set up the perl + path accordingly. + </para> + + </section> + +</section> |