diff --git a/doc/manual.xml b/doc/manual.xml index f31897aed039..ab845e1a1086 100644 --- a/doc/manual.xml +++ b/doc/manual.xml @@ -1,12 +1,13 @@ - Nixpkgs Contributors Guide + Nixpkgs Users and Contributors Guide Version + diff --git a/doc/package-notes.xml b/doc/package-notes.xml index 54f3079d5541..d3cffab33076 100644 --- a/doc/package-notes.xml +++ b/doc/package-notes.xml @@ -352,312 +352,6 @@ packageOverrides = pkgs: { -
- Steam - -
- Steam in Nix - - - Steam is distributed as a .deb file, for now only as - an i686 package (the amd64 package only has documentation). When unpacked, - it has a script called steam that in ubuntu (their - target distro) would go to /usr/bin . 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. - - - - Nix problems and constraints: - - - - We don't have /bin/bash and many scripts point - there. Similarly for /usr/bin/python . - - - - - We don't have the dynamic loader in /lib . - - - - - The steam.sh script in $HOME can not be patched, as - it is checked and rewritten by steam. - - - - - The steam binary cannot be patched, it's also checked. - - - - - - - The current approach to deploy Steam in NixOS is composing a FHS-compatible - chroot environment, as documented - here. - 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. - -
- -
- How to play - - - For 64-bit systems it's important to have -hardware.opengl.driSupport32Bit = true; - in your /etc/nixos/configuration.nix. You'll also need -hardware.pulseaudio.support32Bit = true; - 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 -hardware.steam-hardware.enable = true; - to your configuration. - -
- -
- Troubleshooting - - - - - - Steam fails to start. What do I do? - - - - Try to run -strace steam - to see what is causing steam to fail. - - - - - - Using the FOSS Radeon or nouveau (nvidia) drivers - - - - - - The newStdcpp parameter was removed since NixOS - 17.09 and should not be needed anymore. - - - - - 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 -steam.sh: line 713: 7842 Segmentation fault (core dumped) - have a look at - this - pull request. - - - - - - - - Java - - - - - - There is no java in steam chrootenv by default. If you get a message - like -/home/foo/.local/share/Steam/SteamApps/common/towns/towns.sh: line 1: java: command not found - You need to add - steam.override { withJava = true; }; - to your configuration. - - - - - - - -
- -
- steam-run - - - 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 -pkgs.(steam.override { - nativeOnly = true; - newStdcpp = true; - }).run - to your configuration, rebuild, and run the game with -steam-run ./foo - -
-
-
- Emacs - -
- Configuring Emacs - - - The Emacs package comes with some extra helpers to make it easier to - configure. emacsWithPackages 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 - company, counsel, - flycheck, ivy, - magit, projectile, and - use-package you could use this as a - ~/.config/nixpkgs/config.nix override: - - - -{ - packageOverrides = pkgs: with pkgs; { - myEmacs = emacsWithPackages (epkgs: (with epkgs.melpaStablePackages; [ - company - counsel - flycheck - ivy - magit - projectile - use-package - ])); - } -} - - - - You can install it like any other packages via nix-env -iA - myEmacs. However, this will only install those packages. It will - not configure 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 - default.el file in - /share/emacs/site-start/. Emacs knows to load this - file automatically when it starts. - - - -{ - 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 - ])); - }; -} - - - - 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 - -q to the Emacs command. - - - - Sometimes emacsWithPackages 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 pkgs/top-level/emacs-packages.nix). 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 - overrideScope'. - - - -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 -]) - -
-
Weechat @@ -762,64 +456,6 @@ stdenv.mkDerivation { }
-
- Citrix Receiver - - - The Citrix - Receiver is a remote desktop viewer which provides access to - XenDesktop - installations. - - -
- Basic usage - - - The tarball archive needs to be downloaded manually as the licenses - agreements of the vendor need to be accepted first. This is available at - the - download - page at citrix.com. Then run nix-prefetch-url - file://$PWD/linuxx64-$version.tar.gz. With the archive available - in the store the package can be built and installed with Nix. - - - - Note: it's recommended to install Citrix - Receiver using nix-env -i or globally to - ensure that the .desktop files are installed properly - into $XDG_CONFIG_DIRS. Otherwise it won't be possible to - open .ica files automatically from the browser to start - a Citrix connection. - -
- -
- Custom certificates - - - The Citrix Receiver in nixpkgs trusts - several certificates - from the - Mozilla database 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 - $ICAROOT, - however this directory is a store path in nixpkgs. In - order to work around this issue the package provides a simple mechanism to - add custom certificates without rebuilding the entire package using - symlinkJoin: - - { config.allowUnfree = true; }; -let extraCerts = [ ./custom-cert-1.pem ./custom-cert-2.pem /* ... */ ]; in -citrix_receiver.override { - inherit extraCerts; -}]]> - - -
-
ibus-engines.typing-booster @@ -887,33 +523,6 @@ citrix_receiver.override { On NixOS it can be installed using the following expression: { pkgs, ... }: { fonts.fonts = with pkgs; [ noto-fonts-emoji ]; -} - -
- -
- DLib - - - DLib is a modern, C++-based toolkit which - provides several machine learning algorithms. - - -
- Compiling without AVX support - - - Especially older CPUs don't support - AVX - (Advanced Vector Extensions) instructions that are used by DLib to - optimize their algorithms. - - - - On the affected hardware errors like Illegal instruction will occur. - In those cases AVX support needs to be disabled: -self: super: { - dlib = super.dlib.override { avxSupport = false; }; }
diff --git a/doc/package-specific-user-notes.xml b/doc/package-specific-user-notes.xml new file mode 100644 index 000000000000..ef9198d1de29 --- /dev/null +++ b/doc/package-specific-user-notes.xml @@ -0,0 +1,469 @@ + + Package-specific usage notes + + 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 package-specific development notes. + + +
+ OpenGL + + + Packages that use OpenGL have NixOS desktop as their primary target. The + current solution for loading the GPU-specific drivers is based on + libglvnd and looks for the driver implementation in + LD_LIBRARY_PATH. 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 + libglvnd and mesa_drivers in + LD_LIBRARY_PATH. For proprietary video drivers you might + have luck with also adding the corresponding video driver package. + +
+
+ Locales + + + To allow simultaneous use of packages linked against different versions of + glibc with different locale archive formats Nixpkgs + patches glibc to rely on + LOCALE_ARCHIVE environment variable. + + + + 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 LOCALE_ARCHIVE variable pointing to + ${glibcLocales}/lib/locale/locale-archive. 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 allLocales and + locales of the package. + +
+ +
+ Emacs + +
+ Configuring Emacs + + + The Emacs package comes with some extra helpers to make it easier to + configure. emacsWithPackages 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 + company, counsel, + flycheck, ivy, + magit, projectile, and + use-package you could use this as a + ~/.config/nixpkgs/config.nix override: + + + +{ + packageOverrides = pkgs: with pkgs; { + myEmacs = emacsWithPackages (epkgs: (with epkgs.melpaStablePackages; [ + company + counsel + flycheck + ivy + magit + projectile + use-package + ])); + } +} + + + + You can install it like any other packages via nix-env -iA + myEmacs. However, this will only install those packages. It will + not configure 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 + default.el file in + /share/emacs/site-start/. Emacs knows to load this + file automatically when it starts. + + + +{ + 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 + ])); + }; +} + + + + 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 + -q to the Emacs command. + + + + Sometimes emacsWithPackages 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 pkgs/top-level/emacs-packages.nix). 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 + overrideScope'. + + + +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 +]) + +
+
+ +
+ DLib + + + DLib is a modern, C++-based toolkit which + provides several machine learning algorithms. + + +
+ Compiling without AVX support + + + Especially older CPUs don't support + AVX + (Advanced Vector Extensions) instructions that are used by DLib to + optimize their algorithms. + + + + On the affected hardware errors like Illegal instruction will occur. + In those cases AVX support needs to be disabled: +self: super: { + dlib = super.dlib.override { avxSupport = false; }; +} + +
+
+ +
+ Unfree software + + + 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 + NIXPKGS_ALLOW_UNFREE=1. For a persistent solution, users + can set allowUnfree in the Nixpkgs configuration. + + + + Fine-grained control is possible by defining + allowUnfreePredicate function in config; it takes the + mkDerivation parameter attrset and returns + true for unfree packages that should be allowed. + +
+ +
+ Steam + +
+ Steam in Nix + + + Steam is distributed as a .deb file, for now only as + an i686 package (the amd64 package only has documentation). When unpacked, + it has a script called steam that in Ubuntu (their + target distro) would go to /usr/bin . 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. + + + + Nix problems and constraints: + + + + We don't have /bin/bash and many scripts point + there. Similarly for /usr/bin/python . + + + + + We don't have the dynamic loader in /lib . + + + + + The steam.sh script in $HOME can not be patched, as + it is checked and rewritten by steam. + + + + + The steam binary cannot be patched, it's also checked. + + + + + + + The current approach to deploy Steam in NixOS is composing a FHS-compatible + chroot environment, as documented + here. + 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. + +
+ +
+ How to play + + + For 64-bit systems it's important to have +hardware.opengl.driSupport32Bit = true; + in your /etc/nixos/configuration.nix. You'll also need +hardware.pulseaudio.support32Bit = true; + 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 +hardware.steam-hardware.enable = true; + to your configuration. + +
+ +
+ Troubleshooting + + + + + + Steam fails to start. What do I do? + + + + Try to run +strace steam + to see what is causing steam to fail. + + + + + + Using the FOSS Radeon or nouveau (nvidia) drivers + + + + + + The newStdcpp parameter was removed since NixOS + 17.09 and should not be needed anymore. + + + + + 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 +steam.sh: line 713: 7842 Segmentation fault (core dumped) + have a look at + this + pull request. + + + + + + + + Java + + + + + + There is no java in steam chrootenv by default. If you get a message + like +/home/foo/.local/share/Steam/SteamApps/common/towns/towns.sh: line 1: java: command not found + You need to add + steam.override { withJava = true; }; + to your configuration. + + + + + + + +
+ +
+ steam-run + + + 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 +pkgs.(steam.override { + nativeOnly = true; + newStdcpp = true; + }).run + to your configuration, rebuild, and run the game with +steam-run ./foo + +
+
+ +
+ Citrix Receiver + + + The Citrix + Receiver is a remote desktop viewer which provides access to + XenDesktop + installations. + + +
+ Basic usage + + + 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 + download + page at citrix.com. Then run nix-prefetch-url + file://$PWD/linuxx64-$version.tar.gz. With the archive available + in the store the package can be built and installed with Nix. + + + + Note: it's recommended to install Citrix + Receiver using nix-env -i or globally to + ensure that the .desktop files are installed properly + into $XDG_CONFIG_DIRS. Otherwise it won't be possible to + open .ica files automatically from the browser to start + a Citrix connection. + +
+ +
+ Custom certificates + + + The Citrix Receiver in nixpkgs trusts + several certificates + from the + Mozilla database 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 + $ICAROOT, + however this directory is a store path in nixpkgs. In + order to work around this issue the package provides a simple mechanism to + add custom certificates without rebuilding the entire package using + symlinkJoin: + + { config.allowUnfree = true; }; +let extraCerts = [ ./custom-cert-1.pem ./custom-cert-2.pem /* ... */ ]; in +citrix_receiver.override { + inherit extraCerts; +}]]> + + +
+
+