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 = { availablePlugins, ... }: {
12 plugins = with availablePlugins; [ perls resize-font vtwheel ];
13 };
14}
15```
16
17If the `configure` function returns an attrset without the `plugins` attribute, `availablePlugins` will be used automatically.
18
19In order to add plugins but also keep all default plugins installed, it is possible to use the following method:
20
21```nix
22rxvt-unicode.override {
23 configure = { availablePlugins, ... }: {
24 plugins = (builtins.attrValues availablePlugins) ++ [ custom-plugin ];
25 };
26}
27```
28
29To get a list of all the plugins available, open the Nix REPL and run
30
31```ShellSession
32$ nix repl
33:l <nixpkgs>
34map (p: p.name) pkgs.rxvt-unicode.plugins
35```
36
37Alternatively, if your shell is bash or zsh and have completion enabled, type `nixpkgs.rxvt-unicode.plugins.<tab>`.
38
39In 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:
40
41```nix
42rxvt-unicode.override {
43 configure = { availablePlugins, ... }: {
44 pluginsDeps = [ xsel ];
45 };
46}
47```
48
49`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:
50
51```nix
52rxvt-unicode.override {
53 configure = { availablePlugins, ... }: {
54 perlDeps = with perlPackages; [ AnyEvent ];
55 };
56}
57```
58
59## Packaging urxvt plugins {#sec-urxvt-pkg}
60
61Urxvt plugins resides 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`.
62
63A 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.
64
65If the plugin is itself a Perl package that needs to be imported from other plugins or scripts, add the following passthrough:
66
67```nix
68passthru.perlPackages = [ "self" ];
69```
70
71This will make the urxvt wrapper pick up the dependency and set up the Perl path accordingly.