nixos/modules/programs/zsh/oh-my-zsh.xml

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