6 Suppose that you are in a directory containing a single Cabal package
7 which you wish to build. You can configure and build it using Nix-style
8 local builds with this command (configuring is not necessary):
14 To open a GHCi shell with this package, use this command:
20 To run an executable defined in this package, use this command:
24 $ cabal new-run <executable name> [executable args]
26 Developing multiple packages
27 ----------------------------
29 Many Cabal projects involve multiple packages which need to be built
30 together. To build multiple Cabal packages, you need to first create a
31 ``cabal.project`` file which declares where all the local package
32 directories live. For example, in the Cabal repository, there is a root
33 directory with a folder per package, e.g., the folders ``Cabal`` and
34 ``cabal-install``. The ``cabal.project`` file specifies each folder as
42 The expectation is that a ``cabal.project`` is checked into your source
43 control, to be used by all developers of a project. If you need to make
44 local changes, they can be placed in ``cabal.project.local`` (which
45 should not be checked in.)
47 Then, to build every component of every package, from the top-level
48 directory, run the command: (Warning: cabal-install-1.24 does NOT have
49 this behavior; you will need to upgrade to HEAD.)
55 To build a specific package, you can either run ``new-build`` from the
56 directory of the package in question:
63 or you can pass the name of the package as an argument to
64 ``cabal new-build`` (this works in any subdirectory of the project):
68 $ cabal new-build cabal-install
70 You can also specify a specific component of the package to build. For
71 example, to build a test suite named ``package-tests``, use the command:
75 $ cabal new-build package-tests
77 Targets can be qualified with package names. So to request
78 ``package-tests`` *from* the ``Cabal`` package, use
79 ``Cabal:package-tests``.
81 Unlike sandboxes, there is no need to setup a sandbox or ``add-source``
82 projects; just check in ``cabal.project`` to your repository and
83 ``new-build`` will just work.
88 How can I profile my library/application?
89 -----------------------------------------
91 First, make sure you have HEAD; 1.24 is affected by :issue:`3790`,
92 which means that if any project which transitively depends on a
93 package which has a Custom setup built against Cabal 1.22 or earlier
94 will silently not work.
96 Create or edit your ``cabal.project.local``, adding the following
101 Now, ``cabal new-build`` will automatically build all libraries and
102 executables with profiling. You can fine-tune the profiling settings
103 for each package using :cfg-field:`profiling-detail`::
106 profiling-detail: toplevel-functions
108 Alternately, you can call ``cabal new-build --enable-profiling`` to
109 temporarily build with profiling.
114 Local versus external packages
115 ------------------------------
117 One of the primary innovations of Nix-style local builds is the
118 distinction between local packages, which users edit and recompile and
119 must be built per-project, versus external packages, which can be cached
120 across projects. To be more precise:
122 1. A **local package** is one that is listed explicitly in the
123 ``packages``, ``optional-packages`` or ``extra-packages`` field of a
124 project. Usually, these refer to packages whose source code lives
125 directly in a folder in your project (although, you can list an
126 arbitrary Hackage package in ``extra-packages`` to force it to be
129 Local packages, as well as the external packages (below) which depend on
130 them, are built **inplace**, meaning that they are always built
131 specifically for the project and are not installed globally. Inplace
132 packages are not cached and not given unique hashes, which makes them
133 suitable for packages which you want to edit and recompile.
135 2. An **external package** is any package which is not listed in the
136 ``packages`` field. The source code for external packages is usually
137 retrieved from Hackage.
139 When an external package does not depend on an inplace package, it can
140 be built and installed to a **global** store, which can be shared across
141 projects. These build products are identified by a hash that over all of
142 the inputs which would influence the compilation of a package (flags,
143 dependency selection, etc.). Just as in Nix, these hashes uniquely
144 identify the result of a build; if we compute this identifier and we
145 find that we already have this ID built, we can just use the already
148 The global package store is ``~/.cabal/store`` (configurable via
149 global `store-dir` option); if you need to clear your store for
150 whatever reason (e.g., to reclaim disk space or because the global
151 store is corrupted), deleting this directory is safe (``new-build``
152 will just rebuild everything it needs on its next invocation).
154 This split motivates some of the UI choices for Nix-style local build
155 commands. For example, flags passed to ``cabal new-build`` are only
156 applied to *local* packages, so that adding a flag to
157 ``cabal new-build`` doesn't necessitate a rebuild of *every* transitive
158 dependency in the global package store.
160 In cabal-install HEAD, Nix-style local builds also take advantage of a
161 new Cabal library feature, `per-component
162 builds <https://github.com/ezyang/ghc-proposals/blob/master/proposals/0000-componentized-cabal.rst>`__,
163 where each component of a package is configured and built separately.
164 This can massively speed up rebuilds of packages with lots of components
165 (e.g., a package that defines multiple executables), as only one
166 executable needs to be rebuilt. Packages that use Custom setup scripts
167 are not currently built on a per-component basis.
169 Where are my build products?
170 ----------------------------
172 A major deficiency in the current implementation of new-build is that
173 there is no programmatic way to access the location of build products.
174 The location of the build products is intended to be an internal
175 implementation detail of new-build, but we also understand that many
176 unimplemented features (e.g., ``new-install``) can only be reasonably
177 worked around by accessing build products directly.
179 The location where build products can be found varies depending on the
180 version of cabal-install:
182 - In cabal-install-1.24, the dist directory for a package ``p-0.1`` is
183 stored in ``dist-newstyle/build/p-0.1``. For example, if you built an
184 executable or test suite named ``pexe``, it would be located at
185 ``dist-newstyle/build/p-0.1/build/pexe/pexe``.
187 - In cabal-install HEAD, the dist directory for a package ``p-0.1``
188 defining a library built with GHC 8.0.1 on 64-bit Linux is
189 ``dist-newstyle/build/x86_64-linux/ghc-8.0.1/p-0.1``. When
190 per-component builds are enabled (any non-Custom package), a
191 subcomponent like an executable or test suite named ``pexe`` will be
193 ``dist-newstyle/build/x86_64-linux/ghc-8.0.1/p-0.1/c/pexe``; thus,
194 the full path of the executable is
195 ``dist-newstyle/build/x86_64-linux/ghc-8.0.1/p-0.1/c/pexe/build/pexe/pexe``
196 (you can see why we want this to be an implementation detail!)
198 The paths are a bit longer in HEAD but the benefit is that you can
199 transparently have multiple builds with different versions of GHC. We
200 plan to add the ability to create aliases for certain build
201 configurations, and more convenient paths to access particularly useful
202 build products like executables.
207 Nix-style local builds sport a robust caching system which help reduce
208 the time it takes to execute a rebuild cycle. While the details of how
209 ``cabal-install`` does caching are an implementation detail and may
210 change in the future, knowing what gets cached is helpful for
211 understanding the performance characteristics of invocations to
212 ``new-build``. The cached intermediate results are stored in
213 ``dist-newstyle/cache``; this folder can be safely deleted to clear the
216 The following intermediate results are cached in the following files in
217 this folder (the most important two are first):
219 ``solver-plan`` (binary)
220 The result of calling the dependency solver, assuming that the
221 Hackage index, local ``cabal.project`` file, and local ``cabal``
222 files are unmodified. (Notably, we do NOT have to dependency solve
223 again if new build products are stored in the global store; the
224 invocation of the dependency solver is independent of what is
225 already available in the store.)
226 ``source-hashes`` (binary)
227 The hashes of all local source files. When all local source files of
228 a local package are unchanged, ``cabal new-build`` will skip
229 invoking ``setup build`` entirely (saving us from a possibly
230 expensive call to ``ghc --make``). The full list of source files
231 participating in compilation are determined using
232 ``setup sdist --list-sources`` (thus, if you do not list all your
233 source files in a Cabal file, you may fail to recompile when you
235 ``config`` (same format as ``cabal.project``)
236 The full project configuration, merged from ``cabal.project`` (and
237 friends) as well as the command line arguments.
238 ``compiler`` (binary)
239 The configuration of the compiler being used to build the project.
240 ``improved-plan`` (binary)
241 Like ``solver-plan``, but with all non-inplace packages improved
242 into pre-existing copies from the store.
244 Note that every package also has a local cache managed by the Cabal
245 build system, e.g., in ``$distdir/cache``.
247 There is another useful file in ``dist-newstyle/cache``, ``plan.json``,
248 which is a JSON serialization of the computed install plan. (TODO: docs)
253 We now give an in-depth description of all the commands, describing the
254 arguments and flags they accept.
259 ``cabal new-configure`` takes a set of arguments and writes a
260 ``cabal.project.local`` file based on the flags passed to this command.
261 ``cabal new-configure FLAGS; cabal new-build`` is roughly equivalent to
262 ``cabal new-build FLAGS``, except that with ``new-configure`` the flags
263 are persisted to all subsequent calls to ``new-build``.
265 ``cabal new-configure`` is intended to be a convenient way to write out
266 a ``cabal.project.local`` for simple configurations; e.g.,
267 ``cabal new-configure -w ghc-7.8`` would ensure that all subsequent
268 builds with ``cabal new-build`` are performed with the compiler
269 ``ghc-7.8``. For more complex configuration, we recommend writing the
270 ``cabal.project.local`` file directly (or placing it in
273 ``cabal new-configure`` inherits options from ``Cabal``. semantics:
275 - Any flag accepted by ``./Setup configure``.
277 - Any flag accepted by ``cabal configure`` beyond
278 ``./Setup configure``, namely ``--cabal-lib-version``,
279 ``--constraint``, ``--preference`` and ``--solver.``
281 - Any flag accepted by ``cabal install`` beyond ``./Setup configure``.
283 - Any flag accepted by ``./Setup haddock``.
285 The options of all of these flags apply only to *local* packages in a
286 project; this behavior is different than that of ``cabal install``,
287 which applies flags to every package that would be built. The motivation
288 for this is to avoid an innocuous addition to the flags of a package
289 resulting in a rebuild of every package in the store (which might need
290 to happen if a flag actually applied to every transitive dependency). To
291 apply options to an external package, use a ``package`` stanza in a
292 ``cabal.project`` file.
297 ``cabal new-update`` updates the state of the package index. If the
298 project contains multiple remote package repositories it will update
299 the index of all of them (e.g. when using overlays).
305 $ cabal new-update # update all remote repos
306 $ cabal new-update head.hackage # update only head.hackage
311 ``cabal new-build`` takes a set of targets and builds them. It
312 automatically handles building and installing any dependencies of these
315 A target can take any of the following forms:
317 - A package target: ``package``, which specifies that all enabled
318 components of a package to be built. By default, test suites and
319 benchmarks are *not* enabled, unless they are explicitly requested
320 (e.g., via ``--enable-tests``.)
322 - A component target: ``[package:][ctype:]component``, which specifies
323 a specific component (e.g., a library, executable, test suite or
324 benchmark) to be built.
326 - All packages: ``all``, which specifies all packages within the project.
328 - Components of a particular type: ``package:ctypes``, ``all:ctypes``:
329 which specifies all components of the given type. Where valid
331 - ``libs``, ``libraries``,
332 - ``flibs``, ``foreign-libraries``,
333 - ``exes``, ``executables``,
335 - ``benches``, ``benchmarks``.
337 In component targets, ``package:`` and ``ctype:`` (valid component types
338 are ``lib``, ``flib``, ``exe``, ``test`` and ``bench``) can be used to
339 disambiguate when multiple packages define the same component, or the
340 same component name is used in a package (e.g., a package ``foo``
341 defines both an executable and library named ``foo``). We always prefer
342 interpreting a target as a package name rather than as a component name.
344 Some example targets:
348 $ cabal new-build lib:foo-pkg # build the library named foo-pkg
349 $ cabal new-build foo-pkg:foo-tests # build foo-tests in foo-pkg
351 (There is also syntax for specifying module and file targets, but it
352 doesn't currently do anything.)
354 Beyond a list of targets, ``cabal new-build`` accepts all the flags that
355 ``cabal new-configure`` takes. Most of these flags are only taken into
356 consideration when building local packages; however, some flags may
357 cause extra store packages to be built (for example,
358 ``--enable-profiling`` will automatically make sure profiling libraries
359 for all transitive dependencies are built and installed.)
364 ``cabal new-repl TARGET`` loads all of the modules of the target into
365 GHCi as interpreted bytecode. It takes the same flags as
368 Currently, it is not supported to pass multiple targets to ``new-repl``
369 (``new-repl`` will just successively open a separate GHCi session for
375 ``cabal new-run [TARGET [ARGS]]`` runs the executable specified by the
376 target, which can be a component, a package or can be left blank, as
377 long as it can uniquely identify an executable within the project.
379 See `the new-build section <#cabal-new-build>`__ for the target syntax.
381 Except in the case of the empty target, the strings after it will be
382 passed to the executable as arguments.
384 If one of the arguments starts with ``-`` it will be interpreted as
385 a cabal flag, so if you need to pass flags to the executable you
386 have to separate them with ``--``.
390 $ cabal new-run target -- -a -bcd --argument
395 ``cabal new-freeze`` writes out a **freeze file** which records all of
396 the versions and flags which that are picked by the solver under the
397 current index and flags. Default name of this file is
398 ``cabal.project.freeze`` but in combination with a
399 ``--project-file=my.project`` flag (see :ref:`project-file
400 <cmdoption-project-file>`)
401 the name will be ``my.project.freeze``.
402 A freeze file has the same syntax as ``cabal.project`` and looks
409 constraints: HTTP ==4000.3.3,
410 HTTP +warp-tests -warn-as-error -network23 +network-uri -mtl1 -conduit10,
412 QuickCheck +templatehaskell,
416 For end-user executables, it is recommended that you distribute the
417 ``cabal.project.freeze`` file in your source repository so that all
418 users see a consistent set of dependencies. For libraries, this is not
419 recommended: users often need to build against different versions of
420 libraries than what you developed against.
425 ``cabal new-bench [TARGETS] [OPTIONS]`` runs the specified benchmarks
426 (all the benchmarks in the current package by default), first ensuring
432 ``cabal new-test [TARGETS] [OPTIONS]`` runs the specified test suites
433 (all the test suites in the current package by default), first ensuring
439 ``cabal new-haddock [FLAGS] TARGET`` builds Haddock documentation for
440 the specified packages within the project.
445 ``cabal new-exec [FLAGS] [--] COMMAND [--] [ARGS]`` runs the specified command
446 using the project's environment. That is, passing the right flags to compiler
447 invocations and bringing the project's executables into scope.
452 The following commands are not currently supported:
454 ``cabal new-install`` (:issue:`3737` and :issue:`3332`)
455 Workaround: no good workaround at the moment. (But note that you no
456 longer need to install libraries before building!)
458 Configuring builds with cabal.project
459 =====================================
461 ``cabal.project`` files support a variety of options which configure the
462 details of your build. The general syntax of a ``cabal.project`` file is
463 similar to that of a Cabal file: there are a number of fields, some of
464 which live inside stanzas:
469 with-compiler: /opt/ghc/8.0.1/bin/ghc
474 In general, the accepted field names coincide with the accepted command
475 line flags that ``cabal install`` and other commands take. For example,
476 ``cabal new-configure --enable-profiling`` will write out a project
477 file with ``profiling: True``.
479 The full configuration of a project is determined by combining the
480 following sources (later entries override earlier ones):
482 1. ``~/.cabal/config`` (the user-wide global configuration)
484 2. ``cabal.project`` (the project configuratoin)
486 3. ``cabal.project.freeze`` (the output of ``cabal new-freeze``)
488 4. ``cabal.project.local`` (the output of ``cabal new-configure``)
491 Specifying the local packages
492 -----------------------------
494 The following top-level options specify what the local packages of a
497 .. cfg-field:: packages: package location list (space or comma separated)
498 :synopsis: Project packages.
500 :default: ``./*.cabal``
502 Specifies the list of package locations which contain the local
503 packages to be built by this project. Package locations can take the
506 1. They can specify a Cabal file, or a directory containing a Cabal
507 file, e.g., ``packages: Cabal cabal-install/cabal-install.cabal``.
509 2. They can specify a glob-style wildcards, which must match one or
510 more (a) directories containing a (single) Cabal file, (b) Cabal
511 files (extension ``.cabal``), or (c) [STRIKEOUT:tarballs which
512 contain Cabal packages (extension ``.tar.gz``)] (not implemented
513 yet). For example, to match all Cabal files in all
514 subdirectories, as well as the Cabal projects in the parent
515 directories ``foo`` and ``bar``, use
516 ``packages: */*.cabal ../{foo,bar}/``
518 3. [STRIKEOUT:They can specify an ``http``, ``https`` or ``file``
519 URL, representing the path to a remote tarball to be downloaded
520 and built.] (not implemented yet)
522 There is no command line variant of this field; see :issue:`3585`.
524 .. cfg-field:: optional-packages: package location list (space or comma-separated)
525 :synopsis: Optional project packages.
527 :default: ``./*/*.cabal``
529 Like :cfg-field:`packages`, specifies a list of package locations
530 containing local packages to be built. Unlike :cfg-field:`packages`,
531 if we glob for a package, it is permissible for the glob to match against
532 zero packages. The intended use-case for :cfg-field:`optional-packages`
533 is to make it so that vendored packages can be automatically picked up if
534 they are placed in a subdirectory, but not error if there aren't any.
536 There is no command line variant of this field.
538 .. cfg-field:: extra-packages: package list with version bounds (comma separated)
539 :synopsis: Adds external pacakges as local
541 [STRIKEOUT:Specifies a list of external packages from Hackage which
542 should be considered local packages.] (Not implemented)
544 There is no command line variant of this field.
546 [STRIKEOUT:There is also a stanza ``source-repository-package`` for
547 specifying packages from an external version control.] (Not
550 All local packages are *vendored*, in the sense that if other packages
551 (including external ones from Hackage) depend on a package with the name
552 of a local package, the local package is preferentially used. This
553 motivates the default settings::
556 optional-packages: ./*/*.cabal
558 ...any package can be vendored simply by making a checkout in the
559 top-level project directory, as might be seen in this hypothetical
563 foo-helper/ # local package
564 unix/ # vendored external package
566 All of these options support globs. ``cabal new-build`` has its own glob
569 - Anywhere in a path, as many times as you like, you can specify an
570 asterisk ``*`` wildcard. E.g., ``*/*.cabal`` matches all ``.cabal``
571 files in all immediate subdirectories. Like in glob(7), asterisks do
572 not match hidden files unless there is an explicit period, e.g.,
573 ``.*/foo.cabal`` will match ``.private/foo.cabal`` (but
574 ``*/foo.cabal`` will not).
576 - You can use braces to specify specific directories; e.g.,
577 ``{vendor,pkgs}/*.cabal`` matches all Cabal files in the ``vendor``
578 and ``pkgs`` subdirectories.
580 Formally, the format described by the following BNF:
584 FilePathGlob ::= FilePathRoot FilePathGlobRel
585 FilePathRoot ::= {- empty -} # relative to cabal.project
587 | [a-zA-Z] ":" [/\\] # Windows root
588 | "~" # home directory
589 FilePathGlobRel ::= Glob "/" FilePathGlobRel # Unix directory
590 | Glob "\\" FilePathGlobRel # Windows directory
592 | {- empty -} # trailing slash
594 GlobPiece ::= "*" # wildcard
595 | [^*{},/\\] * # literal string
596 | "\\" [*{},] # escaped reserved character
597 | "{" Glob "," ... "," Glob "}" # union (match any of these)
599 Global configuration options
600 ----------------------------
602 The following top-level configuration options are not specific to any
603 package, and thus apply globally:
605 .. cfg-field:: verbose: nat
607 :synopsis: Build verbosity level.
611 Control the verbosity of ``cabal`` commands, valid values are from 0
614 The command line variant of this field is ``--verbose=2``; a short
615 form ``-v2`` is also supported.
617 .. cfg-field:: jobs: nat or $ncpus
618 --jobs=n, -jn, --jobs=$ncpus
619 :synopsis: Number of builds running in parallel.
623 Run *nat* jobs simultaneously when building. If ``$ncpus`` is
624 specified, run the number of jobs equal to the number of CPUs.
625 Package building is often quite parallel, so turning on parallelism
626 can speed up build times quite a bit!
628 The command line variant of this field is ``--jobs=2``; a short form
629 ``-j2`` is also supported; a bare ``--jobs`` or ``-j`` is equivalent
630 to ``--jobs=$ncpus``.
632 .. cfg-field:: keep-going: boolean
634 :synopsis: Try to continue building on failure.
638 If true, after a build failure, continue to build other unaffected
641 The command line variant of this field is ``--keep-going``.
643 .. option:: --builddir=DIR
645 Specifies the name of the directory where build products for
646 build will be stored; defaults to ``dist-newstyle``. If a
647 relative name is specified, this directory is resolved relative
648 to the root of the project (i.e., where the ``cabal.project``
651 This option cannot be specified via a ``cabal.project`` file.
653 .. _cmdoption-project-file:
654 .. option:: --project-file=FILE
656 Specifies the name of the project file used to specify the
657 rest of the top-level configuration; defaults to ``cabal.project``.
658 This name not only specifies the name of the main project file,
659 but also the auxiliary project files ``cabal.project.freeze``
660 and ``cabal.project.local``; for example, if you specify
661 ``--project-file=my.project``, then the other files that will
662 be probed are ``my.project.freeze`` and ``my.project.local``.
664 If the specified project file is a relative path, we will
665 look for the file relative to the current working directory,
666 and then for the parent directory, until the project file is
667 found or we have hit the top of the user's home directory.
669 This option cannot be specified via a ``cabal.project`` file.
671 .. option:: --store-dir=DIR
673 Specifies the name of the directory of the global package store.
675 Solver configuration options
676 ----------------------------
678 The following settings control the behavior of the dependency solver:
680 .. cfg-field:: constraints: constraints list (comma separated)
681 --constraint="pkg >= 2.0"
682 :synopsis: Extra dependencies constraints.
684 Add extra constraints to the version bounds, flag settings,
685 and other properties a solver can pick for a
686 package. For example:
690 constraints: bar == 2.1
692 A package can be specified multiple times in ``constraints``, in
693 which case the specified constraints are intersected. This is
694 useful, since the syntax does not allow you to specify multiple
695 constraints at once. For example, to specify both version bounds and
696 flag assignments, you would write:
700 constraints: bar == 2.1,
703 Valid constraints take the same form as for the `constraint
705 <installing-packages.html#cmdoption-setup-configure--constraint>`__.
707 .. cfg-field:: preferences: preference (comma separated)
708 --preference="pkg >= 2.0"
709 :synopsis: Prefered dependency versions.
711 Like :cfg-field:`constraints`, but the solver will attempt to satisfy
712 these preferences on a best-effort basis. The resulting install is locally
713 optimal with respect to preferences; specifically, no single package
714 could be replaced with a more preferred version that still satisfies
715 the hard constraints.
717 Operationally, preferences can cause the solver to attempt certain
718 version choices of a package before others, which can improve
719 dependency solver runtime.
721 One way to use :cfg-field:`preferences` is to take a known working set of
722 constraints (e.g., via ``cabal new-freeze``) and record them as
723 preferences. In this case, the solver will first attempt to use this
724 configuration, and if this violates hard constraints, it will try to
725 find the minimal number of upgrades to satisfy the hard constraints
728 The command line variant of this field is
729 ``--preference="pkg >= 2.0"``; to specify multiple preferences, pass
730 the flag multiple times.
732 .. cfg-field:: allow-newer: none, all or list of scoped package names (space or comma separated)
733 --allow-newer, --allow-newer=[none,all,[scope:][^]pkg]
734 :synopsis: Lift dependencies upper bound constaints.
738 Allow the solver to pick an newer version of some packages than
739 would normally be permitted by than the :pkg-field:`build-depends` bounds
740 of packages in the install plan. This option may be useful if the
741 dependency solver cannot otherwise find a valid install plan.
743 For example, to relax ``pkg``\ s :pkg-field:`build-depends` upper bound on
744 ``dep-pkg``, write a scoped package name of the form:
748 allow-newer: pkg:dep-pkg
750 If the scope shall be limited to specific releases of ``pkg``, the
755 allow-newer: pkg-1.2.3:dep-pkg, pkg-1.1.2:dep-pkg
757 can be used to limit the relaxation of dependencies on
758 ``dep-pkg`` by the ``pkg-1.2.3`` and ``pkg-1.1.2`` releases only.
760 The scoped syntax is recommended, as it is often only a single package
761 whose upper bound is misbehaving. In this case, the upper bounds of
762 other packages should still be respected; indeed, relaxing the bound
763 can break some packages which test the selected version of packages.
765 The syntax also allows to prefix the dependee package with a
766 modifier symbol to modify the scope/semantic of the relaxation
767 transformation in a additional ways. Currently only one modifier
768 symbol is defined, i.e. ``^`` (i.e. caret) which causes the
769 relaxation to be applied only to ``^>=`` operators and leave all other
770 version operators untouched.
772 However, in some situations (e.g., when attempting to build packages
773 on a new version of GHC), it is useful to disregard *all*
774 upper-bounds, with respect to a package or all packages. This can be
775 done by specifying just a package name, or using the keyword ``all``
776 to specify all packages:
780 -- Disregard upper bounds involving the dependencies on
781 -- packages bar, baz. For quux only, relax
782 -- 'quux ^>= ...'-style constraints only.
783 allow-newer: bar, baz, ^quux
785 -- Disregard all upper bounds when dependency solving
788 -- Disregard all `^>=`-style upper bounds when dependency solving
792 For consistency, there is also the explicit wildcard scope syntax
793 ``*`` (or its alphabetic synonym ``all``). Consequently, the
794 examples above are equivalent to the explicitly scoped variants:
798 allow-newer: all:bar, *:baz, *:^quux
804 allow-newer: all:^all
806 In order to ignore all bounds specified by a package ``pkg-1.2.3``
807 you can combine scoping with a right-hand-side wildcard like so
811 -- Disregard any upper bounds specified by pkg-1.2.3
812 allow-newer: pkg-1.2.3:*
814 -- Disregard only `^>=`-style upper bounds in pkg-1.2.3
815 allow-newer: pkg-1.2.3:^*
818 :cfg-field:`allow-newer` is often used in conjunction with a constraint
819 (in the cfg-field:`constraints` field) forcing the usage of a specific,
820 newer version of a package.
822 The command line variant of this field is e.g. ``--allow-newer=bar``. A
823 bare ``--allow-newer`` is equivalent to ``--allow-newer=all``.
825 .. cfg-field:: allow-older: none, all, list of scoped package names (space or comma separated)
826 --allow-older, --allow-older=[none,all,[scope:][^]pkg]
827 :synopsis: Lift dependency lower bound constaints.
832 Like :cfg-field:`allow-newer`, but applied to lower bounds rather than
835 The command line variant of this field is ``--allow-older=all``. A
836 bare ``--allow-older`` is equivalent to ``--allow-older=all``.
839 .. cfg-field:: index-state: HEAD, unix-timestamp, ISO8601 UTC timestamp.
840 :synopsis: Use source package index state as it existed at a previous time.
845 This allows to change the source package index state the solver uses
846 to compute install-plans. This is particularly useful in
847 combination with freeze-files in order to also freeze the state the
848 package index was in at the time the install-plan was frozen.
852 -- UNIX timestamp format example
853 index-state: @1474739268
855 -- ISO8601 UTC timestamp format example
856 -- This format is used by 'cabal new-configure'
857 -- for storing `--index-state` values.
858 index-state: 2016-09-24T17:47:48Z
861 Package configuration options
862 -----------------------------
864 Package options affect the building of specific packages. There are two
865 ways a package option can be specified:
867 - They can be specified at the top-level, in which case they apply only
868 to **local package**, or
870 - They can be specified inside a ``package`` stanza, in which case they
871 apply to the build of the package, whether or not it is local or
874 For example, the following options specify that :cfg-field:`optimization`
875 should be turned off for all local packages, and that ``bytestring`` (possibly
876 an external dependency) should be built with ``-fno-state-hack``::
881 ghc-options: -fno-state-hack
883 ``ghc-options`` is not specifically described in this documentation,
884 but is one of many fields for configuring programs. They take the form
885 ``progname-options`` and ``progname-location``, and
886 can only be set inside package stanzas. (TODO: They are not supported
887 at top-level, see :issue:`3579`.)
889 At the moment, there is no way to specify an option to apply to all
890 external packages or all inplace packages. Additionally, it is only
891 possible to specify these options on the command line for all local
892 packages (there is no per-package command line interface.)
894 Some flags were added by more recent versions of the Cabal library. This
895 means that they are NOT supported by packages which use Custom setup
896 scripts that require a version of the Cabal library older than when the
899 .. cfg-field:: flags: list of +flagname or -flagname (space separated)
900 --flags="+foo -bar", -ffoo, -f-bar
901 :synopsis: Enable or disable package flags.
903 Force all flags specified as ``+flagname`` to be true, and all flags
904 specified as ``-flagname`` to be false. For example, to enable the
905 flag ``foo`` and disable ``bar``, set:
911 If there is no leading punctuation, it is assumed that the flag
912 should be enabled; e.g., this is equivalent:
918 Flags are *per-package*, so it doesn't make much sense to specify
919 flags at the top-level, unless you happen to know that *all* of your
920 local packages support the same named flags. If a flag is not
921 supported by a package, it is ignored.
923 See also the solver configuration field :cfg-field:`constraints`.
925 The command line variant of this flag is ``--flags``. There is also
926 a shortened form ``-ffoo -f-bar``.
928 A common mistake is to say ``cabal new-build -fhans``, where
929 ``hans`` is a flag for a transitive dependency that is not in the
930 local package; in this case, the flag will be silently ignored. If
931 ``haskell-tor`` is the package you want this flag to apply to, try
932 ``--constraint="haskell-tor +hans"`` instead.
934 .. cfg-field:: with-compiler: executable
935 --with-compiler=executable
936 :synopsis: Path to compiler executable.
938 Specify the path to a particular compiler to be used. If not an
939 absolute path, it will be resolved according to the :envvar:`PATH`
940 environment. The type of the compiler (GHC, GHCJS, etc) must be
941 consistent with the setting of the :cfg-field:`compiler` field.
943 The most common use of this option is to specify a different version
944 of your compiler to be used; e.g., if you have ``ghc-7.8`` in your
945 path, you can specify ``with-compiler: ghc-7.8`` to use it.
947 This flag also sets the default value of :cfg-field:`with-hc-pkg`, using
948 the heuristic that it is named ``ghc-pkg-7.8`` (if your executable name
949 is suffixed with a version number), or is the executable named
950 ``ghc-pkg`` in the same directory as the ``ghc`` directory. If this
951 heuristic does not work, set :cfg-field:`with-hc-pkg` explicitly.
953 For inplace packages, ``cabal new-build`` maintains a separate build
954 directory for each version of GHC, so you can maintain multiple
955 build trees for different versions of GHC without clobbering each
958 At the moment, it's not possible to set :cfg-field:`with-compiler` on a
959 per-package basis, but eventually we plan on relaxing this
960 restriction. If this is something you need, give us a shout.
962 The command line variant of this flag is
963 ``--with-compiler=ghc-7.8``; there is also a short version
966 .. cfg-field:: with-hc-pkg: executable
967 --with-hc-pkg=executable
968 :synopsis: Specifies package tool.
970 Specify the path to the package tool, e.g., ``ghc-pkg``. This
971 package tool must be compatible with the compiler specified by
972 :cfg-field:`with-compiler` (generally speaking, it should be precisely
973 the tool that was distributed with the compiler). If this option is
974 omitted, the default value is determined from :cfg-field:`with-compiler`.
976 The command line variant of this flag is
977 ``--with-hc-pkg=ghc-pkg-7.8``.
979 .. cfg-field:: optimization: nat
980 --enable-optimization
981 --disable-optimization
982 :synopsis: Build with optimization.
986 Build with optimization. This is appropriate for production use,
987 taking more time to build faster libraries and programs.
989 The optional *nat* value is the optimisation level. Some compilers
990 support multiple optimisation levels. The range is 0 to 2. Level 0
991 disables optimization, level 1 is the default. Level 2 is higher
992 optimisation if the compiler supports it. Level 2 is likely to lead
993 to longer compile times and bigger generated code. If you are not
994 planning to run code, turning off optimization will lead to better
995 build times and less code to be rebuilt when a module changes.
997 When optimizations are enabled, Cabal passes ``-O2`` to the C compiler.
999 We also accept ``True`` (equivalent to 1) and ``False`` (equivalent
1002 Note that as of GHC 8.0, GHC does not recompile when optimization
1003 levels change (see :ghc-ticket:`10923`), so if
1004 you change the optimization level for a local package you may need
1005 to blow away your old build products in order to rebuild with the
1006 new optimization level.
1008 The command line variant of this flag is ``-O2`` (with ``-O1``
1009 equivalent to ``-O``). There are also long-form variants
1010 ``--enable-optimization`` and ``--disable-optimization``.
1012 .. cfg-field:: configure-options: args (space separated)
1013 --configure-option=arg
1014 :synopsis: Options to pass to configure script.
1016 A list of extra arguments to pass to the external ``./configure``
1017 script, if one is used. This is only useful for packages which have
1018 the ``Configure`` build type. See also the section on
1020 parameters <developing-packages.html#system-dependent-parameters>`__.
1022 The command line variant of this flag is ``--configure-option=arg``,
1023 which can be specified multiple times to pass multiple options.
1025 .. cfg-field:: compiler: ghc, ghcjs, jhc, lhc, uhc or haskell-suite
1027 :synopsis: Compiler to build with.
1031 Specify which compiler toolchain to be used. This is independent of
1032 ``with-compiler``, because the choice of toolchain affects Cabal's
1035 The command line variant of this flag is ``--compiler=ghc``.
1037 .. cfg-field:: tests: boolean
1040 :synopsis: Build tests.
1044 Force test suites to be enabled. For most users this should not be
1045 needed, as we always attempt to solve for test suite dependencies,
1046 even when this value is ``False``; furthermore, test suites are
1047 automatically enabled if they are requested as a built target.
1049 The command line variant of this flag is ``--enable-tests`` and
1050 ``--disable-tests``.
1052 .. cfg-field:: benchmarks: boolean
1054 --disable-benchmarks
1055 :synopsis: Build benchmarks.
1059 Force benchmarks to be enabled. For most users this should not be
1060 needed, as we always attempt to solve for benchmark dependencies,
1061 even when this value is ``False``; furthermore, benchmarks are
1062 automatically enabled if they are requested as a built target.
1064 The command line variant of this flag is ``--enable-benchmarks`` and
1065 ``--disable-benchmarks``.
1067 .. cfg-field:: extra-prog-path: paths (newline or comma separated)
1068 --extra-prog-path=PATH
1069 :synopsis: Add directories to program search path.
1072 A list of directories to search for extra required programs. Most
1073 users should not need this, as programs like ``happy`` and ``alex``
1074 will automatically be installed and added to the path. This can be
1075 useful if a ``Custom`` setup script relies on an exotic extra
1078 The command line variant of this flag is ``--extra-prog-path=PATH``,
1079 which can be specified multiple times.
1081 .. cfg-field:: run-tests: boolean
1083 :synopsis: Run package test suite upon installation.
1087 Run the package test suite upon installation. This is useful for
1088 saying "When this package is installed, check that the test suite
1089 passes, terminating the rest of the build if it is broken."
1093 One deficiency: the :cfg-field:`run-tests` setting of a package is NOT
1094 recorded as part of the hash, so if you install something without
1095 :cfg-field:`run-tests` and then turn on ``run-tests``, we won't
1096 subsequently test the package. If this is causing you problems, give
1099 The command line variant of this flag is ``--run-tests``.
1104 .. cfg-field:: debug-info: integer
1105 --enable-debug-info=<n>
1106 --disable-debug-info
1107 :synopsis: Build with debug info enabled.
1112 If the compiler (e.g., GHC 7.10 and later) supports outputing OS
1113 native debug info (e.g., DWARF), setting ``debug-info: True`` will
1114 instruct it to do so. See the GHC wiki page on :ghc-wiki:`DWARF`
1115 for more information about this feature.
1117 (This field also accepts numeric syntax, but until GHC 8.2 this didn't
1120 The command line variant of this flag is ``--enable-debug-info`` and
1121 ``--disable-debug-info``.
1123 .. cfg-field:: split-sections: boolean
1124 --enable-split-sections
1125 --disable-split-sections
1126 :synopsis: Use GHC's split sections feature.
1131 Use the GHC ``-split-sections`` feature when building the library. This
1132 reduces the final size of the executables that use the library by
1133 allowing them to link with only the bits that they use rather than
1134 the entire library. The downside is that building the library takes
1135 longer and uses a bit more memory.
1137 This feature is supported by GHC 8.0 and later.
1139 The command line variant of this flag is ``--enable-split-sections`` and
1140 ``--disable-split-sections``.
1142 .. cfg-field:: split-objs: boolean
1144 --disable-split-objs
1145 :synopsis: Use GHC's split objects feature.
1149 Use the GHC ``-split-objs`` feature when building the library. This
1150 reduces the final size of the executables that use the library by
1151 allowing them to link with only the bits that they use rather than
1152 the entire library. The downside is that building the library takes
1153 longer and uses considerably more memory.
1155 It is generally recommend that you use ``split-sections`` instead
1156 of ``split-objs`` where possible.
1158 The command line variant of this flag is ``--enable-split-objs`` and
1159 ``--disable-split-objs``.
1161 .. cfg-field:: executable-stripping: boolean
1162 --enable-executable-stripping
1163 --disable-executable-stripping
1164 :synopsis: Strip installed programs.
1168 When installing binary executable programs, run the ``strip``
1169 program on the binary. This can considerably reduce the size of the
1170 executable binary file. It does this by removing debugging
1171 information and symbols.
1173 Not all Haskell implementations generate native binaries. For such
1174 implementations this option has no effect.
1176 (TODO: Check what happens if you combine this with ``debug-info``.)
1178 The command line variant of this flag is
1179 ``--enable-executable-stripping`` and
1180 ``--disable-executable-stripping``.
1182 .. cfg-field:: library-stripping: boolean
1183 --enable-library-stripping
1184 --disable-library-stripping
1185 :synopsis: Strip installed libraries.
1188 When installing binary libraries, run the ``strip`` program on the
1189 binary, saving space on the file system. See also
1190 ``executable-stripping``.
1192 The command line variant of this flag is
1193 ``--enable-library-stripping`` and ``--disable-library-stripping``.
1198 .. cfg-field:: program-prefix: prefix
1199 --program-prefix=prefix
1200 :synopsis: Prepend prefix to program names.
1202 [STRIKEOUT:Prepend *prefix* to installed program names.] (Currently
1203 implemented in a silly and not useful way. If you need this to work
1206 *prefix* may contain the following path variables: ``$pkgid``,
1207 ``$pkg``, ``$version``, ``$compiler``, ``$os``, ``$arch``, ``$abi``,
1210 The command line variant of this flag is ``--program-prefix=foo-``.
1212 .. cfg-field:: program-suffix: suffix
1213 --program-suffix=suffix
1214 :synopsis: Append refix to program names.
1216 [STRIKEOUT:Append *suffix* to installed program names.] (Currently
1217 implemented in a silly and not useful way. If you need this to work
1220 The most obvious use for this is to append the program's version
1221 number to make it possible to install several versions of a program
1222 at once: ``program-suffix: $version``.
1224 *suffix* may contain the following path variables: ``$pkgid``,
1225 ``$pkg``, ``$version``, ``$compiler``, ``$os``, ``$arch``, ``$abi``,
1228 The command line variant of this flag is
1229 ``--program-suffix='$version'``.
1231 Dynamic linking options
1232 ^^^^^^^^^^^^^^^^^^^^^^^
1234 .. cfg-field:: shared: boolean
1237 :synopsis: Build shared library.
1241 Build shared library. This implies a separate compiler run to
1242 generate position independent code as required on most platforms.
1244 The command line variant of this flag is ``--enable-shared`` and
1245 ``--disable-shared``.
1247 .. cfg-field:: executable-dynamic: boolean
1248 --enable-executable-dynamic
1249 --disable-executable-dynamic
1250 :synopsis: Link executables dynamically.
1254 Link executables dynamically. The executable's library dependencies
1255 should be built as shared objects. This implies ``shared: True``
1256 unless ``shared: False`` is explicitly specified.
1258 The command line variant of this flag is
1259 ``--enable-executable-dynamic`` and
1260 ``--disable-executable-dynamic``.
1262 .. cfg-field:: library-for-ghci: boolean
1263 --enable-library-for-ghci
1264 --disable-library-for-ghci
1265 :synopsis: Build libraries suitable for use with GHCi.
1269 Build libraries suitable for use with GHCi. This involves an extra
1270 linking step after the build.
1272 Not all platforms support GHCi and indeed on some platforms, trying
1273 to build GHCi libs fails. In such cases, consider setting
1274 ``library-for-ghci: False``.
1276 The command line variant of this flag is
1277 ``--enable-library-for-ghci`` and ``--disable-library-for-ghci``.
1279 .. cfg-field:: relocatable:
1281 :synopsis: Build relocatable package.
1286 [STRIKEOUT:Build a package which is relocatable.] (TODO: It is not
1287 clear what this actually does, or if it works at all.)
1289 The command line variant of this flag is ``--relocatable``.
1291 Static linking options
1292 ^^^^^^^^^^^^^^^^^^^^^^
1294 .. cfg-field:: static: boolean
1297 :synopsis: Build static library.
1302 Roll this and all dependent libraries into a combined ``.a`` archive.
1303 This uses GHCs ``-staticlib`` flag, which is avaiable for iOS and with
1304 GHC 8.4 and later for other platforms as well.
1306 Foreign function interface options
1307 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1309 .. cfg-field:: extra-include-dirs: directories (comma or newline separated list)
1310 --extra-include-dirs=DIR
1311 :synopsis: Adds C header search path.
1313 An extra directory to search for C header files. You can use this
1314 flag multiple times to get a list of directories.
1316 You might need to use this flag if you have standard system header
1317 files in a non-standard location that is not mentioned in the
1318 package's ``.cabal`` file. Using this option has the same affect as
1319 appending the directory *dir* to the :pkg-field:`include-dirs` field in each
1320 library and executable in the package's ``.cabal`` file. The
1321 advantage of course is that you do not have to modify the package at
1322 all. These extra directories will be used while building the package
1323 and for libraries it is also saved in the package registration
1324 information and used when compiling modules that use the library.
1326 The command line variant of this flag is
1327 ``--extra-include-dirs=DIR``, which can be specified multiple times.
1329 .. cfg-field:: extra-lib-dirs: directories (comma or newline separated list)
1330 --extra-lib-dirs=DIR
1331 :synopsis: Adds library search directory.
1333 An extra directory to search for system libraries files.
1335 The command line variant of this flag is ``--extra-lib-dirs=DIR``,
1336 which can be specified multiple times.
1338 .. cfg-field:: extra-framework-dirs: directories (comma or newline separated list)
1339 --extra-framework-dirs=DIR
1340 :synopsis: Adds framework search directory (OS X only).
1342 An extra directory to search for frameworks (OS X only).
1344 You might need to use this flag if you have standard system
1345 libraries in a non-standard location that is not mentioned in the
1346 package's ``.cabal`` file. Using this option has the same affect as
1347 appending the directory *dir* to the :cfg-field:`extra-lib-dirs` field in
1348 each library and executable in the package's ``.cabal`` file. The
1349 advantage of course is that you do not have to modify the package at
1350 all. These extra directories will be used while building the package
1351 and for libraries it is also saved in the package registration
1352 information and used when compiling modules that use the library.
1354 The command line variant of this flag is
1355 ``--extra-framework-dirs=DIR``, which can be specified multiple
1361 .. cfg-field:: profiling: boolean
1364 :synopsis: Enable profiling builds.
1369 Build libraries and executables with profiling enabled (for
1370 compilers that support profiling as a separate mode). It is only
1371 necessary to specify :cfg-field:`profiling` for the specific package you
1372 want to profile; ``cabal new-build`` will ensure that all of its
1373 transitive dependencies are built with profiling enabled.
1375 To enable profiling for only libraries or executables, see
1376 :cfg-field:`library-profiling` and :cfg-field:`executable-profiling`.
1378 For useful profiling, it can be important to control precisely what
1379 cost centers are allocated; see :cfg-field:`profiling-detail`.
1381 The command line variant of this flag is ``--enable-profiling`` and
1382 ``--disable-profiling``.
1384 .. cfg-field:: profiling-detail: level
1385 --profiling-detail=level
1386 :synopsis: Profiling detail level.
1389 Some compilers that support profiling, notably GHC, can allocate
1390 costs to different parts of the program and there are different
1391 levels of granularity or detail with which this can be done. In
1392 particular for GHC this concept is called "cost centers", and GHC
1393 can automatically add cost centers, and can do so in different ways.
1395 This flag covers both libraries and executables, but can be
1396 overridden by the ``library-profiling-detail`` field.
1398 Currently this setting is ignored for compilers other than GHC. The
1399 levels that cabal currently supports are:
1402 For GHC this uses ``exported-functions`` for libraries and
1403 ``toplevel-functions`` for executables.
1405 No costs will be assigned to any code within this component.
1407 Costs will be assigned at the granularity of all top level
1408 functions exported from each module. In GHC, this
1409 is for non-inline functions. Corresponds to ``-fprof-auto-exported``.
1411 Costs will be assigned at the granularity of all top level
1412 functions in each module, whether they are exported from the
1413 module or not. In GHC specifically, this is for non-inline
1414 functions. Corresponds to ``-fprof-auto-top``.
1416 Costs will be assigned at the granularity of all functions in
1417 each module, whether top level or local. In GHC specifically,
1418 this is for non-inline toplevel or where-bound functions or
1419 values. Corresponds to ``-fprof-auto``.
1421 The command line variant of this flag is
1422 ``--profiling-detail=none``.
1424 .. cfg-field:: library-profiling-detail: level
1425 --library-profiling-detail=level
1426 :synopsis: Libraries profiling detail level.
1429 Like :cfg-field:`profiling-detail`, but applied only to libraries
1431 The command line variant of this flag is
1432 ``--library-profiling-detail=none``.
1434 .. cfg-field:: library-vanilla: boolean
1435 --enable-library-vanilla
1436 --disable-library-vanilla
1437 :synopsis: Build libraries without profiling.
1441 Build ordinary libraries (as opposed to profiling libraries).
1442 Mostly, you can set this to False to avoid building ordinary
1443 libraries when you are profiling.
1445 The command line variant of this flag is
1446 ``--enable-library-vanilla`` and ``--disable-library-vanilla``.
1448 .. cfg-field:: library-profiling: boolean
1449 --enable-library-profiling
1450 --disable-library-profiling
1451 :synopsis: Build libraries with profiling enabled.
1456 Build libraries with profiling enabled. You probably want
1457 to use :cfg-field:`profiling` instead.
1459 The command line variant of this flag is
1460 ``--enable-library-profiling`` and ``--disable-library-profiling``.
1462 .. cfg-field:: executable-profiling: boolean
1463 --enable-executable-profiling
1464 --disable-executable-profiling
1465 :synopsis: Build executables with profiling enabled.
1470 Build executables with profiling enabled. You probably want
1471 to use :cfg-field:`profiling` instead.
1473 The command line variant of this flag is
1474 ``--enable-executable-profiling`` and
1475 ``--disable-executable-profiling``.
1480 .. cfg-field:: coverage: boolean
1483 :synopsis: Build with coverage enabled.
1488 Build libraries and executables (including test suites) with Haskell
1489 Program Coverage enabled. Running the test suites will automatically
1490 generate coverage reports with HPC.
1492 The command line variant of this flag is ``--enable-coverage`` and
1493 ``--disable-coverage``.
1495 .. cfg-field:: library-coverage: boolean
1496 --enable-library-coverage
1497 --disable-library-coverage
1503 Deprecated, use :cfg-field:`coverage`.
1505 The command line variant of this flag is
1506 ``--enable-library-coverage`` and ``--disable-library-coverage``.
1511 Documentation building support is fairly sparse at the moment. Let us
1512 know if it's a priority for you!
1514 .. cfg-field:: documentation: boolean
1515 --enable-documentation
1516 --disable-documentation
1517 :synopsis: Enable building of documentation.
1521 Enables building of Haddock documentation
1523 The command line variant of this flag is ``--enable-documentation``
1524 and ``--disable-documentation``.
1526 .. cfg-field:: doc-index-file: templated path
1527 --doc-index-file=TEMPLATE
1528 :synopsis: Path to haddock templates.
1530 A central index of Haddock API documentation (template cannot use
1531 ``$pkgid``), which should be updated as documentation is built.
1533 The command line variant of this flag is
1534 ``--doc-index-file=TEMPLATE``
1536 The following commands are equivalent to ones that would be passed when
1537 running ``setup haddock``. (TODO: Where does the documentation get put.)
1539 .. cfg-field:: haddock-hoogle: boolean
1540 :synopsis: Generate Hoogle file.
1544 Generate a text file which can be converted by Hoogle_
1545 into a database for searching. This is equivalent to running ``haddock``
1546 with the ``--hoogle`` flag.
1548 The command line variant of this flag is ``--hoogle`` (for the
1549 ``haddock`` command).
1551 .. cfg-field:: haddock-html: boolean
1552 :synopsis: Build HTML documentation.
1556 Build HTML documentation.
1558 The command line variant of this flag is ``--html`` (for the
1559 ``haddock`` command).
1561 .. cfg-field:: haddock-html-location: templated path
1562 :synopsis: Haddock HTML templates location.
1564 Specify a template for the location of HTML documentation for
1565 prerequisite packages. The substitutions are applied to the template
1566 to obtain a location for each package, which will be used by
1567 hyperlinks in the generated documentation. For example, the
1568 following command generates links pointing at [Hackage] pages:
1572 html-location: 'http://hackage.haskell.org/packages/archive/$pkg/latest/doc/html'
1574 Here the argument is quoted to prevent substitution by the shell. If
1575 this option is omitted, the location for each package is obtained
1576 using the package tool (e.g. ``ghc-pkg``).
1578 The command line variant of this flag is ``--html-location`` (for
1579 the ``haddock`` subcommand).
1581 .. cfg-field:: haddock-executables: boolean
1582 :synopsis: Generate documentation for executables.
1586 Run haddock on all executable programs.
1588 The command line variant of this flag is ``--executables`` (for the
1589 ``haddock`` subcommand).
1591 .. cfg-field:: haddock-tests: boolean
1592 :synopsis: Generate documentation for tests.
1596 Run haddock on all test suites.
1598 The command line variant of this flag is ``--tests`` (for the
1599 ``haddock`` subcommand).
1601 .. cfg-field:: haddock-benchmarks: boolean
1602 :synopsis: Generate documentation for benchmarks.
1606 Run haddock on all benchmarks.
1608 The command line variant of this flag is ``--benchmarks`` (for the
1609 ``haddock`` subcommand).
1611 .. cfg-field:: haddock-all: boolean
1612 :synopsis: Generate documentation for everything
1616 Run haddock on all components.
1618 The command line variant of this flag is ``--all`` (for the
1619 ``haddock`` subcommand).
1621 .. cfg-field:: haddock-internal: boolean
1622 :synopsis: Generate documentation for internal modules
1626 Build haddock documentation which includes unexposed modules and
1629 The command line variant of this flag is ``--internal`` (for the
1630 ``haddock`` subcommand).
1632 .. cfg-field:: haddock-css: path
1633 :synopsis: Location of Haddoc CSS file.
1635 The CSS file that should be used to style the generated
1636 documentation (overriding haddock's default.)
1638 The command line variant of this flag is ``--css`` (for the
1639 ``haddock`` subcommand).
1641 .. cfg-field:: haddock-hyperlink-source: boolean
1642 :synopsis: Generate hyperlinked source code for documentation
1646 Generated hyperlinked source code using `HsColour`_, and have
1647 Haddock documentation link to it.
1649 The command line variant of this flag is ``--hyperlink-source`` (for
1650 the ``haddock`` subcommand).
1652 .. cfg-field:: haddock-hscolour-css: path
1653 :synopsis: Location of CSS file for HsColour
1655 The CSS file that should be used to style the generated hyperlinked
1656 source code (from `HsColour`_).
1658 The command line variant of this flag is ``--hscolour-css`` (for the
1659 ``haddock`` subcommand).
1661 .. cfg-field:: haddock-contents-location: URL
1662 :synopsis: URL for contents page.
1664 A baked-in URL to be used as the location for the contents page.
1666 The command line variant of this flag is ``--contents-location``
1667 (for the ``haddock`` subcommand).
1669 .. cfg-field:: haddock-keep-temp-files: boolean
1670 :synopsis: Keep temporary Haddock files.
1672 Keep temporary files.
1674 The command line variant of this flag is ``--keep-temp-files`` (for
1675 the ``haddock`` subcommand).
1677 Advanced global configuration options
1678 -------------------------------------
1680 .. cfg-field:: http-transport: curl, wget, powershell, or plain-http
1681 --http-transport=transport
1682 :synopsis: Transport to use with http(s) requests.
1686 Set a transport to be used when making http(s) requests.
1688 The command line variant of this field is ``--http-transport=curl``.
1690 .. cfg-field:: ignore-expiry: boolean
1692 :synopsis: Ignore Hackage expiration dates.
1696 If ``True``, we will ignore expiry dates on metadata from Hackage.
1698 In general, you should not set this to ``True`` as it will leave you
1699 vulnerable to stale cache attacks. However, it may be temporarily
1700 useful if the main Hackage server is down, and we need to rely on
1701 mirrors which have not been updated for longer than the expiry
1702 period on the timestamp.
1704 The command line variant of this field is ``--ignore-expiry``.
1706 .. cfg-field:: remote-repo-cache: directory
1707 --remote-repo-cache=DIR
1708 :synopsis: Location of packages cache.
1710 :default: ``~/.cabal/packages``
1712 [STRIKEOUT:The location where packages downloaded from remote
1713 repositories will be cached.] Not implemented yet.
1715 The command line variant of this flag is
1716 ``--remote-repo-cache=DIR``.
1718 .. cfg-field:: logs-dir: directory
1720 :synopsis: Directory to store build logs.
1722 :default: ``~/.cabal/logs``
1724 [STRIKEOUT:The location where build logs for packages are stored.]
1725 Not implemented yet.
1727 The command line variant of this flag is ``--logs-dir=DIR``.
1729 .. cfg-field:: build-summary: template filepath
1730 --build-summary=TEMPLATE
1731 :synopsis: Build summaries location.
1733 :default: ``~/.cabal/logs/build.log``
1735 [STRIKEOUT:The file to save build summaries. Valid variables which
1736 can be used in the path are ``$pkgid``, ``$compiler``, ``$os`` and
1737 ``$arch``.] Not implemented yet.
1739 The command line variant of this flag is
1740 ``--build-summary=TEMPLATE``.
1742 .. cfg-field:: local-repo: directory
1746 [STRIKEOUT:The location of a local repository.] Deprecated. See
1747 "Legacy repositories."
1749 The command line variant of this flag is ``--local-repo=DIR``.
1751 .. cfg-field:: world-file: path
1755 [STRIKEOUT:The location of the world file.] Deprecated.
1757 The command line variant of this flag is ``--world-file=FILE``.
1759 Undocumented fields: ``root-cmd``, ``symlink-bindir``, ``build-log``,
1760 ``remote-build-reporting``, ``report-planned-failure``, ``one-shot``,
1763 Advanced solver options
1764 ^^^^^^^^^^^^^^^^^^^^^^^
1766 Most users generally won't need these.
1768 .. cfg-field:: solver: modular
1770 :synopsis: Which solver to use.
1772 This field is reserved to allow the specification of alternative
1773 dependency solvers. At the moment, the only accepted option is
1776 The command line variant of this field is ``--solver=modular``.
1778 .. cfg-field:: max-backjumps: nat
1780 :synopsis: Maximum number of solver backjumps.
1784 Maximum number of backjumps (backtracking multiple steps) allowed
1785 while solving. Set -1 to allow unlimited backtracking, and 0 to
1786 disable backtracking completely.
1788 The command line variant of this field is ``--max-backjumps=2000``.
1790 .. cfg-field:: reorder-goals: boolean
1793 :synopsis: Allow solver to reorder goals.
1797 When enabled, the solver will reorder goals according to certain
1798 heuristics. Slows things down on average, but may make backtracking
1799 faster for some packages. It's unlikely to help for small projects,
1800 but for big install plans it may help you find a plan when otherwise
1801 this is not possible. See :issue:`1780` for more commentary.
1803 The command line variant of this field is ``--(no-)reorder-goals``.
1805 .. cfg-field:: count-conflicts: boolean
1807 --no-count-conflicts
1808 :synopsis: Solver prefers versions with less conflicts.
1812 Try to speed up solving by preferring goals that are involved in a
1815 The command line variant of this field is
1816 ``--(no-)count-conflicts``.
1818 .. cfg-field:: strong-flags: boolean
1821 :synopsis: Do not defer flag choices when solving.
1825 Do not defer flag choices. (TODO: Better documentation.)
1827 The command line variant of this field is ``--(no-)strong-flags``.
1829 .. cfg-field:: allow-boot-library-installs: boolean
1830 --allow-boot-library-installs
1831 --no-allow-boot-library-installs
1832 :synopsis: Allow cabal to install or upgrade any package.
1836 By default, the dependency solver doesn't allow ``base``,
1837 ``ghc-prim``, ``integer-simple``, ``integer-gmp``, and
1838 ``template-haskell`` to be installed or upgraded. This flag
1839 removes the restriction.
1841 The command line variant of this field is
1842 ``--(no-)allow-boot-library-installs``.
1844 .. cfg-field:: cabal-lib-version: version
1845 --cabal-lib-version=version
1846 :synopsis: Version of Cabal library used to build package.
1848 This field selects the version of the Cabal library which should be
1849 used to build packages. This option is intended primarily for
1850 internal development use (e.g., forcing a package to build with a
1851 newer version of Cabal, to test a new version of Cabal.) (TODO:
1852 Specify its semantics more clearly.)
1854 The command line variant of this field is
1855 ``--cabal-lib-version=1.24.0.1``.
1857 .. include:: references.inc