blob: 568c2de655766cd94cf45ae191c056797018281d (
plain) (
blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
|
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="module-programs-zsh-ohmyzsh">
<title>Oh my ZSH</title>
<para>
<literal><link xlink:href="https://ohmyz.sh/">oh-my-zsh</link></literal> is a
framework to manage your <link xlink:href="https://www.zsh.org/">ZSH</link>
configuration including completion scripts for several CLI tools or custom
prompt themes.
</para>
<section xml:id="module-programs-oh-my-zsh-usage">
<title>Basic usage</title>
<para>
The module uses the <literal>oh-my-zsh</literal> package with all available
features. The initial setup using Nix expressions is fairly similar to the
configuration format of <literal>oh-my-zsh</literal>.
<programlisting>
{
programs.zsh.ohMyZsh = {
enable = true;
plugins = [ "git" "python" "man" ];
theme = "agnoster";
};
}
</programlisting>
For a detailed explanation of these arguments please refer to the
<link xlink:href="https://github.com/robbyrussell/oh-my-zsh/wiki"><literal>oh-my-zsh</literal>
docs</link>.
</para>
<para>
The expression generates the needed configuration and writes it into your
<literal>/etc/zshrc</literal>.
</para>
</section>
<section xml:id="module-programs-oh-my-zsh-additions">
<title>Custom additions</title>
<para>
Sometimes third-party or custom scripts such as a modified theme may be
needed. <literal>oh-my-zsh</literal> provides the
<link xlink:href="https://github.com/robbyrussell/oh-my-zsh/wiki/Customization#overriding-internals"><literal>ZSH_CUSTOM</literal></link>
environment variable for this which points to a directory with additional
scripts.
</para>
<para>
The module can do this as well:
<programlisting>
{
programs.zsh.ohMyZsh.custom = "~/path/to/custom/scripts";
}
</programlisting>
</para>
</section>
<section xml:id="module-programs-oh-my-zsh-environments">
<title>Custom environments</title>
<para>
There are several extensions for <literal>oh-my-zsh</literal> packaged in
<literal>nixpkgs</literal>. One of them is
<link xlink:href="https://github.com/spwhitt/nix-zsh-completions">nix-zsh-completions</link>
which bundles completion scripts and a plugin for
<literal>oh-my-zsh</literal>.
</para>
<para>
Rather than using a single mutable path for <literal>ZSH_CUSTOM</literal>,
it's also possible to generate this path from a list of Nix packages:
<programlisting>
{ pkgs, ... }:
{
programs.zsh.ohMyZsh.customPkgs = with pkgs; [
pkgs.nix-zsh-completions
# and even more...
];
}
</programlisting>
Internally a single store path will be created using
<literal>buildEnv</literal>. Please refer to the docs of
<link xlink:href="https://nixos.org/nixpkgs/manual/#sec-building-environment"><literal>buildEnv</literal></link>
for further reference.
</para>
<para>
<emphasis>Please keep in mind that this is not compatible with
<literal>programs.zsh.ohMyZsh.custom</literal> as it requires an immutable
store path while <literal>custom</literal> shall remain mutable! An
evaluation failure will be thrown if both <literal>custom</literal> and
<literal>customPkgs</literal> are set.</emphasis>
</para>
</section>
<section xml:id="module-programs-oh-my-zsh-packaging-customizations">
<title>Package your own customizations</title>
<para>
If third-party customizations (e.g. new themes) are supposed to be added to
<literal>oh-my-zsh</literal> there are several pitfalls to keep in mind:
</para>
<itemizedlist>
<listitem>
<para>
To comply with the default structure of <literal>ZSH</literal> the entire
output needs to be written to <literal>$out/share/zsh.</literal>
</para>
</listitem>
<listitem>
<para>
Completion scripts are supposed to be stored at
<literal>$out/share/zsh/site-functions</literal>. This directory is part
of the
<literal><link xlink:href="http://zsh.sourceforge.net/Doc/Release/Functions.html">fpath</link></literal>
and the package should be compatible with pure <literal>ZSH</literal>
setups. The module will automatically link the contents of
<literal>site-functions</literal> to completions directory in the proper
store path.
</para>
</listitem>
<listitem>
<para>
The <literal>plugins</literal> directory needs the structure
<literal>pluginname/pluginname.plugin.zsh</literal> as structured in the
<link xlink:href="https://github.com/robbyrussell/oh-my-zsh/tree/91b771914bc7c43dd7c7a43b586c5de2c225ceb7/plugins">upstream
repo.</link>
</para>
</listitem>
</itemizedlist>
<para>
A derivation for <literal>oh-my-zsh</literal> may look like this:
<programlisting>
{ stdenv, fetchFromGitHub }:
stdenv.mkDerivation rec {
name = "exemplary-zsh-customization-${version}";
version = "1.0.0";
src = fetchFromGitHub {
# path to the upstream repository
};
dontBuild = true;
installPhase = ''
mkdir -p $out/share/zsh/site-functions
cp {themes,plugins} $out/share/zsh
cp completions $out/share/zsh/site-functions
'';
}
</programlisting>
</para>
</section>
</chapter>
|