doc/how-to-build-like-nix.rst

   1 .. _nix-style-builds:
   2
   3 How to build locally like in Nix
   4 ================================
   5
   6 Nix-style local builds are a new build system implementation inspired by Nix.
   7 The Nix-style local build system is commonly called "v2-build" for short
   8 after the ``cabal v2-*`` family of commands that control it. However, those
   9 names are only temporary now that Nix-style local builds have become the
  10 default. For those who do not wish to use the new
  11 functionality, the classic project style will not be removed immediately,
  12 but these legacy commands will require the usage of the ``v1-`` prefix as of
  13 Cabal 3.0 and will be removed in a future release. For a future-proof
  14 way to use these commands in a script or tutorial that anticipates the
  15 possibility of another UI paradigm being devised in the future, there
  16 are also ``v2-`` prefixed versions that will reference the same functionality
  17 until such a point as it is completely removed from Cabal.
  18
  19 Nix-style local builds combine the best of non-sandboxed and sandboxed Cabal:
  20
  21 1. Like sandboxed Cabal previously, we build sets of independent local
  22    packages deterministically and independent of any global state.
  23    v2-build will never tell you that it can't build your package
  24    because it would result in a "dangerous reinstall." Given a
  25    particular state of the Hackage index, your build is completely
  26    reproducible. For example, you no longer need to compile packages
  27    with profiling ahead of time; just request profiling and v2-build
  28    will rebuild all its dependencies with profiling automatically.
  29
  30 2. Like non-sandboxed Cabal today, builds of external packages are
  31    cached in ``~/.cabal/store``, so that a package can be built once,
  32    and then reused anywhere else it is also used. No need to continually
  33    rebuild dependencies whenever you make a new sandbox: dependencies
  34    which can be shared, are shared.
  35
  36 Nix-style local builds were first released as beta in cabal-install 1.24.
  37 They currently work with all versions of GHC supported by that release: GHC 7.0 and later.
  38
  39 Some features described in this manual are not implemented. If you need
  40 them, please give us a shout and we'll prioritize accordingly.
  41
  42
  43
  44 .. toctree::
  45    nix-local-build