Cabal-2.4.0.1: doc/users-guide/nix-local-build-overview.html
<!DOCTYPE html>
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>5. Nix-style Local Builds — Cabal <release> User's Guide</title>
<link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
<link rel="index" title="Index"
href="genindex.html"/>
<link rel="search" title="Search" href="search.html"/>
<link rel="top" title="Cabal <release> User's Guide" href="index.html"/>
<link rel="next" title="5.1. Quickstart" href="nix-local-build.html"/>
<link rel="prev" title="4.1. Reporting bugs and deficiencies" href="misc.html"/>
<script src="_static/js/modernizr.min.js"></script>
</head>
<body class="wy-body-for-nav" role="document">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search">
<a href="index.html" class="icon icon-home"> Cabal
<img src="_static/Cabal-dark.png" class="logo" />
</a>
<div class="version">
2.4.0.1
</div>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="search.html" method="get">
<input type="text" name="q" placeholder="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="intro.html">1. Introduction</a></li>
<li class="toctree-l1"><a class="reference internal" href="config-and-install.html">2. Configuration and Installing Packages</a></li>
<li class="toctree-l1"><a class="reference internal" href="concepts-and-development.html">3. Package Concepts and Development</a></li>
<li class="toctree-l1"><a class="reference internal" href="bugs-and-stability.html">4. Reporting Bugs and Stability of Cabal Interfaces</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">5. Nix-style Local Builds</a><ul>
<li class="toctree-l2"><a class="reference internal" href="nix-local-build.html">5.1. Quickstart</a></li>
<li class="toctree-l2"><a class="reference internal" href="nix-local-build.html#cookbook">5.2. Cookbook</a></li>
<li class="toctree-l2"><a class="reference internal" href="nix-local-build.html#how-it-works">5.3. How it works</a></li>
<li class="toctree-l2"><a class="reference internal" href="nix-local-build.html#commands">5.4. Commands</a></li>
<li class="toctree-l2"><a class="reference internal" href="nix-local-build.html#configuring-builds-with-cabal-project">5.5. Configuring builds with cabal.project</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="nix-integration.html">6. Nix Integration</a></li>
<li class="toctree-l1"><a class="reference internal" href="file-format-changelog.html">7. Cabal file format changelog</a></li>
</ul>
<a href="cabal-projectindex.html">Reference</a>
<a href="genindex.html">Index</a>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
<nav class="wy-nav-top" role="navigation" aria-label="top navigation">
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="index.html">Cabal</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="breadcrumbs navigation">
<ul class="wy-breadcrumbs">
<li><a href="index.html">Docs</a> »</li>
<li>5. Nix-style Local Builds</li>
<li class="wy-breadcrumbs-aside">
<a href="https://github.com/haskell/cabal/blob/master/Cabal/doc/nix-local-build-overview.rst" class="fa fa-github"> Edit on GitHub</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<div class="section" id="nix-style-local-builds">
<h1>5. Nix-style Local Builds<a class="headerlink" href="#nix-style-local-builds" title="Permalink to this headline">¶</a></h1>
<p>Nix-style local builds are a new build system implementation inspired by Nix.
The Nix-style local build system is commonly called “new-build” for short
after the <code class="docutils literal"><span class="pre">cabal</span> <span class="pre">new-*</span></code> family of commands that control it. However, those
names are only temporary until Nix-style local builds become the default.
This is expected to happen soon. For those who do not wish to use the new
functionality, the classic project style will not be removed immediately,
but these legacy commands will require the usage of the <code class="docutils literal"><span class="pre">v1-</span></code> prefix as of
Cabal 3.0 and will be removed in a future release. For a future-proof
way to use these commands in a script or tutorial that anticipates the
possibility of another UI paradigm being devised in the future, there
are also <code class="docutils literal"><span class="pre">v2-</span></code> prefixed versions that will reference the same functionality
until such a point as it is completely removed from Cabal.</p>
<p>Nix-style local builds combine the best of non-sandboxed and sandboxed Cabal:</p>
<ol class="arabic simple">
<li>Like sandboxed Cabal today, we build sets of independent local
packages deterministically and independent of any global state.
new-build will never tell you that it can’t build your package
because it would result in a “dangerous reinstall.” Given a
particular state of the Hackage index, your build is completely
reproducible. For example, you no longer need to compile packages
with profiling ahead of time; just request profiling and new-build
will rebuild all its dependencies with profiling automatically.</li>
<li>Like non-sandboxed Cabal today, builds of external packages are
cached in <code class="docutils literal"><span class="pre">~/.cabal/store</span></code>, so that a package can be built once,
and then reused anywhere else it is also used. No need to continually
rebuild dependencies whenever you make a new sandbox: dependencies
which can be shared, are shared.</li>
</ol>
<p>Nix-style local builds were first released as beta in cabal-install 1.24.
They currently work with all versions of GHC supported by that release: GHC 7.0 and later.</p>
<p>Some features described in this manual are not implemented. If you need
them, please give us a shout and we’ll prioritize accordingly.</p>
<div class="toctree-wrapper compound">
<ul>
<li class="toctree-l1"><a class="reference internal" href="nix-local-build.html">5.1. Quickstart</a><ul>
<li class="toctree-l2"><a class="reference internal" href="nix-local-build.html#developing-multiple-packages">5.1.1. Developing multiple packages</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="nix-local-build.html#cookbook">5.2. Cookbook</a><ul>
<li class="toctree-l2"><a class="reference internal" href="nix-local-build.html#how-can-i-profile-my-library-application">5.2.1. How can I profile my library/application?</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="nix-local-build.html#how-it-works">5.3. How it works</a><ul>
<li class="toctree-l2"><a class="reference internal" href="nix-local-build.html#local-versus-external-packages">5.3.1. Local versus external packages</a></li>
<li class="toctree-l2"><a class="reference internal" href="nix-local-build.html#where-are-my-build-products">5.3.2. Where are my build products?</a></li>
<li class="toctree-l2"><a class="reference internal" href="nix-local-build.html#caching">5.3.3. Caching</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="nix-local-build.html#commands">5.4. Commands</a><ul>
<li class="toctree-l2"><a class="reference internal" href="nix-local-build.html#cabal-new-configure">5.4.1. cabal new-configure</a></li>
<li class="toctree-l2"><a class="reference internal" href="nix-local-build.html#cabal-new-update">5.4.2. cabal new-update</a></li>
<li class="toctree-l2"><a class="reference internal" href="nix-local-build.html#cabal-new-build">5.4.3. cabal new-build</a></li>
<li class="toctree-l2"><a class="reference internal" href="nix-local-build.html#cabal-new-repl">5.4.4. cabal new-repl</a></li>
<li class="toctree-l2"><a class="reference internal" href="nix-local-build.html#cabal-new-run">5.4.5. cabal new-run</a></li>
<li class="toctree-l2"><a class="reference internal" href="nix-local-build.html#cabal-new-freeze">5.4.6. cabal new-freeze</a></li>
<li class="toctree-l2"><a class="reference internal" href="nix-local-build.html#cabal-new-bench">5.4.7. cabal new-bench</a></li>
<li class="toctree-l2"><a class="reference internal" href="nix-local-build.html#cabal-new-test">5.4.8. cabal new-test</a></li>
<li class="toctree-l2"><a class="reference internal" href="nix-local-build.html#cabal-new-haddock">5.4.9. cabal new-haddock</a></li>
<li class="toctree-l2"><a class="reference internal" href="nix-local-build.html#cabal-new-exec">5.4.10. cabal new-exec</a></li>
<li class="toctree-l2"><a class="reference internal" href="nix-local-build.html#cabal-new-install">5.4.11. cabal new-install</a></li>
<li class="toctree-l2"><a class="reference internal" href="nix-local-build.html#cabal-new-clean">5.4.12. cabal new-clean</a></li>
<li class="toctree-l2"><a class="reference internal" href="nix-local-build.html#cabal-new-sdist">5.4.13. cabal new-sdist</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="nix-local-build.html#configuring-builds-with-cabal-project">5.5. Configuring builds with cabal.project</a><ul>
<li class="toctree-l2"><a class="reference internal" href="nix-local-build.html#specifying-the-local-packages">5.5.1. Specifying the local packages</a></li>
<li class="toctree-l2"><a class="reference internal" href="nix-local-build.html#global-configuration-options">5.5.2. Global configuration options</a></li>
<li class="toctree-l2"><a class="reference internal" href="nix-local-build.html#solver-configuration-options">5.5.3. Solver configuration options</a></li>
<li class="toctree-l2"><a class="reference internal" href="nix-local-build.html#package-configuration-options">5.5.4. Package configuration options</a><ul>
<li class="toctree-l3"><a class="reference internal" href="nix-local-build.html#object-code-options">5.5.4.1. Object code options</a></li>
<li class="toctree-l3"><a class="reference internal" href="nix-local-build.html#executable-options">5.5.4.2. Executable options</a></li>
<li class="toctree-l3"><a class="reference internal" href="nix-local-build.html#dynamic-linking-options">5.5.4.3. Dynamic linking options</a></li>
<li class="toctree-l3"><a class="reference internal" href="nix-local-build.html#static-linking-options">5.5.4.4. Static linking options</a></li>
<li class="toctree-l3"><a class="reference internal" href="nix-local-build.html#foreign-function-interface-options">5.5.4.5. Foreign function interface options</a></li>
<li class="toctree-l3"><a class="reference internal" href="nix-local-build.html#profiling-options">5.5.4.6. Profiling options</a></li>
<li class="toctree-l3"><a class="reference internal" href="nix-local-build.html#coverage-options">5.5.4.7. Coverage options</a></li>
<li class="toctree-l3"><a class="reference internal" href="nix-local-build.html#haddock-options">5.5.4.8. Haddock options</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="nix-local-build.html#advanced-global-configuration-options">5.5.5. Advanced global configuration options</a><ul>
<li class="toctree-l3"><a class="reference internal" href="nix-local-build.html#advanced-solver-options">5.5.5.1. Advanced solver options</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</div>
</div>
</div>
<div class="articleComments">
</div>
</div>
<footer>
<div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
<a href="nix-local-build.html" class="btn btn-neutral float-right" title="5.1. Quickstart" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right"></span></a>
<a href="misc.html" class="btn btn-neutral" title="4.1. Reporting bugs and deficiencies" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left"></span> Previous</a>
</div>
<hr/>
<div role="contentinfo">
<p>
© Copyright 2003-2017, Cabal Team.
</p>
</div>
Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
</div>
</div>
</section>
</div>
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT:'./',
VERSION:'2.4.0.1',
COLLAPSE_INDEX:false,
FILE_SUFFIX:'.html',
HAS_SOURCE: true,
SOURCELINK_SUFFIX: '.txt'
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<script type="text/javascript" src="_static/js/theme.js"></script>
<script type="text/javascript">
jQuery(function () {
SphinxRtdTheme.StickyNav.enable();
});
</script>
</body>
</html>