mirror of
https://github.com/NixOS/nixpkgs.git
synced 2024-12-13 17:23:08 +00:00
2a911454d3
Motivation: There is a thriving plugin ecosystem for Kakoune now, and it is nice to add these in our Nix configurations. This was modeled on neovim's plugins. parinfer-rust is useable both standalone and as a Kakoune plugin, so the plugin file inherits the same definition as pkgs. I'll make PRs for other plugins if this gets accepted. [Here](https://github.com/eraserhd/nixpkgs/tree/kak-ansi)'s a tested branch for the `kak-ansi` plugin.
591 lines
22 KiB
XML
591 lines
22 KiB
XML
<chapter xmlns="http://docbook.org/ns/docbook"
|
||
xmlns:xlink="http://www.w3.org/1999/xlink"
|
||
xml:id="chap-package-notes">
|
||
<title>Package Notes</title>
|
||
<para>
|
||
This chapter contains information about how to use and maintain the Nix
|
||
expressions for a number of specific packages, such as the Linux kernel or
|
||
X.org.
|
||
</para>
|
||
<!--============================================================-->
|
||
<section xml:id="sec-linux-kernel">
|
||
<title>Linux kernel</title>
|
||
|
||
<para>
|
||
The Nix expressions to build the Linux kernel are in
|
||
<link
|
||
xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/os-specific/linux/kernel"><filename>pkgs/os-specific/linux/kernel</filename></link>.
|
||
</para>
|
||
|
||
<para>
|
||
The function that builds the kernel has an argument
|
||
<varname>kernelPatches</varname> which should be a list of <literal>{name,
|
||
patch, extraConfig}</literal> attribute sets, where <varname>name</varname>
|
||
is the name of the patch (which is included in the kernel’s
|
||
<varname>meta.description</varname> attribute), <varname>patch</varname> is
|
||
the patch itself (possibly compressed), and <varname>extraConfig</varname>
|
||
(optional) is a string specifying extra options to be concatenated to the
|
||
kernel configuration file (<filename>.config</filename>).
|
||
</para>
|
||
|
||
<para>
|
||
The kernel derivation exports an attribute <varname>features</varname>
|
||
specifying whether optional functionality is or isn’t enabled. This is
|
||
used in NixOS to implement kernel-specific behaviour. For instance, if the
|
||
kernel has the <varname>iwlwifi</varname> feature (i.e. has built-in support
|
||
for Intel wireless chipsets), then NixOS doesn’t have to build the
|
||
external <varname>iwlwifi</varname> package:
|
||
<programlisting>
|
||
modulesTree = [kernel]
|
||
++ pkgs.lib.optional (!kernel.features ? iwlwifi) kernelPackages.iwlwifi
|
||
++ ...;
|
||
</programlisting>
|
||
</para>
|
||
|
||
<para>
|
||
How to add a new (major) version of the Linux kernel to Nixpkgs:
|
||
<orderedlist>
|
||
<listitem>
|
||
<para>
|
||
Copy the old Nix expression (e.g. <filename>linux-2.6.21.nix</filename>)
|
||
to the new one (e.g. <filename>linux-2.6.22.nix</filename>) and update
|
||
it.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
Add the new kernel to <filename>all-packages.nix</filename> (e.g., create
|
||
an attribute <varname>kernel_2_6_22</varname>).
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
Now we’re going to update the kernel configuration. First unpack the
|
||
kernel. Then for each supported platform (<literal>i686</literal>,
|
||
<literal>x86_64</literal>, <literal>uml</literal>) do the following:
|
||
<orderedlist>
|
||
<listitem>
|
||
<para>
|
||
Make an copy from the old config (e.g.
|
||
<filename>config-2.6.21-i686-smp</filename>) to the new one (e.g.
|
||
<filename>config-2.6.22-i686-smp</filename>).
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
Copy the config file for this platform (e.g.
|
||
<filename>config-2.6.22-i686-smp</filename>) to
|
||
<filename>.config</filename> in the kernel source tree.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
Run <literal>make oldconfig
|
||
ARCH=<replaceable>{i386,x86_64,um}</replaceable></literal> and answer
|
||
all questions. (For the uml configuration, also add
|
||
<literal>SHELL=bash</literal>.) Make sure to keep the configuration
|
||
consistent between platforms (i.e. don’t enable some feature on
|
||
<literal>i686</literal> and disable it on <literal>x86_64</literal>).
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
If needed you can also run <literal>make menuconfig</literal>:
|
||
<screen>
|
||
<prompt>$ </prompt>nix-env -i ncurses
|
||
<prompt>$ </prompt>export NIX_CFLAGS_LINK=-lncurses
|
||
<prompt>$ </prompt>make menuconfig ARCH=<replaceable>arch</replaceable></screen>
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
Copy <filename>.config</filename> over the new config file (e.g.
|
||
<filename>config-2.6.22-i686-smp</filename>).
|
||
</para>
|
||
</listitem>
|
||
</orderedlist>
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
Test building the kernel: <literal>nix-build -A kernel_2_6_22</literal>.
|
||
If it compiles, ship it! For extra credit, try booting NixOS with it.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
It may be that the new kernel requires updating the external kernel
|
||
modules and kernel-dependent packages listed in the
|
||
<varname>linuxPackagesFor</varname> function in
|
||
<filename>all-packages.nix</filename> (such as the NVIDIA drivers, AUFS,
|
||
etc.). If the updated packages aren’t backwards compatible with older
|
||
kernels, you may need to keep the older versions around.
|
||
</para>
|
||
</listitem>
|
||
</orderedlist>
|
||
</para>
|
||
</section>
|
||
<!--============================================================-->
|
||
<section xml:id="sec-xorg">
|
||
<title>X.org</title>
|
||
|
||
<para>
|
||
The Nix expressions for the X.org packages reside in
|
||
<filename>pkgs/servers/x11/xorg/default.nix</filename>. This file is
|
||
automatically generated from lists of tarballs in an X.org release. As such
|
||
it should not be modified directly; rather, you should modify the lists, the
|
||
generator script or the file
|
||
<filename>pkgs/servers/x11/xorg/overrides.nix</filename>, in which you can
|
||
override or add to the derivations produced by the generator.
|
||
</para>
|
||
|
||
<para>
|
||
The generator is invoked as follows:
|
||
<screen>
|
||
<prompt>$ </prompt>cd pkgs/servers/x11/xorg
|
||
<prompt>$ </prompt>cat tarballs-7.5.list extra.list old.list \
|
||
| perl ./generate-expr-from-tarballs.pl
|
||
</screen>
|
||
For each of the tarballs in the <filename>.list</filename> files, the script
|
||
downloads it, unpacks it, and searches its <filename>configure.ac</filename>
|
||
and <filename>*.pc.in</filename> files for dependencies. This information is
|
||
used to generate <filename>default.nix</filename>. The generator caches
|
||
downloaded tarballs between runs. Pay close attention to the <literal>NOT
|
||
FOUND: <replaceable>name</replaceable></literal> messages at the end of the
|
||
run, since they may indicate missing dependencies. (Some might be optional
|
||
dependencies, however.)
|
||
</para>
|
||
|
||
<para>
|
||
A file like <filename>tarballs-7.5.list</filename> contains all tarballs in
|
||
a X.org release. It can be generated like this:
|
||
<screen>
|
||
<prompt>$ </prompt>export i="mirror://xorg/X11R7.4/src/everything/"
|
||
<prompt>$ </prompt>cat $(PRINT_PATH=1 nix-prefetch-url $i | tail -n 1) \
|
||
| perl -e 'while (<>) { if (/(href|HREF)="([^"]*.bz2)"/) { print "$ENV{'i'}$2\n"; }; }' \
|
||
| sort > tarballs-7.4.list
|
||
</screen>
|
||
<filename>extra.list</filename> contains libraries that aren’t part of
|
||
X.org proper, but are closely related to it, such as
|
||
<literal>libxcb</literal>. <filename>old.list</filename> contains some
|
||
packages that were removed from X.org, but are still needed by some people
|
||
or by other packages (such as <varname>imake</varname>).
|
||
</para>
|
||
|
||
<para>
|
||
If the expression for a package requires derivation attributes that the
|
||
generator cannot figure out automatically (say, <varname>patches</varname>
|
||
or a <varname>postInstall</varname> hook), you should modify
|
||
<filename>pkgs/servers/x11/xorg/overrides.nix</filename>.
|
||
</para>
|
||
</section>
|
||
<!--============================================================-->
|
||
<!--
|
||
<section xml:id="sec-package-notes-gnome">
|
||
<title>Gnome</title>
|
||
<para>* Expression is auto-generated</para>
|
||
<para>* How to update</para>
|
||
</section>
|
||
-->
|
||
<!--============================================================-->
|
||
<!--
|
||
<section xml:id="sec-package-notes-gcc">
|
||
<title>GCC</title>
|
||
<para>…</para>
|
||
</section>
|
||
-->
|
||
<!--============================================================-->
|
||
<section xml:id="sec-eclipse">
|
||
<title>Eclipse</title>
|
||
|
||
<para>
|
||
The Nix expressions related to the Eclipse platform and IDE are in
|
||
<link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/editors/eclipse"><filename>pkgs/applications/editors/eclipse</filename></link>.
|
||
</para>
|
||
|
||
<para>
|
||
Nixpkgs provides a number of packages that will install Eclipse in its
|
||
various forms. These range from the bare-bones Eclipse Platform to the more
|
||
fully featured Eclipse SDK or Scala-IDE packages and multiple version are
|
||
often available. It is possible to list available Eclipse packages by
|
||
issuing the command:
|
||
<screen>
|
||
<prompt>$ </prompt>nix-env -f '<nixpkgs>' -qaP -A eclipses --description
|
||
</screen>
|
||
Once an Eclipse variant is installed it can be run using the
|
||
<command>eclipse</command> command, as expected. From within Eclipse it is
|
||
then possible to install plugins in the usual manner by either manually
|
||
specifying an Eclipse update site or by installing the Marketplace Client
|
||
plugin and using it to discover and install other plugins. This installation
|
||
method provides an Eclipse installation that closely resemble a manually
|
||
installed Eclipse.
|
||
</para>
|
||
|
||
<para>
|
||
If you prefer to install plugins in a more declarative manner then Nixpkgs
|
||
also offer a number of Eclipse plugins that can be installed in an
|
||
<emphasis>Eclipse environment</emphasis>. This type of environment is
|
||
created using the function <varname>eclipseWithPlugins</varname> found
|
||
inside the <varname>nixpkgs.eclipses</varname> attribute set. This function
|
||
takes as argument <literal>{ eclipse, plugins ? [], jvmArgs ? [] }</literal>
|
||
where <varname>eclipse</varname> is a one of the Eclipse packages described
|
||
above, <varname>plugins</varname> is a list of plugin derivations, and
|
||
<varname>jvmArgs</varname> is a list of arguments given to the JVM running
|
||
the Eclipse. For example, say you wish to install the latest Eclipse
|
||
Platform with the popular Eclipse Color Theme plugin and also allow Eclipse
|
||
to use more RAM. You could then add
|
||
<screen>
|
||
packageOverrides = pkgs: {
|
||
myEclipse = with pkgs.eclipses; eclipseWithPlugins {
|
||
eclipse = eclipse-platform;
|
||
jvmArgs = [ "-Xmx2048m" ];
|
||
plugins = [ plugins.color-theme ];
|
||
};
|
||
}
|
||
</screen>
|
||
to your Nixpkgs configuration
|
||
(<filename>~/.config/nixpkgs/config.nix</filename>) and install it by
|
||
running <command>nix-env -f '<nixpkgs>' -iA myEclipse</command> and
|
||
afterward run Eclipse as usual. It is possible to find out which plugins are
|
||
available for installation using <varname>eclipseWithPlugins</varname> by
|
||
running
|
||
<screen>
|
||
<prompt>$ </prompt>nix-env -f '<nixpkgs>' -qaP -A eclipses.plugins --description
|
||
</screen>
|
||
</para>
|
||
|
||
<para>
|
||
If there is a need to install plugins that are not available in Nixpkgs then
|
||
it may be possible to define these plugins outside Nixpkgs using the
|
||
<varname>buildEclipseUpdateSite</varname> and
|
||
<varname>buildEclipsePlugin</varname> functions found in the
|
||
<varname>nixpkgs.eclipses.plugins</varname> attribute set. Use the
|
||
<varname>buildEclipseUpdateSite</varname> function to install a plugin
|
||
distributed as an Eclipse update site. This function takes <literal>{ name,
|
||
src }</literal> as argument where <literal>src</literal> indicates the
|
||
Eclipse update site archive. All Eclipse features and plugins within the
|
||
downloaded update site will be installed. When an update site archive is not
|
||
available then the <varname>buildEclipsePlugin</varname> function can be
|
||
used to install a plugin that consists of a pair of feature and plugin JARs.
|
||
This function takes an argument <literal>{ name, srcFeature, srcPlugin
|
||
}</literal> where <literal>srcFeature</literal> and
|
||
<literal>srcPlugin</literal> are the feature and plugin JARs, respectively.
|
||
</para>
|
||
|
||
<para>
|
||
Expanding the previous example with two plugins using the above functions we
|
||
have
|
||
<screen>
|
||
packageOverrides = pkgs: {
|
||
myEclipse = with pkgs.eclipses; eclipseWithPlugins {
|
||
eclipse = eclipse-platform;
|
||
jvmArgs = [ "-Xmx2048m" ];
|
||
plugins = [
|
||
plugins.color-theme
|
||
(plugins.buildEclipsePlugin {
|
||
name = "myplugin1-1.0";
|
||
srcFeature = fetchurl {
|
||
url = "http://…/features/myplugin1.jar";
|
||
sha256 = "123…";
|
||
};
|
||
srcPlugin = fetchurl {
|
||
url = "http://…/plugins/myplugin1.jar";
|
||
sha256 = "123…";
|
||
};
|
||
});
|
||
(plugins.buildEclipseUpdateSite {
|
||
name = "myplugin2-1.0";
|
||
src = fetchurl {
|
||
stripRoot = false;
|
||
url = "http://…/myplugin2.zip";
|
||
sha256 = "123…";
|
||
};
|
||
});
|
||
];
|
||
};
|
||
}
|
||
</screen>
|
||
</para>
|
||
</section>
|
||
<section xml:id="sec-elm">
|
||
<title>Elm</title>
|
||
|
||
<para>
|
||
To start a development environment do <command>nix-shell -p elmPackages.elm elmPackages.elm-format</command>
|
||
</para>
|
||
|
||
<para>
|
||
To update Elm compiler, see
|
||
<filename>nixpkgs/pkgs/development/compilers/elm/README.md</filename>.
|
||
</para>
|
||
|
||
<para>
|
||
To package Elm applications,
|
||
<link xlink:href="https://github.com/hercules-ci/elm2nix#elm2nix">read about
|
||
elm2nix</link>.
|
||
</para>
|
||
</section>
|
||
<section xml:id="sec-kakoune">
|
||
<title>Kakoune</title>
|
||
|
||
<para>
|
||
Kakoune can be built to autoload plugins:
|
||
<programlisting>(kakoune.override {
|
||
configure = {
|
||
plugins = with pkgs.kakounePlugins; [ parinfer-rust ];
|
||
};
|
||
})</programlisting>
|
||
</para>
|
||
</section>
|
||
<section xml:id="sec-shell-helpers">
|
||
<title>Interactive shell helpers</title>
|
||
|
||
<para>
|
||
Some packages provide the shell integration to be more useful. But unlike
|
||
other systems, nix doesn't have a standard share directory location. This is
|
||
why a bunch <command>PACKAGE-share</command> scripts are shipped that print
|
||
the location of the corresponding shared folder. Current list of such
|
||
packages is as following:
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para>
|
||
<literal>autojump</literal>: <command>autojump-share</command>
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
<literal>fzf</literal>: <command>fzf-share</command>
|
||
</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
E.g. <literal>autojump</literal> can then used in the .bashrc like this:
|
||
<screen>
|
||
source "$(autojump-share)/autojump.bash"
|
||
</screen>
|
||
</para>
|
||
</section>
|
||
<section xml:id="sec-weechat">
|
||
<title>Weechat</title>
|
||
|
||
<para>
|
||
Weechat can be configured to include your choice of plugins, reducing its
|
||
closure size from the default configuration which includes all available
|
||
plugins. To make use of this functionality, install an expression that
|
||
overrides its configuration such as
|
||
<programlisting>weechat.override {configure = {availablePlugins, ...}: {
|
||
plugins = with availablePlugins; [ python perl ];
|
||
}
|
||
}</programlisting>
|
||
If the <literal>configure</literal> function returns an attrset without the
|
||
<literal>plugins</literal> attribute, <literal>availablePlugins</literal>
|
||
will be used automatically.
|
||
</para>
|
||
|
||
<para>
|
||
The plugins currently available are <literal>python</literal>,
|
||
<literal>perl</literal>, <literal>ruby</literal>, <literal>guile</literal>,
|
||
<literal>tcl</literal> and <literal>lua</literal>.
|
||
</para>
|
||
|
||
<para>
|
||
The python and perl plugins allows the addition of extra libraries. For
|
||
instance, the <literal>inotify.py</literal> script in weechat-scripts
|
||
requires D-Bus or libnotify, and the <literal>fish.py</literal> script
|
||
requires pycrypto. To use these scripts, use the plugin's
|
||
<literal>withPackages</literal> attribute:
|
||
<programlisting>weechat.override { configure = {availablePlugins, ...}: {
|
||
plugins = with availablePlugins; [
|
||
(python.withPackages (ps: with ps; [ pycrypto python-dbus ]))
|
||
];
|
||
};
|
||
}
|
||
</programlisting>
|
||
</para>
|
||
|
||
<para>
|
||
In order to also keep all default plugins installed, it is possible to use
|
||
the following method:
|
||
<programlisting>weechat.override { configure = { availablePlugins, ... }: {
|
||
plugins = builtins.attrValues (availablePlugins // {
|
||
python = availablePlugins.python.withPackages (ps: with ps; [ pycrypto python-dbus ]);
|
||
});
|
||
}; }
|
||
</programlisting>
|
||
</para>
|
||
|
||
<para>
|
||
WeeChat allows to set defaults on startup using the
|
||
<literal>--run-command</literal>. The <literal>configure</literal> method
|
||
can be used to pass commands to the program:
|
||
<programlisting>weechat.override {
|
||
configure = { availablePlugins, ... }: {
|
||
init = ''
|
||
/set foo bar
|
||
/server add freenode chat.freenode.org
|
||
'';
|
||
};
|
||
}</programlisting>
|
||
Further values can be added to the list of commands when running
|
||
<literal>weechat --run-command "your-commands"</literal>.
|
||
</para>
|
||
|
||
<para>
|
||
Additionally it's possible to specify scripts to be loaded when starting
|
||
<literal>weechat</literal>. These will be loaded before the commands from
|
||
<literal>init</literal>:
|
||
<programlisting>weechat.override {
|
||
configure = { availablePlugins, ... }: {
|
||
scripts = with pkgs.weechatScripts; [
|
||
weechat-xmpp weechat-matrix-bridge wee-slack
|
||
];
|
||
init = ''
|
||
/set plugins.var.python.jabber.key "val"
|
||
'':
|
||
};
|
||
}</programlisting>
|
||
</para>
|
||
|
||
<para>
|
||
In <literal>nixpkgs</literal> there's a subpackage which contains
|
||
derivations for WeeChat scripts. Such derivations expect a
|
||
<literal>passthru.scripts</literal> attribute which contains a list of all
|
||
scripts inside the store path. Furthermore all scripts have to live in
|
||
<literal>$out/share</literal>. An exemplary derivation looks like this:
|
||
<programlisting>{ stdenv, fetchurl }:
|
||
|
||
stdenv.mkDerivation {
|
||
name = "exemplary-weechat-script";
|
||
src = fetchurl {
|
||
url = "https://scripts.tld/your-scripts.tar.gz";
|
||
sha256 = "...";
|
||
};
|
||
passthru.scripts = [ "foo.py" "bar.lua" ];
|
||
installPhase = ''
|
||
mkdir $out/share
|
||
cp foo.py $out/share
|
||
cp bar.lua $out/share
|
||
'';
|
||
}</programlisting>
|
||
</para>
|
||
</section>
|
||
<section xml:id="sec-ibus-typing-booster">
|
||
<title>ibus-engines.typing-booster</title>
|
||
|
||
<para>
|
||
This package is an ibus-based completion method to speed up typing.
|
||
</para>
|
||
|
||
<section xml:id="sec-ibus-typing-booster-activate">
|
||
<title>Activating the engine</title>
|
||
|
||
<para>
|
||
IBus needs to be configured accordingly to activate
|
||
<literal>typing-booster</literal>. The configuration depends on the desktop
|
||
manager in use. For detailed instructions, please refer to the
|
||
<link xlink:href="https://mike-fabian.github.io/ibus-typing-booster/documentation.html">upstream
|
||
docs</link>.
|
||
</para>
|
||
|
||
<para>
|
||
On NixOS you need to explicitly enable <literal>ibus</literal> with given
|
||
engines before customizing your desktop to use
|
||
<literal>typing-booster</literal>. This can be achieved using the
|
||
<literal>ibus</literal> module:
|
||
<programlisting>{ pkgs, ... }: {
|
||
i18n.inputMethod = {
|
||
enabled = "ibus";
|
||
ibus.engines = with pkgs.ibus-engines; [ typing-booster ];
|
||
};
|
||
}</programlisting>
|
||
</para>
|
||
</section>
|
||
|
||
<section xml:id="sec-ibus-typing-booster-customize-hunspell">
|
||
<title>Using custom hunspell dictionaries</title>
|
||
|
||
<para>
|
||
The IBus engine is based on <literal>hunspell</literal> to support
|
||
completion in many languages. By default the dictionaries
|
||
<literal>de-de</literal>, <literal>en-us</literal>, <literal>fr-moderne</literal>
|
||
<literal>es-es</literal>, <literal>it-it</literal>,
|
||
<literal>sv-se</literal> and <literal>sv-fi</literal> are in use. To add
|
||
another dictionary, the package can be overridden like this:
|
||
<programlisting>ibus-engines.typing-booster.override {
|
||
langs = [ "de-at" "en-gb" ];
|
||
}</programlisting>
|
||
</para>
|
||
|
||
<para>
|
||
<emphasis>Note: each language passed to <literal>langs</literal> must be an
|
||
attribute name in <literal>pkgs.hunspellDicts</literal>.</emphasis>
|
||
</para>
|
||
</section>
|
||
|
||
<section xml:id="sec-ibus-typing-booster-emoji-picker">
|
||
<title>Built-in emoji picker</title>
|
||
|
||
<para>
|
||
The <literal>ibus-engines.typing-booster</literal> package contains a
|
||
program named <literal>emoji-picker</literal>. To display all emojis
|
||
correctly, a special font such as <literal>noto-fonts-emoji</literal> is
|
||
needed:
|
||
</para>
|
||
|
||
<para>
|
||
On NixOS it can be installed using the following expression:
|
||
<programlisting>{ pkgs, ... }: {
|
||
fonts.fonts = with pkgs; [ noto-fonts-emoji ];
|
||
}</programlisting>
|
||
</para>
|
||
</section>
|
||
</section>
|
||
<section xml:id="sec-nginx">
|
||
<title>Nginx</title>
|
||
|
||
<para>
|
||
<link xlink:href="https://nginx.org/">Nginx</link> is a
|
||
reverse proxy and lightweight webserver.
|
||
</para>
|
||
|
||
<section xml:id="sec-nginx-etag">
|
||
<title>ETags on static files served from the Nix store</title>
|
||
|
||
<para>
|
||
HTTP has a couple different mechanisms for caching to prevent
|
||
clients from having to download the same content repeatedly
|
||
if a resource has not changed since the last time it was requested.
|
||
When nginx is used as a server for static files, it implements
|
||
the caching mechanism based on the
|
||
<link xlink:href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Last-Modified"><literal>Last-Modified</literal></link>
|
||
response header automatically; unfortunately, it works by using
|
||
filesystem timestamps to determine the value of the
|
||
<literal>Last-Modified</literal> header. This doesn't give the
|
||
desired behavior when the file is in the Nix store, because all
|
||
file timestamps are set to 0 (for reasons related to build
|
||
reproducibility).
|
||
</para>
|
||
|
||
<para>
|
||
Fortunately, HTTP supports an alternative (and more effective)
|
||
caching mechanism: the
|
||
<link xlink:href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag"><literal>ETag</literal></link>
|
||
response header. The value of the <literal>ETag</literal> header
|
||
specifies some identifier for the particular content that the
|
||
server is sending (e.g. a hash). When a client makes a second
|
||
request for the same resource, it sends that value back in an
|
||
<literal>If-None-Match</literal> header. If the ETag value is
|
||
unchanged, then the server does not need to resend the content.
|
||
</para>
|
||
|
||
<para>
|
||
As of NixOS 19.09, the nginx package in Nixpkgs is patched such
|
||
that when nginx serves a file out of <filename>/nix/store</filename>,
|
||
the hash in the store path is used as the <literal>ETag</literal>
|
||
header in the HTTP response, thus providing proper caching functionality.
|
||
This happens automatically; you do not need to do modify any
|
||
configuration to get this behavior.
|
||
</para>
|
||
</section>
|
||
</section>
|
||
</chapter>
|