mirror of
https://github.com/NixOS/nixpkgs.git
synced 2024-11-30 17:41:12 +00:00
4e750fa92c
* manual: rename to users and contributors manual, add some user notes that should be there but don't fit in any chapter * manual: move the package notes that are completely usage-related to the upper user notes section * manual: link to package-specific development notes from user notes
470 lines
16 KiB
XML
470 lines
16 KiB
XML
<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>
|
||
<para>
|
||
These chapters includes some notes
|
||
that apply to specific packages and should
|
||
answer some of the frequently asked questions
|
||
related to Nixpkgs use.
|
||
|
||
Some useful information related to package use
|
||
can be found in <link linkend="chap-package-notes">package-specific development notes</link>.
|
||
|
||
</para>
|
||
<section xml:id="opengl">
|
||
<title>OpenGL</title>
|
||
|
||
<para>
|
||
Packages that use OpenGL have NixOS desktop as their primary target. The
|
||
current solution for loading the GPU-specific drivers is based on
|
||
<literal>libglvnd</literal> and looks for the driver implementation in
|
||
<literal>LD_LIBRARY_PATH</literal>. If you are using a non-NixOS
|
||
GNU/Linux/X11 desktop with free software video drivers, consider launching
|
||
OpenGL-dependent programs from Nixpkgs with Nixpkgs versions of
|
||
<literal>libglvnd</literal> and <literal>mesa_drivers</literal> in
|
||
<literal>LD_LIBRARY_PATH</literal>. For proprietary video drivers you might
|
||
have luck with also adding the corresponding video driver package.
|
||
</para>
|
||
</section>
|
||
<section xml:id="locales">
|
||
<title>Locales</title>
|
||
|
||
<para>
|
||
To allow simultaneous use of packages linked against different versions of
|
||
<literal>glibc</literal> with different locale archive formats Nixpkgs
|
||
patches <literal>glibc</literal> to rely on
|
||
<literal>LOCALE_ARCHIVE</literal> environment variable.
|
||
</para>
|
||
|
||
<para>
|
||
On non-NixOS distributions this variable is obviously not set. This can
|
||
cause regressions in language support or even crashes in some
|
||
Nixpkgs-provided programs. The simplest way to mitigate this problem is
|
||
exporting the <literal>LOCALE_ARCHIVE</literal> variable pointing to
|
||
<literal>${glibcLocales}/lib/locale/locale-archive</literal>. The drawback
|
||
(and the reason this is not the default) is the relatively large (a hundred
|
||
MiB) size of the full set of locales. It is possible to build a custom set
|
||
of locales by overriding parameters <literal>allLocales</literal> and
|
||
<literal>locales</literal> of the package.
|
||
</para>
|
||
</section>
|
||
|
||
<section xml:id="sec-emacs">
|
||
<title>Emacs</title>
|
||
|
||
<section xml:id="sec-emacs-config">
|
||
<title>Configuring Emacs</title>
|
||
|
||
<para>
|
||
The Emacs package comes with some extra helpers to make it easier to
|
||
configure. <varname>emacsWithPackages</varname> allows you to manage
|
||
packages from ELPA. This means that you will not have to install that
|
||
packages from within Emacs. For instance, if you wanted to use
|
||
<literal>company</literal>, <literal>counsel</literal>,
|
||
<literal>flycheck</literal>, <literal>ivy</literal>,
|
||
<literal>magit</literal>, <literal>projectile</literal>, and
|
||
<literal>use-package</literal> you could use this as a
|
||
<filename>~/.config/nixpkgs/config.nix</filename> override:
|
||
</para>
|
||
|
||
<screen>
|
||
{
|
||
packageOverrides = pkgs: with pkgs; {
|
||
myEmacs = emacsWithPackages (epkgs: (with epkgs.melpaStablePackages; [
|
||
company
|
||
counsel
|
||
flycheck
|
||
ivy
|
||
magit
|
||
projectile
|
||
use-package
|
||
]));
|
||
}
|
||
}
|
||
</screen>
|
||
|
||
<para>
|
||
You can install it like any other packages via <command>nix-env -iA
|
||
myEmacs</command>. However, this will only install those packages. It will
|
||
not <literal>configure</literal> them for us. To do this, we need to
|
||
provide a configuration file. Luckily, it is possible to do this from
|
||
within Nix! By modifying the above example, we can make Emacs load a custom
|
||
config file. The key is to create a package that provide a
|
||
<filename>default.el</filename> file in
|
||
<filename>/share/emacs/site-start/</filename>. Emacs knows to load this
|
||
file automatically when it starts.
|
||
</para>
|
||
|
||
<screen>
|
||
{
|
||
packageOverrides = pkgs: with pkgs; rec {
|
||
myEmacsConfig = writeText "default.el" ''
|
||
;; initialize package
|
||
|
||
(require 'package)
|
||
(package-initialize 'noactivate)
|
||
(eval-when-compile
|
||
(require 'use-package))
|
||
|
||
;; load some packages
|
||
|
||
(use-package company
|
||
:bind ("<C-tab>" . company-complete)
|
||
:diminish company-mode
|
||
:commands (company-mode global-company-mode)
|
||
:defer 1
|
||
:config
|
||
(global-company-mode))
|
||
|
||
(use-package counsel
|
||
:commands (counsel-descbinds)
|
||
:bind (([remap execute-extended-command] . counsel-M-x)
|
||
("C-x C-f" . counsel-find-file)
|
||
("C-c g" . counsel-git)
|
||
("C-c j" . counsel-git-grep)
|
||
("C-c k" . counsel-ag)
|
||
("C-x l" . counsel-locate)
|
||
("M-y" . counsel-yank-pop)))
|
||
|
||
(use-package flycheck
|
||
:defer 2
|
||
:config (global-flycheck-mode))
|
||
|
||
(use-package ivy
|
||
:defer 1
|
||
:bind (("C-c C-r" . ivy-resume)
|
||
("C-x C-b" . ivy-switch-buffer)
|
||
:map ivy-minibuffer-map
|
||
("C-j" . ivy-call))
|
||
:diminish ivy-mode
|
||
:commands ivy-mode
|
||
:config
|
||
(ivy-mode 1))
|
||
|
||
(use-package magit
|
||
:defer
|
||
:if (executable-find "git")
|
||
:bind (("C-x g" . magit-status)
|
||
("C-x G" . magit-dispatch-popup))
|
||
:init
|
||
(setq magit-completing-read-function 'ivy-completing-read))
|
||
|
||
(use-package projectile
|
||
:commands projectile-mode
|
||
:bind-keymap ("C-c p" . projectile-command-map)
|
||
:defer 5
|
||
:config
|
||
(projectile-global-mode))
|
||
'';
|
||
myEmacs = emacsWithPackages (epkgs: (with epkgs.melpaStablePackages; [
|
||
(runCommand "default.el" {} ''
|
||
mkdir -p $out/share/emacs/site-lisp
|
||
cp ${myEmacsConfig} $out/share/emacs/site-lisp/default.el
|
||
'')
|
||
company
|
||
counsel
|
||
flycheck
|
||
ivy
|
||
magit
|
||
projectile
|
||
use-package
|
||
]));
|
||
};
|
||
}
|
||
</screen>
|
||
|
||
<para>
|
||
This provides a fairly full Emacs start file. It will load in addition to
|
||
the user's presonal config. You can always disable it by passing
|
||
<command>-q</command> to the Emacs command.
|
||
</para>
|
||
|
||
<para>
|
||
Sometimes <varname>emacsWithPackages</varname> is not enough, as this
|
||
package set has some priorities imposed on packages (with the lowest
|
||
priority assigned to Melpa Unstable, and the highest for packages manually
|
||
defined in <filename>pkgs/top-level/emacs-packages.nix</filename>). But you
|
||
can't control this priorities when some package is installed as a
|
||
dependency. You can override it on per-package-basis, providing all the
|
||
required dependencies manually - but it's tedious and there is always a
|
||
possibility that an unwanted dependency will sneak in through some other
|
||
package. To completely override such a package you can use
|
||
<varname>overrideScope'</varname>.
|
||
</para>
|
||
|
||
<screen>
|
||
overrides = self: super: rec {
|
||
haskell-mode = self.melpaPackages.haskell-mode;
|
||
...
|
||
};
|
||
((emacsPackagesNgGen emacs).overrideScope' overrides).emacsWithPackages (p: with p; [
|
||
# here both these package will use haskell-mode of our own choice
|
||
ghc-mod
|
||
dante
|
||
])
|
||
</screen>
|
||
</section>
|
||
</section>
|
||
|
||
<section xml:id="dlib">
|
||
<title>DLib</title>
|
||
|
||
<para>
|
||
<link xlink:href="http://dlib.net/">DLib</link> is a modern, C++-based toolkit which
|
||
provides several machine learning algorithms.
|
||
</para>
|
||
|
||
<section xml:id="compiling-without-avx-support">
|
||
<title>Compiling without AVX support</title>
|
||
|
||
<para>
|
||
Especially older CPUs don't support
|
||
<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
|
||
optimize their algorithms.
|
||
</para>
|
||
|
||
<para>
|
||
On the affected hardware errors like <literal>Illegal instruction</literal> will occur.
|
||
In those cases AVX support needs to be disabled:
|
||
<programlisting>self: super: {
|
||
dlib = super.dlib.override { avxSupport = false; };
|
||
}</programlisting>
|
||
</para>
|
||
</section>
|
||
</section>
|
||
|
||
<section xml:id="unfree-software">
|
||
<title>Unfree software</title>
|
||
|
||
<para>
|
||
All users of Nixpkgs are free software users, and many users (and
|
||
developers) of Nixpkgs want to limit and tightly control their exposure to
|
||
unfree software. At the same time, many users need (or want)
|
||
to run some specific
|
||
pieces of proprietary software. Nixpkgs includes some expressions for unfree
|
||
software packages. By default unfree software cannot be installed and
|
||
doesn’t show up in searches. To allow installing unfree software in a
|
||
single Nix invocation one can export
|
||
<literal>NIXPKGS_ALLOW_UNFREE=1</literal>. For a persistent solution, users
|
||
can set <literal>allowUnfree</literal> in the Nixpkgs configuration.
|
||
</para>
|
||
|
||
<para>
|
||
Fine-grained control is possible by defining
|
||
<literal>allowUnfreePredicate</literal> function in config; it takes the
|
||
<literal>mkDerivation</literal> parameter attrset and returns
|
||
<literal>true</literal> for unfree packages that should be allowed.
|
||
</para>
|
||
</section>
|
||
|
||
<section xml:id="sec-steam">
|
||
<title>Steam</title>
|
||
|
||
<section xml:id="sec-steam-nix">
|
||
<title>Steam in Nix</title>
|
||
|
||
<para>
|
||
Steam is distributed as a <filename>.deb</filename> file, for now only as
|
||
an i686 package (the amd64 package only has documentation). When unpacked,
|
||
it has a script called <filename>steam</filename> that in Ubuntu (their
|
||
target distro) would go to <filename>/usr/bin </filename>. When run for the
|
||
first time, this script copies some files to the user's home, which include
|
||
another script that is the ultimate responsible for launching the steam
|
||
binary, which is also in $HOME.
|
||
</para>
|
||
|
||
<para>
|
||
Nix problems and constraints:
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para>
|
||
We don't have <filename>/bin/bash</filename> and many scripts point
|
||
there. Similarly for <filename>/usr/bin/python</filename> .
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
We don't have the dynamic loader in <filename>/lib </filename>.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
The <filename>steam.sh</filename> script in $HOME can not be patched, as
|
||
it is checked and rewritten by steam.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
The steam binary cannot be patched, it's also checked.
|
||
</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
</para>
|
||
|
||
<para>
|
||
The current approach to deploy Steam in NixOS is composing a FHS-compatible
|
||
chroot environment, as documented
|
||
<link xlink:href="http://sandervanderburg.blogspot.nl/2013/09/composing-fhs-compatible-chroot.html">here</link>.
|
||
This allows us to have binaries in the expected paths without disrupting
|
||
the system, and to avoid patching them to work in a non FHS environment.
|
||
</para>
|
||
</section>
|
||
|
||
<section xml:id="sec-steam-play">
|
||
<title>How to play</title>
|
||
|
||
<para>
|
||
For 64-bit systems it's important to have
|
||
<programlisting>hardware.opengl.driSupport32Bit = true;</programlisting>
|
||
in your <filename>/etc/nixos/configuration.nix</filename>. You'll also need
|
||
<programlisting>hardware.pulseaudio.support32Bit = true;</programlisting>
|
||
if you are using PulseAudio - this will enable 32bit ALSA apps integration.
|
||
To use the Steam controller or other Steam supported controllers such as
|
||
the DualShock 4 or Nintendo Switch Pro, you need to add
|
||
<programlisting>hardware.steam-hardware.enable = true;</programlisting>
|
||
to your configuration.
|
||
</para>
|
||
</section>
|
||
|
||
<section xml:id="sec-steam-troub">
|
||
<title>Troubleshooting</title>
|
||
|
||
<para>
|
||
<variablelist>
|
||
<varlistentry>
|
||
<term>
|
||
Steam fails to start. What do I do?
|
||
</term>
|
||
<listitem>
|
||
<para>
|
||
Try to run
|
||
<programlisting>strace steam</programlisting>
|
||
to see what is causing steam to fail.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
Using the FOSS Radeon or nouveau (nvidia) drivers
|
||
</term>
|
||
<listitem>
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para>
|
||
The <literal>newStdcpp</literal> parameter was removed since NixOS
|
||
17.09 and should not be needed anymore.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
Steam ships statically linked with a version of libcrypto that
|
||
conflics with the one dynamically loaded by radeonsi_dri.so. If you
|
||
get the error
|
||
<programlisting>steam.sh: line 713: 7842 Segmentation fault (core dumped)</programlisting>
|
||
have a look at
|
||
<link xlink:href="https://github.com/NixOS/nixpkgs/pull/20269">this
|
||
pull request</link>.
|
||
</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>
|
||
Java
|
||
</term>
|
||
<listitem>
|
||
<orderedlist>
|
||
<listitem>
|
||
<para>
|
||
There is no java in steam chrootenv by default. If you get a message
|
||
like
|
||
<programlisting>/home/foo/.local/share/Steam/SteamApps/common/towns/towns.sh: line 1: java: command not found</programlisting>
|
||
You need to add
|
||
<programlisting> steam.override { withJava = true; };</programlisting>
|
||
to your configuration.
|
||
</para>
|
||
</listitem>
|
||
</orderedlist>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
</para>
|
||
</section>
|
||
|
||
<section xml:id="sec-steam-run">
|
||
<title>steam-run</title>
|
||
|
||
<para>
|
||
The FHS-compatible chroot used for steam can also be used to run other
|
||
linux games that expect a FHS environment. To do it, add
|
||
<programlisting>pkgs.(steam.override {
|
||
nativeOnly = true;
|
||
newStdcpp = true;
|
||
}).run</programlisting>
|
||
to your configuration, rebuild, and run the game with
|
||
<programlisting>steam-run ./foo</programlisting>
|
||
</para>
|
||
</section>
|
||
</section>
|
||
|
||
<section xml:id="sec-citrix">
|
||
<title>Citrix Receiver</title>
|
||
|
||
<para>
|
||
The <link xlink:href="https://www.citrix.com/products/receiver/">Citrix
|
||
Receiver</link> is a remote desktop viewer which provides access to
|
||
<link xlink:href="https://www.citrix.com/products/xenapp-xendesktop/">XenDesktop</link>
|
||
installations.
|
||
</para>
|
||
|
||
<section xml:id="sec-citrix-base">
|
||
<title>Basic usage</title>
|
||
|
||
<para>
|
||
The tarball archive needs to be downloaded manually as the license
|
||
agreements of the vendor need to be accepted first. This is available at
|
||
the
|
||
<link xlink:href="https://www.citrix.com/downloads/citrix-receiver/">download
|
||
page at citrix.com</link>. Then run <literal>nix-prefetch-url
|
||
file://$PWD/linuxx64-$version.tar.gz</literal>. With the archive available
|
||
in the store the package can be built and installed with Nix.
|
||
</para>
|
||
|
||
<para>
|
||
<emphasis>Note: it's recommended to install <literal>Citrix
|
||
Receiver</literal> using <literal>nix-env -i</literal> or globally to
|
||
ensure that the <literal>.desktop</literal> files are installed properly
|
||
into <literal>$XDG_CONFIG_DIRS</literal>. Otherwise it won't be possible to
|
||
open <literal>.ica</literal> files automatically from the browser to start
|
||
a Citrix connection.</emphasis>
|
||
</para>
|
||
</section>
|
||
|
||
<section xml:id="sec-citrix-custom-certs">
|
||
<title>Custom certificates</title>
|
||
|
||
<para>
|
||
The <literal>Citrix Receiver</literal> in <literal>nixpkgs</literal> trusts
|
||
several certificates
|
||
<link xlink:href="https://curl.haxx.se/docs/caextract.html">from the
|
||
Mozilla database</link> by default. However several companies using Citrix
|
||
might require their own corporate certificate. On distros with imperative
|
||
packaging these certs can be stored easily in
|
||
<link xlink:href="https://developer-docs.citrix.com/projects/receiver-for-linux-command-reference/en/13.7/"><literal>$ICAROOT</literal></link>,
|
||
however this directory is a store path in <literal>nixpkgs</literal>. In
|
||
order to work around this issue the package provides a simple mechanism to
|
||
add custom certificates without rebuilding the entire package using
|
||
<literal>symlinkJoin</literal>:
|
||
<programlisting>
|
||
<![CDATA[with import <nixpkgs> { config.allowUnfree = true; };
|
||
let extraCerts = [ ./custom-cert-1.pem ./custom-cert-2.pem /* ... */ ]; in
|
||
citrix_receiver.override {
|
||
inherit extraCerts;
|
||
}]]>
|
||
</programlisting>
|
||
</para>
|
||
</section>
|
||
</section>
|
||
</chapter>
|