JakeHillion/nixpkgs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge pull request #66147 from worldofpeace/meson-ninja-docs

Browse Source 
doc/stdenv: document meson variables
This commit is contained in:
worldofpeace 2019-09-17 21:30:36 -04:00 committed by GitHub
commit 4eaa8a815c
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
11 changed files with 456 additions and 279 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

40
doc/cross-compilation.xml
View File

@ -485,10 +485,10 @@ nix-build <nixpkgs> --arg crossSystem '{ config = "<arch>-<os>
<xref <xref
linkend="ssec-cross-dependency-categorization"/> are specified as linkend="ssec-cross-dependency-categorization"/> are specified as
lists of derivations given to <varname>mkDerivation</varname>, as lists of derivations given to <varname>mkDerivation</varname>, as
documented in <xref linkend="ssec-stdenv-dependencies"/>. In short, documented in <xref linkend="ssec-stdenv-dependencies"/>. In short, each
each list of dependencies for "host → target" of "foo → bar" is called list of dependencies for "host → target" of "foo → bar" is called
<varname>depsFooBar</varname>, with exceptions for backwards <varname>depsFooBar</varname>, with exceptions for backwards compatibility
compatibility that <varname>depsBuildHost</varname> is instead called that <varname>depsBuildHost</varname> is instead called
<varname>nativeBuildInputs</varname> and <varname>depsHostTarget</varname> <varname>nativeBuildInputs</varname> and <varname>depsHostTarget</varname>
is instead called <varname>buildInputs</varname>. Nixpkgs is now structured is instead called <varname>buildInputs</varname>. Nixpkgs is now structured
so that each <varname>depsFooBar</varname> is automatically taken from so that each <varname>depsFooBar</varname> is automatically taken from
@ -507,9 +507,8 @@ nix-build &lt;nixpkgs&gt; --arg crossSystem '{ config = "&lt;arch&gt;-&lt;os&gt;
<varname>buildPackages</varname>, <varname>pkgs</varname>, and <varname>buildPackages</varname>, <varname>pkgs</varname>, and
<varname>targetPackages</varname>. Those are now redefined as aliases to <varname>targetPackages</varname>. Those are now redefined as aliases to
<varname>pkgsBuildHost</varname>, <varname>pkgsHostTarget</varname>, and <varname>pkgsBuildHost</varname>, <varname>pkgsHostTarget</varname>, and
<varname>pkgsTargetTarget</varname>. It is acceptable, even <varname>pkgsTargetTarget</varname>. It is acceptable, even recommended, to
recommended, to use them for libraries to show that the host platform is use them for libraries to show that the host platform is irrelevant.
irrelevant.
</para> </para>
<para> <para>
@ -581,14 +580,15 @@ nix-build &lt;nixpkgs&gt; --arg crossSystem '{ config = "&lt;arch&gt;-&lt;os&gt;
<varname>pkgsHostTarget</varname> refers to the current one, and <varname>pkgsHostTarget</varname> refers to the current one, and
<varname>pkgsTargetTarget</varname> refers to the next one. When there is <varname>pkgsTargetTarget</varname> refers to the next one. When there is
no previous or next stage, they instead refer to the current stage. Note no previous or next stage, they instead refer to the current stage. Note
how all the invariants regarding the mapping between dependency and depending how all the invariants regarding the mapping between dependency and
packages' build host and target platforms are preserved. depending packages' build host and target platforms are preserved.
<varname>pkgsBuildTarget</varname> and <varname>pkgsHostHost</varname> are <varname>pkgsBuildTarget</varname> and <varname>pkgsHostHost</varname> are
more complex in that the stage fitting the requirements isn't always a more complex in that the stage fitting the requirements isn't always a
fixed chain of "prevs" and "nexts" away (modulo the "saturating" fixed chain of "prevs" and "nexts" away (modulo the "saturating"
self-references at the ends). We just special case each instead. All the primary self-references at the ends). We just special case each instead. All the
edges are implemented is in <filename>pkgs/stdenv/booter.nix</filename>, primary edges are implemented is in
and secondarily aliases in <filename>pkgs/top-level/stage.nix</filename>. <filename>pkgs/stdenv/booter.nix</filename>, and secondarily aliases in
<filename>pkgs/top-level/stage.nix</filename>.
</para> </para>
<note> <note>
@ -645,19 +645,19 @@ nix-build &lt;nixpkgs&gt; --arg crossSystem '{ config = "&lt;arch&gt;-&lt;os&gt;
"infinite recursions" / cycles. When only package sets that don't mention "infinite recursions" / cycles. When only package sets that don't mention
target are used, the package set forms a directed acyclic graph. This target are used, the package set forms a directed acyclic graph. This
means that all cycles that exist are confined to one stage. This means means that all cycles that exist are confined to one stage. This means
they are a lot smaller, and easier to follow in the code or a backtrace. It they are a lot smaller, and easier to follow in the code or a backtrace.
also means they are present in native and cross builds alike, and so more It also means they are present in native and cross builds alike, and so
likely to be caught by CI and other users. more likely to be caught by CI and other users.
</para> </para>
<para> <para>
Thirdly, it is because everything target-mentioning only exists to Thirdly, it is because everything target-mentioning only exists to
accommodate compilers with lousy build systems that insist on the compiler accommodate compilers with lousy build systems that insist on the compiler
itself and standard library being built together. Of course that is bad itself and standard library being built together. Of course that is bad
because bigger derivations means longer rebuilds. It is also problematic because because bigger derivations means longer rebuilds. It is also problematic
it tends to make the standard libraries less like other libraries than because it tends to make the standard libraries less like other libraries
they could be, complicating code and build systems alike. Because of the than they could be, complicating code and build systems alike. Because of
other problems, and because of these innate disadvantages, compilers ought the other problems, and because of these innate disadvantages, compilers
to be packaged another way where possible. ought to be packaged another way where possible.
</para> </para>
</note> </note>

34
doc/functions/dockertools.xml
View File

