blob: c5202d818c9ff80542f3133250427a87bc8f778d (
plain)
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
|
<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>
|
