doc/nix-integration.rst

   1 Nix Integration
   2 ===============
   3
   4 .. note::
   5
   6     This functionality doesn't work with nix-style builds.
   7     Nix-style builds are not related to Nix integration.
   8
   9 `Nix <http://nixos.org/nix/>`_ is a package manager popular with some Haskell developers due to its focus on reliability and reproducibility. ``cabal`` now has the ability to integrate with Nix for dependency management during local package development.
  10
  11 Enabling Nix Integration
  12 ------------------------
  13
  14 To enable Nix integration, simply pass the ``--enable-nix`` global option when you call ``cabal`` (eg. ``cabal --enable-nix v1-build``).
  15 To use this option everywhere, edit your :ref:`global configuration file<config-file-discovery>` (default: ``~/.config/cabal/config``) to include:
  16
  17 .. code-block:: cabal
  18
  19     nix: True
  20
  21 If the package (which must be locally unpacked) provides a ``shell.nix`` or ``default.nix`` file, this flag will cause ``cabal`` to run most commands through ``nix-shell``. If both expressions are present, ``shell.nix`` is preferred. The following commands are affected:
  22
  23 - ``cabal v1-configure``
  24 - ``cabal v1-build``
  25 - ``cabal v1-repl``
  26 - ``cabal v1-install`` (only if installing into a sandbox)
  27 - ``cabal v1-haddock``
  28 - ``cabal v1-freeze``
  29 - ``cabal v1-gen-bounds``
  30 - ``cabal v1-run``
  31
  32 If the package does not provide a Nix expression, ``cabal`` runs normally.
  33
  34 Creating Nix Expressions
  35 ------------------------
  36
  37 The Nix package manager is based on a lazy, pure, functional programming language; packages are defined by expressions in this language. The fastest way to create a Nix expression for a Cabal package is with the `cabal2nix <https://github.com/NixOS/cabal2nix>`_ tool. To create a ``shell.nix`` expression for the package in the current directory, run this command:
  38
  39 .. code-block:: console
  40
  41     $ cabal2nix --shell ./. >shell.nix
  42
  43 Nix Expression Evaluation
  44 -------------------------
  45
  46 (This section describes for advanced users how Nix expressions are evaluated.)
  47
  48 First, the Nix expression (``shell.nix`` or ``default.nix``) is instantiated with ``nix-instantiate``. The ``--add-root`` and ``--indirect`` options are used to create an indirect root in the Cabal build directory, preventing Nix from garbage collecting the derivation while in use. The ``IN_NIX_SHELL`` environment variable is set so that ``builtins.getEnv`` works as it would in ``nix-shell``.
  49
  50 Next, the commands above are run through ``nix-shell`` using the instantiated derivation. Again, ``--add-root`` and ``--indirect`` are used to prevent Nix from garbage collecting the packages in the environment. The child ``cabal`` process reads the ``CABAL_IN_NIX_SHELL`` environment variable to prevent it from spawning additional child shells.
  51
  52 Further Reading
  53 ----------------
  54
  55 The `Nix manual <http://nixos.org/nix/manual/#chap-writing-nix-expressions>`_ provides further instructions for writing Nix expressions. The `Nixpkgs manual <http://nixos.org/nixpkgs/manual/#users-guide-to-the-haskell-infrastructure>`_ describes the infrastructure provided for Haskell packages.