@ -325,10 +325,9 @@ hello latest de2bf4786de6 About a minute ago 25.2MB
</term> </term>
<listitem> <listitem>
<para> <para>
Shell commands to run while building the final layer, without access Shell commands to run while building the final layer, without access to
to most of the layer contents. Changes to this layer are "on top" most of the layer contents. Changes to this layer are "on top" of all the
of all the other layers, so can create additional directories other layers, so can create additional directories and files.
and files.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -493,28 +492,23 @@ pullImage {
</calloutlist> </calloutlist>
<para> <para>
<literal>nix-prefetch-docker</literal> command can be used to get required <literal>nix-prefetch-docker</literal> command can be used to get required
image parameters: image parameters:
<screen> <screen>
<prompt>$ </prompt>nix run nixpkgs.nix-prefetch-docker -c nix-prefetch-docker --image-name mysql --image-tag 5 <prompt>$ </prompt>nix run nixpkgs.nix-prefetch-docker -c nix-prefetch-docker --image-name mysql --image-tag 5
</screen> </screen>
Since a given <varname>imageName</varname> may transparently refer to a
Since a given <varname>imageName</varname> may transparently refer to a manifest list of images which support multiple architectures and/or
manifest list of images which support multiple architectures and/or operating systems, you can supply the <option>--os</option> and
operating systems, you can supply the <option>--os</option> and <option>--arch</option> arguments to specify exactly which image you want.
<option>--arch</option> arguments to specify exactly which image you want. By default it will match the OS and architecture of the host the command is
By default it will match the OS and architecture of the host the command is run on.
run on.
<screen> <screen>
<prompt>$ </prompt>nix-prefetch-docker --image-name mysql --image-tag 5 --arch x86_64 --os linux <prompt>$ </prompt>nix-prefetch-docker --image-name mysql --image-tag 5 --arch x86_64 --os linux
</screen> </screen>
Desired image name and tag can be set using
Desired image name and tag can be set using <option>--final-image-name</option> and <option>--final-image-tag</option>
<option>--final-image-name</option> and <option>--final-image-tag</option> arguments:
arguments:
<screen> <screen>
<prompt>$ </prompt>nix-prefetch-docker --image-name mysql --image-tag 5 --final-image-name eu.gcr.io/my-project/mysql --final-image-tag prod <prompt>$ </prompt>nix-prefetch-docker --image-name mysql --image-tag 5 --final-image-name eu.gcr.io/my-project/mysql --final-image-tag prod
</screen> </screen>

12
doc/functions/ocitools.xml
View File

@ -51,10 +51,10 @@ buildContainer {
<calloutlist> <calloutlist>
<callout arearefs='ex-ociTools-buildContainer-1'> <callout arearefs='ex-ociTools-buildContainer-1'>
<para> <para>
<varname>args</varname> specifies a set of arguments to run inside the container. <varname>args</varname> specifies a set of arguments to run inside the
This is the only required argument for <varname>buildContainer</varname>. container. This is the only required argument for
All referenced packages inside the derivation will be made available <varname>buildContainer</varname>. All referenced packages inside the
inside the container derivation will be made available inside the container
</para> </para>
</callout> </callout>
<callout arearefs='ex-ociTools-buildContainer-2'> <callout arearefs='ex-ociTools-buildContainer-2'>
@ -66,8 +66,8 @@ buildContainer {
</callout> </callout>
<callout arearefs='ex-ociTools-buildContainer-3'> <callout arearefs='ex-ociTools-buildContainer-3'>
<para> <para>
<varname>readonly</varname> makes the container's rootfs read-only if it is set to true. <varname>readonly</varname> makes the container's rootfs read-only if it
The default value is false <literal>false</literal>. is set to true. The default value is false <literal>false</literal>.
</para> </para>
</callout> </callout>
</calloutlist> </calloutlist>

185
doc/languages-frameworks/gnome.xml
View File

@ -5,26 +5,53 @@
<title>Packaging GNOME applications</title> <title>Packaging GNOME applications</title>
<para> <para>
Programs in the GNOME universe are written in various languages but they all use GObject-based libraries like GLib, GTK or GStreamer. These libraries are often modular, relying on looking into certain directories to find their modules. However, due to Nix’s specific file system organization, this will fail without our intervention. Fortunately, the libraries usually allow overriding the directories through environment variables, either natively or thanks to a patch in nixpkgs. <link xlink:href="#fun-wrapProgram">Wrapping</link> the executables to ensure correct paths are available to the application constitutes a significant part of packaging a modern desktop application. In this section, we will describe various modules needed by such applications, environment variables needed to make the modules load, and finally a script that will do the work for us. Programs in the GNOME universe are written in various languages but they all
use GObject-based libraries like GLib, GTK or GStreamer. These libraries are
often modular, relying on looking into certain directories to find their
modules. However, due to Nix’s specific file system organization, this
will fail without our intervention. Fortunately, the libraries usually allow
overriding the directories through environment variables, either natively or
thanks to a patch in nixpkgs.
<link xlink:href="#fun-wrapProgram">Wrapping</link> the executables to
ensure correct paths are available to the application constitutes a
significant part of packaging a modern desktop application. In this section,
we will describe various modules needed by such applications, environment
variables needed to make the modules load, and finally a script that will do
the work for us.
</para> </para>
<section xml:id="ssec-gnome-settings"> <section xml:id="ssec-gnome-settings">
<title>Settings</title> <title>Settings</title>
<para> <para>
<link xlink:href="https://developer.gnome.org/gio/stable/GSettings.html">GSettings</link> API is often used for storing settings. GSettings schemas are required, to know the type and other metadata of the stored values. GLib looks for <filename>glib-2.0/schemas/gschemas.compiled</filename> files inside the directories of <envar>XDG_DATA_DIRS</envar>. <link xlink:href="https://developer.gnome.org/gio/stable/GSettings.html">GSettings</link>
API is often used for storing settings. GSettings schemas are required, to
know the type and other metadata of the stored values. GLib looks for
<filename>glib-2.0/schemas/gschemas.compiled</filename> files inside the
directories of <envar>XDG_DATA_DIRS</envar>.
</para> </para>
<para> <para>
On Linux, GSettings API is implemented using <link xlink:href="https://wiki.gnome.org/Projects/dconf">dconf</link> backend. You will need to add <literal>dconf</literal> GIO module to <envar>GIO_EXTRA_MODULES</envar> variable, otherwise the <literal>memory</literal> backend will be used and the saved settings will not be persistent. On Linux, GSettings API is implemented using
<link xlink:href="https://wiki.gnome.org/Projects/dconf">dconf</link>
backend. You will need to add <literal>dconf</literal> GIO module to
<envar>GIO_EXTRA_MODULES</envar> variable, otherwise the
<literal>memory</literal> backend will be used and the saved settings will
not be persistent.
</para> </para>
<para> <para>
Last you will need the dconf database D-Bus service itself. You can enable it using <option>programs.dconf.enable</option>. Last you will need the dconf database D-Bus service itself. You can enable
it using <option>programs.dconf.enable</option>.
</para> </para>
<para> <para>
Some applications will also require <package>gsettings-desktop-schemas</package> for things like reading proxy configuration or user interface customization. This dependency is often not mentioned by upstream, you should grep for <literal>org.gnome.desktop</literal> and <literal>org.gnome.system</literal> to see if the schemas are needed. Some applications will also require
<package>gsettings-desktop-schemas</package> for things like reading proxy
configuration or user interface customization. This dependency is often not
mentioned by upstream, you should grep for
<literal>org.gnome.desktop</literal> and
<literal>org.gnome.system</literal> to see if the schemas are needed.
</para> </para>
</section> </section>
@ -32,7 +59,16 @@
<title>Icons</title> <title>Icons</title>
<para> <para>
When an application uses icons, an icon theme should be available in <envar>XDG_DATA_DIRS</envar>. The package for the default, icon-less <link xlink:href="https://www.freedesktop.org/wiki/Software/icon-theme/">hicolor-icon-theme</link> contains <link linkend="ssec-gnome-hooks-hicolor-icon-theme">a setup hook</link> that will pick up icon themes from <literal>buildInputs</literal> and pass it to our wrapper. Unfortunately, relying on that would mean every user has to download the theme included in the package expression no matter their preference. For that reason, we leave the installation of icon theme on the user. If you use one of the desktop environments, you probably already have an icon theme installed. When an application uses icons, an icon theme should be available in
<envar>XDG_DATA_DIRS</envar>. The package for the default, icon-less
<link xlink:href="https://www.freedesktop.org/wiki/Software/icon-theme/">hicolor-icon-theme</link>
contains <link linkend="ssec-gnome-hooks-hicolor-icon-theme">a setup
hook</link> that will pick up icon themes from
<literal>buildInputs</literal> and pass it to our wrapper. Unfortunately,
relying on that would mean every user has to download the theme included in
the package expression no matter their preference. For that reason, we
leave the installation of icon theme on the user. If you use one of the
desktop environments, you probably already have an icon theme installed.
</para> </para>
</section> </section>
@ -40,7 +76,12 @@
<title>GTK Themes</title> <title>GTK Themes</title>
<para> <para>
Previously, a GTK theme needed to be in <envar>XDG_DATA_DIRS</envar>. This is no longer necessary for most programs since GTK incorporated Adwaita theme. Some programs (for example, those designed for <link xlink:href="https://elementary.io/docs/human-interface-guidelines#human-interface-guidelines">elementary HIG</link>) might require a special theme like <package>pantheon.elementary-gtk-theme</package>. Previously, a GTK theme needed to be in <envar>XDG_DATA_DIRS</envar>. This
is no longer necessary for most programs since GTK incorporated Adwaita
theme. Some programs (for example, those designed for
<link xlink:href="https://elementary.io/docs/human-interface-guidelines#human-interface-guidelines">elementary
HIG</link>) might require a special theme like
<package>pantheon.elementary-gtk-theme</package>.
</para> </para>
</section> </section>
@ -48,7 +89,10 @@
<title>GObject introspection typelibs</title> <title>GObject introspection typelibs</title>
<para> <para>
<link xlink:href="https://wiki.gnome.org/Projects/GObjectIntrospection">GObject introspection</link> allows applications to use C libraries in other languages easily. It does this through <literal>typelib</literal> files searched in <envar>GI_TYPELIB_PATH</envar>. <link xlink:href="https://wiki.gnome.org/Projects/GObjectIntrospection">GObject
introspection</link> allows applications to use C libraries in other
languages easily. It does this through <literal>typelib</literal> files
searched in <envar>GI_TYPELIB_PATH</envar>.
</para> </para>
</section> </section>
@ -56,7 +100,11 @@
<title>Various plug-ins</title> <title>Various plug-ins</title>
<para> <para>
If your application uses <link xlink:href="https://gstreamer.freedesktop.org/">GStreamer</link> or <link xlink:href="https://wiki.gnome.org/Projects/Grilo">Grilo</link>, you should set <envar>GST_PLUGIN_SYSTEM_PATH_1_0</envar> and <envar>GRL_PLUGIN_PATH</envar>, respectively. If your application uses
<link xlink:href="https://gstreamer.freedesktop.org/">GStreamer</link> or
<link xlink:href="https://wiki.gnome.org/Projects/Grilo">Grilo</link>, you
should set <envar>GST_PLUGIN_SYSTEM_PATH_1_0</envar> and
<envar>GRL_PLUGIN_PATH</envar>, respectively.
</para> </para>
</section> </section>
</section> </section>
@ -65,7 +113,8 @@
<title>Onto <package>wrapGAppsHook</package></title> <title>Onto <package>wrapGAppsHook</package></title>
<para> <para>
Given the requirements above, the package expression would become messy quickly: Given the requirements above, the package expression would become messy
quickly:
<programlisting> <programlisting>
preFixup = '' preFixup = ''
for f in $(find $out/bin/ $out/libexec/ -type f -executable); do for f in $(find $out/bin/ $out/libexec/ -type f -executable); do
@ -79,48 +128,76 @@ preFixup = ''
done done
''; '';
</programlisting> </programlisting>
Fortunately, there is <package>wrapGAppsHook</package>, that does the wrapping for us. In particular, it works in conjunction with other setup hooks that will populate the variable: Fortunately, there is <package>wrapGAppsHook</package>, that does the
wrapping for us. In particular, it works in conjunction with other setup
hooks that will populate the variable:
<itemizedlist> <itemizedlist>
<listitem xml:id="ssec-gnome-hooks-wrapgappshook"> <listitem xml:id="ssec-gnome-hooks-wrapgappshook">
<para> <para>
<package>wrapGAppsHook</package> itself will add the package’s <filename>share</filename> directory to <envar>XDG_DATA_DIRS</envar>. <package>wrapGAppsHook</package> itself will add the package’s
<filename>share</filename> directory to <envar>XDG_DATA_DIRS</envar>.
</para> </para>
</listitem> </listitem>
<listitem xml:id="ssec-gnome-hooks-glib"> <listitem xml:id="ssec-gnome-hooks-glib">
<para> <para>
<package>glib</package> setup hook will populate <envar>GSETTINGS_SCHEMAS_PATH</envar> and then <package>wrapGAppsHook</package> will prepend it to <envar>XDG_DATA_DIRS</envar>. <package>glib</package> setup hook will populate
<envar>GSETTINGS_SCHEMAS_PATH</envar> and then
<package>wrapGAppsHook</package> will prepend it to
<envar>XDG_DATA_DIRS</envar>.
</para> </para>
</listitem> </listitem>
<listitem xml:id="ssec-gnome-hooks-dconf"> <listitem xml:id="ssec-gnome-hooks-dconf">
<para> <para>
<package>gnome3.dconf.lib</package> is a dependency of <package>wrapGAppsHook</package>, which then also adds it to the <envar>GIO_EXTRA_MODULES</envar> variable. <package>gnome3.dconf.lib</package> is a dependency of
<package>wrapGAppsHook</package>, which then also adds it to the
<envar>GIO_EXTRA_MODULES</envar> variable.
</para> </para>
</listitem> </listitem>
<listitem xml:id="ssec-gnome-hooks-hicolor-icon-theme"> <listitem xml:id="ssec-gnome-hooks-hicolor-icon-theme">
<para> <para>
<package>hicolor-icon-theme</package>’s setup hook will add icon themes to <envar>XDG_ICON_DIRS</envar> which is prepended to <envar>XDG_DATA_DIRS</envar> by <package>wrapGAppsHook</package>. <package>hicolor-icon-theme</package>’s setup hook will add icon themes
to <envar>XDG_ICON_DIRS</envar> which is prepended to
<envar>XDG_DATA_DIRS</envar> by <package>wrapGAppsHook</package>.
</para> </para>
</listitem> </listitem>
<listitem xml:id="ssec-gnome-hooks-gobject-introspection"> <listitem xml:id="ssec-gnome-hooks-gobject-introspection">
<para> <para>
<package>gobject-introspection</package> setup hook populates <envar>GI_TYPELIB_PATH</envar> variable with <filename>lib/girepository-1.0</filename> directories of dependencies, which is then added to wrapper by <package>wrapGAppsHook</package>. It also adds <filename>share</filename> directories of dependencies to <envar>XDG_DATA_DIRS</envar>, which is intended to promote GIR files but it also <link xlink:href="https://github.com/NixOS/nixpkgs/issues/32790">pollutes the closures</link> of packages using <package>wrapGAppsHook</package>. <package>gobject-introspection</package> setup hook populates
<envar>GI_TYPELIB_PATH</envar> variable with
<filename>lib/girepository-1.0</filename> directories of dependencies,
which is then added to wrapper by <package>wrapGAppsHook</package>. It
also adds <filename>share</filename> directories of dependencies to
<envar>XDG_DATA_DIRS</envar>, which is intended to promote GIR files but
it also
<link xlink:href="https://github.com/NixOS/nixpkgs/issues/32790">pollutes
the closures</link> of packages using <package>wrapGAppsHook</package>.
</para> </para>
<warning> <warning>
<para> <para>
The setup hook <link xlink:href="https://github.com/NixOS/nixpkgs/issues/56943">currently</link> does not work in expressions with <literal>strictDeps</literal> enabled, like Python packages. In those cases, you will need to disable it with <code>strictDeps = false;</code>. The setup hook
<link xlink:href="https://github.com/NixOS/nixpkgs/issues/56943">currently</link>
does not work in expressions with <literal>strictDeps</literal> enabled,
like Python packages. In those cases, you will need to disable it with
<code>strictDeps = false;</code>.
</para> </para>
</warning> </warning>
</listitem> </listitem>
<listitem xml:id="ssec-gnome-hooks-gst-grl-plugins"> <listitem xml:id="ssec-gnome-hooks-gst-grl-plugins">
<para> <para>
Setup hooks of <package>gst_all_1.gstreamer</package> and <package>gnome3.grilo</package> will populate the <envar>GST_PLUGIN_SYSTEM_PATH_1_0</envar> and <envar>GRL_PLUGIN_PATH</envar> variables, respectively, which will then be added to the wrapper by <literal>wrapGAppsHook</literal>. Setup hooks of <package>gst_all_1.gstreamer</package> and
<package>gnome3.grilo</package> will populate the
<envar>GST_PLUGIN_SYSTEM_PATH_1_0</envar> and
<envar>GRL_PLUGIN_PATH</envar> variables, respectively, which will then
be added to the wrapper by <literal>wrapGAppsHook</literal>.
</para> </para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
</para> </para>
<para> <para>
You can also pass additional arguments to <literal>makeWrapper</literal> using <literal>gappsWrapperArgs</literal> in <literal>preFixup</literal> hook: You can also pass additional arguments to <literal>makeWrapper</literal>
using <literal>gappsWrapperArgs</literal> in <literal>preFixup</literal>
hook:
<programlisting> <programlisting>
preFixup = '' preFixup = ''
gappsWrapperArgs+=( gappsWrapperArgs+=(
@ -138,7 +215,13 @@ preFixup = ''
<title>Updating GNOME packages</title> <title>Updating GNOME packages</title>
<para> <para>
Most GNOME package offer <link linkend="var-passthru-updateScript"><literal>updateScript</literal></link>, it is therefore possible to update to latest source tarball by running <command>nix-shell maintainers/scripts/update.nix --argstr package gnome3.nautilus</command> or even en masse with <command>nix-shell maintainers/scripts/update.nix --argstr path gnome3</command>. Read the package’s <filename>NEWS</filename> file to see what changed. Most GNOME package offer
<link linkend="var-passthru-updateScript"><literal>updateScript</literal></link>,
it is therefore possible to update to latest source tarball by running
<command>nix-shell maintainers/scripts/update.nix --argstr package
gnome3.nautilus</command> or even en masse with <command>nix-shell
maintainers/scripts/update.nix --argstr path gnome3</command>. Read the
package’s <filename>NEWS</filename> file to see what changed.
</para> </para>
</section> </section>
@ -152,7 +235,17 @@ preFixup = ''
</term> </term>
<listitem> <listitem>
<para> <para>
There are no schemas avalable in <envar>XDG_DATA_DIRS</envar>. Temporarily add a random package containing schemas like <package>gsettings-desktop-schemas</package> to <literal>buildInputs</literal>. <link linkend="ssec-gnome-hooks-glib"><package>glib</package></link> and <link linkend="ssec-gnome-hooks-wrapgappshook"><package>wrapGAppsHook</package></link> setup hooks will take care of making the schemas available to application and you will see the actual missing schemas with the <link linkend="ssec-gnome-common-issues-missing-schema">next error</link>. Or you can try looking through the source code for the actual schemas used. There are no schemas avalable in <envar>XDG_DATA_DIRS</envar>.
Temporarily add a random package containing schemas like
<package>gsettings-desktop-schemas</package> to
<literal>buildInputs</literal>.
<link linkend="ssec-gnome-hooks-glib"><package>glib</package></link> and
<link linkend="ssec-gnome-hooks-wrapgappshook"><package>wrapGAppsHook</package></link>
setup hooks will take care of making the schemas available to application
and you will see the actual missing schemas with the
<link linkend="ssec-gnome-common-issues-missing-schema">next
error</link>. Or you can try looking through the source code for the
actual schemas used.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -162,7 +255,11 @@ preFixup = ''
</term> </term>
<listitem> <listitem>
<para> <para>
Package is missing some GSettings schemas. You can find out the package containing the schema with <command>nix-locate <replaceable>org.gnome.foo</replaceable>.gschema.xml</command> and let the hooks handle the wrapping as <link linkend="ssec-gnome-common-issues-no-schemas">above</link>. Package is missing some GSettings schemas. You can find out the package
containing the schema with <command>nix-locate
<replaceable>org.gnome.foo</replaceable>.gschema.xml</command> and let
the hooks handle the wrapping as
<link linkend="ssec-gnome-common-issues-no-schemas">above</link>.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -172,7 +269,14 @@ preFixup = ''
</term> </term>
<listitem> <listitem>
<para> <para>
This is because derivers like <function>python.pkgs.buildPythonApplication</function> or <function>qt5.mkDerivation</function> have setup-hooks automatically added that produce wrappers with <package>makeWrapper</package>. The simplest way to workaround that is to disable the <package>wrapGAppsHook</package> automatic wrapping with <code>dontWrapGApps = true;</code> and pass the arguments it intended to pass to <package>makeWrapper</package> to another. This is because derivers like
<function>python.pkgs.buildPythonApplication</function> or
<function>qt5.mkDerivation</function> have setup-hooks automatically
added that produce wrappers with <package>makeWrapper</package>. The
simplest way to workaround that is to disable the
<package>wrapGAppsHook</package> automatic wrapping with
<code>dontWrapGApps = true;</code> and pass the arguments it intended to
pass to <package>makeWrapper</package> to another.
</para> </para>
<para> <para>
In the case of a Python application it could look like: In the case of a Python application it could look like:
@ -224,34 +328,55 @@ mkDerivation {
</term> </term>
<listitem> <listitem>
<para> <para>
You can rely on applications depending on the library set the necessary environment variables but that it often easy to miss. Instead we recommend to patch the paths in the source code whenever possible. Here are some examples: You can rely on applications depending on the library set the necessary
environment variables but that it often easy to miss. Instead we
recommend to patch the paths in the source code whenever possible. Here
are some examples:
<itemizedlist> <itemizedlist>
<listitem xml:id="ssec-gnome-common-issues-unwrappable-package-gnome-shell-ext"> <listitem xml:id="ssec-gnome-common-issues-unwrappable-package-gnome-shell-ext">
<para> <para>
<link xlink:href="https://github.com/NixOS/nixpkgs/blob/7bb8f05f12ca3cff9da72b56caa2f7472d5732bc/pkgs/desktops/gnome-3/core/gnome-shell-extensions/default.nix#L21-L24">Replacing a <envar>GI_TYPELIB_PATH</envar> in GNOME Shell extension</link> – we are using <function>substituteAll</function> to include the path to a typelib into a patch. <link xlink:href="https://github.com/NixOS/nixpkgs/blob/7bb8f05f12ca3cff9da72b56caa2f7472d5732bc/pkgs/desktops/gnome-3/core/gnome-shell-extensions/default.nix#L21-L24">Replacing
a <envar>GI_TYPELIB_PATH</envar> in GNOME Shell extension</link> –
we are using <function>substituteAll</function> to include the path to
a typelib into a patch.
</para> </para>
</listitem> </listitem>
<listitem xml:id="ssec-gnome-common-issues-unwrappable-package-gsettings"> <listitem xml:id="ssec-gnome-common-issues-unwrappable-package-gsettings">
<para> <para>
The following examples are hardcoding GSettings schema paths. To get the schema paths we use the functions The following examples are hardcoding GSettings schema paths. To get
the schema paths we use the functions
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para> <para>
<function>glib.getSchemaPath</function> Takes a nix package attribute as an argument. <function>glib.getSchemaPath</function> Takes a nix package
attribute as an argument.
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
<function>glib.makeSchemaPath</function> Takes a package output like <literal>$out</literal> and a derivation name. You should use this if the schemas you need to hardcode are in the same derivation. <function>glib.makeSchemaPath</function> Takes a package output
like <literal>$out</literal> and a derivation name. You should use
this if the schemas you need to hardcode are in the same
derivation.
</para> </para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
</para> </para>
<para xml:id="ssec-gnome-common-issues-unwrappable-package-gsettings-vala"> <para xml:id="ssec-gnome-common-issues-unwrappable-package-gsettings-vala">
<link xlink:href="https://github.com/NixOS/nixpkgs/blob/7bb8f05f12ca3cff9da72b56caa2f7472d5732bc/pkgs/desktops/pantheon/apps/elementary-files/default.nix#L78-L86">Hard-coding GSettings schema path in Vala plug-in (dynamically loaded library)</link> – here, <function>substituteAll</function> cannot be used since the schema comes from the same package preventing us from pass its path to the function, probably due to a <link xlink:href="https://github.com/NixOS/nix/issues/1846">Nix bug</link>. <link xlink:href="https://github.com/NixOS/nixpkgs/blob/7bb8f05f12ca3cff9da72b56caa2f7472d5732bc/pkgs/desktops/pantheon/apps/elementary-files/default.nix#L78-L86">Hard-coding
GSettings schema path in Vala plug-in (dynamically loaded
library)</link> – here, <function>substituteAll</function> cannot be
used since the schema comes from the same package preventing us from
pass its path to the function, probably due to a
<link xlink:href="https://github.com/NixOS/nix/issues/1846">Nix
bug</link>.
</para> </para>
<para xml:id="ssec-gnome-common-issues-unwrappable-package-gsettings-c"> <para xml:id="ssec-gnome-common-issues-unwrappable-package-gsettings-c">
<link xlink:href="https://github.com/NixOS/nixpkgs/blob/29c120c065d03b000224872251bed93932d42412/pkgs/development/libraries/glib-networking/default.nix#L31-L34">Hard-coding GSettings schema path in C library</link> – nothing special other than using <link xlink:href="https://github.com/NixOS/nixpkgs/pull/67957#issuecomment-527717467">Coccinelle patch</link> to generate the patch itself. <link xlink:href="https://github.com/NixOS/nixpkgs/blob/29c120c065d03b000224872251bed93932d42412/pkgs/development/libraries/glib-networking/default.nix#L31-L34">Hard-coding
GSettings schema path in C library</link> – nothing special other
than using
<link xlink:href="https://github.com/NixOS/nixpkgs/pull/67957#issuecomment-527717467">Coccinelle
patch</link> to generate the patch itself.
</para> </para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>

12
doc/languages-frameworks/perl.xml
View File

@ -141,8 +141,8 @@ ClassC3Componentised = buildPerlPackage rec {
<para> <para>
On Darwin, if a script has too many On Darwin, if a script has too many
<literal>-I<replaceable>dir</replaceable></literal> flags in its first line <literal>-I<replaceable>dir</replaceable></literal> flags in its first line
(its “shebang line”), it will not run. This can be worked around by calling (its “shebang line”), it will not run. This can be worked around by
the <literal>shortenPerlShebang</literal> function from the calling the <literal>shortenPerlShebang</literal> function from the
<literal>postInstall</literal> phase: <literal>postInstall</literal> phase:
<programlisting> <programlisting>
{ stdenv, buildPerlPackage, fetchurl, shortenPerlShebang }: { stdenv, buildPerlPackage, fetchurl, shortenPerlShebang }:
@ -162,10 +162,10 @@ ImageExifTool = buildPerlPackage {
''; '';
}; };
</programlisting> </programlisting>
This will remove the <literal>-I</literal> flags from the shebang line, This will remove the <literal>-I</literal> flags from the shebang line,
rewrite them in the <literal>use lib</literal> form, and put them on the next rewrite them in the <literal>use lib</literal> form, and put them on the next
line instead. This function can be given any number of Perl scripts as line instead. This function can be given any number of Perl scripts as
arguments; it will modify them in-place. arguments; it will modify them in-place.
</para> </para>
<section xml:id="ssec-generation-from-CPAN"> <section xml:id="ssec-generation-from-CPAN">

154
doc/languages-frameworks/qt.xml
View File

@ -4,16 +4,16 @@
<title>Qt</title> <title>Qt</title>
<para> <para>
This section describes the differences between Nix expressions for Qt This section describes the differences between Nix expressions for Qt
libraries and applications and Nix expressions for other C++ software. Some libraries and applications and Nix expressions for other C++ software. Some
knowledge of the latter is assumed. There are primarily two problems which knowledge of the latter is assumed. There are primarily two problems which
the Qt infrastructure is designed to address: ensuring consistent versioning the Qt infrastructure is designed to address: ensuring consistent versioning
of all dependencies and finding dependencies at runtime. of all dependencies and finding dependencies at runtime.
</para> </para>
<example xml:id='qt-default-nix'> <example xml:id='qt-default-nix'>
<title>Nix expression for a Qt package (<filename>default.nix</filename>)</title> <title>Nix expression for a Qt package (<filename>default.nix</filename>)</title>
<programlisting> <programlisting>
{ mkDerivation, lib, qtbase }: <co xml:id='qt-default-nix-co-1' /> { mkDerivation, lib, qtbase }: <co xml:id='qt-default-nix-co-1' />
mkDerivation { <co xml:id='qt-default-nix-co-2' /> mkDerivation { <co xml:id='qt-default-nix-co-2' />
@ -26,53 +26,51 @@ mkDerivation { <co xml:id='qt-default-nix-co-2' />
</example> </example>
<calloutlist> <calloutlist>
<callout arearefs='qt-default-nix-co-1'> <callout arearefs='qt-default-nix-co-1'>
<para> <para>
Import <literal>mkDerivation</literal> and Qt (such as Import <literal>mkDerivation</literal> and Qt (such as
<literal>qtbase</literal> modules directly. <emphasis>Do not</emphasis> <literal>qtbase</literal> modules directly. <emphasis>Do not</emphasis>
import Qt package sets; the Qt versions of dependencies may not be import Qt package sets; the Qt versions of dependencies may not be
coherent, causing build and runtime failures. coherent, causing build and runtime failures.
</para> </para>
</callout> </callout>
<callout arearefs='qt-default-nix-co-2'> <callout arearefs='qt-default-nix-co-2'>
<para> <para>
Use <literal>mkDerivation</literal> instead of Use <literal>mkDerivation</literal> instead of
<literal>stdenv.mkDerivation</literal>. <literal>mkDerivation</literal> <literal>stdenv.mkDerivation</literal>. <literal>mkDerivation</literal> is
is a wrapper around <literal>stdenv.mkDerivation</literal> which a wrapper around <literal>stdenv.mkDerivation</literal> which applies some
applies some Qt-specific settings. Qt-specific settings. This deriver accepts the same arguments as
This deriver accepts the same arguments as <literal>stdenv.mkDerivation</literal>; refer to
<literal>stdenv.mkDerivation</literal>; refer to <xref linkend='chap-stdenv' /> for details.
<xref linkend='chap-stdenv' /> for details. </para>
</para> <para>
<para> To use another deriver instead of <literal>stdenv.mkDerivation</literal>,
To use another deriver instead of use <literal>mkDerivationWith</literal>:
<literal>stdenv.mkDerivation</literal>, use
<literal>mkDerivationWith</literal>:
<programlisting> <programlisting>
mkDerivationWith myDeriver { mkDerivationWith myDeriver {
# ... # ...
} }
</programlisting> </programlisting>
If you cannot use <literal>mkDerivationWith</literal>, please refer to If you cannot use <literal>mkDerivationWith</literal>, please refer to
<xref linkend='qt-runtime-dependencies' />. <xref linkend='qt-runtime-dependencies' />.
</para> </para>
</callout> </callout>
<callout arearefs='qt-default-nix-co-3'> <callout arearefs='qt-default-nix-co-3'>
<para> <para>
<literal>mkDerivation</literal> accepts the same arguments as <literal>mkDerivation</literal> accepts the same arguments as
<literal>stdenv.mkDerivation</literal>, such as <literal>stdenv.mkDerivation</literal>, such as
<literal>buildInputs</literal>. <literal>buildInputs</literal>.
</para> </para>
</callout> </callout>
</calloutlist> </calloutlist>
<formalpara xml:id='qt-runtime-dependencies'> <formalpara xml:id='qt-runtime-dependencies'>
<title>Locating runtime dependencies</title> <title>Locating runtime dependencies</title>
<para> <para>
Qt applications need to be wrapped to find runtime dependencies. If you Qt applications need to be wrapped to find runtime dependencies. If you
cannot use <literal>mkDerivation</literal> or cannot use <literal>mkDerivation</literal> or
<literal>mkDerivationWith</literal> above, include <literal>mkDerivationWith</literal> above, include
<literal>wrapQtAppsHook</literal> in <literal>nativeBuildInputs</literal>: <literal>wrapQtAppsHook</literal> in <literal>nativeBuildInputs</literal>:
<programlisting> <programlisting>
stdenv.mkDerivation { stdenv.mkDerivation {
# ... # ...
@ -80,13 +78,13 @@ stdenv.mkDerivation {
nativeBuildInputs = [ wrapQtAppsHook ]; nativeBuildInputs = [ wrapQtAppsHook ];
} }
</programlisting> </programlisting>
</para> </para>
</formalpara> </formalpara>
<para> <para>
Entries added to <literal>qtWrapperArgs</literal> are used to modify the Entries added to <literal>qtWrapperArgs</literal> are used to modify the
wrappers created by <literal>wrapQtAppsHook</literal>. The entries are wrappers created by <literal>wrapQtAppsHook</literal>. The entries are passed
passed as arguments to <xref linkend='fun-wrapProgram' />. as arguments to <xref linkend='fun-wrapProgram' />.
<programlisting> <programlisting>
mkDerivation { mkDerivation {
# ... # ...
@ -97,8 +95,8 @@ mkDerivation {
</para> </para>
<para> <para>
Set <literal>dontWrapQtApps</literal> to stop applications from being Set <literal>dontWrapQtApps</literal> to stop applications from being wrapped
wrapped automatically. It is required to wrap applications manually with automatically. It is required to wrap applications manually with
<literal>wrapQtApp</literal>, using the syntax of <literal>wrapQtApp</literal>, using the syntax of
<xref linkend='fun-wrapProgram' />: <xref linkend='fun-wrapProgram' />:
<programlisting> <programlisting>
@ -115,16 +113,17 @@ mkDerivation {
<note> <note>
<para> <para>
<literal>wrapQtAppsHook</literal> ignores files that are non-ELF executables. <literal>wrapQtAppsHook</literal> ignores files that are non-ELF
This means that scripts won't be automatically wrapped so you'll need to manually executables. This means that scripts won't be automatically wrapped so
wrap them as previously mentioned. An example of when you'd always need to do this you'll need to manually wrap them as previously mentioned. An example of
is with Python applications that use PyQT. when you'd always need to do this is with Python applications that use PyQT.
</para> </para>
</note> </note>
<para> <para>
Libraries are built with every available version of Qt. Use the <literal>meta.broken</literal> Libraries are built with every available version of Qt. Use the
attribute to disable the package for unsupported Qt versions: <literal>meta.broken</literal> attribute to disable the package for
unsupported Qt versions:
<programlisting> <programlisting>
mkDerivation { mkDerivation {
# ... # ...
@ -136,13 +135,13 @@ mkDerivation {
</para> </para>
<formalpara> <formalpara>
<title>Adding a library to Nixpkgs</title> <title>Adding a library to Nixpkgs</title>
<para> <para>
Add a Qt library to <filename>all-packages.nix</filename> by adding it to the Add a Qt library to <filename>all-packages.nix</filename> by adding it to
collection inside <literal>mkLibsForQt5</literal>. This ensures that the the collection inside <literal>mkLibsForQt5</literal>. This ensures that the
library is built with every available version of Qt as needed. library is built with every available version of Qt as needed.
<example xml:id='qt-library-all-packages-nix'> <example xml:id='qt-library-all-packages-nix'>
<title>Adding a Qt library to <filename>all-packages.nix</filename></title> <title>Adding a Qt library to <filename>all-packages.nix</filename></title>
<programlisting> <programlisting>
{ {
# ... # ...
@ -156,19 +155,19 @@ mkDerivation {
# ... # ...
} }
</programlisting> </programlisting>
</example> </example>
</para> </para>
</formalpara> </formalpara>
<formalpara> <formalpara>
<title>Adding an application to Nixpkgs</title> <title>Adding an application to Nixpkgs</title>
<para> <para>
Add a Qt application to <filename>all-packages.nix</filename> using Add a Qt application to <filename>all-packages.nix</filename> using
<literal>libsForQt5.callPackage</literal> instead of the usual <literal>libsForQt5.callPackage</literal> instead of the usual
<literal>callPackage</literal>. The former ensures that all dependencies <literal>callPackage</literal>. The former ensures that all dependencies are
are built with the same version of Qt. built with the same version of Qt.
<example xml:id='qt-application-all-packages-nix'> <example xml:id='qt-application-all-packages-nix'>
<title>Adding a Qt application to <filename>all-packages.nix</filename></title> <title>Adding a Qt application to <filename>all-packages.nix</filename></title>
<programlisting> <programlisting>
{ {
# ... # ...
@ -178,8 +177,7 @@ mkDerivation {
# ... # ...
} }
</programlisting> </programlisting>
</example> </example>
</para> </para>
</formalpara> </formalpara>
</section> </section>

10
doc/meta.xml
View File

@ -156,9 +156,9 @@ hello-2.3 A program that produces a familiar, friendly greeting
</term> </term>
<listitem> <listitem>
<para> <para>
A link or a list of links to the location of Changelog for a package. A link or a list of links to the location of Changelog for a package. A
A link may use expansion to refer to the correct changelog version. link may use expansion to refer to the correct changelog version.
Example: Example:
<literal>"https://git.savannah.gnu.org/cgit/hello.git/plain/NEWS?h=v${version}"</literal> <literal>"https://git.savannah.gnu.org/cgit/hello.git/plain/NEWS?h=v${version}"</literal>
</para> </para>
</listitem> </listitem>
@ -273,8 +273,8 @@ meta.platforms = stdenv.lib.platforms.linux;
This attribute is special in that it is not actually under the This attribute is special in that it is not actually under the
<literal>meta</literal> attribute set but rather under the <literal>meta</literal> attribute set but rather under the
<literal>passthru</literal> attribute set. This is due to how <literal>passthru</literal> attribute set. This is due to how
<literal>meta</literal> attributes work, and the fact that they <literal>meta</literal> attributes work, and the fact that they are
are supposed to contain only metadata, not derivations. supposed to contain only metadata, not derivations.
</para> </para>
</warning> </warning>
<para> <para>

66
doc/package-notes.xml
View File

@ -311,7 +311,8 @@ packageOverrides = pkgs: {
<title>Elm</title> <title>Elm</title>
<para> <para>
To start a development environment do <command>nix-shell -p elmPackages.elm elmPackages.elm-format</command> To start a development environment do <command>nix-shell -p elmPackages.elm
elmPackages.elm-format</command>
</para> </para>
<para> <para>
@ -506,10 +507,11 @@ stdenv.mkDerivation {
<para> <para>
The IBus engine is based on <literal>hunspell</literal> to support The IBus engine is based on <literal>hunspell</literal> to support
completion in many languages. By default the dictionaries completion in many languages. By default the dictionaries
<literal>de-de</literal>, <literal>en-us</literal>, <literal>fr-moderne</literal> <literal>de-de</literal>, <literal>en-us</literal>,
<literal>es-es</literal>, <literal>it-it</literal>, <literal>fr-moderne</literal> <literal>es-es</literal>,
<literal>sv-se</literal> and <literal>sv-fi</literal> are in use. To add <literal>it-it</literal>, <literal>sv-se</literal> and
another dictionary, the package can be overridden like this: <literal>sv-fi</literal> are in use. To add another dictionary, the package
can be overridden like this:
<programlisting>ibus-engines.typing-booster.override { <programlisting>ibus-engines.typing-booster.override {
langs = [ "de-at" "en-gb" ]; langs = [ "de-at" "en-gb" ];
}</programlisting> }</programlisting>
@ -543,47 +545,45 @@ stdenv.mkDerivation {
<title>Nginx</title> <title>Nginx</title>
<para> <para>
<link xlink:href="https://nginx.org/">Nginx</link> is a <link xlink:href="https://nginx.org/">Nginx</link> is a reverse proxy and
reverse proxy and lightweight webserver. lightweight webserver.
</para> </para>
<section xml:id="sec-nginx-etag"> <section xml:id="sec-nginx-etag">
<title>ETags on static files served from the Nix store</title> <title>ETags on static files served from the Nix store</title>
<para> <para>
HTTP has a couple different mechanisms for caching to prevent HTTP has a couple different mechanisms for caching to prevent clients from
clients from having to download the same content repeatedly having to download the same content repeatedly if a resource has not
if a resource has not changed since the last time it was requested. changed since the last time it was requested. When nginx is used as a
When nginx is used as a server for static files, it implements server for static files, it implements the caching mechanism based on the
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>
<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
response header automatically; unfortunately, it works by using timestamps to determine the value of the <literal>Last-Modified</literal>
filesystem timestamps to determine the value of the header. This doesn't give the desired behavior when the file is in the Nix
<literal>Last-Modified</literal> header. This doesn't give the store, because all file timestamps are set to 0 (for reasons related to
desired behavior when the file is in the Nix store, because all build reproducibility).
file timestamps are set to 0 (for reasons related to build
reproducibility).
</para> </para>
<para> <para>
Fortunately, HTTP supports an alternative (and more effective) Fortunately, HTTP supports an alternative (and more effective) caching
caching mechanism: the mechanism: the
<link xlink:href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag"><literal>ETag</literal></link> <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 response header. The value of the <literal>ETag</literal> header specifies
specifies some identifier for the particular content that the some identifier for the particular content that the server is sending (e.g.
server is sending (e.g. a hash). When a client makes a second a hash). When a client makes a second request for the same resource, it
request for the same resource, it sends that value back in an sends that value back in an <literal>If-None-Match</literal> header. If the
<literal>If-None-Match</literal> header. If the ETag value is ETag value is unchanged, then the server does not need to resend the
unchanged, then the server does not need to resend the content. content.
</para> </para>
<para> <para>
As of NixOS 19.09, the nginx package in Nixpkgs is patched such As of NixOS 19.09, the nginx package in Nixpkgs is patched such that when
that when nginx serves a file out of <filename>/nix/store</filename>, nginx serves a file out of <filename>/nix/store</filename>, the hash in the
the hash in the store path is used as the <literal>ETag</literal> store path is used as the <literal>ETag</literal> header in the HTTP
header in the HTTP response, thus providing proper caching functionality. response, thus providing proper caching functionality. This happens
This happens automatically; you do not need to do modify any automatically; you do not need to do modify any configuration to get this
configuration to get this behavior. behavior.
</para> </para>
</section> </section>
</section> </section>

88
doc/package-specific-user-notes.xml
View File

@ -1,14 +1,10 @@
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="package-specific-user-notes"> <chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="package-specific-user-notes">
<title>Package-specific usage notes</title> <title>Package-specific usage notes</title>
<para> <para>
These chapters includes some notes These chapters includes some notes that apply to specific packages and should
that apply to specific packages and should answer some of the frequently asked questions related to Nixpkgs use. Some
answer some of the frequently asked questions useful information related to package use can be found in
related to Nixpkgs use. <link linkend="chap-package-notes">package-specific development notes</link>.
Some useful information related to package use
can be found in <link linkend="chap-package-notes">package-specific development notes</link>.
</para> </para>
<section xml:id="opengl"> <section xml:id="opengl">
<title>OpenGL</title> <title>OpenGL</title>
@ -47,7 +43,6 @@
<literal>locales</literal> of the package. <literal>locales</literal> of the package.
</para> </para>
</section> </section>
<section xml:id="sec-emacs"> <section xml:id="sec-emacs">
<title>Emacs</title> <title>Emacs</title>
@ -204,46 +199,43 @@ overrides = self: super: rec {
</screen> </screen>
</section> </section>
</section> </section>
<section xml:id="dlib"> <section xml:id="dlib">
<title>DLib</title> <title>DLib</title>
<para> <para>
<link xlink:href="http://dlib.net/">DLib</link> is a modern, C++-based toolkit which <link xlink:href="http://dlib.net/">DLib</link> is a modern, C++-based
provides several machine learning algorithms. toolkit which provides several machine learning algorithms.
</para> </para>
<section xml:id="compiling-without-avx-support"> <section xml:id="compiling-without-avx-support">
<title>Compiling without AVX support</title> <title>Compiling without AVX support</title>
<para> <para>
Especially older CPUs don't support Especially older CPUs don't support
<link xlink:href="https://en.wikipedia.org/wiki/Advanced_Vector_Extensions">AVX</link> <link xlink:href="https://en.wikipedia.org/wiki/Advanced_Vector_Extensions">AVX</link>
(<abbrev>Advanced Vector Extensions</abbrev>) instructions that are used by DLib to (<abbrev>Advanced Vector Extensions</abbrev>) instructions that are used by
optimize their algorithms. DLib to optimize their algorithms.
</para> </para>
<para> <para>
On the affected hardware errors like <literal>Illegal instruction</literal> will occur. On the affected hardware errors like <literal>Illegal instruction</literal>
In those cases AVX support needs to be disabled: will occur. In those cases AVX support needs to be disabled:
<programlisting>self: super: { <programlisting>self: super: {
dlib = super.dlib.override { avxSupport = false; }; dlib = super.dlib.override { avxSupport = false; };
}</programlisting> }</programlisting>
</para> </para>
</section> </section>
</section> </section>
<section xml:id="unfree-software"> <section xml:id="unfree-software">
<title>Unfree software</title> <title>Unfree software</title>
<para> <para>
All users of Nixpkgs are free software users, and many users (and All users of Nixpkgs are free software users, and many users (and
developers) of Nixpkgs want to limit and tightly control their exposure to developers) of Nixpkgs want to limit and tightly control their exposure to
unfree software. At the same time, many users need (or want) unfree software. At the same time, many users need (or want) to run some
to run some specific specific pieces of proprietary software. Nixpkgs includes some expressions
pieces of proprietary software. Nixpkgs includes some expressions for unfree for unfree software packages. By default unfree software cannot be installed
software packages. By default unfree software cannot be installed and and doesn’t show up in searches. To allow installing unfree software in a
doesn’t show up in searches. To allow installing unfree software in a
single Nix invocation one can export single Nix invocation one can export
<literal>NIXPKGS_ALLOW_UNFREE=1</literal>. For a persistent solution, users <literal>NIXPKGS_ALLOW_UNFREE=1</literal>. For a persistent solution, users
can set <literal>allowUnfree</literal> in the Nixpkgs configuration. can set <literal>allowUnfree</literal> in the Nixpkgs configuration.
@ -256,7 +248,6 @@ overrides = self: super: rec {
<literal>true</literal> for unfree packages that should be allowed. <literal>true</literal> for unfree packages that should be allowed.
</para> </para>
</section> </section>
<section xml:id="sec-steam"> <section xml:id="sec-steam">
<title>Steam</title> <title>Steam</title>
@ -407,21 +398,24 @@ overrides = self: super: rec {
</para> </para>
</section> </section>
</section> </section>
<section xml:id="sec-citrix"> <section xml:id="sec-citrix">
<title>Citrix Receiver &amp; Citrix Workspace App</title> <title>Citrix Receiver &amp; Citrix Workspace App</title>
<para> <para>
<note> <note>
<para> <para>
Please note that the <literal>citrix_receiver</literal> package has been deprecated since its Please note that the <literal>citrix_receiver</literal> package has been
development was <link xlink:href="https://docs.citrix.com/en-us/citrix-workspace-app.html">discontinued by upstream</link> deprecated since its development was
and has been replaced by <link xlink:href="https://www.citrix.com/products/workspace-app/">the citrix workspace app</link>. <link xlink:href="https://docs.citrix.com/en-us/citrix-workspace-app.html">discontinued
by upstream</link> and has been replaced by
<link xlink:href="https://www.citrix.com/products/workspace-app/">the
citrix workspace app</link>.
</para> </para>
</note> </note>
<link xlink:href="https://www.citrix.com/products/receiver/">Citrix Receiver</link> and <link xlink:href="https://www.citrix.com/products/receiver/">Citrix
<link xlink:href="https://www.citrix.com/products/workspace-app/">Citrix Workspace App</link> Receiver</link> and
are a remote desktop viewers which provide access to <link xlink:href="https://www.citrix.com/products/workspace-app/">Citrix
Workspace App</link> are a remote desktop viewers which provide access to
<link xlink:href="https://www.citrix.com/products/xenapp-xendesktop/">XenDesktop</link> <link xlink:href="https://www.citrix.com/products/xenapp-xendesktop/">XenDesktop</link>
installations. installations.
</para> </para>
@ -432,24 +426,24 @@ overrides = self: super: rec {
<para> <para>
The tarball archive needs to be downloaded manually as the license The tarball archive needs to be downloaded manually as the license
agreements of the vendor for agreements of the vendor for
<link xlink:href="https://www.citrix.com/downloads/citrix-receiver/">Citrix Receiver</link> <link xlink:href="https://www.citrix.com/downloads/citrix-receiver/">Citrix
or <link xlink:href="https://www.citrix.de/downloads/workspace-app/linux/workspace-app-for-linux-latest.html">Citrix Workspace</link> Receiver</link> or
need to be accepted first. <link xlink:href="https://www.citrix.de/downloads/workspace-app/linux/workspace-app-for-linux-latest.html">Citrix
Then run <command>nix-prefetch-url file://$PWD/linuxx64-$version.tar.gz</command>. Workspace</link> need to be accepted first. Then run
With the archive available <command>nix-prefetch-url file://$PWD/linuxx64-$version.tar.gz</command>.
in the store the package can be built and installed with Nix. With the archive available in the store the package can be built and
installed with Nix.
</para> </para>
<warning> <warning>
<title>Caution with <command>nix-shell</command> installs</title> <title>Caution with <command>nix-shell</command> installs</title>
<para> <para>
It's recommended to install <literal>Citrix Receiver</literal> It's recommended to install <literal>Citrix Receiver</literal> and/or
and/or <literal>Citrix Workspace</literal> using <literal>Citrix Workspace</literal> using <literal>nix-env -i</literal> or
<literal>nix-env -i</literal> or globally to globally to ensure that the <literal>.desktop</literal> files are
ensure that the <literal>.desktop</literal> files are installed properly installed properly into <literal>$XDG_CONFIG_DIRS</literal>. Otherwise it
into <literal>$XDG_CONFIG_DIRS</literal>. Otherwise it won't be possible to won't be possible to open <literal>.ica</literal> files automatically from
open <literal>.ica</literal> files automatically from the browser to start the browser to start a Citrix connection.
a Citrix connection.
</para> </para>
</warning> </warning>
</section> </section>
@ -458,8 +452,8 @@ overrides = self: super: rec {
<title>Custom certificates</title> <title>Custom certificates</title>
<para> <para>
The <literal>Citrix Workspace App</literal> The <literal>Citrix Workspace App</literal> in <literal>nixpkgs</literal>
in <literal>nixpkgs</literal> trust several certificates trust several certificates
<link xlink:href="https://curl.haxx.se/docs/caextract.html">from the <link xlink:href="https://curl.haxx.se/docs/caextract.html">from the
Mozilla database</link> by default. However several companies using Citrix Mozilla database</link> by default. However several companies using Citrix
might require their own corporate certificate. On distros with imperative might require their own corporate certificate. On distros with imperative

8
doc/quick-start.xml
View File

@ -210,9 +210,11 @@
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
Optionally commit the new package and open a pull request <link Optionally commit the new package and open a pull request
xlink:href="https://github.com/NixOS/nixpkgs/pulls">to nixpkgs</link>, or <link
use <link xlink:href="https://github.com/NixOS/nixpkgs/pulls">to
nixpkgs</link>, or use
<link
xlink:href="https://discourse.nixos.org/t/about-the-patches-category/477"> xlink:href="https://discourse.nixos.org/t/about-the-patches-category/477">
the Patches category</link> on Discourse for sending a patch without a the Patches category</link> on Discourse for sending a patch without a
GitHub account. GitHub account.

126
doc/stdenv.xml
View File

@ -736,8 +736,8 @@ passthru.updateScript = [ ../../update.sh pname "--requested-release=unstable" ]
commit</command> or any other commands that cannot handle that. commit</command> or any other commands that cannot handle that.
</para> </para>
<para> <para>
For information about how to run the updates, execute For information about how to run the updates, execute <command>nix-shell
<command>nix-shell maintainers/scripts/update.nix</command>. maintainers/scripts/update.nix</command>.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -764,7 +764,8 @@ passthru.updateScript = [ ../../update.sh pname "--requested-release=unstable" ]
to <emphasis>add</emphasis> some commands to a phase, e.g. by defining to <emphasis>add</emphasis> some commands to a phase, e.g. by defining
<literal>postInstall</literal> or <literal>preFixup</literal>, as skipping <literal>postInstall</literal> or <literal>preFixup</literal>, as skipping
some of the default actions may have unexpected consequences. The default some of the default actions may have unexpected consequences. The default
script for each phase is defined in the file <filename>pkgs/stdenv/generic/setup.sh</filename>. script for each phase is defined in the file
<filename>pkgs/stdenv/generic/setup.sh</filename>.
</para> </para>
<section xml:id="ssec-controlling-phases"> <section xml:id="ssec-controlling-phases">
@ -786,7 +787,8 @@ passthru.updateScript = [ ../../update.sh pname "--requested-release=unstable" ]
set, the default value is used, which is <literal>$prePhases set, the default value is used, which is <literal>$prePhases
unpackPhase patchPhase $preConfigurePhases configurePhase unpackPhase patchPhase $preConfigurePhases configurePhase
$preBuildPhases buildPhase checkPhase $preInstallPhases installPhase $preBuildPhases buildPhase checkPhase $preInstallPhases installPhase
fixupPhase installCheckPhase $preDistPhases distPhase $postPhases</literal>. fixupPhase installCheckPhase $preDistPhases distPhase
$postPhases</literal>.
</para> </para>
<para> <para>
Usually, if you just want to add a few phases, it’s more convenient Usually, if you just want to add a few phases, it’s more convenient
@ -1605,7 +1607,7 @@ installTargets = "install-bin install-doc";</programlisting>
</term> </term>
<listitem> <listitem>
<para> <para>
Set to true to skip the fixup phase. Set to true to skip the fixup phase.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -2411,12 +2413,12 @@ addEnvHooks "$hostOffset" myBashFunction
<para> <para>
The Bintools Wrapper was only just recently split off from CC Wrapper, The Bintools Wrapper was only just recently split off from CC Wrapper,
so the division of labor is still being worked out. For example, it so the division of labor is still being worked out. For example, it
shouldn't care about the C standard library, but just take a shouldn't care about the C standard library, but just take a derivation
derivation with the dynamic loader (which happens to be the glibc on with the dynamic loader (which happens to be the glibc on linux).
linux). Dependency finding however is a task both wrappers will continue Dependency finding however is a task both wrappers will continue to need
to need to share, and probably the most important to understand. It is to share, and probably the most important to understand. It is currently
currently accomplished by collecting directories of host-platform accomplished by collecting directories of host-platform dependencies
dependencies (i.e. <varname>buildInputs</varname> and (i.e. <varname>buildInputs</varname> and
<varname>nativeBuildInputs</varname>) in environment variables. The <varname>nativeBuildInputs</varname>) in environment variables. The
Bintools Wrapper's setup hook causes any <filename>lib</filename> and Bintools Wrapper's setup hook causes any <filename>lib</filename> and
<filename>lib64</filename> subdirectories to be added to <filename>lib64</filename> subdirectories to be added to
@ -2633,7 +2635,8 @@ addEnvHooks "$hostOffset" myBashFunction
</term> </term>
<listitem> <listitem>
<para> <para>
Hooks related to GNOME platform and related libraries like GLib, GTK and GStreamer are described in <xref linkend="sec-language-gnome" />. Hooks related to GNOME platform and related libraries like GLib, GTK and
GStreamer are described in <xref linkend="sec-language-gnome" />.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -2688,12 +2691,12 @@ addEnvHooks "$hostOffset" myBashFunction
At <filename>/var/lib/cntr</filename> the sandboxed filesystem is At <filename>/var/lib/cntr</filename> the sandboxed filesystem is
mounted. All commands and files of the system are still accessible mounted. All commands and files of the system are still accessible
within the shell. To execute commands from the sandbox use the cntr exec within the shell. To execute commands from the sandbox use the cntr exec
subcommand. <command>cntr</command> is only supported subcommand. <command>cntr</command> is only supported on Linux-based
on Linux-based platforms. To use it first add <literal>cntr</literal> to platforms. To use it first add <literal>cntr</literal> to your
your <literal>environment.systemPackages</literal> on NixOS or <literal>environment.systemPackages</literal> on NixOS or alternatively
alternatively to the root user on non-NixOS systems. Then in the package to the root user on non-NixOS systems. Then in the package that is
that is supposed to be inspected, add <literal>breakpointHook</literal> supposed to be inspected, add <literal>breakpointHook</literal> to
to <literal>nativeBuildInputs</literal>. <literal>nativeBuildInputs</literal>.
<programlisting> <programlisting>
nativeBuildInputs = [ breakpointHook ]; nativeBuildInputs = [ breakpointHook ];
</programlisting> </programlisting>
@ -2703,11 +2706,11 @@ nativeBuildInputs = [ breakpointHook ];
<note> <note>
<title>Caution with remote builds</title> <title>Caution with remote builds</title>
<para> <para>
This won't work with remote builds as the build environment is on This won't work with remote builds as the build environment is on a
a different machine and can't be accessed by <command>cntr</command>. different machine and can't be accessed by <command>cntr</command>.
Remote builds can be turned off by setting <literal>--option builders ''</literal> Remote builds can be turned off by setting <literal>--option builders
for <command>nix-build</command> or <literal>--builders ''</literal> for ''</literal> for <command>nix-build</command> or <literal>--builders
<command>nix build</command>. ''</literal> for <command>nix build</command>.
</para> </para>
</note> </note>
</listitem> </listitem>
@ -2806,17 +2809,78 @@ postInstall = ''
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term> <term>
meson Meson
</term> </term>
<listitem> <listitem>
<para> <para>
Overrides the configure phase to run meson to generate Ninja files. You Overrides the configure phase to run meson to generate Ninja files. To
can disable this behavior by setting configurePhase to a custom value, run these files, you should accompany Meson with ninja. By default,
or by setting dontUseMesonConfigure. To run these files, you should <varname>enableParallelBuilding</varname> is enabled as Meson supports
accompany meson with ninja. mesonFlags controls only the flags passed to
meson. By default, parallel building is enabled as Meson supports
parallel building almost everywhere. parallel building almost everywhere.
</para> </para>
<variablelist>
<title>Variables controlling Meson</title>
<varlistentry>
<term>
<varname>mesonFlags</varname>
</term>
<listitem>
<para>
Controls the flags passed to meson.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<varname>mesonBuildType</varname>
</term>
<listitem>
<para>
Which
<link
xlink:href="https://mesonbuild.com/Builtin-options.html#core-options"><command>--buildtype</command></link>
to pass to Meson. We default to <literal>plain</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<varname>mesonAutoFeatures</varname>
</term>
<listitem>
<para>
What value to set
<link
xlink:href="https://mesonbuild.com/Builtin-options.html#core-options"><command>-Dauto_features=</command></link>
to. We default to <command>enabled</command>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<varname>mesonWrapMode</varname>
</term>
<listitem>
<para>
What value to set
<link
xlink:href="https://mesonbuild.com/Builtin-options.html#core-options"><command>-Dwrap_mode=</command></link>
to. We default to <command>nodownload</command> as we disallow
network access.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<varname>dontUseMesonConfigure</varname>
</term>
<listitem>
<para>
Disables using Meson's <varname>configurePhase</varname>.
</para>
</listitem>
</varlistentry>
</variablelist>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
@ -2851,8 +2915,8 @@ postInstall = ''
<para> <para>
Overrides the configure, build, and install phases. This will run the Overrides the configure, build, and install phases. This will run the
"waf" script used by many projects. If wafPath (default ./waf) doesn’t "waf" script used by many projects. If wafPath (default ./waf) doesn’t
exist, it will copy the version of waf available in Nixpkgs. wafFlags can exist, it will copy the version of waf available in Nixpkgs. wafFlags
be used to pass flags to the waf script. can be used to pass flags to the waf script.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>