pyrox.dev
1# Urxvt {#sec-urxvt}
2
3Urxvt, also known as rxvt-unicode, is a highly customizable terminal emulator.
4
5## Configuring urxvt {#sec-urxvt-conf}
6
7In `nixpkgs`, urxvt is provided by the package `rxvt-unicode`. 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:
8
9```nix
10rxvt-unicode.override {
11 configure =
12 { availablePlugins, ... }:
13 {
14 plugins = with availablePlugins; [
15 perls
16 resize-font
17 vtwheel
18 ];
19 };
20}
21```
22
23If the `configure` function returns an attrset without the `plugins` attribute, `availablePlugins` will be used automatically.
24
25In order to add plugins but also keep all default plugins installed, it is possible to use the following method:
26
27```nix
28rxvt-unicode.override {
29 configure =
30 { availablePlugins, ... }:
31 {
32 plugins = (builtins.attrValues availablePlugins) ++ [ custom-plugin ];
33 };
34}
35```
36
37To get a list of all the plugins available, open the Nix REPL and run
38
39```ShellSession
40$ nix repl
41:l <nixpkgs>
42map (p: p.name) pkgs.rxvt-unicode.plugins
43```
44
45Alternatively, if your shell is bash or zsh and have completion enabled, type `nixpkgs.rxvt-unicode.plugins.<tab>`.
46
47In addition to `plugins` the options `extraDeps` and `perlDeps` can be used to install extra packages. `extraDeps` can be used, for example, to provide `xsel` (a clipboard manager) to the clipboard plugin, without installing it globally:
48
49```nix
50rxvt-unicode.override {
51 configure =
52 { availablePlugins, ... }:
53 {
54 pluginsDeps = [ xsel ];
55 };
56}
57```
58
59`perlDeps` is a handy way to provide Perl packages to your custom plugins (in `$HOME/.urxvt/ext`). For example, if you need `AnyEvent` you can do:
60
61```nix
62rxvt-unicode.override {
63 configure =
64 { availablePlugins, ... }:
65 {
66 perlDeps = with perlPackages; [ AnyEvent ];
67 };
68}
69```
70
71## Packaging urxvt plugins {#sec-urxvt-pkg}
72
73Urxvt plugins reside in `pkgs/applications/misc/rxvt-unicode-plugins`. To add a new plugin, create an expression in a subdirectory and add the package to the set in `pkgs/applications/misc/rxvt-unicode-plugins/default.nix`.
74
75A plugin can be any kind of derivation; the only requirement is that it should always install perl scripts in `$out/lib/urxvt/perl`. Look for existing plugins for examples.
76
77If the plugin is itself a Perl package that needs to be imported from other plugins or scripts, add the following passthrough:
78
79```nix
80{ passthru.perlPackages = [ "self" ]; }
81```
82
83This will make the urxvt wrapper pick up the dependency and set up the Perl path accordingly.