mirror of
https://github.com/NixOS/nixpkgs.git
synced 2024-11-18 15:56:50 +01:00
nixos/oh-my-zsh: convert manual chapter to MD
This commit is contained in:
pennae
parent
eb2e1b04a6
commit
f60e9eac85
3 changed files with 223 additions and 115 deletions
109
nixos/modules/programs/zsh/oh-my-zsh.md
Normal file
109
nixos/modules/programs/zsh/oh-my-zsh.md
Normal file
|
|
@ -0,0 +1,109 @@
|
|||
# Oh my ZSH {#module-programs-zsh-ohmyzsh}
|
||||
|
||||
[`oh-my-zsh`](https://ohmyz.sh/) is a framework to manage your [ZSH](https://www.zsh.org/)
|
||||
configuration including completion scripts for several CLI tools or custom
|
||||
prompt themes.
|
||||
|
||||
## Basic usage {#module-programs-oh-my-zsh-usage}
|
||||
|
||||
The module uses the `oh-my-zsh` package with all available
|
||||
features. The initial setup using Nix expressions is fairly similar to the
|
||||
configuration format of `oh-my-zsh`.
|
||||
```
|
||||
{
|
||||
programs.zsh.ohMyZsh = {
|
||||
enable = true;
|
||||
plugins = [ "git" "python" "man" ];
|
||||
theme = "agnoster";
|
||||
};
|
||||
}
|
||||
```
|
||||
For a detailed explanation of these arguments please refer to the
|
||||
[`oh-my-zsh` docs](https://github.com/robbyrussell/oh-my-zsh/wiki).
|
||||
|
||||
The expression generates the needed configuration and writes it into your
|
||||
`/etc/zshrc`.
|
||||
|
||||
## Custom additions {#module-programs-oh-my-zsh-additions}
|
||||
|
||||
Sometimes third-party or custom scripts such as a modified theme may be
|
||||
needed. `oh-my-zsh` provides the
|
||||
[`ZSH_CUSTOM`](https://github.com/robbyrussell/oh-my-zsh/wiki/Customization#overriding-internals)
|
||||
environment variable for this which points to a directory with additional
|
||||
scripts.
|
||||
|
||||
The module can do this as well:
|
||||
```
|
||||
{
|
||||
programs.zsh.ohMyZsh.custom = "~/path/to/custom/scripts";
|
||||
}
|
||||
```
|
||||
|
||||
## Custom environments {#module-programs-oh-my-zsh-environments}
|
||||
|
||||
There are several extensions for `oh-my-zsh` packaged in
|
||||
`nixpkgs`. One of them is
|
||||
[nix-zsh-completions](https://github.com/spwhitt/nix-zsh-completions)
|
||||
which bundles completion scripts and a plugin for `oh-my-zsh`.
|
||||
|
||||
Rather than using a single mutable path for `ZSH_CUSTOM`,
|
||||
it's also possible to generate this path from a list of Nix packages:
|
||||
```
|
||||
{ pkgs, ... }:
|
||||
{
|
||||
programs.zsh.ohMyZsh.customPkgs = [
|
||||
pkgs.nix-zsh-completions
|
||||
# and even more...
|
||||
];
|
||||
}
|
||||
```
|
||||
Internally a single store path will be created using
|
||||
`buildEnv`. Please refer to the docs of
|
||||
[`buildEnv`](https://nixos.org/nixpkgs/manual/#sec-building-environment)
|
||||
for further reference.
|
||||
|
||||
*Please keep in mind that this is not compatible with
|
||||
`programs.zsh.ohMyZsh.custom` as it requires an immutable
|
||||
store path while `custom` shall remain mutable! An
|
||||
evaluation failure will be thrown if both `custom` and
|
||||
`customPkgs` are set.*
|
||||
|
||||
## Package your own customizations {#module-programs-oh-my-zsh-packaging-customizations}
|
||||
|
||||
If third-party customizations (e.g. new themes) are supposed to be added to
|
||||
`oh-my-zsh` there are several pitfalls to keep in mind:
|
||||
|
||||
- To comply with the default structure of `ZSH` the entire
|
||||
output needs to be written to `$out/share/zsh.`
|
||||
|
||||
- Completion scripts are supposed to be stored at
|
||||
`$out/share/zsh/site-functions`. This directory is part of the
|
||||
[`fpath`](http://zsh.sourceforge.net/Doc/Release/Functions.html)
|
||||
and the package should be compatible with pure `ZSH`
|
||||
setups. The module will automatically link the contents of
|
||||
`site-functions` to completions directory in the proper
|
||||
store path.
|
||||
|
||||
- The `plugins` directory needs the structure
|
||||
`pluginname/pluginname.plugin.zsh` as structured in the
|
||||
[upstream repo.](https://github.com/robbyrussell/oh-my-zsh/tree/91b771914bc7c43dd7c7a43b586c5de2c225ceb7/plugins)
|
||||
|
||||
A derivation for `oh-my-zsh` may look like this:
|
||||
```
|
||||
{ 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
|
||||
'';
|
||||
}
|
||||
```
|
||||
|
|
@ -142,5 +142,7 @@ in
|
|||
|
||||
};
|
||||
|
||||
# Don't edit the docbook xml directly, edit the md and generate it:
|
||||
# `pandoc oh-my-zsh.md -t docbook --top-level-division=chapter --extract-media=media -f markdown-smart --lua-filter ../../../../doc/build-aux/pandoc-filters/myst-reader/roles.lua --lua-filter ../../../../doc/build-aux/pandoc-filters/docbook-writer/rst-roles.lua > oh-my-zsh.xml`
|
||||
meta.doc = ./oh-my-zsh.xml;
|
||||
}
|
||||
|
|
|
|||
|
|
@ -1,76 +1,72 @@
|
|||
<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>
|
||||
<link xlink:href="https://ohmyz.sh/"><literal>oh-my-zsh</literal></link> 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>
|
||||
|
||||
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="module-programs-zsh-ohmyzsh">
|
||||
<title>Oh my ZSH</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>
|
||||
<link xlink:href="https://ohmyz.sh/"><literal>oh-my-zsh</literal></link>
|
||||
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>.
|
||||
</para>
|
||||
<programlisting>
|
||||
{
|
||||
programs.zsh.ohMyZsh = {
|
||||
enable = true;
|
||||
plugins = [ "git" "python" "man" ];
|
||||
theme = "agnoster";
|
||||
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>
|
||||
<para>
|
||||
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:
|
||||
</para>
|
||||
<programlisting>
|
||||
{
|
||||
programs.zsh.ohMyZsh.custom = "~/path/to/custom/scripts";
|
||||
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>
|
||||
</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:
|
||||
</para>
|
||||
<programlisting>
|
||||
{ pkgs, ... }:
|
||||
{
|
||||
programs.zsh.ohMyZsh.customPkgs = [
|
||||
|
|
@ -79,65 +75,67 @@
|
|||
];
|
||||
}
|
||||
</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>
|
||||
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>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
Completion scripts are supposed to be stored at
|
||||
<literal>$out/share/zsh/site-functions</literal>. This directory is part
|
||||
of the
|
||||
<link xlink:href="http://zsh.sourceforge.net/Doc/Release/Functions.html"><literal>fpath</literal></link>
|
||||
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.
|
||||
<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>
|
||||
</listitem>
|
||||
<listitem>
|
||||
</section>
|
||||
<section xml:id="module-programs-oh-my-zsh-packaging-customizations">
|
||||
<title>Package your own customizations</title>
|
||||
<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>
|
||||
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>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
|
||||
<para>
|
||||
A derivation for <literal>oh-my-zsh</literal> may look like this:
|
||||
<programlisting>
|
||||
<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
|
||||
<link xlink:href="http://zsh.sourceforge.net/Doc/Release/Functions.html"><literal>fpath</literal></link>
|
||||
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:
|
||||
</para>
|
||||
<programlisting>
|
||||
{ stdenv, fetchFromGitHub }:
|
||||
|
||||
stdenv.mkDerivation rec {
|
||||
name = "exemplary-zsh-customization-${version}";
|
||||
version = "1.0.0";
|
||||
name = "exemplary-zsh-customization-${version}";
|
||||
version = "1.0.0";
|
||||
src = fetchFromGitHub {
|
||||
# path to the upstream repository
|
||||
};
|
||||
|
|
@ -150,6 +148,5 @@ stdenv.mkDerivation rec {
|
|||
'';
|
||||
}
|
||||
</programlisting>
|
||||
</para>
|
||||
</section>
|
||||
</section>
|
||||
</chapter>
|
||||
|
|
|
|||
Loading…
Reference in a new issue