| blob | ebd154cadd3fdf063d4ce53b6a3a067b2f4d3aa8 |
1 cabal.project Reference
2 =======================
4 ``cabal.project`` files support a variety of options which configure the
5 details of your build. The general syntax of a ``cabal.project`` file is
6 similar to that of a Cabal file: there are a number of fields, some of
7 which live inside stanzas (groups of fields that apply to only part of a
8 project or can be referenced as a unit):
10 ::
12 packages: */*.cabal
13 with-compiler: /opt/ghc/8.0.1/bin/ghc
15 package cryptohash
16 optimization: False
18 In general, the accepted field names coincide with the accepted command
19 line flags that ``cabal install`` and other commands take. For example,
20 ``cabal v2-configure --enable-profiling`` will write out a project
21 file with ``profiling: True``.
23 The full configuration of a project is determined by combining the
24 following sources (later entries override earlier ones, except for appendable
25 options):
27 1. ``~/.cabal/config`` (the user-wide global configuration)
29 2. ``cabal.project`` (the project configuration)
31 3. ``cabal.project.freeze`` (the output of ``cabal v2-freeze``)
33 4. ``cabal.project.local`` (the output of ``cabal v2-configure``)
36 Specifying the local packages
37 -----------------------------
39 The following top-level options specify what the local packages of a
40 project are:
42 .. cfg-field:: packages: package location list (space or comma separated)
43 :synopsis: Project packages.
45 :default: ``./*.cabal``
47 Specifies the list of package locations which contain the local
48 packages to be built by this project. Package locations can take the
49 following forms:
51 1. They can specify a Cabal file, or a directory containing a Cabal
52 file, e.g., ``packages: Cabal cabal-install/cabal-install.cabal``.
54 2. They can specify glob-style wildcards, which must match one or
55 more (a) directories containing a (single) Cabal file, (b) Cabal
56 files (extension ``.cabal``), or (c) tarballs which contain Cabal
57 packages (extension ``.tar.gz``).
58 For example, to match all Cabal files in all
59 subdirectories, as well as the Cabal projects in the parent
60 directories ``foo`` and ``bar``, use
61 ``packages: */*.cabal ../{foo,bar}/``
63 3. They can specify an ``http``, ``https`` or ``file``
64 URL, representing the path to a remote tarball to be downloaded
65 and built.
67 There is no command line variant of this field; see :issue:`3585`.
68 Note that the default value is only included if there is no
69 ``cabal.project`` file. The field is appendable which means there would be
70 no way to drop the default value if it was included.
72 .. cfg-field:: optional-packages: package location list (space or comma-separated)
73 :synopsis: Optional project packages.
75 :default: empty
77 Like :cfg-field:`packages`, specifies a list of package locations
78 containing local packages to be built. Unlike :cfg-field:`packages`,
79 if we glob for a package, it is permissible for the glob to match against
80 zero packages. The intended use-case for :cfg-field:`optional-packages`
81 is to make it so that vendored packages can be automatically picked up if
82 they are placed in a subdirectory, but not error if there aren't any.
84 There is no command line variant of this field.
86 .. cfg-field:: extra-packages: package list with version bounds (comma separated)
87 :synopsis: Adds external packages as local
89 [STRIKEOUT:Specifies a list of external packages from Hackage which
90 should be considered local packages.] (Not implemented)
92 There is no command line variant of this field.
96 All local packages are *vendored*, in the sense that if other packages
97 (including external ones from Hackage) depend on a package with the name
98 of a local package, the local package is preferentially used.
99 For subdirectories to be considered local packages, the following setting
100 can be used::
102 packages: ./*.cabal
103 optional-packages: ./*/*.cabal
105 ...then any package can be vendored simply by making a checkout in the
106 top-level project directory, as might be seen in this hypothetical
107 directory layout::
109 foo.cabal
110 foo-helper/ # local package
111 unix/ # vendored external package
113 All of these options support globs. ``cabal v2-build`` has its own glob
114 format:
116 - Anywhere in a path, as many times as you like, you can specify an
117 asterisk ``*`` wildcard. E.g., ``*/*.cabal`` matches all ``.cabal``
118 files in all immediate subdirectories. Like in glob(7), asterisks do
119 not match hidden files unless there is an explicit period, e.g.,
120 ``.*/foo.cabal`` will match ``.private/foo.cabal`` (but
121 ``*/foo.cabal`` will not).
123 - You can use braces to specify specific directories; e.g.,
124 ``{vendor,pkgs}/*.cabal`` matches all Cabal files in the ``vendor``
125 and ``pkgs`` subdirectories.
127 Formally, the format is described by the following BNF:
129 .. todo::
130 convert globbing grammar to proper ABNF_ syntax
132 .. code-block:: abnf
134 FilePathGlob ::= FilePathRoot FilePathGlobRel
135 FilePathRoot ::= {- empty -} # relative to cabal.project
136 | "/" # Unix root
137 | [a-zA-Z] ":" [/\\] # Windows root
138 | "~" # home directory
139 FilePathGlobRel ::= Glob "/" FilePathGlobRel # Unix directory
140 | Glob "\\" FilePathGlobRel # Windows directory
141 | Glob # file
142 | {- empty -} # trailing slash
143 Glob ::= GlobPiece *
144 GlobPiece ::= "*" # wildcard
145 | [^*{},/\\] * # literal string
146 | "\\" [*{},] # escaped reserved character
147 | "{" Glob "," ... "," Glob "}" # union (match any of these)
150 Specifying Packages from Remote Version Control Locations
151 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
153 Starting with Cabal 2.4, there is now a stanza
154 ``source-repository-package`` for specifying packages from an external
155 version control.
157 .. code-block:: cabal
159 packages: .
161 source-repository-package
162 type: git
163 location: https://github.com/hvr/HsYAML.git
164 tag: e70cf0c171c9a586b62b3f75d72f1591e4e6aaa1
166 source-repository-package
167 type: git
168 location: https://github.com/well-typed/cborg
169 tag: 3d274c14ca3077c3a081ba7ad57c5182da65c8c1
170 subdir: cborg
172 source-repository-package
173 type: git
174 location: https://github.com/haskell/network.git
175 tag: e76fdc753e660dfa615af6c8b6a2ad9ddf6afe70
176 post-checkout-command: autoreconf -i
178 cabal-install 3.4 sdists the ``source-repository-package`` repositories and uses resulting tarballs as project packages.
179 This allows sharing of packages across different projects.
181 .. cfg-field:: type: VCS kind
183 .. cfg-field:: location: VCS location (usually URL)
185 .. cfg-field:: type: VCS tag
187 .. cfg-field:: subdir: subdirectory list
189 Use one or more subdirectories of the repository.
191 .. cfg-field:: post-checkout-command: command
193 Run command in the checked out repository, prior sdisting.
195 Global configuration options
196 ----------------------------
198 The following top-level configuration options are not specific to any
199 package, and thus apply globally:
202 .. cfg-field:: verbose: nat
203 --verbose=n, -vn
204 :synopsis: Build verbosity level.
206 :default: 1
208 Control the verbosity of ``cabal`` commands, valid values are from 0
209 to 3.
211 The command line variant of this field is ``--verbose=2``; a short
212 form ``-v2`` is also supported.
214 .. cfg-field:: jobs: nat or $ncpus
215 --jobs=n, -jn, --jobs=$ncpus
216 :synopsis: Number of builds running in parallel.
218 :default: 1
220 Run *nat* jobs simultaneously when building. If ``$ncpus`` is
221 specified, run the number of jobs equal to the number of CPUs.
222 Package building is often quite parallel, so turning on parallelism
223 can speed up build times quite a bit!
225 The command line variant of this field is ``--jobs=2``; a short form
226 ``-j2`` is also supported; a bare ``--jobs`` or ``-j`` is equivalent
227 to ``--jobs=$ncpus``.
229 .. cfg-field:: keep-going: boolean
230 --keep-going
231 :synopsis: Try to continue building on failure.
233 :default: False
235 If true, after a build failure, continue to build other unaffected
236 packages.
238 The command line variant of this field is ``--keep-going``.
240 .. option:: --builddir=DIR
242 Specifies the name of the directory where build products for
243 build will be stored; defaults to ``dist-newstyle``. If a
244 relative name is specified, this directory is resolved relative
245 to the root of the project (i.e., where the ``cabal.project``
246 file lives.)
248 This option cannot be specified via a ``cabal.project`` file.
250 .. _cmdoption-project-file:
251 .. option:: --project-file=FILE
253 Specifies the name of the project file used to specify the
254 rest of the top-level configuration; defaults to ``cabal.project``.
255 This name not only specifies the name of the main project file,
256 but also the auxiliary project files ``cabal.project.freeze``
257 and ``cabal.project.local``; for example, if you specify
258 ``--project-file=my.project``, then the other files that will
259 be probed are ``my.project.freeze`` and ``my.project.local``.
261 If the specified project file is a relative path, we will
262 look for the file relative to the current working directory,
263 and then for the parent directory, until the project file is
264 found or we have hit the top of the user's home directory.
266 This option cannot be specified via a ``cabal.project`` file.
268 .. option:: --store-dir=DIR
270 Specifies the name of the directory of the global package store.
272 Phase control
273 -------------
275 The following settings apply to commands that result in build actions
276 (``build``, ``run``, ``repl``, ``test``...), and control which phases of the
277 build are executed.
279 .. option:: --dry-run
281 Do not download, build, or install anything, only print what would happen.
283 .. option:: --only-configure
285 Instead of performing a full build just run the configure step.
286 Only accepted by the ``build`` command.
288 .. option:: --only-download
290 Do not build anything, only fetch the packages.
292 .. option:: --only-dependencies
294 Install only the dependencies necessary to build the given packages.
295 Not accepted by the ``repl`` command.
297 Solver configuration options
298 ----------------------------
300 The following settings control the behavior of the dependency solver:
302 .. cfg-field:: constraints: constraints list (comma separated)
303 --constraint="pkg >= 2.0"
304 :synopsis: Extra dependencies constraints.
306 Add extra constraints to the version bounds, flag settings,
307 and other properties a solver can pick for a
308 package. For example:
310 ::
312 constraints: bar == 2.1
314 A package can be specified multiple times in ``constraints``, in
315 which case the specified constraints are intersected. This is
316 useful, since the syntax does not allow you to specify multiple
317 constraints at once. For example, to specify both version bounds and
318 flag assignments, you would write:
320 ::
322 constraints: bar == 2.1,
323 bar +foo -baz
325 Valid constraints take the same form as for the `constraint
326 command line option
327 <installing-packages.html#cmdoption-setup-configure-constraint>`__.
329 .. cfg-field:: preferences: preference (comma separated)
330 --preference="pkg >= 2.0"
331 :synopsis: Preferred dependency versions.
333 Like :cfg-field:`constraints`, but the solver will attempt to satisfy
334 these preferences on a best-effort basis. The resulting install is locally
335 optimal with respect to preferences; specifically, no single package
336 could be replaced with a more preferred version that still satisfies
337 the hard constraints.
339 Operationally, preferences can cause the solver to attempt certain
340 version choices of a package before others, which can improve
341 dependency solver runtime.
343 One way to use :cfg-field:`preferences` is to take a known working set of
344 constraints (e.g., via ``cabal v2-freeze``) and record them as
345 preferences. In this case, the solver will first attempt to use this
346 configuration, and if this violates hard constraints, it will try to
347 find the minimal number of upgrades to satisfy the hard constraints
348 again.
350 The command line variant of this field is
351 ``--preference="pkg >= 2.0"``; to specify multiple preferences, pass
352 the flag multiple times.
354 .. cfg-field:: allow-newer: none, all or list of scoped package names (space or comma separated)
355 --allow-newer, --allow-newer=[none,all,[scope:][^]pkg]
356 :synopsis: Lift dependencies upper bound constraints.
358 :default: ``none``
360 Allow the solver to pick more recent version of some packages than
361 would normally be permitted by the :pkg-field:`build-depends` bounds
362 of packages in the install plan. This option may be useful if the
363 dependency solver cannot otherwise find a valid install plan.
365 For example, to relax ``pkg``\ s :pkg-field:`build-depends` upper bound on
366 ``dep-pkg``, write a scoped package name of the form:
368 ::
370 allow-newer: pkg:dep-pkg
372 If the scope shall be limited to specific releases of ``pkg``, the
373 extended form as in
375 ::
377 allow-newer: pkg-1.2.3:dep-pkg, pkg-1.1.2:dep-pkg
379 can be used to limit the relaxation of dependencies on
380 ``dep-pkg`` by the ``pkg-1.2.3`` and ``pkg-1.1.2`` releases only.
382 The scoped syntax is recommended, as it is often only a single package
383 whose upper bound is misbehaving. In this case, the upper bounds of
384 other packages should still be respected; indeed, relaxing the bound
385 can break some packages which test the selected version of packages.
387 The syntax also allows to prefix the dependee package with a
388 modifier symbol to modify the scope/semantic of the relaxation
389 transformation in a additional ways. Currently only one modifier
390 symbol is defined, i.e. ``^`` (i.e. caret) which causes the
391 relaxation to be applied only to ``^>=`` operators and leave all other
392 version operators untouched.
394 However, in some situations (e.g., when attempting to build packages
395 on a new version of GHC), it is useful to disregard *all*
396 upper-bounds, with respect to a package or all packages. This can be
397 done by specifying just a package name, or using the keyword ``all``
398 to specify all packages:
400 ::
402 -- Disregard upper bounds involving the dependencies on
403 -- packages bar, baz. For quux only, relax
404 -- 'quux ^>= ...'-style constraints only.
405 allow-newer: bar, baz, ^quux
407 -- Disregard all upper bounds when dependency solving
408 allow-newer: all
410 -- Disregard all `^>=`-style upper bounds when dependency solving
411 allow-newer: ^all
414 For consistency, there is also the explicit wildcard scope syntax
415 ``*`` (or its alphabetic synonym ``all``). Consequently, the
416 examples above are equivalent to the explicitly scoped variants:
418 ::
420 allow-newer: all:bar, *:baz, *:^quux
422 allow-newer: *:*
423 allow-newer: all:all
425 allow-newer: *:^*
426 allow-newer: all:^all
428 In order to ignore all bounds specified by a package ``pkg-1.2.3``
429 you can combine scoping with a right-hand-side wildcard like so
431 ::
433 -- Disregard any upper bounds specified by pkg-1.2.3
434 allow-newer: pkg-1.2.3:*
436 -- Disregard only `^>=`-style upper bounds in pkg-1.2.3
437 allow-newer: pkg-1.2.3:^*
440 :cfg-field:`allow-newer` is often used in conjunction with a constraint
441 (in the :cfg-field:`constraints` field) forcing the usage of a specific,
442 newer version of a package.
444 The command line variant of this field is e.g. ``--allow-newer=bar``. A
445 bare ``--allow-newer`` is equivalent to ``--allow-newer=all``.
447 .. cfg-field:: allow-older: none, all, list of scoped package names (space or comma separated)
448 --allow-older, --allow-older=[none,all,[scope:][^]pkg]
449 :synopsis: Lift dependency lower bound constraints.
450 :since: 2.0
452 :default: ``none``
454 Like :cfg-field:`allow-newer`, but applied to lower bounds rather than
455 upper bounds.
457 The command line variant of this field is ``--allow-older=all``. A
458 bare ``--allow-older`` is equivalent to ``--allow-older=all``.
461 .. cfg-field:: index-state: HEAD, unix-timestamp, ISO8601 UTC timestamp.
462 :synopsis: Use source package index state as it existed at a previous time.
463 :since: 2.0
465 :default: ``HEAD``
467 This allows to change the source package index state the solver uses
468 to compute install-plans. This is particularly useful in
469 combination with freeze-files in order to also freeze the state the
470 package index was in at the time the install-plan was frozen.
472 ::
474 -- UNIX timestamp format example
475 index-state: @1474739268
477 -- ISO8601 UTC timestamp format example
478 -- This format is used by 'cabal v2-configure'
479 -- for storing `--index-state` values.
480 index-state: 2016-09-24T17:47:48Z
482 -- Specify different index-states per package repository
483 -- Supported since 3.4
484 index-state:
485 , hackage.haskell.org 2020-05-06T22:33:27Z
486 , head.hackage 2020-04-29T04:11:05Z
488 .. cfg-field:: active-repositories: reponame1, reponame2
490 :synopsis: Specify active package repositories
491 :since: 3.4
493 :default: ``:rest``
495 This allows to specify the active package repositories,
496 when multiple are specified. This is useful as you
497 can specify the order and the way active repositories are merged.
499 ::
501 -- for packages in head.hackage
502 -- only versions in head.hackage are considered
503 active-repositories:
504 , hackage.haskell.org
505 , head.hackage:override
507 -- Force head.hackage to be the primary repository considered
508 active-repositories: :rest, head.hackage
510 -- "Offline" mode
511 active-repositories: none
514 .. cfg-field:: reject-unconstrained-dependencies: all, none
515 --reject-unconstrained-dependencies=[all|none]
516 :synopsis: Restrict the solver to packages that have constraints on them.
518 :default: none
519 :since: 2.6
521 By default, the dependency solver can include any package that it's
522 aware of in a build plan. If you wish to restrict the build plan to
523 a closed set of packages (e.g., from a freeze file), use this flag.
525 When set to `all`, all non-local packages that aren't goals must be
526 explicitly constrained. When set to `none`, the solver will
527 consider all packages.
530 Package configuration options
531 -----------------------------
533 Package options affect the building of specific packages. There are three
534 ways a package option can be specified:
536 - They can be specified at the top-level, in which case they apply only
537 to **local package**, or
539 - They can be specified inside a ``package`` stanza, in which case they
540 apply to the build of the package, whether or not it is local or
541 external.
543 - They can be specified inside an ``package *`` stanza, in which case they
544 apply to all packages, local ones from the project and also external
545 dependencies.
548 For example, the following options specify that :cfg-field:`optimization`
549 should be turned off for all local packages, and that ``bytestring`` (possibly
550 an external dependency) should be built with ``-fno-state-hack``::
552 optimization: False
554 package bytestring
555 ghc-options: -fno-state-hack
557 ``ghc-options`` is not specifically described in this documentation,
558 but is one of many fields for configuring programs. They take the form
559 ``progname-options`` and ``progname-location``, and
560 can only be set inside package stanzas. (TODO: They are not supported
561 at top-level, see :issue:`3579`.)
563 At the moment, there is no way to specify an option to apply to all
564 external packages or all inplace packages. Additionally, it is only
565 possible to specify these options on the command line for all local
566 packages (there is no per-package command line interface.)
568 Some flags were added by more recent versions of the Cabal library. This
569 means that they are NOT supported by packages which use Custom setup
570 scripts that require a version of the Cabal library older than when the
571 feature was added.
573 .. cfg-field:: flags: list of +flagname or -flagname (space separated)
574 --flags="+foo -bar", -ffoo, -f-bar
575 :synopsis: Enable or disable package flags.
577 Force all flags specified as ``+flagname`` to be true, and all flags
578 specified as ``-flagname`` to be false. For example, to enable the
579 flag ``foo`` and disable ``bar``, set:
581 ::
583 flags: +foo -bar
585 Exactly one of + or - is required before each flag.
587 Flags are *per-package*, so it doesn't make much sense to specify
588 flags at the top-level, unless you happen to know that *all* of your
589 local packages support the same named flags. If a flag is not
590 supported by a package, it is ignored.
592 See also the solver configuration field :cfg-field:`constraints`.
594 The command line variant of this flag is ``--flags``. There is also
595 a shortened form ``-ffoo -f-bar``.
597 A common mistake is to say ``cabal v2-build -fhans``, where
598 ``hans`` is a flag for a transitive dependency that is not in the
599 local package; in this case, the flag will be silently ignored. If
600 ``haskell-tor`` is the package you want this flag to apply to, try
601 ``--constraint="haskell-tor +hans"`` instead.
603 .. cfg-field:: with-compiler: executable
604 --with-compiler=executable
605 :synopsis: Path to compiler executable.
607 Specify the path to a particular compiler to be used. If not an
608 absolute path, it will be resolved according to the :envvar:`PATH`
609 environment. The type of the compiler (GHC, GHCJS, etc) must be
610 consistent with the setting of the :cfg-field:`compiler` field.
612 The most common use of this option is to specify a different version
613 of your compiler to be used; e.g., if you have ``ghc-7.8`` in your
614 path, you can specify ``with-compiler: ghc-7.8`` to use it.
616 This flag also sets the default value of :cfg-field:`with-hc-pkg`, using
617 the heuristic that it is named ``ghc-pkg-7.8`` (if your executable name
618 is suffixed with a version number), or is the executable named
619 ``ghc-pkg`` in the same directory as the ``ghc`` directory. If this
620 heuristic does not work, set :cfg-field:`with-hc-pkg` explicitly.
622 For inplace packages, ``cabal v2-build`` maintains a separate build
623 directory for each version of GHC, so you can maintain multiple
624 build trees for different versions of GHC without clobbering each
625 other.
627 It's not possible to set :cfg-field:`with-compiler` on a
628 per-package basis.
630 The command line variant of this flag is
631 ``--with-compiler=ghc-7.8``; there is also a short version
632 ``-w ghc-7.8``.
634 .. cfg-field:: with-hc-pkg: executable
635 --with-hc-pkg=executable
636 :synopsis: Specifies package tool.
638 Specify the path to the package tool, e.g., ``ghc-pkg``. This
639 package tool must be compatible with the compiler specified by
640 :cfg-field:`with-compiler` (generally speaking, it should be precisely
641 the tool that was distributed with the compiler). If this option is
642 omitted, the default value is determined from :cfg-field:`with-compiler`.
644 The command line variant of this flag is
645 ``--with-hc-pkg=ghc-pkg-7.8``.
647 .. cfg-field:: optimization: nat
648 --enable-optimization
649 --disable-optimization
650 :synopsis: Build with optimization.
652 :default: ``1``
654 Build with optimization. This is appropriate for production use,
655 taking more time to build faster libraries and programs.
657 The optional *nat* value is the optimisation level. Some compilers
658 support multiple optimisation levels. The range is 0 to 2. Level 0
659 disables optimization, level 1 is the default. Level 2 is higher
660 optimisation if the compiler supports it. Level 2 is likely to lead
661 to longer compile times and bigger generated code. If you are not
662 planning to run code, turning off optimization will lead to better
663 build times and less code to be rebuilt when a module changes.
665 When optimizations are enabled, Cabal passes ``-O2`` to the C compiler.
667 We also accept ``True`` (equivalent to 1) and ``False`` (equivalent
668 to 0).
670 Note that as of GHC 8.0, GHC does not recompile when optimization
671 levels change (see :ghc-ticket:`10923`), so if
672 you change the optimization level for a local package you may need
673 to blow away your old build products in order to rebuild with the
674 new optimization level.
676 The command line variant of this flag is ``-O2`` (with ``-O1``
677 equivalent to ``-O``). There are also long-form variants
678 ``--enable-optimization`` and ``--disable-optimization``.
680 .. cfg-field:: configure-options: args (space separated)
681 --configure-option=arg
682 :synopsis: Options to pass to configure script.
684 A list of extra arguments to pass to the external ``./configure``
685 script, if one is used. This is only useful for packages which have
686 the ``Configure`` build type. See also the section on
687 `system-dependent
688 parameters <developing-packages.html#system-dependent-parameters>`__.
690 The command line variant of this flag is ``--configure-option=arg``,
691 which can be specified multiple times to pass multiple options.
693 .. cfg-field:: compiler: ghc, ghcjs, jhc, lhc, uhc or haskell-suite
694 --compiler=compiler
695 :synopsis: Compiler to build with.
697 :default: ``ghc``
699 Specify the compiler toolchain to be used. This is independent of
700 ``with-compiler``, because the choice of toolchain affects Cabal's
701 build logic.
703 The command line variant of this flag is ``--compiler=ghc``.
705 It's not possible to set :cfg-field:`compiler` on a
706 per-package basis.
708 .. cfg-field:: tests: boolean
709 --enable-tests
710 --disable-tests
711 :synopsis: Build tests.
713 :default: ``False``
715 Force test suites to be enabled. For most users this should not be
716 needed, as we always attempt to solve for test suite dependencies,
717 even when this value is ``False``; furthermore, test suites are
718 automatically enabled if they are requested as a built target.
720 The command line variant of this flag is ``--enable-tests`` and
721 ``--disable-tests``.
723 .. cfg-field:: benchmarks: boolean
724 --enable-benchmarks
725 --disable-benchmarks
726 :synopsis: Build benchmarks.
728 :default: ``False``
730 Force benchmarks to be enabled. For most users this should not be
731 needed, as we always attempt to solve for benchmark dependencies,
732 even when this value is ``False``; furthermore, benchmarks are
733 automatically enabled if they are requested as a built target.
735 The command line variant of this flag is ``--enable-benchmarks`` and
736 ``--disable-benchmarks``.
738 .. cfg-field:: extra-prog-path: paths (newline or comma separated)
739 --extra-prog-path=PATH
740 :synopsis: Add directories to program search path.
741 :since: 1.18
743 A list of directories to search for extra required programs. Most
744 users should not need this, as programs like ``happy`` and ``alex``
745 will automatically be installed and added to the path. This can be
746 useful if a ``Custom`` setup script relies on an exotic extra
747 program.
749 The command line variant of this flag is ``--extra-prog-path=PATH``,
750 which can be specified multiple times.
752 .. cfg-field:: run-tests: boolean
753 --run-tests
754 :synopsis: Run package test suite upon installation.
756 :default: ``False``
758 Run the package test suite upon installation. This is useful for
759 saying "When this package is installed, check that the test suite
760 passes, terminating the rest of the build if it is broken."
762 .. warning::
764 One deficiency: the :cfg-field:`run-tests` setting of a package is NOT
765 recorded as part of the hash, so if you install something without
766 :cfg-field:`run-tests` and then turn on ``run-tests``, we won't
767 subsequently test the package. If this is causing you problems, give
768 us a shout.
770 The command line variant of this flag is ``--run-tests``.
772 Object code options
773 ^^^^^^^^^^^^^^^^^^^
775 .. cfg-field:: debug-info: integer
776 --enable-debug-info=<n>
777 --disable-debug-info
778 :synopsis: Build with debug info enabled.
779 :since: 1.22
781 :default: False
783 If the compiler (e.g., GHC 7.10 and later) supports outputing OS
784 native debug info (e.g., DWARF), setting ``debug-info: True`` will
785 instruct it to do so. See the GHC wiki page on :ghc-wiki:`DWARF`
786 for more information about this feature.
788 (This field also accepts numeric syntax, but until GHC 8.2 this didn't
789 do anything.)
791 The command line variant of this flag is ``--enable-debug-info`` and
792 ``--disable-debug-info``.
794 .. cfg-field:: split-sections: boolean
795 --enable-split-sections
796 --disable-split-sections
797 :synopsis: Use GHC's split sections feature.
798 :since: 2.2
800 :default: False
802 Use the GHC ``-split-sections`` feature when building the library. This
803 reduces the final size of the executables that use the library by
804 allowing them to link with only the bits that they use rather than
805 the entire library. The downside is that building the library takes
806 longer and uses a bit more memory.
808 This feature is supported by GHC 8.0 and later.
810 The command line variant of this flag is ``--enable-split-sections`` and
811 ``--disable-split-sections``.
813 .. cfg-field:: split-objs: boolean
814 --enable-split-objs
815 --disable-split-objs
816 :synopsis: Use GHC's split objects feature.
818 :default: False
820 Use the GHC ``-split-objs`` feature when building the library. This
821 reduces the final size of the executables that use the library by
822 allowing them to link with only the bits that they use rather than
823 the entire library. The downside is that building the library takes
824 longer and uses considerably more memory.
826 It is generally recommend that you use ``split-sections`` instead
827 of ``split-objs`` where possible.
829 The command line variant of this flag is ``--enable-split-objs`` and
830 ``--disable-split-objs``.
832 .. cfg-field:: executable-stripping: boolean
833 --enable-executable-stripping
834 --disable-executable-stripping
835 :synopsis: Strip installed programs.
837 :default: True
839 When installing binary executable programs, run the ``strip``
840 program on the binary. This can considerably reduce the size of the
841 executable binary file. It does this by removing debugging
842 information and symbols.
844 Not all Haskell implementations generate native binaries. For such
845 implementations this option has no effect.
847 If ``debug-info`` is set explicitly then ``executable-stripping`` is set
848 to ``False`` as otherwise all the debug symbols will be stripped.
850 The command line variant of this flag is
851 ``--enable-executable-stripping`` and
852 ``--disable-executable-stripping``.
854 .. cfg-field:: library-stripping: boolean
855 --enable-library-stripping
856 --disable-library-stripping
857 :synopsis: Strip installed libraries.
858 :since: 1.20
860 When installing binary libraries, run the ``strip`` program on the
861 binary, saving space on the file system. See also
862 ``executable-stripping``.
864 If ``debug-info`` is set explicitly then ``library-stripping`` is set
865 to ``False`` as otherwise all the debug symbols will be stripped.
867 The command line variant of this flag is
868 ``--enable-library-stripping`` and ``--disable-library-stripping``.
870 Executable options
871 ^^^^^^^^^^^^^^^^^^
873 .. cfg-field:: program-prefix: prefix
874 --program-prefix=prefix
875 :synopsis: Prepend prefix to program names.
877 [STRIKEOUT:Prepend *prefix* to installed program names.] (Currently
878 implemented in a silly and not useful way. If you need this to work
879 give us a shout.)
881 *prefix* may contain the following path variables: ``$pkgid``,
882 ``$pkg``, ``$version``, ``$compiler``, ``$os``, ``$arch``, ``$abi``,
883 ``$abitag``
885 The command line variant of this flag is ``--program-prefix=foo-``.
887 .. cfg-field:: program-suffix: suffix
888 --program-suffix=suffix
889 :synopsis: Append refix to program names.
891 [STRIKEOUT:Append *suffix* to installed program names.] (Currently
892 implemented in a silly and not useful way. If you need this to work
893 give us a shout.)
895 The most obvious use for this is to append the program's version
896 number to make it possible to install several versions of a program
897 at once: ``program-suffix: $version``.
899 *suffix* may contain the following path variables: ``$pkgid``,
900 ``$pkg``, ``$version``, ``$compiler``, ``$os``, ``$arch``, ``$abi``,
901 ``$abitag``
903 The command line variant of this flag is
904 ``--program-suffix='$version'``.
906 Dynamic linking options
907 ^^^^^^^^^^^^^^^^^^^^^^^
909 .. cfg-field:: shared: boolean
910 --enable-shared
911 --disable-shared
912 :synopsis: Build shared library.
914 :default: False
916 Build shared library. This implies a separate compiler run to
917 generate position independent code as required on most platforms.
919 The command line variant of this flag is ``--enable-shared`` and
920 ``--disable-shared``.
922 .. cfg-field:: executable-dynamic: boolean
923 --enable-executable-dynamic
924 --disable-executable-dynamic
925 :synopsis: Link executables dynamically.
927 :default: False
929 Link executables dynamically. The executable's library dependencies
930 should be built as shared objects. This implies ``shared: True``
931 unless ``shared: False`` is explicitly specified.
933 The command line variant of this flag is
934 ``--enable-executable-dynamic`` and
935 ``--disable-executable-dynamic``.
937 .. cfg-field:: library-for-ghci: boolean
938 --enable-library-for-ghci
939 --disable-library-for-ghci
940 :synopsis: Build libraries suitable for use with GHCi.
942 :default: True
944 Build libraries suitable for use with GHCi. This involves an extra
945 linking step after the build.
947 Not all platforms support GHCi and indeed on some platforms, trying
948 to build GHCi libs fails. In such cases, consider setting
949 ``library-for-ghci: False``.
951 The command line variant of this flag is
952 ``--enable-library-for-ghci`` and ``--disable-library-for-ghci``.
954 .. cfg-field:: relocatable:
955 --relocatable
956 :synopsis: Build relocatable package.
957 :since: 1.22
959 :default: False
961 [STRIKEOUT:Build a package which is relocatable.] (TODO: It is not
962 clear what this actually does, or if it works at all.)
964 The command line variant of this flag is ``--relocatable``.
966 Static linking options
967 ^^^^^^^^^^^^^^^^^^^^^^
969 .. cfg-field:: static: boolean
970 --enable-static
971 --disable-static
972 :synopsis: Build static library.
975 :default: False
977 Roll this and all dependent libraries into a combined ``.a`` archive.
978 This uses GHCs ``-staticlib`` flag, which is available for iOS and with
979 GHC 8.4 and later for other platforms as well.
981 .. cfg-field:: executable-static: boolean
982 --enable-executable-static
983 --disable-executable-static
984 :synopsis: Build fully static executables.
987 :default: False
989 Build fully static executables.
990 This links all dependent libraries into executables statically,
991 including libc.
992 This passes ``-static`` and ``-optl=-static`` to GHC.
994 Foreign function interface options
995 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
997 .. cfg-field:: extra-include-dirs: directories (comma or newline separated list)
998 --extra-include-dirs=DIR
999 :synopsis: Adds C header search path.
1001 An extra directory to search for C header files. You can use this
1002 flag multiple times to get a list of directories.
1004 You might need to use this flag if you have standard system header
1005 files in a non-standard location that is not mentioned in the
1006 package's ``.cabal`` file. Using this option has the same affect as
1007 appending the directory *dir* to the :pkg-field:`include-dirs` field in each
1008 library and executable in the package's ``.cabal`` file. The
1009 advantage of course is that you do not have to modify the package at
1010 all. These extra directories will be used while building the package
1011 and for libraries it is also saved in the package registration
1012 information and used when compiling modules that use the library.
1014 The command line variant of this flag is
1015 ``--extra-include-dirs=DIR``, which can be specified multiple times.
1017 .. cfg-field:: extra-lib-dirs: directories (comma or newline separated list)
1018 --extra-lib-dirs=DIR
1019 :synopsis: Adds library search directory.
1021 An extra directory to search for system libraries files.
1023 The command line variant of this flag is ``--extra-lib-dirs=DIR``,
1024 which can be specified multiple times.
1026 .. cfg-field:: extra-framework-dirs: directories (comma or newline separated list)
1027 --extra-framework-dirs=DIR
1028 :synopsis: Adds framework search directory (OS X only).
1030 An extra directory to search for frameworks (OS X only).
1032 You might need to use this flag if you have standard system
1033 libraries in a non-standard location that is not mentioned in the
1034 package's ``.cabal`` file. Using this option has the same affect as
1035 appending the directory *dir* to the :cfg-field:`extra-lib-dirs` field in
1036 each library and executable in the package's ``.cabal`` file. The
1037 advantage of course is that you do not have to modify the package at
1038 all. These extra directories will be used while building the package
1039 and for libraries it is also saved in the package registration
1040 information and used when compiling modules that use the library.
1042 The command line variant of this flag is
1043 ``--extra-framework-dirs=DIR``, which can be specified multiple
1044 times.
1046 Profiling options
1047 ^^^^^^^^^^^^^^^^^
1049 .. cfg-field:: profiling: boolean
1050 --enable-profiling
1051 --disable-profiling
1052 :synopsis: Enable profiling builds.
1053 :since: 1.22
1055 :default: False
1057 Build libraries and executables with profiling enabled (for
1058 compilers that support profiling as a separate mode). It is only
1059 necessary to specify :cfg-field:`profiling` for the specific package you
1060 want to profile; ``cabal v2-build`` will ensure that all of its
1061 transitive dependencies are built with profiling enabled.
1063 To enable profiling for only libraries or executables, see
1064 :cfg-field:`library-profiling` and :cfg-field:`executable-profiling`.
1066 For useful profiling, it can be important to control precisely what
1067 cost centers are allocated; see :cfg-field:`profiling-detail`.
1069 The command line variant of this flag is ``--enable-profiling`` and
1070 ``--disable-profiling``.
1072 .. cfg-field:: profiling-detail: level
1073 --profiling-detail=level
1074 :synopsis: Profiling detail level.
1075 :since: 1.24
1077 Some compilers that support profiling, notably GHC, can allocate
1078 costs to different parts of the program and there are different
1079 levels of granularity or detail with which this can be done. In
1080 particular for GHC this concept is called "cost centers", and GHC
1081 can automatically add cost centers, and can do so in different ways.
1083 This flag covers both libraries and executables, but can be
1084 overridden by the ``library-profiling-detail`` field.
1086 Currently this setting is ignored for compilers other than GHC. The
1087 levels that cabal currently supports are:
1089 default
1090 For GHC this uses ``exported-functions`` for libraries and
1091 ``toplevel-functions`` for executables.
1092 none
1093 No costs will be assigned to any code within this component.
1094 exported-functions
1095 Costs will be assigned at the granularity of all top level
1096 functions exported from each module. In GHC, this
1097 is for non-inline functions. Corresponds to ``-fprof-auto-exported``.
1098 toplevel-functions
1099 Costs will be assigned at the granularity of all top level
1100 functions in each module, whether they are exported from the
1101 module or not. In GHC specifically, this is for non-inline
1102 functions. Corresponds to ``-fprof-auto-top``.
1103 all-functions
1104 Costs will be assigned at the granularity of all functions in
1105 each module, whether top level or local. In GHC specifically,
1106 this is for non-inline toplevel or where-bound functions or
1107 values. Corresponds to ``-fprof-auto``.
1109 The command line variant of this flag is
1110 ``--profiling-detail=none``.
1112 .. cfg-field:: library-profiling-detail: level
1113 --library-profiling-detail=level
1114 :synopsis: Libraries profiling detail level.
1115 :since: 1.24
1117 Like :cfg-field:`profiling-detail`, but applied only to libraries
1119 The command line variant of this flag is
1120 ``--library-profiling-detail=none``.
1122 .. cfg-field:: library-vanilla: boolean
1123 --enable-library-vanilla
1124 --disable-library-vanilla
1125 :synopsis: Build libraries without profiling.
1127 :default: True
1129 Build ordinary libraries (as opposed to profiling libraries).
1130 Mostly, you can set this to False to avoid building ordinary
1131 libraries when you are profiling.
1133 The command line variant of this flag is
1134 ``--enable-library-vanilla`` and ``--disable-library-vanilla``.
1136 .. cfg-field:: library-profiling: boolean
1137 --enable-library-profiling
1138 --disable-library-profiling
1139 :synopsis: Build libraries with profiling enabled.
1140 :since: 1.22
1142 :default: False
1144 Build libraries with profiling enabled. You probably want
1145 to use :cfg-field:`profiling` instead.
1147 The command line variant of this flag is
1148 ``--enable-library-profiling`` and ``--disable-library-profiling``.
1150 .. cfg-field:: executable-profiling: boolean
1151 --enable-executable-profiling
1152 --disable-executable-profiling
1153 :synopsis: Build executables with profiling enabled.
1154 :since: 1.22
1156 :default: False
1158 Build executables with profiling enabled. You probably want
1159 to use :cfg-field:`profiling` instead.
1161 The command line variant of this flag is
1162 ``--enable-executable-profiling`` and
1163 ``--disable-executable-profiling``.
1165 Coverage options
1166 ^^^^^^^^^^^^^^^^
1168 .. cfg-field:: coverage: boolean
1169 --enable-coverage
1170 --disable-coverage
1171 :synopsis: Build with coverage enabled.
1172 :since: 1.22
1174 :default: False
1176 Build libraries and executables (including test suites) with Haskell
1177 Program Coverage enabled. Running the test suites will automatically
1178 generate coverage reports with HPC.
1180 The command line variant of this flag is ``--enable-coverage`` and
1181 ``--disable-coverage``.
1183 .. cfg-field:: library-coverage: boolean
1184 --enable-library-coverage
1185 --disable-library-coverage
1186 :since: 1.22
1187 :deprecated:
1189 :default: False
1191 Deprecated, use :cfg-field:`coverage`.
1193 The command line variant of this flag is
1194 ``--enable-library-coverage`` and ``--disable-library-coverage``.
1196 Haddock options
1197 ^^^^^^^^^^^^^^^
1199 .. cfg-field:: documentation: boolean
1200 --enable-documentation
1201 --disable-documentation
1202 :synopsis: Enable building of documentation.
1204 :default: False
1206 Enables building of Haddock documentation
1208 The command line variant of this flag is ``--enable-documentation``
1209 and ``--disable-documentation``.
1211 `documentation: true` does not imply :cfg-field:`haddock-benchmarks`,
1212 :cfg-field:`haddock-executables`, :cfg-field:`haddock-internal` or
1213 :cfg-field:`haddock-tests`. These need to be enabled separately if
1214 desired.
1216 .. cfg-field:: doc-index-file: templated path
1217 --doc-index-file=TEMPLATE
1218 :synopsis: Path to haddock templates.
1220 A central index of Haddock API documentation (template cannot use
1221 ``$pkgid``), which should be updated as documentation is built.
1223 The command line variant of this flag is
1224 ``--doc-index-file=TEMPLATE``
1226 The following commands are equivalent to ones that would be passed when
1227 running ``setup haddock``. (TODO: Where does the documentation get put.)
1229 .. cfg-field:: haddock-hoogle: boolean
1230 :synopsis: Generate Hoogle file.
1232 :default: False
1234 Generate a text file which can be converted by Hoogle_
1235 into a database for searching. This is equivalent to running ``haddock``
1236 with the ``--hoogle`` flag.
1238 The command line variant of this flag is ``--hoogle`` (for the
1239 ``haddock`` command).
1241 .. cfg-field:: haddock-html: boolean
1242 :synopsis: Build HTML documentation.
1244 :default: True
1246 Build HTML documentation.
1248 The command line variant of this flag is ``--html`` (for the
1249 ``haddock`` command).
1251 .. cfg-field:: haddock-html-location: templated path
1252 --html-location=TEMPLATE
1253 :synopsis: Haddock HTML templates location.
1255 Specify a template for the location of HTML documentation for
1256 prerequisite packages. The substitutions are applied to the template
1257 to obtain a location for each package, which will be used by
1258 hyperlinks in the generated documentation. For example, the
1259 following command generates links pointing at [Hackage] pages:
1261 ::
1263 html-location: http://hackage.haskell.org/packages/archive/$pkg/latest/doc/html
1265 The command line variant of this flag is ``--html-location`` (for
1266 the ``haddock`` subcommand).
1268 ::
1270 --html-location='http://hackage.haskell.org/packages/archive/$pkg/latest/doc/html'
1272 Here the argument is quoted to prevent substitution by the shell. If
1273 this option is omitted, the location for each package is obtained
1274 using the package tool (e.g. ``ghc-pkg``).
1276 .. cfg-field:: haddock-executables: boolean
1277 :synopsis: Generate documentation for executables.
1279 :default: False
1281 Run haddock on all executable programs.
1283 The command line variant of this flag is ``--executables`` (for the
1284 ``haddock`` subcommand).
1286 .. cfg-field:: haddock-tests: boolean
1287 :synopsis: Generate documentation for tests.
1289 :default: False
1291 Run haddock on all test suites.
1293 The command line variant of this flag is ``--tests`` (for the
1294 ``haddock`` subcommand).
1296 .. cfg-field:: haddock-benchmarks: boolean
1297 :synopsis: Generate documentation for benchmarks.
1299 :default: False
1301 Run haddock on all benchmarks.
1303 The command line variant of this flag is ``--benchmarks`` (for the
1304 ``haddock`` subcommand).
1306 .. cfg-field:: haddock-all: boolean
1307 :synopsis: Generate documentation for everything
1309 :default: False
1311 Run haddock on all components.
1313 The command line variant of this flag is ``--all`` (for the
1314 ``haddock`` subcommand).
1316 .. cfg-field:: haddock-internal: boolean
1317 :synopsis: Generate documentation for internal modules
1319 :default: False
1321 Build haddock documentation which includes unexposed modules and
1322 symbols.
1324 The command line variant of this flag is ``--internal`` (for the
1325 ``haddock`` subcommand).
1327 .. cfg-field:: haddock-css: path
1328 :synopsis: Location of Haddoc CSS file.
1330 The CSS file that should be used to style the generated
1331 documentation (overriding haddock's default.)
1333 The command line variant of this flag is ``--css`` (for the
1334 ``haddock`` subcommand).
1336 .. cfg-field:: haddock-hyperlink-source: boolean
1337 :synopsis: Generate hyperlinked source code for documentation
1339 :default: False
1341 Generated hyperlinked source code using `HsColour`_, and have
1342 Haddock documentation link to it.
1344 The command line variant of this flag is ``--hyperlink-source`` (for
1345 the ``haddock`` subcommand).
1347 .. cfg-field:: haddock-hscolour-css: path
1348 :synopsis: Location of CSS file for HsColour
1350 The CSS file that should be used to style the generated hyperlinked
1351 source code (from `HsColour`_).
1353 The command line variant of this flag is ``--hscolour-css`` (for the
1354 ``haddock`` subcommand).
1356 .. cfg-field:: haddock-contents-location: URL
1357 :synopsis: URL for contents page.
1359 A baked-in URL to be used as the location for the contents page.
1361 The command line variant of this flag is ``--contents-location``
1362 (for the ``haddock`` subcommand).
1364 .. cfg-field:: haddock-keep-temp-files: boolean
1365 :synopsis: Keep temporary Haddock files.
1367 Keep temporary files.
1369 The command line variant of this flag is ``--keep-temp-files`` (for
1370 the ``haddock`` subcommand).
1372 Advanced global configuration options
1373 -------------------------------------
1375 .. cfg-field:: write-ghc-environment-files: always, never, or ghc8.4.4+
1376 --write-ghc-environment-files=policy
1377 :synopsis: Whether a ``.ghc.environment`` should be created after a successful build.
1379 :default: ``never``
1381 Whether a `GHC package environment file <https://downloads.haskell.org/~ghc/master/users-guide/packages.html#package-environments>`_
1382 should be created after a successful build.
1384 Since Cabal 3.0, defaults to ``never``. Before that, defaulted to
1385 creating them only when compiling with GHC 8.4.4 and older (GHC
1386 8.4.4 `is the first version
1387 <https://gitlab.haskell.org/ghc/ghc/-/issues/13753>`_ that supports
1388 the ``-package-env -`` option that allows ignoring the package
1389 environment files).
1392 .. cfg-field:: http-transport: curl, wget, powershell, or plain-http
1393 --http-transport=transport
1394 :synopsis: Transport to use with http(s) requests.
1396 :default: ``curl``
1398 Set a transport to be used when making http(s) requests.
1400 The command line variant of this field is ``--http-transport=curl``.
1402 .. cfg-field:: ignore-expiry: boolean
1403 --ignore-expiry
1404 :synopsis: Ignore Hackage expiration dates.
1406 :default: False
1408 If ``True``, we will ignore expiry dates on metadata from Hackage.
1410 In general, you should not set this to ``True`` as it will leave you
1411 vulnerable to stale cache attacks. However, it may be temporarily
1412 useful if the main Hackage server is down, and we need to rely on
1413 mirrors which have not been updated for longer than the expiry
1414 period on the timestamp.
1416 The command line variant of this field is ``--ignore-expiry``.
1418 .. cfg-field:: remote-repo-cache: directory
1419 --remote-repo-cache=DIR
1420 :synopsis: Location of packages cache.
1422 :default: ``~/.cabal/packages``
1424 [STRIKEOUT:The location where packages downloaded from remote
1425 repositories will be cached.] Not implemented yet.
1427 The command line variant of this flag is
1428 ``--remote-repo-cache=DIR``.
1430 .. cfg-field:: logs-dir: directory
1431 --logs-dir=DIR
1432 :synopsis: Directory to store build logs.
1434 :default: ``~/.cabal/logs``
1436 [STRIKEOUT:The location where build logs for packages are stored.]
1437 Not implemented yet.
1439 The command line variant of this flag is ``--logs-dir=DIR``.
1441 .. cfg-field:: build-summary: template filepath
1442 --build-summary=TEMPLATE
1443 :synopsis: Build summaries location.
1445 :default: ``~/.cabal/logs/build.log``
1447 [STRIKEOUT:The file to save build summaries. Valid variables which
1448 can be used in the path are ``$pkgid``, ``$compiler``, ``$os`` and
1449 ``$arch``.] Not implemented yet.
1451 The command line variant of this flag is
1452 ``--build-summary=TEMPLATE``.
1454 .. cfg-field:: world-file: path
1455 --world-file=FILE
1456 :deprecated:
1458 [STRIKEOUT:The location of the world file.] Deprecated.
1460 The command line variant of this flag is ``--world-file=FILE``.
1462 Undocumented fields: ``root-cmd``, ``symlink-bindir``, ``build-log``,
1463 ``remote-build-reporting``, ``report-planned-failure``, ``one-shot``,
1464 ``offline``.
1466 Advanced solver options
1467 ^^^^^^^^^^^^^^^^^^^^^^^
1469 Most users generally won't need these.
1471 .. cfg-field:: solver: modular
1472 --solver=modular
1473 :synopsis: Which solver to use.
1475 This field is reserved to allow the specification of alternative
1476 dependency solvers. At the moment, the only accepted option is
1477 ``modular``.
1479 The command line variant of this field is ``--solver=modular``.
1481 .. cfg-field:: max-backjumps: nat
1482 --max-backjumps=N
1483 :synopsis: Maximum number of solver backjumps.
1485 :default: 4000
1487 Maximum number of backjumps (backtracking multiple steps) allowed
1488 while solving. Set -1 to allow unlimited backtracking, and 0 to
1489 disable backtracking completely.
1491 The command line variant of this field is ``--max-backjumps=4000``.
1493 .. cfg-field:: reorder-goals: boolean
1494 --reorder-goals
1495 --no-reorder-goals
1496 :synopsis: Allow solver to reorder goals.
1498 :default: False
1500 When enabled, the solver will reorder goals according to certain
1501 heuristics. Slows things down on average, but may make backtracking
1502 faster for some packages. It's unlikely to help for small projects,
1503 but for big install plans it may help you find a plan when otherwise
1504 this is not possible. See :issue:`1780` for more commentary.
1506 The command line variant of this field is ``--(no-)reorder-goals``.
1508 .. cfg-field:: count-conflicts: boolean
1509 --count-conflicts
1510 --no-count-conflicts
1511 :synopsis: Solver prefers versions with less conflicts.
1513 :default: True
1515 Try to speed up solving by preferring goals that are involved in a
1516 lot of conflicts.
1518 The command line variant of this field is
1519 ``--(no-)count-conflicts``.
1521 .. cfg-field:: fine-grained-conflicts: boolean
1522 --fine-grained-conflicts
1523 --no-fine-grained-conflicts
1524 :synopsis: Skip a version of a package if it does not resolve any conflicts
1525 encountered in the last version (solver optimization).
1527 :default: True
1529 When enabled, the solver will skip a version of a package if it does not
1530 resolve any of the conflicts encountered in the last version of that
1531 package. For example, if ``foo-1.2`` depended on ``bar``, and the solver
1532 couldn't find consistent versions for ``bar``'s dependencies, then the
1533 solver would skip ``foo-1.1`` if it also depended on ``bar``.
1535 The command line variant of this field is
1536 ``--(no-)fine-grained-conflicts``.
1538 .. cfg-field:: minimize-conflict-set: boolean
1539 --minimize-conflict-set
1540 --no-minimize-conflict-set
1541 :synopsis: Try to improve the solver error message when there is no
1542 solution.
1544 :default: False
1546 When there is no solution, try to improve the solver error message
1547 by finding a minimal conflict set. This option may increase run
1548 time significantly, so it is off by default.
1550 The command line variant of this field is
1551 ``--(no-)minimize-conflict-set``.
1553 .. cfg-field:: strong-flags: boolean
1554 --strong-flags
1555 --no-strong-flags
1556 :synopsis: Do not defer flag choices when solving.
1558 :default: False
1560 Do not defer flag choices. (TODO: Better documentation.)
1562 The command line variant of this field is ``--(no-)strong-flags``.
1564 .. cfg-field:: allow-boot-library-installs: boolean
1565 --allow-boot-library-installs
1566 --no-allow-boot-library-installs
1567 :synopsis: Allow cabal to install or upgrade any package.
1569 :default: False
1571 By default, the dependency solver doesn't allow ``base``,
1572 ``ghc-prim``, ``integer-simple``, ``integer-gmp``, and
1573 ``template-haskell`` to be installed or upgraded. This flag
1574 removes the restriction.
1576 The command line variant of this field is
1577 ``--(no-)allow-boot-library-installs``.
1579 .. cfg-field:: cabal-lib-version: version
1580 --cabal-lib-version=version
1581 :synopsis: Version of Cabal library used to build package.
1583 This field selects the version of the Cabal library which should be
1584 used to build packages. This option is intended primarily for
1585 internal development use (e.g., forcing a package to build with a
1586 newer version of Cabal, to test a new version of Cabal.) (TODO:
1587 Specify its semantics more clearly.)
1589 The command line variant of this field is
1590 ``--cabal-lib-version=1.24.0.1``.
1592 .. include:: references.inc