Cabal-2.4.0.1: doc/users-guide/nix-local-build.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.1. Quickstart — 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="up" title="5. Nix-style Local Builds" href="nix-local-build-overview.html"/>
<link rel="next" title="6. Nix Integration" href="nix-integration.html"/>
<link rel="prev" title="5. Nix-style Local Builds" href="nix-local-build-overview.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="reference internal" href="nix-local-build-overview.html">5. Nix-style Local Builds</a><ul class="current">
<li class="toctree-l2 current"><a class="current reference internal" href="#">5.1. Quickstart</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#developing-multiple-packages">5.1.1. Developing multiple packages</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#cookbook">5.2. Cookbook</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#how-can-i-profile-my-library-application">5.2.1. How can I profile my library/application?</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#how-it-works">5.3. How it works</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#local-versus-external-packages">5.3.1. Local versus external packages</a></li>
<li class="toctree-l3"><a class="reference internal" href="#where-are-my-build-products">5.3.2. Where are my build products?</a></li>
<li class="toctree-l3"><a class="reference internal" href="#caching">5.3.3. Caching</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#commands">5.4. Commands</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#cabal-new-configure">5.4.1. cabal new-configure</a></li>
<li class="toctree-l3"><a class="reference internal" href="#cabal-new-update">5.4.2. cabal new-update</a></li>
<li class="toctree-l3"><a class="reference internal" href="#cabal-new-build">5.4.3. cabal new-build</a></li>
<li class="toctree-l3"><a class="reference internal" href="#cabal-new-repl">5.4.4. cabal new-repl</a></li>
<li class="toctree-l3"><a class="reference internal" href="#cabal-new-run">5.4.5. cabal new-run</a></li>
<li class="toctree-l3"><a class="reference internal" href="#cabal-new-freeze">5.4.6. cabal new-freeze</a></li>
<li class="toctree-l3"><a class="reference internal" href="#cabal-new-bench">5.4.7. cabal new-bench</a></li>
<li class="toctree-l3"><a class="reference internal" href="#cabal-new-test">5.4.8. cabal new-test</a></li>
<li class="toctree-l3"><a class="reference internal" href="#cabal-new-haddock">5.4.9. cabal new-haddock</a></li>
<li class="toctree-l3"><a class="reference internal" href="#cabal-new-exec">5.4.10. cabal new-exec</a></li>
<li class="toctree-l3"><a class="reference internal" href="#cabal-new-install">5.4.11. cabal new-install</a></li>
<li class="toctree-l3"><a class="reference internal" href="#cabal-new-clean">5.4.12. cabal new-clean</a></li>
<li class="toctree-l3"><a class="reference internal" href="#cabal-new-sdist">5.4.13. cabal new-sdist</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#configuring-builds-with-cabal-project">5.5. Configuring builds with cabal.project</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#specifying-the-local-packages">5.5.1. Specifying the local packages</a></li>
<li class="toctree-l3"><a class="reference internal" href="#global-configuration-options">5.5.2. Global configuration options</a></li>
<li class="toctree-l3"><a class="reference internal" href="#solver-configuration-options">5.5.3. Solver configuration options</a></li>
<li class="toctree-l3"><a class="reference internal" href="#package-configuration-options">5.5.4. Package configuration options</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#object-code-options">5.5.4.1. Object code options</a></li>
<li class="toctree-l4"><a class="reference internal" href="#executable-options">5.5.4.2. Executable options</a></li>
<li class="toctree-l4"><a class="reference internal" href="#dynamic-linking-options">5.5.4.3. Dynamic linking options</a></li>
<li class="toctree-l4"><a class="reference internal" href="#static-linking-options">5.5.4.4. Static linking options</a></li>
<li class="toctree-l4"><a class="reference internal" href="#foreign-function-interface-options">5.5.4.5. Foreign function interface options</a></li>
<li class="toctree-l4"><a class="reference internal" href="#profiling-options">5.5.4.6. Profiling options</a></li>
<li class="toctree-l4"><a class="reference internal" href="#coverage-options">5.5.4.7. Coverage options</a></li>
<li class="toctree-l4"><a class="reference internal" href="#haddock-options">5.5.4.8. Haddock options</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#advanced-global-configuration-options">5.5.5. Advanced global configuration options</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#advanced-solver-options">5.5.5.1. Advanced solver options</a></li>
</ul>
</li>
</ul>
</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><a href="nix-local-build-overview.html">5. Nix-style Local Builds</a> »</li>
<li>5.1. Quickstart</li>
<li class="wy-breadcrumbs-aside">
<a href="https://github.com/haskell/cabal/blob/master/Cabal/doc/nix-local-build.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="quickstart">
<h1>5.1. Quickstart<a class="headerlink" href="#quickstart" title="Permalink to this headline">¶</a></h1>
<p>Suppose that you are in a directory containing a single Cabal package
which you wish to build. You can configure and build it using Nix-style
local builds with this command (configuring is not necessary):</p>
<div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">$</span> cabal new-build
</pre></div>
</div>
<p>To open a GHCi shell with this package, use this command:</p>
<div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">$</span> cabal new-repl
</pre></div>
</div>
<p>To run an executable defined in this package, use this command:</p>
<div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">$</span> cabal new-run <executable name> <span class="o">[</span>executable args<span class="o">]</span>
</pre></div>
</div>
<div class="section" id="developing-multiple-packages">
<h2>5.1.1. Developing multiple packages<a class="headerlink" href="#developing-multiple-packages" title="Permalink to this headline">¶</a></h2>
<p>Many Cabal projects involve multiple packages which need to be built
together. To build multiple Cabal packages, you need to first create a
<code class="docutils literal"><span class="pre">cabal.project</span></code> file which declares where all the local package
directories live. For example, in the Cabal repository, there is a root
directory with a folder per package, e.g., the folders <code class="docutils literal"><span class="pre">Cabal</span></code> and
<code class="docutils literal"><span class="pre">cabal-install</span></code>. The <code class="docutils literal"><span class="pre">cabal.project</span></code> file specifies each folder as
part of the project:</p>
<div class="highlight-cabal"><div class="highlight"><pre><span></span><span class="k">packages</span><span class="p">:</span> Cabal/
cabal-install/
</pre></div>
</div>
<p>The expectation is that a <code class="docutils literal"><span class="pre">cabal.project</span></code> is checked into your source
control, to be used by all developers of a project. If you need to make
local changes, they can be placed in <code class="docutils literal"><span class="pre">cabal.project.local</span></code> (which
should not be checked in.)</p>
<p>Then, to build every component of every package, from the top-level
directory, run the command: (using cabal-install-2.0 or greater.)</p>
<div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">$</span> cabal new-build
</pre></div>
</div>
<p>To build a specific package, you can either run <code class="docutils literal"><span class="pre">new-build</span></code> from the
directory of the package in question:</p>
<div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">$</span> <span class="nb">cd</span> cabal-install
<span class="gp">$</span> cabal new-build
</pre></div>
</div>
<p>or you can pass the name of the package as an argument to
<code class="docutils literal"><span class="pre">cabal</span> <span class="pre">new-build</span></code> (this works in any subdirectory of the project):</p>
<div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">$</span> cabal new-build cabal-install
</pre></div>
</div>
<p>You can also specify a specific component of the package to build. For
example, to build a test suite named <code class="docutils literal"><span class="pre">package-tests</span></code>, use the command:</p>
<div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">$</span> cabal new-build package-tests
</pre></div>
</div>
<p>Targets can be qualified with package names. So to request
<code class="docutils literal"><span class="pre">package-tests</span></code> <em>from</em> the <code class="docutils literal"><span class="pre">Cabal</span></code> package, use
<code class="docutils literal"><span class="pre">Cabal:package-tests</span></code>.</p>
<p>Unlike sandboxes, there is no need to setup a sandbox or <code class="docutils literal"><span class="pre">add-source</span></code>
projects; just check in <code class="docutils literal"><span class="pre">cabal.project</span></code> to your repository and
<code class="docutils literal"><span class="pre">new-build</span></code> will just work.</p>
</div>
</div>
<div class="section" id="cookbook">
<h1>5.2. Cookbook<a class="headerlink" href="#cookbook" title="Permalink to this headline">¶</a></h1>
<div class="section" id="how-can-i-profile-my-library-application">
<h2>5.2.1. How can I profile my library/application?<a class="headerlink" href="#how-can-i-profile-my-library-application" title="Permalink to this headline">¶</a></h2>
<p>Create or edit your <code class="docutils literal"><span class="pre">cabal.project.local</span></code>, adding the following
line:</p>
<div class="highlight-console"><div class="highlight"><pre><span></span><span class="go">profiling: True</span>
</pre></div>
</div>
<p>Now, <code class="docutils literal"><span class="pre">cabal</span> <span class="pre">new-build</span></code> will automatically build all libraries and
executables with profiling. You can fine-tune the profiling settings
for each package using <a class="reference internal" href="#cfg-field-profiling-detail" title="cabal.project profiling-detail field (since version: 1.23)"><code class="xref cabal cabal-cfg-field docutils literal"><span class="pre">profiling-detail</span></code></a>:</p>
<div class="highlight-console"><div class="highlight"><pre><span></span><span class="go">package p</span>
<span class="go"> profiling-detail: toplevel-functions</span>
</pre></div>
</div>
<p>Alternately, you can call <code class="docutils literal"><span class="pre">cabal</span> <span class="pre">new-build</span> <span class="pre">--enable-profiling</span></code> to
temporarily build with profiling.</p>
</div>
</div>
<div class="section" id="how-it-works">
<h1>5.3. How it works<a class="headerlink" href="#how-it-works" title="Permalink to this headline">¶</a></h1>
<div class="section" id="local-versus-external-packages">
<h2>5.3.1. Local versus external packages<a class="headerlink" href="#local-versus-external-packages" title="Permalink to this headline">¶</a></h2>
<p>One of the primary innovations of Nix-style local builds is the
distinction between local packages, which users edit and recompile and
must be built per-project, versus external packages, which can be cached
across projects. To be more precise:</p>
<ol class="arabic simple">
<li>A <strong>local package</strong> is one that is listed explicitly in the
<code class="docutils literal"><span class="pre">packages</span></code>, <code class="docutils literal"><span class="pre">optional-packages</span></code> or <code class="docutils literal"><span class="pre">extra-packages</span></code> field of a
project. Usually, these refer to packages whose source code lives
directly in a folder in your project (although, you can list an
arbitrary Hackage package in <code class="docutils literal"><span class="pre">extra-packages</span></code> to force it to be
treated as local).</li>
</ol>
<p>Local packages, as well as the external packages (below) which depend on
them, are built <strong>inplace</strong>, meaning that they are always built
specifically for the project and are not installed globally. Inplace
packages are not cached and not given unique hashes, which makes them
suitable for packages which you want to edit and recompile.</p>
<ol class="arabic simple" start="2">
<li>An <strong>external package</strong> is any package which is not listed in the
<code class="docutils literal"><span class="pre">packages</span></code> field. The source code for external packages is usually
retrieved from Hackage.</li>
</ol>
<p>When an external package does not depend on an inplace package, it can
be built and installed to a <strong>global</strong> store, which can be shared across
projects. These build products are identified by a hash that over all of
the inputs which would influence the compilation of a package (flags,
dependency selection, etc.). Just as in Nix, these hashes uniquely
identify the result of a build; if we compute this identifier and we
find that we already have this ID built, we can just use the already
built version.</p>
<p>The global package store is <code class="docutils literal"><span class="pre">~/.cabal/store</span></code> (configurable via
global <cite>store-dir</cite> option); if you need to clear your store for
whatever reason (e.g., to reclaim disk space or because the global
store is corrupted), deleting this directory is safe (<code class="docutils literal"><span class="pre">new-build</span></code>
will just rebuild everything it needs on its next invocation).</p>
<p>This split motivates some of the UI choices for Nix-style local build
commands. For example, flags passed to <code class="docutils literal"><span class="pre">cabal</span> <span class="pre">new-build</span></code> are only
applied to <em>local</em> packages, so that adding a flag to
<code class="docutils literal"><span class="pre">cabal</span> <span class="pre">new-build</span></code> doesn’t necessitate a rebuild of <em>every</em> transitive
dependency in the global package store.</p>
<p>In cabal-install 2.0 and above, Nix-style local builds also take advantage of a
new Cabal library feature, <a class="reference external" href="https://github.com/ezyang/ghc-proposals/blob/master/proposals/0000-componentized-cabal.rst">per-component
builds</a>,
where each component of a package is configured and built separately.
This can massively speed up rebuilds of packages with lots of components
(e.g., a package that defines multiple executables), as only one
executable needs to be rebuilt. Packages that use Custom setup scripts
are not currently built on a per-component basis.</p>
</div>
<div class="section" id="where-are-my-build-products">
<h2>5.3.2. Where are my build products?<a class="headerlink" href="#where-are-my-build-products" title="Permalink to this headline">¶</a></h2>
<p>A major deficiency in the current implementation of new-build is that
there is no programmatic way to access the location of build products.
The location of the build products is intended to be an internal
implementation detail of new-build, but we also understand that many
unimplemented features can only be reasonably worked around by
accessing build products directly.</p>
<p>The location where build products can be found varies depending on the
version of cabal-install:</p>
<ul class="simple">
<li>In cabal-install-1.24, the dist directory for a package <code class="docutils literal"><span class="pre">p-0.1</span></code> is
stored in <code class="docutils literal"><span class="pre">dist-newstyle/build/p-0.1</span></code>. For example, if you built an
executable or test suite named <code class="docutils literal"><span class="pre">pexe</span></code>, it would be located at
<code class="docutils literal"><span class="pre">dist-newstyle/build/p-0.1/build/pexe/pexe</span></code>.</li>
<li>In cabal-install-2.0 and above, the dist directory for a package <code class="docutils literal"><span class="pre">p-0.1</span></code>
defining a library built with GHC 8.0.1 on 64-bit Linux is
<code class="docutils literal"><span class="pre">dist-newstyle/build/x86_64-linux/ghc-8.0.1/p-0.1</span></code>. When
per-component builds are enabled (any non-Custom package), a
subcomponent like an executable or test suite named <code class="docutils literal"><span class="pre">pexe</span></code> will be
stored at
<code class="docutils literal"><span class="pre">dist-newstyle/build/x86_64-linux/ghc-8.0.1/p-0.1/c/pexe</span></code>; thus,
the full path of the executable is
<code class="docutils literal"><span class="pre">dist-newstyle/build/x86_64-linux/ghc-8.0.1/p-0.1/c/pexe/build/pexe/pexe</span></code>
(you can see why we want this to be an implementation detail!)</li>
</ul>
<p>The paths are a bit longer in 2.0 and above but the benefit is that you can
transparently have multiple builds with different versions of GHC. We
plan to add the ability to create aliases for certain build
configurations, and more convenient paths to access particularly useful
build products like executables.</p>
</div>
<div class="section" id="caching">
<h2>5.3.3. Caching<a class="headerlink" href="#caching" title="Permalink to this headline">¶</a></h2>
<p>Nix-style local builds sport a robust caching system which help reduce
the time it takes to execute a rebuild cycle. While the details of how
<code class="docutils literal"><span class="pre">cabal-install</span></code> does caching are an implementation detail and may
change in the future, knowing what gets cached is helpful for
understanding the performance characteristics of invocations to
<code class="docutils literal"><span class="pre">new-build</span></code>. The cached intermediate results are stored in
<code class="docutils literal"><span class="pre">dist-newstyle/cache</span></code>; this folder can be safely deleted to clear the
cache.</p>
<p>The following intermediate results are cached in the following files in
this folder (the most important two are first):</p>
<dl class="docutils">
<dt><code class="docutils literal"><span class="pre">solver-plan</span></code> (binary)</dt>
<dd>The result of calling the dependency solver, assuming that the
Hackage index, local <code class="docutils literal"><span class="pre">cabal.project</span></code> file, and local <code class="docutils literal"><span class="pre">cabal</span></code>
files are unmodified. (Notably, we do NOT have to dependency solve
again if new build products are stored in the global store; the
invocation of the dependency solver is independent of what is
already available in the store.)</dd>
<dt><code class="docutils literal"><span class="pre">source-hashes</span></code> (binary)</dt>
<dd>The hashes of all local source files. When all local source files of
a local package are unchanged, <code class="docutils literal"><span class="pre">cabal</span> <span class="pre">new-build</span></code> will skip
invoking <code class="docutils literal"><span class="pre">setup</span> <span class="pre">build</span></code> entirely (saving us from a possibly
expensive call to <code class="docutils literal"><span class="pre">ghc</span> <span class="pre">--make</span></code>). The full list of source files
participating in compilation are determined using
<code class="docutils literal"><span class="pre">setup</span> <span class="pre">sdist</span> <span class="pre">--list-sources</span></code> (thus, if you do not list all your
source files in a Cabal file, you may fail to recompile when you
edit them.)</dd>
<dt><code class="docutils literal"><span class="pre">config</span></code> (same format as <code class="docutils literal"><span class="pre">cabal.project</span></code>)</dt>
<dd>The full project configuration, merged from <code class="docutils literal"><span class="pre">cabal.project</span></code> (and
friends) as well as the command line arguments.</dd>
<dt><code class="docutils literal"><span class="pre">compiler</span></code> (binary)</dt>
<dd>The configuration of the compiler being used to build the project.</dd>
<dt><code class="docutils literal"><span class="pre">improved-plan</span></code> (binary)</dt>
<dd>Like <code class="docutils literal"><span class="pre">solver-plan</span></code>, but with all non-inplace packages improved
into pre-existing copies from the store.</dd>
<dt><code class="docutils literal"><span class="pre">plan.json</span></code> (JSON)</dt>
<dd><p class="first">A JSON serialization of the computed install plan intended
for integrating <code class="docutils literal"><span class="pre">cabal</span></code> with external tooling.
The <a class="reference external" href="http://hackage.haskell.org/package/cabal-plan">cabal-plan</a>
package provides a library for parsing <code class="docutils literal"><span class="pre">plan.json</span></code> files into a
Haskell data structure as well as an example tool showing possible
applications.</p>
<div class="admonition-todo last admonition" id="index-0">
<p class="first admonition-title">Todo</p>
<p class="last">Document JSON schema (including version history of schema)</p>
</div>
</dd>
</dl>
<p>Note that every package also has a local cache managed by the Cabal
build system, e.g., in <code class="docutils literal"><span class="pre">$distdir/cache</span></code>.</p>
<p>There is another useful file in <code class="docutils literal"><span class="pre">dist-newstyle/cache</span></code>,
<code class="docutils literal"><span class="pre">plan.json</span></code>, which is a JSON serialization of the computed install
plan and is intended for integrating with external tooling.</p>
</div>
</div>
<div class="section" id="commands">
<h1>5.4. Commands<a class="headerlink" href="#commands" title="Permalink to this headline">¶</a></h1>
<p>We now give an in-depth description of all the commands, describing the
arguments and flags they accept.</p>
<div class="section" id="cabal-new-configure">
<h2>5.4.1. cabal new-configure<a class="headerlink" href="#cabal-new-configure" title="Permalink to this headline">¶</a></h2>
<p><code class="docutils literal"><span class="pre">cabal</span> <span class="pre">new-configure</span></code> takes a set of arguments and writes a
<code class="docutils literal"><span class="pre">cabal.project.local</span></code> file based on the flags passed to this command.
<code class="docutils literal"><span class="pre">cabal</span> <span class="pre">new-configure</span> <span class="pre">FLAGS;</span> <span class="pre">cabal</span> <span class="pre">new-build</span></code> is roughly equivalent to
<code class="docutils literal"><span class="pre">cabal</span> <span class="pre">new-build</span> <span class="pre">FLAGS</span></code>, except that with <code class="docutils literal"><span class="pre">new-configure</span></code> the flags
are persisted to all subsequent calls to <code class="docutils literal"><span class="pre">new-build</span></code>.</p>
<p><code class="docutils literal"><span class="pre">cabal</span> <span class="pre">new-configure</span></code> is intended to be a convenient way to write out
a <code class="docutils literal"><span class="pre">cabal.project.local</span></code> for simple configurations; e.g.,
<code class="docutils literal"><span class="pre">cabal</span> <span class="pre">new-configure</span> <span class="pre">-w</span> <span class="pre">ghc-7.8</span></code> would ensure that all subsequent
builds with <code class="docutils literal"><span class="pre">cabal</span> <span class="pre">new-build</span></code> are performed with the compiler
<code class="docutils literal"><span class="pre">ghc-7.8</span></code>. For more complex configuration, we recommend writing the
<code class="docutils literal"><span class="pre">cabal.project.local</span></code> file directly (or placing it in
<code class="docutils literal"><span class="pre">cabal.project</span></code>!)</p>
<p><code class="docutils literal"><span class="pre">cabal</span> <span class="pre">new-configure</span></code> inherits options from <code class="docutils literal"><span class="pre">Cabal</span></code>. semantics:</p>
<ul class="simple">
<li>Any flag accepted by <code class="docutils literal"><span class="pre">./Setup</span> <span class="pre">configure</span></code>.</li>
<li>Any flag accepted by <code class="docutils literal"><span class="pre">cabal</span> <span class="pre">configure</span></code> beyond
<code class="docutils literal"><span class="pre">./Setup</span> <span class="pre">configure</span></code>, namely <code class="docutils literal"><span class="pre">--cabal-lib-version</span></code>,
<code class="docutils literal"><span class="pre">--constraint</span></code>, <code class="docutils literal"><span class="pre">--preference</span></code> and <code class="docutils literal"><span class="pre">--solver.</span></code></li>
<li>Any flag accepted by <code class="docutils literal"><span class="pre">cabal</span> <span class="pre">install</span></code> beyond <code class="docutils literal"><span class="pre">./Setup</span> <span class="pre">configure</span></code>.</li>
<li>Any flag accepted by <code class="docutils literal"><span class="pre">./Setup</span> <span class="pre">haddock</span></code>.</li>
</ul>
<p>The options of all of these flags apply only to <em>local</em> packages in a
project; this behavior is different than that of <code class="docutils literal"><span class="pre">cabal</span> <span class="pre">install</span></code>,
which applies flags to every package that would be built. The motivation
for this is to avoid an innocuous addition to the flags of a package
resulting in a rebuild of every package in the store (which might need
to happen if a flag actually applied to every transitive dependency). To
apply options to an external package, use a <code class="docutils literal"><span class="pre">package</span></code> stanza in a
<code class="docutils literal"><span class="pre">cabal.project</span></code> file.</p>
</div>
<div class="section" id="cabal-new-update">
<h2>5.4.2. cabal new-update<a class="headerlink" href="#cabal-new-update" title="Permalink to this headline">¶</a></h2>
<p><code class="docutils literal"><span class="pre">cabal</span> <span class="pre">new-update</span></code> updates the state of the package index. If the
project contains multiple remote package repositories it will update
the index of all of them (e.g. when using overlays).</p>
<p>Seom examples:</p>
<div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">$</span> cabal new-update <span class="c1"># update all remote repos</span>
<span class="gp">$</span> cabal new-update head.hackage <span class="c1"># update only head.hackage</span>
</pre></div>
</div>
</div>
<div class="section" id="cabal-new-build">
<h2>5.4.3. cabal new-build<a class="headerlink" href="#cabal-new-build" title="Permalink to this headline">¶</a></h2>
<p><code class="docutils literal"><span class="pre">cabal</span> <span class="pre">new-build</span></code> takes a set of targets and builds them. It
automatically handles building and installing any dependencies of these
targets.</p>
<p>A target can take any of the following forms:</p>
<ul>
<li><p class="first">A package target: <code class="docutils literal"><span class="pre">package</span></code>, which specifies that all enabled
components of a package to be built. By default, test suites and
benchmarks are <em>not</em> enabled, unless they are explicitly requested
(e.g., via <code class="docutils literal"><span class="pre">--enable-tests</span></code>.)</p>
</li>
<li><p class="first">A component target: <code class="docutils literal"><span class="pre">[package:][ctype:]component</span></code>, which specifies
a specific component (e.g., a library, executable, test suite or
benchmark) to be built.</p>
</li>
<li><p class="first">All packages: <code class="docutils literal"><span class="pre">all</span></code>, which specifies all packages within the project.</p>
</li>
<li><p class="first">Components of a particular type: <code class="docutils literal"><span class="pre">package:ctypes</span></code>, <code class="docutils literal"><span class="pre">all:ctypes</span></code>:
which specifies all components of the given type. Where valid
<code class="docutils literal"><span class="pre">ctypes</span></code> are:</p>
<blockquote>
<div><ul class="simple">
<li><code class="docutils literal"><span class="pre">libs</span></code>, <code class="docutils literal"><span class="pre">libraries</span></code>,</li>
<li><code class="docutils literal"><span class="pre">flibs</span></code>, <code class="docutils literal"><span class="pre">foreign-libraries</span></code>,</li>
<li><code class="docutils literal"><span class="pre">exes</span></code>, <code class="docutils literal"><span class="pre">executables</span></code>,</li>
<li><code class="docutils literal"><span class="pre">tests</span></code>,</li>
<li><code class="docutils literal"><span class="pre">benches</span></code>, <code class="docutils literal"><span class="pre">benchmarks</span></code>.</li>
</ul>
</div></blockquote>
</li>
</ul>
<p>In component targets, <code class="docutils literal"><span class="pre">package:</span></code> and <code class="docutils literal"><span class="pre">ctype:</span></code> (valid component types
are <code class="docutils literal"><span class="pre">lib</span></code>, <code class="docutils literal"><span class="pre">flib</span></code>, <code class="docutils literal"><span class="pre">exe</span></code>, <code class="docutils literal"><span class="pre">test</span></code> and <code class="docutils literal"><span class="pre">bench</span></code>) can be used to
disambiguate when multiple packages define the same component, or the
same component name is used in a package (e.g., a package <code class="docutils literal"><span class="pre">foo</span></code>
defines both an executable and library named <code class="docutils literal"><span class="pre">foo</span></code>). We always prefer
interpreting a target as a package name rather than as a component name.</p>
<p>Some example targets:</p>
<div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">$</span> cabal new-build lib:foo-pkg <span class="c1"># build the library named foo-pkg</span>
<span class="gp">$</span> cabal new-build foo-pkg:foo-tests <span class="c1"># build foo-tests in foo-pkg</span>
</pre></div>
</div>
<p>(There is also syntax for specifying module and file targets, but it
doesn’t currently do anything.)</p>
<p>Beyond a list of targets, <code class="docutils literal"><span class="pre">cabal</span> <span class="pre">new-build</span></code> accepts all the flags that
<code class="docutils literal"><span class="pre">cabal</span> <span class="pre">new-configure</span></code> takes. Most of these flags are only taken into
consideration when building local packages; however, some flags may
cause extra store packages to be built (for example,
<code class="docutils literal"><span class="pre">--enable-profiling</span></code> will automatically make sure profiling libraries
for all transitive dependencies are built and installed.)</p>
</div>
<div class="section" id="cabal-new-repl">
<h2>5.4.4. cabal new-repl<a class="headerlink" href="#cabal-new-repl" title="Permalink to this headline">¶</a></h2>
<p><code class="docutils literal"><span class="pre">cabal</span> <span class="pre">new-repl</span> <span class="pre">TARGET</span></code> loads all of the modules of the target into
GHCi as interpreted bytecode. In addition to <code class="docutils literal"><span class="pre">cabal</span> <span class="pre">new-build</span></code>’s flags,
it takes an additional <code class="docutils literal"><span class="pre">--repl-options</span></code> flag.</p>
<p>To avoid <code class="docutils literal"><span class="pre">ghci</span></code> specific flags from triggering unneeded global rebuilds these
flags are now stripped from the internal configuration. As a result
<code class="docutils literal"><span class="pre">--ghc-options</span></code> will no longer (reliably) work to pass flags to <code class="docutils literal"><span class="pre">ghci</span></code> (or
other repls). Instead, you should use the new <code class="docutils literal"><span class="pre">--repl-options</span></code> flag to
specify these options to the invoked repl. (This flag also works on <code class="docutils literal"><span class="pre">cabal</span>
<span class="pre">repl</span></code> and <code class="docutils literal"><span class="pre">Setup</span> <span class="pre">repl</span></code> on sufficiently new versions of Cabal.)</p>
<p>Currently, it is not supported to pass multiple targets to <code class="docutils literal"><span class="pre">new-repl</span></code>
(<code class="docutils literal"><span class="pre">new-repl</span></code> will just successively open a separate GHCi session for
each target.)</p>
<p>It also provides a way to experiment with libraries without needing to download
them manually or to install them globally.</p>
<p>This command opens a REPL with the current default target loaded, and a version
of the <code class="docutils literal"><span class="pre">vector</span></code> package matching that specification exposed.</p>
<div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">$</span> cabal new-repl --build-depends <span class="s2">"vector >= 0.12 && < 0.13"</span>
</pre></div>
</div>
<p>Both of these commands do the same thing as the above, but only exposes <code class="docutils literal"><span class="pre">base</span></code>,
<code class="docutils literal"><span class="pre">vector</span></code>, and the``vector`` package’s transitive dependencies even if the user
is in a project context.</p>
<div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">$</span> cabal new-repl --ignore-project --build-depends <span class="s2">"vector >= 0.12 && < 0.13"</span>
<span class="gp">$</span> cabal new-repl --project<span class="o">=</span><span class="s1">''</span> --build-depends <span class="s2">"vector >= 0.12 && < 0.13"</span>
</pre></div>
</div>
<p>This command would add <code class="docutils literal"><span class="pre">vector</span></code>, but not (for example) <code class="docutils literal"><span class="pre">primitive</span></code>, because
it only includes the packages specified on the command line (and <code class="docutils literal"><span class="pre">base</span></code>, which
cannot be excluded for technical reasons).</p>
<div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">$</span> cabal new-repl --build-depends vector --no-transitive-deps
</pre></div>
</div>
</div>
<div class="section" id="cabal-new-run">
<h2>5.4.5. cabal new-run<a class="headerlink" href="#cabal-new-run" title="Permalink to this headline">¶</a></h2>
<p><code class="docutils literal"><span class="pre">cabal</span> <span class="pre">new-run</span> <span class="pre">[TARGET</span> <span class="pre">[ARGS]]</span></code> runs the executable specified by the
target, which can be a component, a package or can be left blank, as
long as it can uniquely identify an executable within the project.
Tests and benchmarks are also treated as executables.</p>
<p>See <a class="reference external" href="#cabal-new-build">the new-build section</a> for the target syntax.</p>
<p>Except in the case of the empty target, the strings after it will be
passed to the executable as arguments.</p>
<p>If one of the arguments starts with <code class="docutils literal"><span class="pre">-</span></code> it will be interpreted as
a cabal flag, so if you need to pass flags to the executable you
have to separate them with <code class="docutils literal"><span class="pre">--</span></code>.</p>
<div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">$</span> cabal new-run target -- -a -bcd --argument
</pre></div>
</div>
<p>‘new-run’ also supports running script files that use a certain format. With
a script that looks like:</p>
<div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">#</span>!/usr/bin/env cabal
<span class="go">{- cabal:</span>
<span class="go">build-depends: base ^>= 4.11</span>
<span class="go"> , shelly ^>= 1.8.1</span>
<span class="go">-}</span>
<span class="go">main :: IO ()</span>
<span class="go">main = do</span>
<span class="go"> ...</span>
</pre></div>
</div>
<p>It can either be executed like any other script, using <code class="docutils literal"><span class="pre">cabal</span></code> as an
interpreter, or through this command:</p>
<div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">$</span> cabal new-run script.hs
<span class="gp">$</span> cabal new-run script.hs -- --arg1 <span class="c1"># args are passed like this</span>
</pre></div>
</div>
</div>
<div class="section" id="cabal-new-freeze">
<h2>5.4.6. cabal new-freeze<a class="headerlink" href="#cabal-new-freeze" title="Permalink to this headline">¶</a></h2>
<p><code class="docutils literal"><span class="pre">cabal</span> <span class="pre">new-freeze</span></code> writes out a <strong>freeze file</strong> which records all of
the versions and flags which that are picked by the solver under the
current index and flags. Default name of this file is
<code class="docutils literal"><span class="pre">cabal.project.freeze</span></code> but in combination with a
<code class="docutils literal"><span class="pre">--project-file=my.project</span></code> flag (see <a class="reference internal" href="#cmdoption-project-file"><span class="std std-ref">project-file</span></a>)
the name will be <code class="docutils literal"><span class="pre">my.project.freeze</span></code>.
A freeze file has the same syntax as <code class="docutils literal"><span class="pre">cabal.project</span></code> and looks
something like this:</p>
<div class="highlight-cabal"><div class="highlight"><pre><span></span><span class="k">constraints</span><span class="p">:</span> HTTP <span class="o">==</span>4000.3.3<span class="p">,</span>
HTTP +warp-tests -warn-as-error -network23 +network-uri -mtl1 -conduit10<span class="p">,</span>
QuickCheck <span class="o">==</span>2.9.1<span class="p">,</span>
QuickCheck +templatehaskell<span class="p">,</span>
<span class="w"> </span><span class="c1">-- etc...</span>
</pre></div>
</div>
<p>For end-user executables, it is recommended that you distribute the
<code class="docutils literal"><span class="pre">cabal.project.freeze</span></code> file in your source repository so that all
users see a consistent set of dependencies. For libraries, this is not
recommended: users often need to build against different versions of
libraries than what you developed against.</p>
</div>
<div class="section" id="cabal-new-bench">
<h2>5.4.7. cabal new-bench<a class="headerlink" href="#cabal-new-bench" title="Permalink to this headline">¶</a></h2>
<p><code class="docutils literal"><span class="pre">cabal</span> <span class="pre">new-bench</span> <span class="pre">[TARGETS]</span> <span class="pre">[OPTIONS]</span></code> runs the specified benchmarks
(all the benchmarks in the current package by default), first ensuring
they are up to date.</p>
</div>
<div class="section" id="cabal-new-test">
<h2>5.4.8. cabal new-test<a class="headerlink" href="#cabal-new-test" title="Permalink to this headline">¶</a></h2>
<p><code class="docutils literal"><span class="pre">cabal</span> <span class="pre">new-test</span> <span class="pre">[TARGETS]</span> <span class="pre">[OPTIONS]</span></code> runs the specified test suites
(all the test suites in the current package by default), first ensuring
they are up to date.</p>
</div>
<div class="section" id="cabal-new-haddock">
<h2>5.4.9. cabal new-haddock<a class="headerlink" href="#cabal-new-haddock" title="Permalink to this headline">¶</a></h2>
<p><code class="docutils literal"><span class="pre">cabal</span> <span class="pre">new-haddock</span> <span class="pre">[FLAGS]</span> <span class="pre">[TARGET]</span></code> builds Haddock documentation for
the specified packages within the project.</p>
<p>If a target is not a library <a class="reference internal" href="#cfg-field-haddock-benchmarks" title="cabal.project haddock-benchmarks field "><code class="xref cabal cabal-cfg-field docutils literal"><span class="pre">haddock-benchmarks</span></code></a>,
<a class="reference internal" href="#cfg-field-haddock-executables" title="cabal.project haddock-executables field "><code class="xref cabal cabal-cfg-field docutils literal"><span class="pre">haddock-executables</span></code></a>, <a class="reference internal" href="#cfg-field-haddock-internal" title="cabal.project haddock-internal field "><code class="xref cabal cabal-cfg-field docutils literal"><span class="pre">haddock-internal</span></code></a>,
<a class="reference internal" href="#cfg-field-haddock-tests" title="cabal.project haddock-tests field "><code class="xref cabal cabal-cfg-field docutils literal"><span class="pre">haddock-tests</span></code></a> will be implied as necessary.</p>
</div>
<div class="section" id="cabal-new-exec">
<h2>5.4.10. cabal new-exec<a class="headerlink" href="#cabal-new-exec" title="Permalink to this headline">¶</a></h2>
<p><code class="docutils literal"><span class="pre">cabal</span> <span class="pre">new-exec</span> <span class="pre">[FLAGS]</span> <span class="pre">[--]</span> <span class="pre">COMMAND</span> <span class="pre">[--]</span> <span class="pre">[ARGS]</span></code> runs the specified command
using the project’s environment. That is, passing the right flags to compiler
invocations and bringing the project’s executables into scope.</p>
</div>
<div class="section" id="cabal-new-install">
<h2>5.4.11. cabal new-install<a class="headerlink" href="#cabal-new-install" title="Permalink to this headline">¶</a></h2>
<p><code class="docutils literal"><span class="pre">cabal</span> <span class="pre">new-install</span> <span class="pre">[FLAGS]</span> <span class="pre">PACKAGES</span></code> builds the specified packages and
symlinks their executables in <code class="docutils literal"><span class="pre">symlink-bindir</span></code> (usually <code class="docutils literal"><span class="pre">~/.cabal/bin</span></code>).</p>
<p>For example this command will build the latest <code class="docutils literal"><span class="pre">cabal-install</span></code> and symlink
its <code class="docutils literal"><span class="pre">cabal</span></code> executable:</p>
<div class="highlight-cabal"><div class="highlight"><pre><span></span>$ cabal new-install cabal-install
</pre></div>
</div>
<p>In addition, it’s possible to use <code class="docutils literal"><span class="pre">cabal</span> <span class="pre">new-install</span></code> to install components
of a local project. For example, with an up-to-date Git clone of the Cabal
repository, this command will build cabal-install HEAD and symlink the
<code class="docutils literal"><span class="pre">cabal</span></code> executable:</p>
<div class="highlight-cabal"><div class="highlight"><pre><span></span>$ cabal new-install exe<span class="p">:</span>cabal
</pre></div>
</div>
<p>It is also possible to “install” libraries using the <code class="docutils literal"><span class="pre">--lib</span></code> flag. For
example, this command will build the latest Cabal library and install it:</p>
<div class="highlight-cabal"><div class="highlight"><pre><span></span>$ cabal new-install --lib Cabal
</pre></div>
</div>
<p>This works by managing GHC environments. By default, it is writing to the
global environment in <code class="docutils literal"><span class="pre">~/.ghc/$ARCH-$OS-$GHCVER/environments/default</span></code>.
<code class="docutils literal"><span class="pre">new-install</span></code> provides the <code class="docutils literal"><span class="pre">--package-env</span></code> flag to control which of
these environments is modified.</p>
<p>This command will modify the environment file in the current directory:</p>
<div class="highlight-cabal"><div class="highlight"><pre><span></span>$ cabal new-install --lib Cabal --package-env .
</pre></div>
</div>
<p>This command will modify the enviroment file in the <code class="docutils literal"><span class="pre">~/foo</span></code> directory:</p>
<div class="highlight-cabal"><div class="highlight"><pre><span></span>$ cabal new-install --lib Cabal --package-env foo/
</pre></div>
</div>
<p>Do note that the results of the previous two commands will be overwritten by
the use of other new-style commands, so it is not reccomended to use them inside
a project directory.</p>
<p>This command will modify the environment in the “local.env” file in the
current directory:</p>
<div class="highlight-cabal"><div class="highlight"><pre><span></span>$ cabal new-install --lib Cabal --package-env local.env
</pre></div>
</div>
<p>This command will modify the <code class="docutils literal"><span class="pre">myenv</span></code> named global environment:</p>
<div class="highlight-cabal"><div class="highlight"><pre><span></span>$ cabal new-install --lib Cabal --package-env myenv
</pre></div>
</div>
<p>If you wish to create a named environment file in the current directory where
the name does not contain an extension, you must reference it as <code class="docutils literal"><span class="pre">./myenv</span></code>.</p>
<p>You can learn more about how to use these environments in <a class="reference external" href="https://downloads.haskell.org/~ghc/latest/docs/html/users_guide/packages.html#package-environments">this section of the
GHC manual</a>.</p>
</div>
<div class="section" id="cabal-new-clean">
<h2>5.4.12. cabal new-clean<a class="headerlink" href="#cabal-new-clean" title="Permalink to this headline">¶</a></h2>
<p><code class="docutils literal"><span class="pre">cabal</span> <span class="pre">new-clean</span> <span class="pre">[FLAGS]</span></code> cleans up the temporary files and build artifacts
stored in the <code class="docutils literal"><span class="pre">dist-newstyle</span></code> folder.</p>
<p>By default, it removes the entire folder, but it can also spare the configuration
and caches if the <code class="docutils literal"><span class="pre">--save-config</span></code> option is given, in which case it only removes
the build artefacts (<code class="docutils literal"><span class="pre">.hi</span></code>, <code class="docutils literal"><span class="pre">.o</span></code> along with any other temporary files generated
by the compiler, along with the build output).</p>
</div>
<div class="section" id="cabal-new-sdist">
<h2>5.4.13. cabal new-sdist<a class="headerlink" href="#cabal-new-sdist" title="Permalink to this headline">¶</a></h2>
<p><code class="docutils literal"><span class="pre">cabal</span> <span class="pre">new-sdist</span> <span class="pre">[FLAGS]</span> <span class="pre">[TARGETS]</span></code> takes the crucial files needed to build <code class="docutils literal"><span class="pre">TARGETS</span></code>
and puts them into an archive format ready for upload to Hackage. These archives are stable
and two archives of the same format built from the same source will hash to the same value.</p>
<p><code class="docutils literal"><span class="pre">cabal</span> <span class="pre">new-sdist</span></code> takes the following flags:</p>
<ul class="simple">
<li><code class="docutils literal"><span class="pre">-l</span></code>, <code class="docutils literal"><span class="pre">--list-only</span></code>: Rather than creating an archive, lists files that would be included.
Output is to <code class="docutils literal"><span class="pre">stdout</span></code> by default. The file paths are relative to the project’s root
directory.</li>
<li><code class="docutils literal"><span class="pre">--targz</span></code>: Output an archive in <code class="docutils literal"><span class="pre">.tar.gz</span></code> format.</li>
<li><code class="docutils literal"><span class="pre">--zip</span></code>: Output an archive in <code class="docutils literal"><span class="pre">.zip</span></code> format.</li>
<li><code class="docutils literal"><span class="pre">-o</span></code>, <code class="docutils literal"><span class="pre">--output-dir</span></code>: Sets the output dir, if a non-default one is desired. The default is
<code class="docutils literal"><span class="pre">dist-newstyle/sdist/</span></code>. <code class="docutils literal"><span class="pre">--output-dir</span> <span class="pre">-</span></code> will send output to <code class="docutils literal"><span class="pre">stdout</span></code>
unless multiple archives are being created.</li>
<li><code class="docutils literal"><span class="pre">-z</span></code>, <code class="docutils literal"><span class="pre">--null</span></code>: Only used with <code class="docutils literal"><span class="pre">--list-only</span></code>. Separates filenames with a NUL
byte instead of newlines.</li>
</ul>
<p><code class="docutils literal"><span class="pre">new-sdist</span></code> is inherently incompatible with sdist hooks, not due to implementation but due
to fundamental core invariants (same source code should result in the same tarball, byte for
byte) that must be satisfied for it to function correctly in the larger new-build ecosystem.
<code class="docutils literal"><span class="pre">autogen-modules</span></code> is able to replace uses of the hooks to add generated modules, along with
the custom publishing of Haddock documentation to Hackage.</p>
</div>
</div>
<div class="section" id="configuring-builds-with-cabal-project">
<h1>5.5. Configuring builds with cabal.project<a class="headerlink" href="#configuring-builds-with-cabal-project" title="Permalink to this headline">¶</a></h1>
<p><code class="docutils literal"><span class="pre">cabal.project</span></code> files support a variety of options which configure the
details of your build. The general syntax of a <code class="docutils literal"><span class="pre">cabal.project</span></code> file is
similar to that of a Cabal file: there are a number of fields, some of
which live inside stanzas:</p>
<div class="highlight-cabal"><div class="highlight"><pre><span></span><span class="k">packages</span><span class="p">:</span> */*.cabal
<span class="k">with-compiler</span><span class="p">:</span> /opt/ghc/8.0.1/bin/ghc
<span class="k">package</span> cryptohash
<span class="w"> </span><span class="k">optimization</span><span class="p">:</span> False
</pre></div>
</div>
<p>In general, the accepted field names coincide with the accepted command
line flags that <code class="docutils literal"><span class="pre">cabal</span> <span class="pre">install</span></code> and other commands take. For example,
<code class="docutils literal"><span class="pre">cabal</span> <span class="pre">new-configure</span> <span class="pre">--enable-profiling</span></code> will write out a project
file with <code class="docutils literal"><span class="pre">profiling:</span> <span class="pre">True</span></code>.</p>
<p>The full configuration of a project is determined by combining the
following sources (later entries override earlier ones):</p>
<ol class="arabic simple">
<li><code class="docutils literal"><span class="pre">~/.cabal/config</span></code> (the user-wide global configuration)</li>
<li><code class="docutils literal"><span class="pre">cabal.project</span></code> (the project configuratoin)</li>
<li><code class="docutils literal"><span class="pre">cabal.project.freeze</span></code> (the output of <code class="docutils literal"><span class="pre">cabal</span> <span class="pre">new-freeze</span></code>)</li>
<li><code class="docutils literal"><span class="pre">cabal.project.local</span></code> (the output of <code class="docutils literal"><span class="pre">cabal</span> <span class="pre">new-configure</span></code>)</li>
</ol>
<div class="section" id="specifying-the-local-packages">
<h2>5.5.1. Specifying the local packages<a class="headerlink" href="#specifying-the-local-packages" title="Permalink to this headline">¶</a></h2>
<p>The following top-level options specify what the local packages of a
project are:</p>
<dl class="cfg-field">
<dt id="cfg-field-packages">
<code class="descname">packages</code><code class="descclassname">: </code><em class="property">package location list (space or comma separated)</em><a class="headerlink" href="#cfg-field-packages" title="Permalink to this definition">¶</a></dt>
<dd><table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Default value:</th><td class="field-body"><code class="docutils literal"><span class="pre">./*.cabal</span></code></td>
</tr>
</tbody>
</table>
<p>Specifies the list of package locations which contain the local
packages to be built by this project. Package locations can take the
following forms:</p>
<ol class="arabic simple">
<li>They can specify a Cabal file, or a directory containing a Cabal
file, e.g., <code class="docutils literal"><span class="pre">packages:</span> <span class="pre">Cabal</span> <span class="pre">cabal-install/cabal-install.cabal</span></code>.</li>
<li>They can specify a glob-style wildcards, which must match one or
more (a) directories containing a (single) Cabal file, (b) Cabal
files (extension <code class="docutils literal"><span class="pre">.cabal</span></code>), or (c) tarballs which contain Cabal
packages (extension <code class="docutils literal"><span class="pre">.tar.gz</span></code>).
For example, to match all Cabal files in all
subdirectories, as well as the Cabal projects in the parent
directories <code class="docutils literal"><span class="pre">foo</span></code> and <code class="docutils literal"><span class="pre">bar</span></code>, use
<code class="docutils literal"><span class="pre">packages:</span> <span class="pre">*/*.cabal</span> <span class="pre">../{foo,bar}/</span></code></li>
<li>[STRIKEOUT:They can specify an <code class="docutils literal"><span class="pre">http</span></code>, <code class="docutils literal"><span class="pre">https</span></code> or <code class="docutils literal"><span class="pre">file</span></code>
URL, representing the path to a remote tarball to be downloaded
and built.] (not implemented yet)</li>
</ol>
<p>There is no command line variant of this field; see <a class="reference external" href="https://github.com/haskell/cabal/issues/3585">#3585</a>.</p>
</dd></dl>
<dl class="cfg-field">
<dt id="cfg-field-optional-packages">
<code class="descname">optional-packages</code><code class="descclassname">: </code><em class="property">package location list (space or comma-separated)</em><a class="headerlink" href="#cfg-field-optional-packages" title="Permalink to this definition">¶</a></dt>
<dd><table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Default value:</th><td class="field-body"><code class="docutils literal"><span class="pre">./*/*.cabal</span></code></td>
</tr>
</tbody>
</table>
<p>Like <a class="reference internal" href="#cfg-field-packages" title="cabal.project packages field "><code class="xref cabal cabal-cfg-field docutils literal"><span class="pre">packages</span></code></a>, specifies a list of package locations
containing local packages to be built. Unlike <a class="reference internal" href="#cfg-field-packages" title="cabal.project packages field "><code class="xref cabal cabal-cfg-field docutils literal"><span class="pre">packages</span></code></a>,
if we glob for a package, it is permissible for the glob to match against
zero packages. The intended use-case for <a class="reference internal" href="#cfg-field-optional-packages" title="cabal.project optional-packages field "><code class="xref cabal cabal-cfg-field docutils literal"><span class="pre">optional-packages</span></code></a>
is to make it so that vendored packages can be automatically picked up if
they are placed in a subdirectory, but not error if there aren’t any.</p>
<p>There is no command line variant of this field.</p>
</dd></dl>
<dl class="cfg-field">
<dt id="cfg-field-extra-packages">
<code class="descname">extra-packages</code><code class="descclassname">: </code><em class="property">package list with version bounds (comma separated)</em><a class="headerlink" href="#cfg-field-extra-packages" title="Permalink to this definition">¶</a></dt>
<dd><p>[STRIKEOUT:Specifies a list of external packages from Hackage which
should be considered local packages.] (Not implemented)</p>
<p>There is no command line variant of this field.</p>
</dd></dl>
<p>[STRIKEOUT:There is also a stanza <code class="docutils literal"><span class="pre">source-repository-package</span></code> for
specifying packages from an external version control.] (Not
implemented.)</p>
<p>All local packages are <em>vendored</em>, in the sense that if other packages
(including external ones from Hackage) depend on a package with the name
of a local package, the local package is preferentially used. This
motivates the default settings:</p>
<div class="highlight-cabal"><div class="highlight"><pre><span></span><span class="k">packages</span><span class="p">:</span> ./*.cabal
<span class="k">optional-packages</span><span class="p">:</span> ./*/*.cabal
</pre></div>
</div>
<p>…any package can be vendored simply by making a checkout in the
top-level project directory, as might be seen in this hypothetical
directory layout:</p>
<div class="highlight-cabal"><div class="highlight"><pre><span></span><span class="k">foo</span>.cabal
<span class="k">foo-helper</span>/ # local package
<span class="k">unix</span>/ # vendored external package
</pre></div>
</div>
<p>All of these options support globs. <code class="docutils literal"><span class="pre">cabal</span> <span class="pre">new-build</span></code> has its own glob
format:</p>
<ul class="simple">
<li>Anywhere in a path, as many times as you like, you can specify an
asterisk <code class="docutils literal"><span class="pre">*</span></code> wildcard. E.g., <code class="docutils literal"><span class="pre">*/*.cabal</span></code> matches all <code class="docutils literal"><span class="pre">.cabal</span></code>
files in all immediate subdirectories. Like in glob(7), asterisks do
not match hidden files unless there is an explicit period, e.g.,
<code class="docutils literal"><span class="pre">.*/foo.cabal</span></code> will match <code class="docutils literal"><span class="pre">.private/foo.cabal</span></code> (but
<code class="docutils literal"><span class="pre">*/foo.cabal</span></code> will not).</li>
<li>You can use braces to specify specific directories; e.g.,
<code class="docutils literal"><span class="pre">{vendor,pkgs}/*.cabal</span></code> matches all Cabal files in the <code class="docutils literal"><span class="pre">vendor</span></code>
and <code class="docutils literal"><span class="pre">pkgs</span></code> subdirectories.</li>
</ul>
<p>Formally, the format described by the following BNF:</p>
<div class="highlight-abnf"><div class="highlight"><pre><span></span><span class="nc">FilePathGlob</span> ::<span class="o">=</span> <span class="nc">FilePathRoot</span> <span class="nc">FilePathGlobRel</span>
<span class="nc">FilePathRoot</span> ::<span class="o">=</span> {- <span class="nc">empty</span> -} # <span class="nc">relative</span> <span class="nc">to</span> <span class="nc">cabal</span>.<span class="nc">project</span>
| <span class="l">"/"</span> # <span class="nc">Unix</span> <span class="nc">root</span>
| <span class="p">[</span><span class="nc">a-zA-Z</span><span class="p">]</span> <span class="l">":"</span> <span class="p">[</span><span class="o">/</span>\\<span class="p">]</span> # <span class="nc">Windows</span> <span class="nc">root</span>
| <span class="l">"~"</span> # <span class="nc">home</span> <span class="nc">directory</span>
<span class="nc">FilePathGlobRel</span> ::<span class="o">=</span> <span class="nc">Glob</span> <span class="l">"/"</span> <span class="nc">FilePathGlobRel</span> # <span class="nc">Unix</span> <span class="nc">directory</span>
| <span class="nc">Glob</span> <span class="l">"\\"</span> <span class="nc">FilePathGlobRel</span> # <span class="nc">Windows</span> <span class="nc">directory</span>
| <span class="nc">Glob</span> # <span class="nc">file</span>
| {- <span class="nc">empty</span> -} # <span class="nc">trailing</span> <span class="nc">slash</span>
<span class="nc">Glob</span> ::<span class="o">=</span> <span class="nc">GlobPiece</span> <span class="o">*</span>
<span class="nc">GlobPiece</span> ::<span class="o">=</span> <span class="l">"*"</span> # <span class="nc">wildcard</span>
| <span class="p">[</span>^<span class="o">*</span>{},<span class="o">/</span>\\<span class="p">]</span> <span class="o">*</span> # <span class="nc">literal</span> <span class="nc">string</span>
| <span class="l">"\\"</span> <span class="p">[</span><span class="o">*</span>{},<span class="p">]</span> # <span class="nc">escaped</span> <span class="nc">reserved</span> <span class="nc">character</span>
| <span class="l">"{"</span> <span class="nc">Glob</span> <span class="l">","</span> ... <span class="l">","</span> <span class="nc">Glob</span> <span class="l">"}"</span> # <span class="nc">union</span> <span class="p">(</span><span class="nc">match</span> <span class="nc">any</span> <span class="nc">of</span> <span class="nc">these</span><span class="p">)</span>
</pre></div>
</div>
</div>
<div class="section" id="global-configuration-options">
<h2>5.5.2. Global configuration options<a class="headerlink" href="#global-configuration-options" title="Permalink to this headline">¶</a></h2>
<p>The following top-level configuration options are not specific to any
package, and thus apply globally:</p>
<dl class="cfg-field">
<dt id="cfg-field-verbose">
<code class="descname">verbose</code><code class="descclassname">: </code><em class="property">nat</em><a class="headerlink" href="#cfg-field-verbose" title="Permalink to this definition">¶</a></dt>
<dt id="cfg-flag---verbose">
<code class="descname">--verbose</code><code class="descclassname">=n</code><code class="descname">, </code><code class="descname">-vn</code><code class="descclassname"> </code><a class="headerlink" href="#cfg-flag---verbose" title="Permalink to this definition">¶</a></dt>
<dd><table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Default value:</th><td class="field-body">1</td>
</tr>
</tbody>
</table>
<p>Control the verbosity of <code class="docutils literal"><span class="pre">cabal</span></code> commands, valid values are from 0
to 3.</p>
<p>The command line variant of this field is <code class="docutils literal"><span class="pre">--verbose=2</span></code>; a short
form <code class="docutils literal"><span class="pre">-v2</span></code> is also supported.</p>
</dd></dl>
<dl class="cfg-field">
<dt id="cfg-field-jobs">
<code class="descname">jobs</code><code class="descclassname">: </code><em class="property">nat or $ncpus</em><a class="headerlink" href="#cfg-field-jobs" title="Permalink to this definition">¶</a></dt>
<dt id="cfg-flag---jobs">
<code class="descname">--jobs</code><code class="descclassname">=n</code><code class="descname">, </code><code class="descname">-jn</code><code class="descclassname"> </code><code class="descname">, </code><code class="descname">--jobs</code><code class="descclassname">=$ncpus</code><a class="headerlink" href="#cfg-flag---jobs" title="Permalink to this definition">¶</a></dt>
<dd><table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Default value:</th><td class="field-body">1</td>
</tr>
</tbody>
</table>
<p>Run <em>nat</em> jobs simultaneously when building. If <code class="docutils literal"><span class="pre">$ncpus</span></code> is
specified, run the number of jobs equal to the number of CPUs.
Package building is often quite parallel, so turning on parallelism
can speed up build times quite a bit!</p>
<p>The command line variant of this field is <code class="docutils literal"><span class="pre">--jobs=2</span></code>; a short form
<code class="docutils literal"><span class="pre">-j2</span></code> is also supported; a bare <code class="docutils literal"><span class="pre">--jobs</span></code> or <code class="docutils literal"><span class="pre">-j</span></code> is equivalent
to <code class="docutils literal"><span class="pre">--jobs=$ncpus</span></code>.</p>
</dd></dl>
<dl class="cfg-field">
<dt id="cfg-field-keep-going">
<code class="descname">keep-going</code><code class="descclassname">: </code><em class="property">boolean</em><a class="headerlink" href="#cfg-field-keep-going" title="Permalink to this definition">¶</a></dt>
<dt id="cfg-flag---keep-going">
<code class="descname">--keep-going</code><code class="descclassname"> </code><a class="headerlink" href="#cfg-flag---keep-going" title="Permalink to this definition">¶</a></dt>
<dd><table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Default value:</th><td class="field-body">False</td>
</tr>
</tbody>
</table>
<p>If true, after a build failure, continue to build other unaffected
packages.</p>
<p>The command line variant of this field is <code class="docutils literal"><span class="pre">--keep-going</span></code>.</p>
</dd></dl>
<dl class="option">
<dt id="cmdoption-builddir">
<code class="descname">--builddir</code><code class="descclassname">=DIR</code><a class="headerlink" href="#cmdoption-builddir" title="Permalink to this definition">¶</a></dt>
<dd><p>Specifies the name of the directory where build products for
build will be stored; defaults to <code class="docutils literal"><span class="pre">dist-newstyle</span></code>. If a
relative name is specified, this directory is resolved relative
to the root of the project (i.e., where the <code class="docutils literal"><span class="pre">cabal.project</span></code>
file lives.)</p>
<p>This option cannot be specified via a <code class="docutils literal"><span class="pre">cabal.project</span></code> file.</p>
</dd></dl>
<span class="target" id="cmdoption-project-file"></span><dl class="option">
<dt id="id1">
<code class="descname">--project-file</code><code class="descclassname">=FILE</code><a class="headerlink" href="#id1" title="Permalink to this definition">¶</a></dt>
<dd><p>Specifies the name of the project file used to specify the
rest of the top-level configuration; defaults to <code class="docutils literal"><span class="pre">cabal.project</span></code>.
This name not only specifies the name of the main project file,
but also the auxiliary project files <code class="docutils literal"><span class="pre">cabal.project.freeze</span></code>
and <code class="docutils literal"><span class="pre">cabal.project.local</span></code>; for example, if you specify
<code class="docutils literal"><span class="pre">--project-file=my.project</span></code>, then the other files that will
be probed are <code class="docutils literal"><span class="pre">my.project.freeze</span></code> and <code class="docutils literal"><span class="pre">my.project.local</span></code>.</p>
<p>If the specified project file is a relative path, we will
look for the file relative to the current working directory,
and then for the parent directory, until the project file is
found or we have hit the top of the user’s home directory.</p>
<p>This option cannot be specified via a <code class="docutils literal"><span class="pre">cabal.project</span></code> file.</p>
</dd></dl>
<dl class="option">
<dt id="cmdoption-store-dir">
<code class="descname">--store-dir</code><code class="descclassname">=DIR</code><a class="headerlink" href="#cmdoption-store-dir" title="Permalink to this definition">¶</a></dt>
<dd><p>Specifies the name of the directory of the global package store.</p>
</dd></dl>
</div>
<div class="section" id="solver-configuration-options">
<h2>5.5.3. Solver configuration options<a class="headerlink" href="#solver-configuration-options" title="Permalink to this headline">¶</a></h2>
<p>The following settings control the behavior of the dependency solver:</p>
<dl class="cfg-field">
<dt id="cfg-field-constraints">
<code class="descname">constraints</code><code class="descclassname">: </code><em class="property">constraints list (comma separated)</em><a class="headerlink" href="#cfg-field-constraints" title="Permalink to this definition">¶</a></dt>
<dt id="cfg-flag---constraint">
<code class="descname">--constraint</code><code class="descclassname">="pkg > 2.0"</code><a class="headerlink" href="#cfg-flag---constraint" title="Permalink to this definition">¶</a></dt>
<dd><p>Add extra constraints to the version bounds, flag settings,
and other properties a solver can pick for a
package. For example:</p>
<div class="highlight-cabal"><div class="highlight"><pre><span></span><span class="k">constraints</span><span class="p">:</span> bar <span class="o">==</span> 2.1
</pre></div>
</div>
<p>A package can be specified multiple times in <code class="docutils literal"><span class="pre">constraints</span></code>, in
which case the specified constraints are intersected. This is
useful, since the syntax does not allow you to specify multiple
constraints at once. For example, to specify both version bounds and
flag assignments, you would write:</p>
<div class="highlight-cabal"><div class="highlight"><pre><span></span><span class="k">constraints</span><span class="p">:</span> bar <span class="o">==</span> 2.1<span class="p">,</span>
bar +foo -baz
</pre></div>
</div>
<p>Valid constraints take the same form as for the <a class="reference external" href="installing-packages.html#cmdoption-setup-configure-constraint">constraint
command line option</a>.</p>
</dd></dl>
<dl class="cfg-field">
<dt id="cfg-field-preferences">
<code class="descname">preferences</code><code class="descclassname">: </code><em class="property">preference (comma separated)</em><a class="headerlink" href="#cfg-field-preferences" title="Permalink to this definition">¶</a></dt>
<dt id="cfg-flag---preference">
<code class="descname">--preference</code><code class="descclassname">="pkg > 2.0"</code><a class="headerlink" href="#cfg-flag---preference" title="Permalink to this definition">¶</a></dt>
<dd><p>Like <a class="reference internal" href="#cfg-field-constraints" title="cabal.project constraints field "><code class="xref cabal cabal-cfg-field docutils literal"><span class="pre">constraints</span></code></a>, but the solver will attempt to satisfy
these preferences on a best-effort basis. The resulting install is locally
optimal with respect to preferences; specifically, no single package
could be replaced with a more preferred version that still satisfies
the hard constraints.</p>
<p>Operationally, preferences can cause the solver to attempt certain
version choices of a package before others, which can improve
dependency solver runtime.</p>
<p>One way to use <a class="reference internal" href="#cfg-field-preferences" title="cabal.project preferences field "><code class="xref cabal cabal-cfg-field docutils literal"><span class="pre">preferences</span></code></a> is to take a known working set of
constraints (e.g., via <code class="docutils literal"><span class="pre">cabal</span> <span class="pre">new-freeze</span></code>) and record them as
preferences. In this case, the solver will first attempt to use this
configuration, and if this violates hard constraints, it will try to
find the minimal number of upgrades to satisfy the hard constraints
again.</p>
<p>The command line variant of this field is
<code class="docutils literal"><span class="pre">--preference="pkg</span> <span class="pre">>=</span> <span class="pre">2.0"</span></code>; to specify multiple preferences, pass
the flag multiple times.</p>
</dd></dl>
<dl class="cfg-field">
<dt id="cfg-field-allow-newer">
<code class="descname">allow-newer</code><code class="descclassname">: </code><em class="property">none, all or list of scoped package names (space or comma separated)</em><a class="headerlink" href="#cfg-field-allow-newer" title="Permalink to this definition">¶</a></dt>
<dt id="cfg-flag---allow-newer">
<code class="descname">--allow-newer</code><code class="descclassname"> </code><code class="descname">, </code><code class="descname">--allow-newer</code><code class="descclassname">=[none</code><code class="descname">, </code><code class="descname">all</code><code class="descclassname"> </code><code class="descname">, </code><code class="descname">[scope:][^]pkg]</code><code class="descclassname"> </code><a class="headerlink" href="#cfg-flag---allow-newer" title="Permalink to this definition">¶</a></dt>
<dd><table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Default value:</th><td class="field-body"><code class="docutils literal"><span class="pre">none</span></code></td>
</tr>
</tbody>
</table>
<p>Allow the solver to pick an newer version of some packages than
would normally be permitted by than the <a class="reference internal" href="developing-packages.html#pkg-field-build-depends" title="package.cabal build-depends field"><code class="xref cabal cabal-pkg-field docutils literal"><span class="pre">build-depends</span></code></a> bounds
of packages in the install plan. This option may be useful if the
dependency solver cannot otherwise find a valid install plan.</p>
<p>For example, to relax <code class="docutils literal"><span class="pre">pkg</span></code>s <a class="reference internal" href="developing-packages.html#pkg-field-build-depends" title="package.cabal build-depends field"><code class="xref cabal cabal-pkg-field docutils literal"><span class="pre">build-depends</span></code></a> upper bound on
<code class="docutils literal"><span class="pre">dep-pkg</span></code>, write a scoped package name of the form:</p>
<div class="highlight-cabal"><div class="highlight"><pre><span></span><span class="k">allow-newer</span><span class="p">:</span> pkg<span class="p">:</span>dep-pkg
</pre></div>
</div>
<p>If the scope shall be limited to specific releases of <code class="docutils literal"><span class="pre">pkg</span></code>, the
extended form as in</p>
<div class="highlight-cabal"><div class="highlight"><pre><span></span><span class="k">allow-newer</span><span class="p">:</span> pkg-1.2.3<span class="p">:</span>dep-pkg<span class="p">,</span> pkg-1.1.2<span class="p">:</span>dep-pkg
</pre></div>
</div>
<p>can be used to limit the relaxation of dependencies on
<code class="docutils literal"><span class="pre">dep-pkg</span></code> by the <code class="docutils literal"><span class="pre">pkg-1.2.3</span></code> and <code class="docutils literal"><span class="pre">pkg-1.1.2</span></code> releases only.</p>
<p>The scoped syntax is recommended, as it is often only a single package
whose upper bound is misbehaving. In this case, the upper bounds of
other packages should still be respected; indeed, relaxing the bound
can break some packages which test the selected version of packages.</p>
<p>The syntax also allows to prefix the dependee package with a
modifier symbol to modify the scope/semantic of the relaxation
transformation in a additional ways. Currently only one modifier
symbol is defined, i.e. <code class="docutils literal"><span class="pre">^</span></code> (i.e. caret) which causes the
relaxation to be applied only to <code class="docutils literal"><span class="pre">^>=</span></code> operators and leave all other
version operators untouched.</p>
<p>However, in some situations (e.g., when attempting to build packages
on a new version of GHC), it is useful to disregard <em>all</em>
upper-bounds, with respect to a package or all packages. This can be
done by specifying just a package name, or using the keyword <code class="docutils literal"><span class="pre">all</span></code>
to specify all packages:</p>
<div class="highlight-cabal"><div class="highlight"><pre><span></span><span class="c1">-- Disregard upper bounds involving the dependencies on</span>
<span class="c1">-- packages bar, baz. For quux only, relax</span>
<span class="c1">-- 'quux ^>= ...'-style constraints only.</span>
<span class="k">allow-newer</span><span class="p">:</span> bar<span class="p">,</span> baz<span class="p">,</span> ^quux
<span class="c1">-- Disregard all upper bounds when dependency solving</span>
<span class="k">allow-newer</span><span class="p">:</span> all
<span class="c1">-- Disregard all `^>=`-style upper bounds when dependency solving</span>
<span class="k">allow-newer</span><span class="p">:</span> ^all
</pre></div>
</div>
<p>For consistency, there is also the explicit wildcard scope syntax
<code class="docutils literal"><span class="pre">*</span></code> (or its alphabetic synonym <code class="docutils literal"><span class="pre">all</span></code>). Consequently, the
examples above are equivalent to the explicitly scoped variants:</p>
<div class="highlight-cabal"><div class="highlight"><pre><span></span><span class="k">allow-newer</span><span class="p">:</span> all<span class="p">:</span>bar<span class="p">,</span> *<span class="p">:</span>baz<span class="p">,</span> *<span class="p">:</span>^quux
<span class="k">allow-newer</span><span class="p">:</span> *<span class="p">:</span>*
<span class="k">allow-newer</span><span class="p">:</span> all<span class="p">:</span>all
<span class="k">allow-newer</span><span class="p">:</span> *<span class="p">:</span>^*
<span class="k">allow-newer</span><span class="p">:</span> all<span class="p">:</span>^all
</pre></div>
</div>
<p>In order to ignore all bounds specified by a package <code class="docutils literal"><span class="pre">pkg-1.2.3</span></code>
you can combine scoping with a right-hand-side wildcard like so</p>
<div class="highlight-cabal"><div class="highlight"><pre><span></span><span class="c1">-- Disregard any upper bounds specified by pkg-1.2.3</span>
<span class="k">allow-newer</span><span class="p">:</span> pkg-1.2.3<span class="p">:</span>*
<span class="c1">-- Disregard only `^>=`-style upper bounds in pkg-1.2.3</span>
<span class="k">allow-newer</span><span class="p">:</span> pkg-1.2.3<span class="p">:</span>^*
</pre></div>
</div>
<p><a class="reference internal" href="#cfg-field-allow-newer" title="cabal.project allow-newer field "><code class="xref cabal cabal-cfg-field docutils literal"><span class="pre">allow-newer</span></code></a> is often used in conjunction with a constraint
(in the cfg-field:<cite>constraints</cite> field) forcing the usage of a specific,
newer version of a package.</p>
<p>The command line variant of this field is e.g. <code class="docutils literal"><span class="pre">--allow-newer=bar</span></code>. A
bare <code class="docutils literal"><span class="pre">--allow-newer</span></code> is equivalent to <code class="docutils literal"><span class="pre">--allow-newer=all</span></code>.</p>
</dd></dl>
<dl class="cfg-field">
<dt id="cfg-field-allow-older">
<code class="descname">allow-older</code><code class="descclassname">: </code><em class="property">none, all, list of scoped package names (space or comma separated)</em><a class="headerlink" href="#cfg-field-allow-older" title="Permalink to this definition">¶</a></dt>
<dt id="cfg-flag---allow-older">
<code class="descname">--allow-older</code><code class="descclassname"> </code><code class="descname">, </code><code class="descname">--allow-older</code><code class="descclassname">=[none</code><code class="descname">, </code><code class="descname">all</code><code class="descclassname"> </code><code class="descname">, </code><code class="descname">[scope:][^]pkg]</code><code class="descclassname"> </code><a class="headerlink" href="#cfg-flag---allow-older" title="Permalink to this definition">¶</a></dt>
<dd><table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Since:</th><td class="field-body">Cabal 2.0</td>
</tr>
<tr class="field-even field"><th class="field-name">Default value:</th><td class="field-body"><code class="docutils literal"><span class="pre">none</span></code></td>
</tr>
</tbody>
</table>
<p>Like <a class="reference internal" href="#cfg-field-allow-newer" title="cabal.project allow-newer field "><code class="xref cabal cabal-cfg-field docutils literal"><span class="pre">allow-newer</span></code></a>, but applied to lower bounds rather than
upper bounds.</p>
<p>The command line variant of this field is <code class="docutils literal"><span class="pre">--allow-older=all</span></code>. A
bare <code class="docutils literal"><span class="pre">--allow-older</span></code> is equivalent to <code class="docutils literal"><span class="pre">--allow-older=all</span></code>.</p>
</dd></dl>
<dl class="cfg-field">
<dt id="cfg-field-index-state">
<code class="descname">index-state</code><code class="descclassname">: </code><em class="property">HEAD, unix-timestamp, ISO8601 UTC timestamp.</em><a class="headerlink" href="#cfg-field-index-state" title="Permalink to this definition">¶</a></dt>
<dd><table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Since:</th><td class="field-body">Cabal 2.0</td>
</tr>
<tr class="field-even field"><th class="field-name">Default value:</th><td class="field-body"><code class="docutils literal"><span class="pre">HEAD</span></code></td>
</tr>
</tbody>
</table>
<p>This allows to change the source package index state the solver uses
to compute install-plans. This is particularly useful in
combination with freeze-files in order to also freeze the state the
package index was in at the time the install-plan was frozen.</p>
<div class="highlight-cabal"><div class="highlight"><pre><span></span><span class="c1">-- UNIX timestamp format example</span>
<span class="k">index-state</span><span class="p">:</span> @1474739268
<span class="c1">-- ISO8601 UTC timestamp format example</span>
<span class="c1">-- This format is used by 'cabal new-configure'</span>
<span class="c1">-- for storing `--index-state` values.</span>
<span class="k">index-state</span><span class="p">:</span> 2016-09-24T17<span class="p">:</span>47<span class="p">:</span>48Z
</pre></div>
</div>
</dd></dl>
</div>
<div class="section" id="package-configuration-options">
<h2>5.5.4. Package configuration options<a class="headerlink" href="#package-configuration-options" title="Permalink to this headline">¶</a></h2>
<p>Package options affect the building of specific packages. There are three
ways a package option can be specified:</p>
<ul class="simple">
<li>They can be specified at the top-level, in which case they apply only
to <strong>local package</strong>, or</li>
<li>They can be specified inside a <code class="docutils literal"><span class="pre">package</span></code> stanza, in which case they
apply to the build of the package, whether or not it is local or
external.</li>
<li>They can be specified inside an <code class="docutils literal"><span class="pre">package</span> <span class="pre">*</span></code> stanza, in which case they
apply to all packages, local ones from the project and also external
dependencies.</li>
</ul>
<p>For example, the following options specify that <a class="reference internal" href="#cfg-field-optimization" title="cabal.project optimization field "><code class="xref cabal cabal-cfg-field docutils literal"><span class="pre">optimization</span></code></a>
should be turned off for all local packages, and that <code class="docutils literal"><span class="pre">bytestring</span></code> (possibly
an external dependency) should be built with <code class="docutils literal"><span class="pre">-fno-state-hack</span></code>:</p>
<div class="highlight-cabal"><div class="highlight"><pre><span></span><span class="k">optimization</span><span class="p">:</span> False
<span class="k">package</span> bytestring
<span class="w"> </span><span class="k">ghc-options</span><span class="p">:</span> -fno-state-hack
</pre></div>
</div>
<p><code class="docutils literal"><span class="pre">ghc-options</span></code> is not specifically described in this documentation,
but is one of many fields for configuring programs. They take the form
<code class="docutils literal"><span class="pre">progname-options</span></code> and <code class="docutils literal"><span class="pre">progname-location</span></code>, and
can only be set inside package stanzas. (TODO: They are not supported
at top-level, see <a class="reference external" href="https://github.com/haskell/cabal/issues/3579">#3579</a>.)</p>
<p>At the moment, there is no way to specify an option to apply to all
external packages or all inplace packages. Additionally, it is only
possible to specify these options on the command line for all local
packages (there is no per-package command line interface.)</p>
<p>Some flags were added by more recent versions of the Cabal library. This
means that they are NOT supported by packages which use Custom setup
scripts that require a version of the Cabal library older than when the
feature was added.</p>
<dl class="cfg-field">
<dt id="cfg-field-flags">
<code class="descname">flags</code><code class="descclassname">: </code><em class="property">list of +flagname or -flagname (space separated)</em><a class="headerlink" href="#cfg-field-flags" title="Permalink to this definition">¶</a></dt>
<dt id="cfg-flag---flags">
<code class="descname">--flags</code><code class="descclassname">="+foo -bar"</code><code class="descname">, </code><code class="descname">-ffoo</code><code class="descclassname"> </code><code class="descname">, </code><code class="descname">-f-bar</code><code class="descclassname"> </code><a class="headerlink" href="#cfg-flag---flags" title="Permalink to this definition">¶</a></dt>
<dd><p>Force all flags specified as <code class="docutils literal"><span class="pre">+flagname</span></code> to be true, and all flags
specified as <code class="docutils literal"><span class="pre">-flagname</span></code> to be false. For example, to enable the
flag <code class="docutils literal"><span class="pre">foo</span></code> and disable <code class="docutils literal"><span class="pre">bar</span></code>, set:</p>
<div class="highlight-cabal"><div class="highlight"><pre><span></span><span class="k">flags</span><span class="p">:</span> +foo -bar
</pre></div>
</div>
<p>If there is no leading punctuation, it is assumed that the flag
should be enabled; e.g., this is equivalent:</p>
<div class="highlight-cabal"><div class="highlight"><pre><span></span><span class="k">flags</span><span class="p">:</span> foo -bar
</pre></div>
</div>
<p>Flags are <em>per-package</em>, so it doesn’t make much sense to specify
flags at the top-level, unless you happen to know that <em>all</em> of your
local packages support the same named flags. If a flag is not
supported by a package, it is ignored.</p>
<p>See also the solver configuration field <a class="reference internal" href="#cfg-field-constraints" title="cabal.project constraints field "><code class="xref cabal cabal-cfg-field docutils literal"><span class="pre">constraints</span></code></a>.</p>
<p>The command line variant of this flag is <code class="docutils literal"><span class="pre">--flags</span></code>. There is also
a shortened form <code class="docutils literal"><span class="pre">-ffoo</span> <span class="pre">-f-bar</span></code>.</p>
<p>A common mistake is to say <code class="docutils literal"><span class="pre">cabal</span> <span class="pre">new-build</span> <span class="pre">-fhans</span></code>, where
<code class="docutils literal"><span class="pre">hans</span></code> is a flag for a transitive dependency that is not in the
local package; in this case, the flag will be silently ignored. If
<code class="docutils literal"><span class="pre">haskell-tor</span></code> is the package you want this flag to apply to, try
<code class="docutils literal"><span class="pre">--constraint="haskell-tor</span> <span class="pre">+hans"</span></code> instead.</p>
</dd></dl>
<dl class="cfg-field">
<dt id="cfg-field-with-compiler">
<code class="descname">with-compiler</code><code class="descclassname">: </code><em class="property">executable</em><a class="headerlink" href="#cfg-field-with-compiler" title="Permalink to this definition">¶</a></dt>
<dt id="cfg-flag---with-compiler">
<code class="descname">--with-compiler</code><code class="descclassname">=executable</code><a class="headerlink" href="#cfg-flag---with-compiler" title="Permalink to this definition">¶</a></dt>
<dd><p>Specify the path to a particular compiler to be used. If not an
absolute path, it will be resolved according to the <span class="target" id="index-1"></span><code class="xref std std-envvar docutils literal"><span class="pre">PATH</span></code>
environment. The type of the compiler (GHC, GHCJS, etc) must be
consistent with the setting of the <a class="reference internal" href="#cfg-field-compiler" title="cabal.project compiler field "><code class="xref cabal cabal-cfg-field docutils literal"><span class="pre">compiler</span></code></a> field.</p>
<p>The most common use of this option is to specify a different version
of your compiler to be used; e.g., if you have <code class="docutils literal"><span class="pre">ghc-7.8</span></code> in your
path, you can specify <code class="docutils literal"><span class="pre">with-compiler:</span> <span class="pre">ghc-7.8</span></code> to use it.</p>
<p>This flag also sets the default value of <a class="reference internal" href="#cfg-field-with-hc-pkg" title="cabal.project with-hc-pkg field "><code class="xref cabal cabal-cfg-field docutils literal"><span class="pre">with-hc-pkg</span></code></a>, using
the heuristic that it is named <code class="docutils literal"><span class="pre">ghc-pkg-7.8</span></code> (if your executable name
is suffixed with a version number), or is the executable named
<code class="docutils literal"><span class="pre">ghc-pkg</span></code> in the same directory as the <code class="docutils literal"><span class="pre">ghc</span></code> directory. If this
heuristic does not work, set <a class="reference internal" href="#cfg-field-with-hc-pkg" title="cabal.project with-hc-pkg field "><code class="xref cabal cabal-cfg-field docutils literal"><span class="pre">with-hc-pkg</span></code></a> explicitly.</p>
<p>For inplace packages, <code class="docutils literal"><span class="pre">cabal</span> <span class="pre">new-build</span></code> maintains a separate build
directory for each version of GHC, so you can maintain multiple
build trees for different versions of GHC without clobbering each
other.</p>
<p>At the moment, it’s not possible to set <a class="reference internal" href="#cfg-field-with-compiler" title="cabal.project with-compiler field "><code class="xref cabal cabal-cfg-field docutils literal"><span class="pre">with-compiler</span></code></a> on a
per-package basis, but eventually we plan on relaxing this
restriction. If this is something you need, give us a shout.</p>
<p>The command line variant of this flag is
<code class="docutils literal"><span class="pre">--with-compiler=ghc-7.8</span></code>; there is also a short version
<code class="docutils literal"><span class="pre">-w</span> <span class="pre">ghc-7.8</span></code>.</p>
</dd></dl>
<dl class="cfg-field">
<dt id="cfg-field-with-hc-pkg">
<code class="descname">with-hc-pkg</code><code class="descclassname">: </code><em class="property">executable</em><a class="headerlink" href="#cfg-field-with-hc-pkg" title="Permalink to this definition">¶</a></dt>
<dt id="cfg-flag---with-hc-pkg">
<code class="descname">--with-hc-pkg</code><code class="descclassname">=executable</code><a class="headerlink" href="#cfg-flag---with-hc-pkg" title="Permalink to this definition">¶</a></dt>
<dd><p>Specify the path to the package tool, e.g., <code class="docutils literal"><span class="pre">ghc-pkg</span></code>. This
package tool must be compatible with the compiler specified by
<a class="reference internal" href="#cfg-field-with-compiler" title="cabal.project with-compiler field "><code class="xref cabal cabal-cfg-field docutils literal"><span class="pre">with-compiler</span></code></a> (generally speaking, it should be precisely
the tool that was distributed with the compiler). If this option is
omitted, the default value is determined from <a class="reference internal" href="#cfg-field-with-compiler" title="cabal.project with-compiler field "><code class="xref cabal cabal-cfg-field docutils literal"><span class="pre">with-compiler</span></code></a>.</p>
<p>The command line variant of this flag is
<code class="docutils literal"><span class="pre">--with-hc-pkg=ghc-pkg-7.8</span></code>.</p>
</dd></dl>
<dl class="cfg-field">
<dt id="cfg-field-optimization">
<code class="descname">optimization</code><code class="descclassname">: </code><em class="property">nat</em><a class="headerlink" href="#cfg-field-optimization" title="Permalink to this definition">¶</a></dt>
<dt id="cfg-flag---enable-optimization">
<code class="descname">--enable-optimization</code><code class="descclassname"> </code><a class="headerlink" href="#cfg-flag---enable-optimization" title="Permalink to this definition">¶</a></dt>
<dt id="cfg-flag---disable-optimization">
<code class="descname">--disable-optimization</code><code class="descclassname"> </code><a class="headerlink" href="#cfg-flag---disable-optimization" title="Permalink to this definition">¶</a></dt>
<dd><table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Default value:</th><td class="field-body"><code class="docutils literal"><span class="pre">1</span></code></td>
</tr>
</tbody>
</table>
<p>Build with optimization. This is appropriate for production use,
taking more time to build faster libraries and programs.</p>
<p>The optional <em>nat</em> value is the optimisation level. Some compilers
support multiple optimisation levels. The range is 0 to 2. Level 0
disables optimization, level 1 is the default. Level 2 is higher
optimisation if the compiler supports it. Level 2 is likely to lead
to longer compile times and bigger generated code. If you are not
planning to run code, turning off optimization will lead to better
build times and less code to be rebuilt when a module changes.</p>
<p>When optimizations are enabled, Cabal passes <code class="docutils literal"><span class="pre">-O2</span></code> to the C compiler.</p>
<p>We also accept <code class="docutils literal"><span class="pre">True</span></code> (equivalent to 1) and <code class="docutils literal"><span class="pre">False</span></code> (equivalent
to 0).</p>
<p>Note that as of GHC 8.0, GHC does not recompile when optimization
levels change (see <a class="reference external" href="http://ghc.haskell.org/trac/ghc/ticket/10923">GHC #10923</a>), so if
you change the optimization level for a local package you may need
to blow away your old build products in order to rebuild with the
new optimization level.</p>
<p>The command line variant of this flag is <code class="docutils literal"><span class="pre">-O2</span></code> (with <code class="docutils literal"><span class="pre">-O1</span></code>
equivalent to <code class="docutils literal"><span class="pre">-O</span></code>). There are also long-form variants
<code class="docutils literal"><span class="pre">--enable-optimization</span></code> and <code class="docutils literal"><span class="pre">--disable-optimization</span></code>.</p>
</dd></dl>
<dl class="cfg-field">
<dt id="cfg-field-configure-options">
<code class="descname">configure-options</code><code class="descclassname">: </code><em class="property">args (space separated)</em><a class="headerlink" href="#cfg-field-configure-options" title="Permalink to this definition">¶</a></dt>
<dt id="cfg-flag---configure-option">
<code class="descname">--configure-option</code><code class="descclassname">=arg</code><a class="headerlink" href="#cfg-flag---configure-option" title="Permalink to this definition">¶</a></dt>
<dd><p>A list of extra arguments to pass to the external <code class="docutils literal"><span class="pre">./configure</span></code>
script, if one is used. This is only useful for packages which have
the <code class="docutils literal"><span class="pre">Configure</span></code> build type. See also the section on
<a class="reference external" href="developing-packages.html#system-dependent-parameters">system-dependent
parameters</a>.</p>
<p>The command line variant of this flag is <code class="docutils literal"><span class="pre">--configure-option=arg</span></code>,
which can be specified multiple times to pass multiple options.</p>
</dd></dl>
<dl class="cfg-field">
<dt id="cfg-field-compiler">
<code class="descname">compiler</code><code class="descclassname">: </code><em class="property">ghc, ghcjs, jhc, lhc, uhc or haskell-suite</em><a class="headerlink" href="#cfg-field-compiler" title="Permalink to this definition">¶</a></dt>
<dt id="cfg-flag---compiler">
<code class="descname">--compiler</code><code class="descclassname">=compiler</code><a class="headerlink" href="#cfg-flag---compiler" title="Permalink to this definition">¶</a></dt>
<dd><table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Default value:</th><td class="field-body"><code class="docutils literal"><span class="pre">ghc</span></code></td>
</tr>
</tbody>
</table>
<p>Specify which compiler toolchain to be used. This is independent of
<code class="docutils literal"><span class="pre">with-compiler</span></code>, because the choice of toolchain affects Cabal’s
build logic.</p>
<p>The command line variant of this flag is <code class="docutils literal"><span class="pre">--compiler=ghc</span></code>.</p>
</dd></dl>
<dl class="cfg-field">
<dt id="cfg-field-tests">
<code class="descname">tests</code><code class="descclassname">: </code><em class="property">boolean</em><a class="headerlink" href="#cfg-field-tests" title="Permalink to this definition">¶</a></dt>
<dt id="cfg-flag---enable-tests">
<code class="descname">--enable-tests</code><code class="descclassname"> </code><a class="headerlink" href="#cfg-flag---enable-tests" title="Permalink to this definition">¶</a></dt>
<dt id="cfg-flag---disable-tests">
<code class="descname">--disable-tests</code><code class="descclassname"> </code><a class="headerlink" href="#cfg-flag---disable-tests" title="Permalink to this definition">¶</a></dt>
<dd><table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Default value:</th><td class="field-body"><code class="docutils literal"><span class="pre">False</span></code></td>
</tr>
</tbody>
</table>
<p>Force test suites to be enabled. For most users this should not be
needed, as we always attempt to solve for test suite dependencies,
even when this value is <code class="docutils literal"><span class="pre">False</span></code>; furthermore, test suites are
automatically enabled if they are requested as a built target.</p>
<p>The command line variant of this flag is <code class="docutils literal"><span class="pre">--enable-tests</span></code> and
<code class="docutils literal"><span class="pre">--disable-tests</span></code>.</p>
</dd></dl>
<dl class="cfg-field">
<dt id="cfg-field-benchmarks">
<code class="descname">benchmarks</code><code class="descclassname">: </code><em class="property">boolean</em><a class="headerlink" href="#cfg-field-benchmarks" title="Permalink to this definition">¶</a></dt>
<dt id="cfg-flag---enable-benchmarks">
<code class="descname">--enable-benchmarks</code><code class="descclassname"> </code><a class="headerlink" href="#cfg-flag---enable-benchmarks" title="Permalink to this definition">¶</a></dt>
<dt id="cfg-flag---disable-benchmarks">
<code class="descname">--disable-benchmarks</code><code class="descclassname"> </code><a class="headerlink" href="#cfg-flag---disable-benchmarks" title="Permalink to this definition">¶</a></dt>
<dd><table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Default value:</th><td class="field-body"><code class="docutils literal"><span class="pre">False</span></code></td>
</tr>
</tbody>
</table>
<p>Force benchmarks to be enabled. For most users this should not be
needed, as we always attempt to solve for benchmark dependencies,
even when this value is <code class="docutils literal"><span class="pre">False</span></code>; furthermore, benchmarks are
automatically enabled if they are requested as a built target.</p>
<p>The command line variant of this flag is <code class="docutils literal"><span class="pre">--enable-benchmarks</span></code> and
<code class="docutils literal"><span class="pre">--disable-benchmarks</span></code>.</p>
</dd></dl>
<dl class="cfg-field">
<dt id="cfg-field-extra-prog-path">
<code class="descname">extra-prog-path</code><code class="descclassname">: </code><em class="property">paths (newline or comma separated)</em><a class="headerlink" href="#cfg-field-extra-prog-path" title="Permalink to this definition">¶</a></dt>
<dt id="cfg-flag---extra-prog-path">
<code class="descname">--extra-prog-path</code><code class="descclassname">=PATH</code><a class="headerlink" href="#cfg-flag---extra-prog-path" title="Permalink to this definition">¶</a></dt>
<dd><table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Since:</th><td class="field-body">Cabal 1.18</td>
</tr>
</tbody>
</table>
<p>A list of directories to search for extra required programs. Most
users should not need this, as programs like <code class="docutils literal"><span class="pre">happy</span></code> and <code class="docutils literal"><span class="pre">alex</span></code>
will automatically be installed and added to the path. This can be
useful if a <code class="docutils literal"><span class="pre">Custom</span></code> setup script relies on an exotic extra
program.</p>
<p>The command line variant of this flag is <code class="docutils literal"><span class="pre">--extra-prog-path=PATH</span></code>,
which can be specified multiple times.</p>
</dd></dl>
<dl class="cfg-field">
<dt id="cfg-field-run-tests">
<code class="descname">run-tests</code><code class="descclassname">: </code><em class="property">boolean</em><a class="headerlink" href="#cfg-field-run-tests" title="Permalink to this definition">¶</a></dt>
<dt id="cfg-flag---run-tests">
<code class="descname">--run-tests</code><code class="descclassname"> </code><a class="headerlink" href="#cfg-flag---run-tests" title="Permalink to this definition">¶</a></dt>
<dd><table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Default value:</th><td class="field-body"><code class="docutils literal"><span class="pre">False</span></code></td>
</tr>
</tbody>
</table>
<p>Run the package test suite upon installation. This is useful for
saying “When this package is installed, check that the test suite
passes, terminating the rest of the build if it is broken.”</p>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">One deficiency: the <a class="reference internal" href="#cfg-field-run-tests" title="cabal.project run-tests field "><code class="xref cabal cabal-cfg-field docutils literal"><span class="pre">run-tests</span></code></a> setting of a package is NOT
recorded as part of the hash, so if you install something without
<a class="reference internal" href="#cfg-field-run-tests" title="cabal.project run-tests field "><code class="xref cabal cabal-cfg-field docutils literal"><span class="pre">run-tests</span></code></a> and then turn on <code class="docutils literal"><span class="pre">run-tests</span></code>, we won’t
subsequently test the package. If this is causing you problems, give
us a shout.</p>
</div>
<p>The command line variant of this flag is <code class="docutils literal"><span class="pre">--run-tests</span></code>.</p>
</dd></dl>
<div class="section" id="object-code-options">
<h3>5.5.4.1. Object code options<a class="headerlink" href="#object-code-options" title="Permalink to this headline">¶</a></h3>
<dl class="cfg-field">
<dt id="cfg-field-debug-info">
<code class="descname">debug-info</code><code class="descclassname">: </code><em class="property">integer</em><a class="headerlink" href="#cfg-field-debug-info" title="Permalink to this definition">¶</a></dt>
<dt id="cfg-flag---enable-debug-info">
<code class="descname">--enable-debug-info</code><code class="descclassname">=⟨n⟩</code><a class="headerlink" href="#cfg-flag---enable-debug-info" title="Permalink to this definition">¶</a></dt>
<dt id="cfg-flag---disable-debug-info">
<code class="descname">--disable-debug-info</code><code class="descclassname"> </code><a class="headerlink" href="#cfg-flag---disable-debug-info" title="Permalink to this definition">¶</a></dt>
<dd><table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Since:</th><td class="field-body">Cabal 1.22</td>
</tr>
<tr class="field-even field"><th class="field-name">Default value:</th><td class="field-body">False</td>
</tr>
</tbody>
</table>
<p>If the compiler (e.g., GHC 7.10 and later) supports outputing OS
native debug info (e.g., DWARF), setting <code class="docutils literal"><span class="pre">debug-info:</span> <span class="pre">True</span></code> will
instruct it to do so. See the GHC wiki page on <a class="reference external" href="http://ghc.haskell.org/trac/ghc/wiki/DWARF">DWARF</a>
for more information about this feature.</p>
<p>(This field also accepts numeric syntax, but until GHC 8.2 this didn’t
do anything.)</p>
<p>The command line variant of this flag is <code class="docutils literal"><span class="pre">--enable-debug-info</span></code> and
<code class="docutils literal"><span class="pre">--disable-debug-info</span></code>.</p>
</dd></dl>
<dl class="cfg-field">
<dt id="cfg-field-split-sections">
<code class="descname">split-sections</code><code class="descclassname">: </code><em class="property">boolean</em><a class="headerlink" href="#cfg-field-split-sections" title="Permalink to this definition">¶</a></dt>
<dt id="cfg-flag---enable-split-sections">
<code class="descname">--enable-split-sections</code><code class="descclassname"> </code><a class="headerlink" href="#cfg-flag---enable-split-sections" title="Permalink to this definition">¶</a></dt>
<dt id="cfg-flag---disable-split-sections">
<code class="descname">--disable-split-sections</code><code class="descclassname"> </code><a class="headerlink" href="#cfg-flag---disable-split-sections" title="Permalink to this definition">¶</a></dt>
<dd><table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Since:</th><td class="field-body">Cabal 2.1</td>
</tr>
<tr class="field-even field"><th class="field-name">Default value:</th><td class="field-body">False</td>
</tr>
</tbody>
</table>
<p>Use the GHC <code class="docutils literal"><span class="pre">-split-sections</span></code> feature when building the library. This
reduces the final size of the executables that use the library by
allowing them to link with only the bits that they use rather than
the entire library. The downside is that building the library takes
longer and uses a bit more memory.</p>
<p>This feature is supported by GHC 8.0 and later.</p>
<p>The command line variant of this flag is <code class="docutils literal"><span class="pre">--enable-split-sections</span></code> and
<code class="docutils literal"><span class="pre">--disable-split-sections</span></code>.</p>
</dd></dl>
<dl class="cfg-field">
<dt id="cfg-field-split-objs">
<code class="descname">split-objs</code><code class="descclassname">: </code><em class="property">boolean</em><a class="headerlink" href="#cfg-field-split-objs" title="Permalink to this definition">¶</a></dt>
<dt id="cfg-flag---enable-split-objs">
<code class="descname">--enable-split-objs</code><code class="descclassname"> </code><a class="headerlink" href="#cfg-flag---enable-split-objs" title="Permalink to this definition">¶</a></dt>
<dt id="cfg-flag---disable-split-objs">
<code class="descname">--disable-split-objs</code><code class="descclassname"> </code><a class="headerlink" href="#cfg-flag---disable-split-objs" title="Permalink to this definition">¶</a></dt>
<dd><table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Default value:</th><td class="field-body">False</td>
</tr>
</tbody>
</table>
<p>Use the GHC <code class="docutils literal"><span class="pre">-split-objs</span></code> feature when building the library. This
reduces the final size of the executables that use the library by
allowing them to link with only the bits that they use rather than
the entire library. The downside is that building the library takes
longer and uses considerably more memory.</p>
<p>It is generally recommend that you use <code class="docutils literal"><span class="pre">split-sections</span></code> instead
of <code class="docutils literal"><span class="pre">split-objs</span></code> where possible.</p>
<p>The command line variant of this flag is <code class="docutils literal"><span class="pre">--enable-split-objs</span></code> and
<code class="docutils literal"><span class="pre">--disable-split-objs</span></code>.</p>
</dd></dl>
<dl class="cfg-field">
<dt id="cfg-field-executable-stripping">
<code class="descname">executable-stripping</code><code class="descclassname">: </code><em class="property">boolean</em><a class="headerlink" href="#cfg-field-executable-stripping" title="Permalink to this definition">¶</a></dt>
<dt id="cfg-flag---enable-executable-stripping">
<code class="descname">--enable-executable-stripping</code><code class="descclassname"> </code><a class="headerlink" href="#cfg-flag---enable-executable-stripping" title="Permalink to this definition">¶</a></dt>
<dt id="cfg-flag---disable-executable-stripping">
<code class="descname">--disable-executable-stripping</code><code class="descclassname"> </code><a class="headerlink" href="#cfg-flag---disable-executable-stripping" title="Permalink to this definition">¶</a></dt>
<dd><table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Default value:</th><td class="field-body">True</td>
</tr>
</tbody>
</table>
<p>When installing binary executable programs, run the <code class="docutils literal"><span class="pre">strip</span></code>
program on the binary. This can considerably reduce the size of the
executable binary file. It does this by removing debugging
information and symbols.</p>
<p>Not all Haskell implementations generate native binaries. For such
implementations this option has no effect.</p>
<p>(TODO: Check what happens if you combine this with <code class="docutils literal"><span class="pre">debug-info</span></code>.)</p>
<p>The command line variant of this flag is
<code class="docutils literal"><span class="pre">--enable-executable-stripping</span></code> and
<code class="docutils literal"><span class="pre">--disable-executable-stripping</span></code>.</p>
</dd></dl>
<dl class="cfg-field">
<dt id="cfg-field-library-stripping">
<code class="descname">library-stripping</code><code class="descclassname">: </code><em class="property">boolean</em><a class="headerlink" href="#cfg-field-library-stripping" title="Permalink to this definition">¶</a></dt>
<dt id="cfg-flag---enable-library-stripping">
<code class="descname">--enable-library-stripping</code><code class="descclassname"> </code><a class="headerlink" href="#cfg-flag---enable-library-stripping" title="Permalink to this definition">¶</a></dt>
<dt id="cfg-flag---disable-library-stripping">
<code class="descname">--disable-library-stripping</code><code class="descclassname"> </code><a class="headerlink" href="#cfg-flag---disable-library-stripping" title="Permalink to this definition">¶</a></dt>
<dd><table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Since:</th><td class="field-body">Cabal 1.19</td>
</tr>
</tbody>
</table>
<p>When installing binary libraries, run the <code class="docutils literal"><span class="pre">strip</span></code> program on the
binary, saving space on the file system. See also
<code class="docutils literal"><span class="pre">executable-stripping</span></code>.</p>
<p>The command line variant of this flag is
<code class="docutils literal"><span class="pre">--enable-library-stripping</span></code> and <code class="docutils literal"><span class="pre">--disable-library-stripping</span></code>.</p>
</dd></dl>
</div>
<div class="section" id="executable-options">
<h3>5.5.4.2. Executable options<a class="headerlink" href="#executable-options" title="Permalink to this headline">¶</a></h3>
<dl class="cfg-field">
<dt id="cfg-field-program-prefix">
<code class="descname">program-prefix</code><code class="descclassname">: </code><em class="property">prefix</em><a class="headerlink" href="#cfg-field-program-prefix" title="Permalink to this definition">¶</a></dt>
<dt id="cfg-flag---program-prefix">
<code class="descname">--program-prefix</code><code class="descclassname">=prefix</code><a class="headerlink" href="#cfg-flag---program-prefix" title="Permalink to this definition">¶</a></dt>
<dd><p>[STRIKEOUT:Prepend <em>prefix</em> to installed program names.] (Currently
implemented in a silly and not useful way. If you need this to work
give us a shout.)</p>
<p><em>prefix</em> may contain the following path variables: <code class="docutils literal"><span class="pre">$pkgid</span></code>,
<code class="docutils literal"><span class="pre">$pkg</span></code>, <code class="docutils literal"><span class="pre">$version</span></code>, <code class="docutils literal"><span class="pre">$compiler</span></code>, <code class="docutils literal"><span class="pre">$os</span></code>, <code class="docutils literal"><span class="pre">$arch</span></code>, <code class="docutils literal"><span class="pre">$abi</span></code>,
<code class="docutils literal"><span class="pre">$abitag</span></code></p>
<p>The command line variant of this flag is <code class="docutils literal"><span class="pre">--program-prefix=foo-</span></code>.</p>
</dd></dl>
<dl class="cfg-field">
<dt id="cfg-field-program-suffix">
<code class="descname">program-suffix</code><code class="descclassname">: </code><em class="property">suffix</em><a class="headerlink" href="#cfg-field-program-suffix" title="Permalink to this definition">¶</a></dt>
<dt id="cfg-flag---program-suffix">
<code class="descname">--program-suffix</code><code class="descclassname">=suffix</code><a class="headerlink" href="#cfg-flag---program-suffix" title="Permalink to this definition">¶</a></dt>
<dd><p>[STRIKEOUT:Append <em>suffix</em> to installed program names.] (Currently
implemented in a silly and not useful way. If you need this to work
give us a shout.)</p>
<p>The most obvious use for this is to append the program’s version
number to make it possible to install several versions of a program
at once: <code class="docutils literal"><span class="pre">program-suffix:</span> <span class="pre">$version</span></code>.</p>
<p><em>suffix</em> may contain the following path variables: <code class="docutils literal"><span class="pre">$pkgid</span></code>,
<code class="docutils literal"><span class="pre">$pkg</span></code>, <code class="docutils literal"><span class="pre">$version</span></code>, <code class="docutils literal"><span class="pre">$compiler</span></code>, <code class="docutils literal"><span class="pre">$os</span></code>, <code class="docutils literal"><span class="pre">$arch</span></code>, <code class="docutils literal"><span class="pre">$abi</span></code>,
<code class="docutils literal"><span class="pre">$abitag</span></code></p>
<p>The command line variant of this flag is
<code class="docutils literal"><span class="pre">--program-suffix='$version'</span></code>.</p>
</dd></dl>
</div>
<div class="section" id="dynamic-linking-options">
<h3>5.5.4.3. Dynamic linking options<a class="headerlink" href="#dynamic-linking-options" title="Permalink to this headline">¶</a></h3>
<dl class="cfg-field">
<dt id="cfg-field-shared">
<code class="descname">shared</code><code class="descclassname">: </code><em class="property">boolean</em><a class="headerlink" href="#cfg-field-shared" title="Permalink to this definition">¶</a></dt>
<dt id="cfg-flag---enable-shared">
<code class="descname">--enable-shared</code><code class="descclassname"> </code><a class="headerlink" href="#cfg-flag---enable-shared" title="Permalink to this definition">¶</a></dt>
<dt id="cfg-flag---disable-shared">
<code class="descname">--disable-shared</code><code class="descclassname"> </code><a class="headerlink" href="#cfg-flag---disable-shared" title="Permalink to this definition">¶</a></dt>
<dd><table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Default value:</th><td class="field-body">False</td>
</tr>
</tbody>
</table>
<p>Build shared library. This implies a separate compiler run to
generate position independent code as required on most platforms.</p>
<p>The command line variant of this flag is <code class="docutils literal"><span class="pre">--enable-shared</span></code> and
<code class="docutils literal"><span class="pre">--disable-shared</span></code>.</p>
</dd></dl>
<dl class="cfg-field">
<dt id="cfg-field-executable-dynamic">
<code class="descname">executable-dynamic</code><code class="descclassname">: </code><em class="property">boolean</em><a class="headerlink" href="#cfg-field-executable-dynamic" title="Permalink to this definition">¶</a></dt>
<dt id="cfg-flag---enable-executable-dynamic">
<code class="descname">--enable-executable-dynamic</code><code class="descclassname"> </code><a class="headerlink" href="#cfg-flag---enable-executable-dynamic" title="Permalink to this definition">¶</a></dt>
<dt id="cfg-flag---disable-executable-dynamic">
<code class="descname">--disable-executable-dynamic</code><code class="descclassname"> </code><a class="headerlink" href="#cfg-flag---disable-executable-dynamic" title="Permalink to this definition">¶</a></dt>
<dd><table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Default value:</th><td class="field-body">False</td>
</tr>
</tbody>
</table>
<p>Link executables dynamically. The executable’s library dependencies
should be built as shared objects. This implies <code class="docutils literal"><span class="pre">shared:</span> <span class="pre">True</span></code>
unless <code class="docutils literal"><span class="pre">shared:</span> <span class="pre">False</span></code> is explicitly specified.</p>
<p>The command line variant of this flag is
<code class="docutils literal"><span class="pre">--enable-executable-dynamic</span></code> and
<code class="docutils literal"><span class="pre">--disable-executable-dynamic</span></code>.</p>
</dd></dl>
<dl class="cfg-field">
<dt id="cfg-field-library-for-ghci">
<code class="descname">library-for-ghci</code><code class="descclassname">: </code><em class="property">boolean</em><a class="headerlink" href="#cfg-field-library-for-ghci" title="Permalink to this definition">¶</a></dt>
<dt id="cfg-flag---enable-library-for-ghci">
<code class="descname">--enable-library-for-ghci</code><code class="descclassname"> </code><a class="headerlink" href="#cfg-flag---enable-library-for-ghci" title="Permalink to this definition">¶</a></dt>
<dt id="cfg-flag---disable-library-for-ghci">
<code class="descname">--disable-library-for-ghci</code><code class="descclassname"> </code><a class="headerlink" href="#cfg-flag---disable-library-for-ghci" title="Permalink to this definition">¶</a></dt>
<dd><table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Default value:</th><td class="field-body">True</td>
</tr>
</tbody>
</table>
<p>Build libraries suitable for use with GHCi. This involves an extra
linking step after the build.</p>
<p>Not all platforms support GHCi and indeed on some platforms, trying
to build GHCi libs fails. In such cases, consider setting
<code class="docutils literal"><span class="pre">library-for-ghci:</span> <span class="pre">False</span></code>.</p>
<p>The command line variant of this flag is
<code class="docutils literal"><span class="pre">--enable-library-for-ghci</span></code> and <code class="docutils literal"><span class="pre">--disable-library-for-ghci</span></code>.</p>
</dd></dl>
<dl class="cfg-field">
<dt id="cfg-field-relocatable">
<code class="descname">relocatable</code><code class="descclassname">: </code><em class="property"></em><a class="headerlink" href="#cfg-field-relocatable" title="Permalink to this definition">¶</a></dt>
<dt id="cfg-flag---relocatable">
<code class="descname">--relocatable</code><code class="descclassname"> </code><a class="headerlink" href="#cfg-flag---relocatable" title="Permalink to this definition">¶</a></dt>
<dd><table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Since:</th><td class="field-body">Cabal 1.21</td>
</tr>
<tr class="field-even field"><th class="field-name">Default value:</th><td class="field-body">False</td>
</tr>
</tbody>
</table>
<p>[STRIKEOUT:Build a package which is relocatable.] (TODO: It is not
clear what this actually does, or if it works at all.)</p>
<p>The command line variant of this flag is <code class="docutils literal"><span class="pre">--relocatable</span></code>.</p>
</dd></dl>
</div>
<div class="section" id="static-linking-options">
<h3>5.5.4.4. Static linking options<a class="headerlink" href="#static-linking-options" title="Permalink to this headline">¶</a></h3>
<dl class="cfg-field">
<dt id="cfg-field-static">
<code class="descname">static</code><code class="descclassname">: </code><em class="property">boolean</em><a class="headerlink" href="#cfg-field-static" title="Permalink to this definition">¶</a></dt>
<dt id="cfg-flag---enable-static">
<code class="descname">--enable-static</code><code class="descclassname"> </code><a class="headerlink" href="#cfg-flag---enable-static" title="Permalink to this definition">¶</a></dt>
<dt id="cfg-flag---disable-static">
<code class="descname">--disable-static</code><code class="descclassname"> </code><a class="headerlink" href="#cfg-flag---disable-static" title="Permalink to this definition">¶</a></dt>
<dd><table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Default value:</th><td class="field-body">False</td>
</tr>
</tbody>
</table>
<p>Roll this and all dependent libraries into a combined <code class="docutils literal"><span class="pre">.a</span></code> archive.
This uses GHCs <code class="docutils literal"><span class="pre">-staticlib</span></code> flag, which is avaiable for iOS and with
GHC 8.4 and later for other platforms as well.</p>
</dd></dl>
</div>
<div class="section" id="foreign-function-interface-options">
<h3>5.5.4.5. Foreign function interface options<a class="headerlink" href="#foreign-function-interface-options" title="Permalink to this headline">¶</a></h3>
<dl class="cfg-field">
<dt id="cfg-field-extra-include-dirs">
<code class="descname">extra-include-dirs</code><code class="descclassname">: </code><em class="property">directories (comma or newline separated list)</em><a class="headerlink" href="#cfg-field-extra-include-dirs" title="Permalink to this definition">¶</a></dt>
<dt id="cfg-flag---extra-include-dirs">
<code class="descname">--extra-include-dirs</code><code class="descclassname">=DIR</code><a class="headerlink" href="#cfg-flag---extra-include-dirs" title="Permalink to this definition">¶</a></dt>
<dd><p>An extra directory to search for C header files. You can use this
flag multiple times to get a list of directories.</p>
<p>You might need to use this flag if you have standard system header
files in a non-standard location that is not mentioned in the
package’s <code class="docutils literal"><span class="pre">.cabal</span></code> file. Using this option has the same affect as
appending the directory <em>dir</em> to the <a class="reference internal" href="developing-packages.html#pkg-field-include-dirs" title="package.cabal include-dirs field"><code class="xref cabal cabal-pkg-field docutils literal"><span class="pre">include-dirs</span></code></a> field in each
library and executable in the package’s <code class="docutils literal"><span class="pre">.cabal</span></code> file. The
advantage of course is that you do not have to modify the package at
all. These extra directories will be used while building the package
and for libraries it is also saved in the package registration
information and used when compiling modules that use the library.</p>
<p>The command line variant of this flag is
<code class="docutils literal"><span class="pre">--extra-include-dirs=DIR</span></code>, which can be specified multiple times.</p>
</dd></dl>
<dl class="cfg-field">
<dt id="cfg-field-extra-lib-dirs">
<code class="descname">extra-lib-dirs</code><code class="descclassname">: </code><em class="property">directories (comma or newline separated list)</em><a class="headerlink" href="#cfg-field-extra-lib-dirs" title="Permalink to this definition">¶</a></dt>
<dt id="cfg-flag---extra-lib-dirs">
<code class="descname">--extra-lib-dirs</code><code class="descclassname">=DIR</code><a class="headerlink" href="#cfg-flag---extra-lib-dirs" title="Permalink to this definition">¶</a></dt>
<dd><p>An extra directory to search for system libraries files.</p>
<p>The command line variant of this flag is <code class="docutils literal"><span class="pre">--extra-lib-dirs=DIR</span></code>,
which can be specified multiple times.</p>
</dd></dl>
<dl class="cfg-field">
<dt id="cfg-field-extra-framework-dirs">
<code class="descname">extra-framework-dirs</code><code class="descclassname">: </code><em class="property">directories (comma or newline separated list)</em><a class="headerlink" href="#cfg-field-extra-framework-dirs" title="Permalink to this definition">¶</a></dt>
<dt id="cfg-flag---extra-framework-dirs">
<code class="descname">--extra-framework-dirs</code><code class="descclassname">=DIR</code><a class="headerlink" href="#cfg-flag---extra-framework-dirs" title="Permalink to this definition">¶</a></dt>
<dd><p>An extra directory to search for frameworks (OS X only).</p>
<p>You might need to use this flag if you have standard system
libraries in a non-standard location that is not mentioned in the
package’s <code class="docutils literal"><span class="pre">.cabal</span></code> file. Using this option has the same affect as
appending the directory <em>dir</em> to the <a class="reference internal" href="#cfg-field-extra-lib-dirs" title="cabal.project extra-lib-dirs field "><code class="xref cabal cabal-cfg-field docutils literal"><span class="pre">extra-lib-dirs</span></code></a> field in
each library and executable in the package’s <code class="docutils literal"><span class="pre">.cabal</span></code> file. The
advantage of course is that you do not have to modify the package at
all. These extra directories will be used while building the package
and for libraries it is also saved in the package registration
information and used when compiling modules that use the library.</p>
<p>The command line variant of this flag is
<code class="docutils literal"><span class="pre">--extra-framework-dirs=DIR</span></code>, which can be specified multiple
times.</p>
</dd></dl>
</div>
<div class="section" id="profiling-options">
<h3>5.5.4.6. Profiling options<a class="headerlink" href="#profiling-options" title="Permalink to this headline">¶</a></h3>
<dl class="cfg-field">
<dt id="cfg-field-profiling">
<code class="descname">profiling</code><code class="descclassname">: </code><em class="property">boolean</em><a class="headerlink" href="#cfg-field-profiling" title="Permalink to this definition">¶</a></dt>
<dt id="cfg-flag---enable-profiling">
<code class="descname">--enable-profiling</code><code class="descclassname"> </code><a class="headerlink" href="#cfg-flag---enable-profiling" title="Permalink to this definition">¶</a></dt>
<dt id="cfg-flag---disable-profiling">
<code class="descname">--disable-profiling</code><code class="descclassname"> </code><a class="headerlink" href="#cfg-flag---disable-profiling" title="Permalink to this definition">¶</a></dt>
<dd><table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Since:</th><td class="field-body">Cabal 1.21</td>
</tr>
<tr class="field-even field"><th class="field-name">Default value:</th><td class="field-body">False</td>
</tr>
</tbody>
</table>
<p>Build libraries and executables with profiling enabled (for
compilers that support profiling as a separate mode). It is only
necessary to specify <a class="reference internal" href="#cfg-field-profiling" title="cabal.project profiling field (since version: 1.21)"><code class="xref cabal cabal-cfg-field docutils literal"><span class="pre">profiling</span></code></a> for the specific package you
want to profile; <code class="docutils literal"><span class="pre">cabal</span> <span class="pre">new-build</span></code> will ensure that all of its
transitive dependencies are built with profiling enabled.</p>
<p>To enable profiling for only libraries or executables, see
<a class="reference internal" href="#cfg-field-library-profiling" title="cabal.project library-profiling field (since version: 1.21)"><code class="xref cabal cabal-cfg-field docutils literal"><span class="pre">library-profiling</span></code></a> and <a class="reference internal" href="#cfg-field-executable-profiling" title="cabal.project executable-profiling field (since version: 1.21)"><code class="xref cabal cabal-cfg-field docutils literal"><span class="pre">executable-profiling</span></code></a>.</p>
<p>For useful profiling, it can be important to control precisely what
cost centers are allocated; see <a class="reference internal" href="#cfg-field-profiling-detail" title="cabal.project profiling-detail field (since version: 1.23)"><code class="xref cabal cabal-cfg-field docutils literal"><span class="pre">profiling-detail</span></code></a>.</p>
<p>The command line variant of this flag is <code class="docutils literal"><span class="pre">--enable-profiling</span></code> and
<code class="docutils literal"><span class="pre">--disable-profiling</span></code>.</p>
</dd></dl>
<dl class="cfg-field">
<dt id="cfg-field-profiling-detail">
<code class="descname">profiling-detail</code><code class="descclassname">: </code><em class="property">level</em><a class="headerlink" href="#cfg-field-profiling-detail" title="Permalink to this definition">¶</a></dt>
<dt id="cfg-flag---profiling-detail">
<code class="descname">--profiling-detail</code><code class="descclassname">=level</code><a class="headerlink" href="#cfg-flag---profiling-detail" title="Permalink to this definition">¶</a></dt>
<dd><table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Since:</th><td class="field-body">Cabal 1.23</td>
</tr>
</tbody>
</table>
<p>Some compilers that support profiling, notably GHC, can allocate
costs to different parts of the program and there are different
levels of granularity or detail with which this can be done. In
particular for GHC this concept is called “cost centers”, and GHC
can automatically add cost centers, and can do so in different ways.</p>
<p>This flag covers both libraries and executables, but can be
overridden by the <code class="docutils literal"><span class="pre">library-profiling-detail</span></code> field.</p>
<p>Currently this setting is ignored for compilers other than GHC. The
levels that cabal currently supports are:</p>
<dl class="docutils">
<dt>default</dt>
<dd>For GHC this uses <code class="docutils literal"><span class="pre">exported-functions</span></code> for libraries and
<code class="docutils literal"><span class="pre">toplevel-functions</span></code> for executables.</dd>
<dt>none</dt>
<dd>No costs will be assigned to any code within this component.</dd>
<dt>exported-functions</dt>
<dd>Costs will be assigned at the granularity of all top level
functions exported from each module. In GHC, this
is for non-inline functions. Corresponds to <code class="docutils literal"><span class="pre">-fprof-auto-exported</span></code>.</dd>
<dt>toplevel-functions</dt>
<dd>Costs will be assigned at the granularity of all top level
functions in each module, whether they are exported from the
module or not. In GHC specifically, this is for non-inline
functions. Corresponds to <code class="docutils literal"><span class="pre">-fprof-auto-top</span></code>.</dd>
<dt>all-functions</dt>
<dd>Costs will be assigned at the granularity of all functions in
each module, whether top level or local. In GHC specifically,
this is for non-inline toplevel or where-bound functions or
values. Corresponds to <code class="docutils literal"><span class="pre">-fprof-auto</span></code>.</dd>
</dl>
<p>The command line variant of this flag is
<code class="docutils literal"><span class="pre">--profiling-detail=none</span></code>.</p>
</dd></dl>
<dl class="cfg-field">
<dt id="cfg-field-library-profiling-detail">
<code class="descname">library-profiling-detail</code><code class="descclassname">: </code><em class="property">level</em><a class="headerlink" href="#cfg-field-library-profiling-detail" title="Permalink to this definition">¶</a></dt>
<dt id="cfg-flag---library-profiling-detail">
<code class="descname">--library-profiling-detail</code><code class="descclassname">=level</code><a class="headerlink" href="#cfg-flag---library-profiling-detail" title="Permalink to this definition">¶</a></dt>
<dd><table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Since:</th><td class="field-body">Cabal 1.23</td>
</tr>
</tbody>
</table>
<p>Like <a class="reference internal" href="#cfg-field-profiling-detail" title="cabal.project profiling-detail field (since version: 1.23)"><code class="xref cabal cabal-cfg-field docutils literal"><span class="pre">profiling-detail</span></code></a>, but applied only to libraries</p>
<p>The command line variant of this flag is
<code class="docutils literal"><span class="pre">--library-profiling-detail=none</span></code>.</p>
</dd></dl>
<dl class="cfg-field">
<dt id="cfg-field-library-vanilla">
<code class="descname">library-vanilla</code><code class="descclassname">: </code><em class="property">boolean</em><a class="headerlink" href="#cfg-field-library-vanilla" title="Permalink to this definition">¶</a></dt>
<dt id="cfg-flag---enable-library-vanilla">
<code class="descname">--enable-library-vanilla</code><code class="descclassname"> </code><a class="headerlink" href="#cfg-flag---enable-library-vanilla" title="Permalink to this definition">¶</a></dt>
<dt id="cfg-flag---disable-library-vanilla">
<code class="descname">--disable-library-vanilla</code><code class="descclassname"> </code><a class="headerlink" href="#cfg-flag---disable-library-vanilla" title="Permalink to this definition">¶</a></dt>
<dd><table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Default value:</th><td class="field-body">True</td>
</tr>
</tbody>
</table>
<p>Build ordinary libraries (as opposed to profiling libraries).
Mostly, you can set this to False to avoid building ordinary
libraries when you are profiling.</p>
<p>The command line variant of this flag is
<code class="docutils literal"><span class="pre">--enable-library-vanilla</span></code> and <code class="docutils literal"><span class="pre">--disable-library-vanilla</span></code>.</p>
</dd></dl>
<dl class="cfg-field">
<dt id="cfg-field-library-profiling">
<code class="descname">library-profiling</code><code class="descclassname">: </code><em class="property">boolean</em><a class="headerlink" href="#cfg-field-library-profiling" title="Permalink to this definition">¶</a></dt>
<dt id="cfg-flag---enable-library-profiling">
<code class="descname">--enable-library-profiling</code><code class="descclassname"> </code><a class="headerlink" href="#cfg-flag---enable-library-profiling" title="Permalink to this definition">¶</a></dt>
<dt id="cfg-flag---disable-library-profiling">
<code class="descname">--disable-library-profiling</code><code class="descclassname"> </code><a class="headerlink" href="#cfg-flag---disable-library-profiling" title="Permalink to this definition">¶</a></dt>
<dd><table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Since:</th><td class="field-body">Cabal 1.21</td>
</tr>
<tr class="field-even field"><th class="field-name">Default value:</th><td class="field-body">False</td>
</tr>
</tbody>
</table>
<p>Build libraries with profiling enabled. You probably want
to use <a class="reference internal" href="#cfg-field-profiling" title="cabal.project profiling field (since version: 1.21)"><code class="xref cabal cabal-cfg-field docutils literal"><span class="pre">profiling</span></code></a> instead.</p>
<p>The command line variant of this flag is
<code class="docutils literal"><span class="pre">--enable-library-profiling</span></code> and <code class="docutils literal"><span class="pre">--disable-library-profiling</span></code>.</p>
</dd></dl>
<dl class="cfg-field">
<dt id="cfg-field-executable-profiling">
<code class="descname">executable-profiling</code><code class="descclassname">: </code><em class="property">boolean</em><a class="headerlink" href="#cfg-field-executable-profiling" title="Permalink to this definition">¶</a></dt>
<dt id="cfg-flag---enable-executable-profiling">
<code class="descname">--enable-executable-profiling</code><code class="descclassname"> </code><a class="headerlink" href="#cfg-flag---enable-executable-profiling" title="Permalink to this definition">¶</a></dt>
<dt id="cfg-flag---disable-executable-profiling">
<code class="descname">--disable-executable-profiling</code><code class="descclassname"> </code><a class="headerlink" href="#cfg-flag---disable-executable-profiling" title="Permalink to this definition">¶</a></dt>
<dd><table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Since:</th><td class="field-body">Cabal 1.21</td>
</tr>
<tr class="field-even field"><th class="field-name">Default value:</th><td class="field-body">False</td>
</tr>
</tbody>
</table>
<p>Build executables with profiling enabled. You probably want
to use <a class="reference internal" href="#cfg-field-profiling" title="cabal.project profiling field (since version: 1.21)"><code class="xref cabal cabal-cfg-field docutils literal"><span class="pre">profiling</span></code></a> instead.</p>
<p>The command line variant of this flag is
<code class="docutils literal"><span class="pre">--enable-executable-profiling</span></code> and
<code class="docutils literal"><span class="pre">--disable-executable-profiling</span></code>.</p>
</dd></dl>
</div>
<div class="section" id="coverage-options">
<h3>5.5.4.7. Coverage options<a class="headerlink" href="#coverage-options" title="Permalink to this headline">¶</a></h3>
<dl class="cfg-field">
<dt id="cfg-field-coverage">
<code class="descname">coverage</code><code class="descclassname">: </code><em class="property">boolean</em><a class="headerlink" href="#cfg-field-coverage" title="Permalink to this definition">¶</a></dt>
<dt id="cfg-flag---enable-coverage">
<code class="descname">--enable-coverage</code><code class="descclassname"> </code><a class="headerlink" href="#cfg-flag---enable-coverage" title="Permalink to this definition">¶</a></dt>
<dt id="cfg-flag---disable-coverage">
<code class="descname">--disable-coverage</code><code class="descclassname"> </code><a class="headerlink" href="#cfg-flag---disable-coverage" title="Permalink to this definition">¶</a></dt>
<dd><table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Since:</th><td class="field-body">Cabal 1.21</td>
</tr>
<tr class="field-even field"><th class="field-name">Default value:</th><td class="field-body">False</td>
</tr>
</tbody>
</table>
<p>Build libraries and executables (including test suites) with Haskell
Program Coverage enabled. Running the test suites will automatically
generate coverage reports with HPC.</p>
<p>The command line variant of this flag is <code class="docutils literal"><span class="pre">--enable-coverage</span></code> and
<code class="docutils literal"><span class="pre">--disable-coverage</span></code>.</p>
</dd></dl>
<dl class="cfg-field">
<dt id="cfg-field-library-coverage">
<code class="descname">library-coverage</code><code class="descclassname">: </code><em class="property">boolean</em><a class="headerlink" href="#cfg-field-library-coverage" title="Permalink to this definition">¶</a></dt>
<dt id="cfg-flag---enable-library-coverage">
<code class="descname">--enable-library-coverage</code><code class="descclassname"> </code><a class="headerlink" href="#cfg-flag---enable-library-coverage" title="Permalink to this definition">¶</a></dt>
<dt id="cfg-flag---disable-library-coverage">
<code class="descname">--disable-library-coverage</code><code class="descclassname"> </code><a class="headerlink" href="#cfg-flag---disable-library-coverage" title="Permalink to this definition">¶</a></dt>
<dd><table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Deprecated:</th><td class="field-body"></td>
</tr>
<tr class="field-even field"><th class="field-name">Since:</th><td class="field-body">Cabal 1.21</td>
</tr>
<tr class="field-odd field"><th class="field-name">Default value:</th><td class="field-body">False</td>
</tr>
</tbody>
</table>
<p>Deprecated, use <a class="reference internal" href="#cfg-field-coverage" title="cabal.project coverage field (since version: 1.21)"><code class="xref cabal cabal-cfg-field docutils literal"><span class="pre">coverage</span></code></a>.</p>
<p>The command line variant of this flag is
<code class="docutils literal"><span class="pre">--enable-library-coverage</span></code> and <code class="docutils literal"><span class="pre">--disable-library-coverage</span></code>.</p>
</dd></dl>
</div>
<div class="section" id="haddock-options">
<h3>5.5.4.8. Haddock options<a class="headerlink" href="#haddock-options" title="Permalink to this headline">¶</a></h3>
<dl class="cfg-field">
<dt id="cfg-field-documentation">
<code class="descname">documentation</code><code class="descclassname">: </code><em class="property">boolean</em><a class="headerlink" href="#cfg-field-documentation" title="Permalink to this definition">¶</a></dt>
<dt id="cfg-flag---enable-documentation">
<code class="descname">--enable-documentation</code><code class="descclassname"> </code><a class="headerlink" href="#cfg-flag---enable-documentation" title="Permalink to this definition">¶</a></dt>
<dt id="cfg-flag---disable-documentation">
<code class="descname">--disable-documentation</code><code class="descclassname"> </code><a class="headerlink" href="#cfg-flag---disable-documentation" title="Permalink to this definition">¶</a></dt>
<dd><table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Default value:</th><td class="field-body">False</td>
</tr>
</tbody>
</table>
<p>Enables building of Haddock documentation</p>
<p>The command line variant of this flag is <code class="docutils literal"><span class="pre">--enable-documentation</span></code>
and <code class="docutils literal"><span class="pre">--disable-documentation</span></code>.</p>
<p><cite>documentation: true</cite> does not imply <a class="reference internal" href="#cfg-field-haddock-benchmarks" title="cabal.project haddock-benchmarks field "><code class="xref cabal cabal-cfg-field docutils literal"><span class="pre">haddock-benchmarks</span></code></a>,
<a class="reference internal" href="#cfg-field-haddock-executables" title="cabal.project haddock-executables field "><code class="xref cabal cabal-cfg-field docutils literal"><span class="pre">haddock-executables</span></code></a>, <a class="reference internal" href="#cfg-field-haddock-internal" title="cabal.project haddock-internal field "><code class="xref cabal cabal-cfg-field docutils literal"><span class="pre">haddock-internal</span></code></a> or
<a class="reference internal" href="#cfg-field-haddock-tests" title="cabal.project haddock-tests field "><code class="xref cabal cabal-cfg-field docutils literal"><span class="pre">haddock-tests</span></code></a>. These need to be enabled separately if
desired.</p>
</dd></dl>
<dl class="cfg-field">
<dt id="cfg-field-doc-index-file">
<code class="descname">doc-index-file</code><code class="descclassname">: </code><em class="property">templated path</em><a class="headerlink" href="#cfg-field-doc-index-file" title="Permalink to this definition">¶</a></dt>
<dt id="cfg-flag---doc-index-file">
<code class="descname">--doc-index-file</code><code class="descclassname">=TEMPLATE</code><a class="headerlink" href="#cfg-flag---doc-index-file" title="Permalink to this definition">¶</a></dt>
<dd><p>A central index of Haddock API documentation (template cannot use
<code class="docutils literal"><span class="pre">$pkgid</span></code>), which should be updated as documentation is built.</p>
<p>The command line variant of this flag is
<code class="docutils literal"><span class="pre">--doc-index-file=TEMPLATE</span></code></p>
</dd></dl>
<p>The following commands are equivalent to ones that would be passed when
running <code class="docutils literal"><span class="pre">setup</span> <span class="pre">haddock</span></code>. (TODO: Where does the documentation get put.)</p>
<dl class="cfg-field">
<dt id="cfg-field-haddock-hoogle">
<code class="descname">haddock-hoogle</code><code class="descclassname">: </code><em class="property">boolean</em><a class="headerlink" href="#cfg-field-haddock-hoogle" title="Permalink to this definition">¶</a></dt>
<dd><table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Default value:</th><td class="field-body">False</td>
</tr>
</tbody>
</table>
<p>Generate a text file which can be converted by <a class="reference external" href="http://www.haskell.org/hoogle/">Hoogle</a>
into a database for searching. This is equivalent to running <code class="docutils literal"><span class="pre">haddock</span></code>
with the <code class="docutils literal"><span class="pre">--hoogle</span></code> flag.</p>
<p>The command line variant of this flag is <code class="docutils literal"><span class="pre">--hoogle</span></code> (for the
<code class="docutils literal"><span class="pre">haddock</span></code> command).</p>
</dd></dl>
<dl class="cfg-field">
<dt id="cfg-field-haddock-html">
<code class="descname">haddock-html</code><code class="descclassname">: </code><em class="property">boolean</em><a class="headerlink" href="#cfg-field-haddock-html" title="Permalink to this definition">¶</a></dt>
<dd><table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Default value:</th><td class="field-body">True</td>
</tr>
</tbody>
</table>
<p>Build HTML documentation.</p>
<p>The command line variant of this flag is <code class="docutils literal"><span class="pre">--html</span></code> (for the
<code class="docutils literal"><span class="pre">haddock</span></code> command).</p>
</dd></dl>
<dl class="cfg-field">
<dt id="cfg-field-haddock-html-location">
<code class="descname">haddock-html-location</code><code class="descclassname">: </code><em class="property">templated path</em><a class="headerlink" href="#cfg-field-haddock-html-location" title="Permalink to this definition">¶</a></dt>
<dd><p>Specify a template for the location of HTML documentation for
prerequisite packages. The substitutions are applied to the template
to obtain a location for each package, which will be used by
hyperlinks in the generated documentation. For example, the
following command generates links pointing at [Hackage] pages:</p>
<div class="highlight-cabal"><div class="highlight"><pre><span></span><span class="k">html-location</span><span class="p">:</span> 'http<span class="p">:</span>//hackage.haskell.org/packages/archive/$pkg/latest/doc/html'
</pre></div>
</div>
<p>Here the argument is quoted to prevent substitution by the shell. If
this option is omitted, the location for each package is obtained
using the package tool (e.g. <code class="docutils literal"><span class="pre">ghc-pkg</span></code>).</p>
<p>The command line variant of this flag is <code class="docutils literal"><span class="pre">--html-location</span></code> (for
the <code class="docutils literal"><span class="pre">haddock</span></code> subcommand).</p>
</dd></dl>
<dl class="cfg-field">
<dt id="cfg-field-haddock-executables">
<code class="descname">haddock-executables</code><code class="descclassname">: </code><em class="property">boolean</em><a class="headerlink" href="#cfg-field-haddock-executables" title="Permalink to this definition">¶</a></dt>
<dd><table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Default value:</th><td class="field-body">False</td>
</tr>
</tbody>
</table>
<p>Run haddock on all executable programs.</p>
<p>The command line variant of this flag is <code class="docutils literal"><span class="pre">--executables</span></code> (for the
<code class="docutils literal"><span class="pre">haddock</span></code> subcommand).</p>
</dd></dl>
<dl class="cfg-field">
<dt id="cfg-field-haddock-tests">
<code class="descname">haddock-tests</code><code class="descclassname">: </code><em class="property">boolean</em><a class="headerlink" href="#cfg-field-haddock-tests" title="Permalink to this definition">¶</a></dt>
<dd><table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Default value:</th><td class="field-body">False</td>
</tr>
</tbody>
</table>
<p>Run haddock on all test suites.</p>
<p>The command line variant of this flag is <code class="docutils literal"><span class="pre">--tests</span></code> (for the
<code class="docutils literal"><span class="pre">haddock</span></code> subcommand).</p>
</dd></dl>
<dl class="cfg-field">
<dt id="cfg-field-haddock-benchmarks">
<code class="descname">haddock-benchmarks</code><code class="descclassname">: </code><em class="property">boolean</em><a class="headerlink" href="#cfg-field-haddock-benchmarks" title="Permalink to this definition">¶</a></dt>
<dd><table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Default value:</th><td class="field-body">False</td>
</tr>
</tbody>
</table>
<p>Run haddock on all benchmarks.</p>
<p>The command line variant of this flag is <code class="docutils literal"><span class="pre">--benchmarks</span></code> (for the
<code class="docutils literal"><span class="pre">haddock</span></code> subcommand).</p>
</dd></dl>
<dl class="cfg-field">
<dt id="cfg-field-haddock-all">
<code class="descname">haddock-all</code><code class="descclassname">: </code><em class="property">boolean</em><a class="headerlink" href="#cfg-field-haddock-all" title="Permalink to this definition">¶</a></dt>
<dd><table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Default value:</th><td class="field-body">False</td>
</tr>
</tbody>
</table>
<p>Run haddock on all components.</p>
<p>The command line variant of this flag is <code class="docutils literal"><span class="pre">--all</span></code> (for the
<code class="docutils literal"><span class="pre">haddock</span></code> subcommand).</p>
</dd></dl>
<dl class="cfg-field">
<dt id="cfg-field-haddock-internal">
<code class="descname">haddock-internal</code><code class="descclassname">: </code><em class="property">boolean</em><a class="headerlink" href="#cfg-field-haddock-internal" title="Permalink to this definition">¶</a></dt>
<dd><table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Default value:</th><td class="field-body">False</td>
</tr>
</tbody>
</table>
<p>Build haddock documentation which includes unexposed modules and
symbols.</p>
<p>The command line variant of this flag is <code class="docutils literal"><span class="pre">--internal</span></code> (for the
<code class="docutils literal"><span class="pre">haddock</span></code> subcommand).</p>
</dd></dl>
<dl class="cfg-field">
<dt id="cfg-field-haddock-css">
<code class="descname">haddock-css</code><code class="descclassname">: </code><em class="property">path</em><a class="headerlink" href="#cfg-field-haddock-css" title="Permalink to this definition">¶</a></dt>
<dd><p>The CSS file that should be used to style the generated
documentation (overriding haddock’s default.)</p>
<p>The command line variant of this flag is <code class="docutils literal"><span class="pre">--css</span></code> (for the
<code class="docutils literal"><span class="pre">haddock</span></code> subcommand).</p>
</dd></dl>
<dl class="cfg-field">
<dt id="cfg-field-haddock-hyperlink-source">
<code class="descname">haddock-hyperlink-source</code><code class="descclassname">: </code><em class="property">boolean</em><a class="headerlink" href="#cfg-field-haddock-hyperlink-source" title="Permalink to this definition">¶</a></dt>
<dd><table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Default value:</th><td class="field-body">False</td>
</tr>
</tbody>
</table>
<p>Generated hyperlinked source code using <a class="reference external" href="http://www.cs.york.ac.uk/fp/darcs/hscolour/">HsColour</a>, and have
Haddock documentation link to it.</p>
<p>The command line variant of this flag is <code class="docutils literal"><span class="pre">--hyperlink-source</span></code> (for
the <code class="docutils literal"><span class="pre">haddock</span></code> subcommand).</p>
</dd></dl>
<dl class="cfg-field">
<dt id="cfg-field-haddock-hscolour-css">
<code class="descname">haddock-hscolour-css</code><code class="descclassname">: </code><em class="property">path</em><a class="headerlink" href="#cfg-field-haddock-hscolour-css" title="Permalink to this definition">¶</a></dt>
<dd><p>The CSS file that should be used to style the generated hyperlinked
source code (from <a class="reference external" href="http://www.cs.york.ac.uk/fp/darcs/hscolour/">HsColour</a>).</p>
<p>The command line variant of this flag is <code class="docutils literal"><span class="pre">--hscolour-css</span></code> (for the
<code class="docutils literal"><span class="pre">haddock</span></code> subcommand).</p>
</dd></dl>
<dl class="cfg-field">
<dt id="cfg-field-haddock-contents-location">
<code class="descname">haddock-contents-location</code><code class="descclassname">: </code><em class="property">URL</em><a class="headerlink" href="#cfg-field-haddock-contents-location" title="Permalink to this definition">¶</a></dt>
<dd><p>A baked-in URL to be used as the location for the contents page.</p>
<p>The command line variant of this flag is <code class="docutils literal"><span class="pre">--contents-location</span></code>
(for the <code class="docutils literal"><span class="pre">haddock</span></code> subcommand).</p>
</dd></dl>
<dl class="cfg-field">
<dt id="cfg-field-haddock-keep-temp-files">
<code class="descname">haddock-keep-temp-files</code><code class="descclassname">: </code><em class="property">boolean</em><a class="headerlink" href="#cfg-field-haddock-keep-temp-files" title="Permalink to this definition">¶</a></dt>
<dd><p>Keep temporary files.</p>
<p>The command line variant of this flag is <code class="docutils literal"><span class="pre">--keep-temp-files</span></code> (for
the <code class="docutils literal"><span class="pre">haddock</span></code> subcommand).</p>
</dd></dl>
</div>
</div>
<div class="section" id="advanced-global-configuration-options">
<h2>5.5.5. Advanced global configuration options<a class="headerlink" href="#advanced-global-configuration-options" title="Permalink to this headline">¶</a></h2>
<dl class="cfg-field">
<dt id="cfg-field-http-transport">
<code class="descname">http-transport</code><code class="descclassname">: </code><em class="property">curl, wget, powershell, or plain-http</em><a class="headerlink" href="#cfg-field-http-transport" title="Permalink to this definition">¶</a></dt>
<dt id="cfg-flag---http-transport">
<code class="descname">--http-transport</code><code class="descclassname">=transport</code><a class="headerlink" href="#cfg-flag---http-transport" title="Permalink to this definition">¶</a></dt>
<dd><table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Default value:</th><td class="field-body"><code class="docutils literal"><span class="pre">curl</span></code></td>
</tr>
</tbody>
</table>
<p>Set a transport to be used when making http(s) requests.</p>
<p>The command line variant of this field is <code class="docutils literal"><span class="pre">--http-transport=curl</span></code>.</p>
</dd></dl>
<dl class="cfg-field">
<dt id="cfg-field-ignore-expiry">
<code class="descname">ignore-expiry</code><code class="descclassname">: </code><em class="property">boolean</em><a class="headerlink" href="#cfg-field-ignore-expiry" title="Permalink to this definition">¶</a></dt>
<dt id="cfg-flag---ignore-expiry">
<code class="descname">--ignore-expiry</code><code class="descclassname"> </code><a class="headerlink" href="#cfg-flag---ignore-expiry" title="Permalink to this definition">¶</a></dt>
<dd><table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Default value:</th><td class="field-body">False</td>
</tr>
</tbody>
</table>
<p>If <code class="docutils literal"><span class="pre">True</span></code>, we will ignore expiry dates on metadata from Hackage.</p>
<p>In general, you should not set this to <code class="docutils literal"><span class="pre">True</span></code> as it will leave you
vulnerable to stale cache attacks. However, it may be temporarily
useful if the main Hackage server is down, and we need to rely on
mirrors which have not been updated for longer than the expiry
period on the timestamp.</p>
<p>The command line variant of this field is <code class="docutils literal"><span class="pre">--ignore-expiry</span></code>.</p>
</dd></dl>
<dl class="cfg-field">
<dt id="cfg-field-remote-repo-cache">
<code class="descname">remote-repo-cache</code><code class="descclassname">: </code><em class="property">directory</em><a class="headerlink" href="#cfg-field-remote-repo-cache" title="Permalink to this definition">¶</a></dt>
<dt id="cfg-flag---remote-repo-cache">
<code class="descname">--remote-repo-cache</code><code class="descclassname">=DIR</code><a class="headerlink" href="#cfg-flag---remote-repo-cache" title="Permalink to this definition">¶</a></dt>
<dd><table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Default value:</th><td class="field-body"><code class="docutils literal"><span class="pre">~/.cabal/packages</span></code></td>
</tr>
</tbody>
</table>
<p>[STRIKEOUT:The location where packages downloaded from remote
repositories will be cached.] Not implemented yet.</p>
<p>The command line variant of this flag is
<code class="docutils literal"><span class="pre">--remote-repo-cache=DIR</span></code>.</p>
</dd></dl>
<dl class="cfg-field">
<dt id="cfg-field-logs-dir">
<code class="descname">logs-dir</code><code class="descclassname">: </code><em class="property">directory</em><a class="headerlink" href="#cfg-field-logs-dir" title="Permalink to this definition">¶</a></dt>
<dt id="cfg-flag---logs-dir">
<code class="descname">--logs-dir</code><code class="descclassname">=DIR</code><a class="headerlink" href="#cfg-flag---logs-dir" title="Permalink to this definition">¶</a></dt>
<dd><table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Default value:</th><td class="field-body"><code class="docutils literal"><span class="pre">~/.cabal/logs</span></code></td>
</tr>
</tbody>
</table>
<p>[STRIKEOUT:The location where build logs for packages are stored.]
Not implemented yet.</p>
<p>The command line variant of this flag is <code class="docutils literal"><span class="pre">--logs-dir=DIR</span></code>.</p>
</dd></dl>
<dl class="cfg-field">
<dt id="cfg-field-build-summary">
<code class="descname">build-summary</code><code class="descclassname">: </code><em class="property">template filepath</em><a class="headerlink" href="#cfg-field-build-summary" title="Permalink to this definition">¶</a></dt>
<dt id="cfg-flag---build-summary">
<code class="descname">--build-summary</code><code class="descclassname">=TEMPLATE</code><a class="headerlink" href="#cfg-flag---build-summary" title="Permalink to this definition">¶</a></dt>
<dd><table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Default value:</th><td class="field-body"><code class="docutils literal"><span class="pre">~/.cabal/logs/build.log</span></code></td>
</tr>
</tbody>
</table>
<p>[STRIKEOUT:The file to save build summaries. Valid variables which
can be used in the path are <code class="docutils literal"><span class="pre">$pkgid</span></code>, <code class="docutils literal"><span class="pre">$compiler</span></code>, <code class="docutils literal"><span class="pre">$os</span></code> and
<code class="docutils literal"><span class="pre">$arch</span></code>.] Not implemented yet.</p>
<p>The command line variant of this flag is
<code class="docutils literal"><span class="pre">--build-summary=TEMPLATE</span></code>.</p>
</dd></dl>
<dl class="cfg-field">
<dt id="cfg-field-local-repo">
<code class="descname">local-repo</code><code class="descclassname">: </code><em class="property">directory</em><a class="headerlink" href="#cfg-field-local-repo" title="Permalink to this definition">¶</a></dt>
<dt id="cfg-flag---local-repo">
<code class="descname">--local-repo</code><code class="descclassname">=DIR</code><a class="headerlink" href="#cfg-flag---local-repo" title="Permalink to this definition">¶</a></dt>
<dd><table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Deprecated:</th><td class="field-body"></td>
</tr>
</tbody>
</table>
<p>[STRIKEOUT:The location of a local repository.] Deprecated. See
“Legacy repositories.”</p>
<p>The command line variant of this flag is <code class="docutils literal"><span class="pre">--local-repo=DIR</span></code>.</p>
</dd></dl>
<dl class="cfg-field">
<dt id="cfg-field-world-file">
<code class="descname">world-file</code><code class="descclassname">: </code><em class="property">path</em><a class="headerlink" href="#cfg-field-world-file" title="Permalink to this definition">¶</a></dt>
<dt id="cfg-flag---world-file">
<code class="descname">--world-file</code><code class="descclassname">=FILE</code><a class="headerlink" href="#cfg-flag---world-file" title="Permalink to this definition">¶</a></dt>
<dd><table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Deprecated:</th><td class="field-body"></td>
</tr>
</tbody>
</table>
<p>[STRIKEOUT:The location of the world file.] Deprecated.</p>
<p>The command line variant of this flag is <code class="docutils literal"><span class="pre">--world-file=FILE</span></code>.</p>
</dd></dl>
<p>Undocumented fields: <code class="docutils literal"><span class="pre">root-cmd</span></code>, <code class="docutils literal"><span class="pre">symlink-bindir</span></code>, <code class="docutils literal"><span class="pre">build-log</span></code>,
<code class="docutils literal"><span class="pre">remote-build-reporting</span></code>, <code class="docutils literal"><span class="pre">report-planned-failure</span></code>, <code class="docutils literal"><span class="pre">one-shot</span></code>,
<code class="docutils literal"><span class="pre">offline</span></code>.</p>
<div class="section" id="advanced-solver-options">
<h3>5.5.5.1. Advanced solver options<a class="headerlink" href="#advanced-solver-options" title="Permalink to this headline">¶</a></h3>
<p>Most users generally won’t need these.</p>
<dl class="cfg-field">
<dt id="cfg-field-solver">
<code class="descname">solver</code><code class="descclassname">: </code><em class="property">modular</em><a class="headerlink" href="#cfg-field-solver" title="Permalink to this definition">¶</a></dt>
<dt id="cfg-flag---solver">
<code class="descname">--solver</code><code class="descclassname">=modular</code><a class="headerlink" href="#cfg-flag---solver" title="Permalink to this definition">¶</a></dt>
<dd><p>This field is reserved to allow the specification of alternative
dependency solvers. At the moment, the only accepted option is
<code class="docutils literal"><span class="pre">modular</span></code>.</p>
<p>The command line variant of this field is <code class="docutils literal"><span class="pre">--solver=modular</span></code>.</p>
</dd></dl>
<dl class="cfg-field">
<dt id="cfg-field-max-backjumps">
<code class="descname">max-backjumps</code><code class="descclassname">: </code><em class="property">nat</em><a class="headerlink" href="#cfg-field-max-backjumps" title="Permalink to this definition">¶</a></dt>
<dt id="cfg-flag---max-backjumps">
<code class="descname">--max-backjumps</code><code class="descclassname">=N</code><a class="headerlink" href="#cfg-flag---max-backjumps" title="Permalink to this definition">¶</a></dt>
<dd><table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Default value:</th><td class="field-body">2000</td>
</tr>
</tbody>
</table>
<p>Maximum number of backjumps (backtracking multiple steps) allowed
while solving. Set -1 to allow unlimited backtracking, and 0 to
disable backtracking completely.</p>
<p>The command line variant of this field is <code class="docutils literal"><span class="pre">--max-backjumps=2000</span></code>.</p>
</dd></dl>
<dl class="cfg-field">
<dt id="cfg-field-reorder-goals">
<code class="descname">reorder-goals</code><code class="descclassname">: </code><em class="property">boolean</em><a class="headerlink" href="#cfg-field-reorder-goals" title="Permalink to this definition">¶</a></dt>
<dt id="cfg-flag---reorder-goals">
<code class="descname">--reorder-goals</code><code class="descclassname"> </code><a class="headerlink" href="#cfg-flag---reorder-goals" title="Permalink to this definition">¶</a></dt>
<dt id="cfg-flag---no-reorder-goals">
<code class="descname">--no-reorder-goals</code><code class="descclassname"> </code><a class="headerlink" href="#cfg-flag---no-reorder-goals" title="Permalink to this definition">¶</a></dt>
<dd><table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Default value:</th><td class="field-body">False</td>
</tr>
</tbody>
</table>
<p>When enabled, the solver will reorder goals according to certain
heuristics. Slows things down on average, but may make backtracking
faster for some packages. It’s unlikely to help for small projects,
but for big install plans it may help you find a plan when otherwise
this is not possible. See <a class="reference external" href="https://github.com/haskell/cabal/issues/1780">#1780</a> for more commentary.</p>
<p>The command line variant of this field is <code class="docutils literal"><span class="pre">--(no-)reorder-goals</span></code>.</p>
</dd></dl>
<dl class="cfg-field">
<dt id="cfg-field-count-conflicts">
<code class="descname">count-conflicts</code><code class="descclassname">: </code><em class="property">boolean</em><a class="headerlink" href="#cfg-field-count-conflicts" title="Permalink to this definition">¶</a></dt>
<dt id="cfg-flag---count-conflicts">
<code class="descname">--count-conflicts</code><code class="descclassname"> </code><a class="headerlink" href="#cfg-flag---count-conflicts" title="Permalink to this definition">¶</a></dt>
<dt id="cfg-flag---no-count-conflicts">
<code class="descname">--no-count-conflicts</code><code class="descclassname"> </code><a class="headerlink" href="#cfg-flag---no-count-conflicts" title="Permalink to this definition">¶</a></dt>
<dd><table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Default value:</th><td class="field-body">True</td>
</tr>
</tbody>
</table>
<p>Try to speed up solving by preferring goals that are involved in a
lot of conflicts.</p>
<p>The command line variant of this field is
<code class="docutils literal"><span class="pre">--(no-)count-conflicts</span></code>.</p>
</dd></dl>
<dl class="cfg-field">
<dt id="cfg-field-strong-flags">
<code class="descname">strong-flags</code><code class="descclassname">: </code><em class="property">boolean</em><a class="headerlink" href="#cfg-field-strong-flags" title="Permalink to this definition">¶</a></dt>
<dt id="cfg-flag---strong-flags">
<code class="descname">--strong-flags</code><code class="descclassname"> </code><a class="headerlink" href="#cfg-flag---strong-flags" title="Permalink to this definition">¶</a></dt>
<dt id="cfg-flag---no-strong-flags">
<code class="descname">--no-strong-flags</code><code class="descclassname"> </code><a class="headerlink" href="#cfg-flag---no-strong-flags" title="Permalink to this definition">¶</a></dt>
<dd><table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Default value:</th><td class="field-body">False</td>
</tr>
</tbody>
</table>
<p>Do not defer flag choices. (TODO: Better documentation.)</p>
<p>The command line variant of this field is <code class="docutils literal"><span class="pre">--(no-)strong-flags</span></code>.</p>
</dd></dl>
<dl class="cfg-field">
<dt id="cfg-field-allow-boot-library-installs">
<code class="descname">allow-boot-library-installs</code><code class="descclassname">: </code><em class="property">boolean</em><a class="headerlink" href="#cfg-field-allow-boot-library-installs" title="Permalink to this definition">¶</a></dt>
<dt id="cfg-flag---allow-boot-library-installs">
<code class="descname">--allow-boot-library-installs</code><code class="descclassname"> </code><a class="headerlink" href="#cfg-flag---allow-boot-library-installs" title="Permalink to this definition">¶</a></dt>
<dt id="cfg-flag---no-allow-boot-library-installs">
<code class="descname">--no-allow-boot-library-installs</code><code class="descclassname"> </code><a class="headerlink" href="#cfg-flag---no-allow-boot-library-installs" title="Permalink to this definition">¶</a></dt>
<dd><table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Default value:</th><td class="field-body">False</td>
</tr>
</tbody>
</table>
<p>By default, the dependency solver doesn’t allow <code class="docutils literal"><span class="pre">base</span></code>,
<code class="docutils literal"><span class="pre">ghc-prim</span></code>, <code class="docutils literal"><span class="pre">integer-simple</span></code>, <code class="docutils literal"><span class="pre">integer-gmp</span></code>, and
<code class="docutils literal"><span class="pre">template-haskell</span></code> to be installed or upgraded. This flag
removes the restriction.</p>
<p>The command line variant of this field is
<code class="docutils literal"><span class="pre">--(no-)allow-boot-library-installs</span></code>.</p>
</dd></dl>
<dl class="cfg-field">
<dt id="cfg-field-cabal-lib-version">
<code class="descname">cabal-lib-version</code><code class="descclassname">: </code><em class="property">version</em><a class="headerlink" href="#cfg-field-cabal-lib-version" title="Permalink to this definition">¶</a></dt>
<dt id="cfg-flag---cabal-lib-version">
<code class="descname">--cabal-lib-version</code><code class="descclassname">=version</code><a class="headerlink" href="#cfg-flag---cabal-lib-version" title="Permalink to this definition">¶</a></dt>
<dd><p>This field selects the version of the Cabal library which should be
used to build packages. This option is intended primarily for
internal development use (e.g., forcing a package to build with a
newer version of Cabal, to test a new version of Cabal.) (TODO:
Specify its semantics more clearly.)</p>
<p>The command line variant of this field is
<code class="docutils literal"><span class="pre">--cabal-lib-version=1.24.0.1</span></code>.</p>
</dd></dl>
</div>
</div>
</div>
</div>
<div class="articleComments">
</div>
</div>
<footer>
<div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
<a href="nix-integration.html" class="btn btn-neutral float-right" title="6. Nix Integration" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right"></span></a>
<a href="nix-local-build-overview.html" class="btn btn-neutral" title="5. Nix-style Local Builds" 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>