diff options
author | Maximilian Bosch <maximilian@mbosch.me> | 2018-08-07 15:38:20 +0200 |
---|---|---|
committer | Maximilian Bosch <maximilian@mbosch.me> | 2018-08-07 15:47:02 +0200 |
commit | bd40c92c2c3c862bff59318ea29677dd66de9526 (patch) | |
tree | 5c052f02d8355ac6aee6c161fc39846f57187948 /nixos | |
parent | 39b85451de2daa7927629dbac7b641becffc839e (diff) | |
download | nixlib-bd40c92c2c3c862bff59318ea29677dd66de9526.tar nixlib-bd40c92c2c3c862bff59318ea29677dd66de9526.tar.gz nixlib-bd40c92c2c3c862bff59318ea29677dd66de9526.tar.bz2 nixlib-bd40c92c2c3c862bff59318ea29677dd66de9526.tar.lz nixlib-bd40c92c2c3c862bff59318ea29677dd66de9526.tar.xz nixlib-bd40c92c2c3c862bff59318ea29677dd66de9526.tar.zst nixlib-bd40c92c2c3c862bff59318ea29677dd66de9526.zip |
nixos/oh-my-zsh: add documentation
In the last year `programs.oh-my-zsh` gained more complexity and since the introduction of features like `customPkgs` which builds a `ZSH_CUSTOM` path from a sequence of derivation a documentation may be fairly helpful to make the knowledge how to use the module and how to package new ZSH plugins visible. See https://github.com/NixOS/nixpkgs/pull/43282#issuecomment-410770432
Diffstat (limited to 'nixos')
-rw-r--r-- | nixos/modules/programs/zsh/oh-my-zsh.nix | 2 | ||||
-rw-r--r-- | nixos/modules/programs/zsh/oh-my-zsh.xml | 125 |
2 files changed, 127 insertions, 0 deletions
diff --git a/nixos/modules/programs/zsh/oh-my-zsh.nix b/nixos/modules/programs/zsh/oh-my-zsh.nix index 8435e0eb9f0f..f4df4e983e42 100644 --- a/nixos/modules/programs/zsh/oh-my-zsh.nix +++ b/nixos/modules/programs/zsh/oh-my-zsh.nix @@ -133,4 +133,6 @@ in ]; }; + + meta.doc = ./oh-my-zsh.xml; } diff --git a/nixos/modules/programs/zsh/oh-my-zsh.xml b/nixos/modules/programs/zsh/oh-my-zsh.xml new file mode 100644 index 000000000000..b74da8630ee7 --- /dev/null +++ b/nixos/modules/programs/zsh/oh-my-zsh.xml @@ -0,0 +1,125 @@ +<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><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.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><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.ohMyZsh.custom = "~/path/to/custom/scripts"; +} +</programlisting> +</para></section> + +<section><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.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.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><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> |