| blob | b9c925913b237b862567121315cef1a5255c7074 |
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 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 freeze``)
33 4. ``cabal.project.local`` (the output of ``cabal configure``)
35 Any call to ``cabal build`` will consider ``cabal.project*`` files from parent
36 directories when there is none in the current directory.
38 .. _conditionals and imports:
40 Conditionals and imports
41 ------------------------
43 As of ``cabal-install`` version 3.8, cabal supports conditional logic
44 and imports in ``cabal.project`` files. :ref:`conditions` in cabal
45 may case on operating system, architecture, and
46 compiler (i.e. there is no support for a notion of custom flags in
47 project files). Imports may specify local filepaths or remote urls,
48 and may reference either cabal.project files or v1-style cabal.config
49 freeze files. As a usage example:
51 ::
53 if(os(darwin))
54 optimization: False
55 elif(os(freebsd))
56 packages: freebsd/*.cabal
57 else
58 optimization: True
60 import: https://some.remote.source/subdir/cabal.config
62 import: relativepath/extra-project.project
64 import: /absolutepath/some-project.project
66 Specifying the local packages
67 -----------------------------
69 The following top-level options specify what the local packages of a
70 project are:
72 .. cfg-field:: packages: package location list (space or comma separated)
73 :synopsis: Project packages.
75 :default: ``./*.cabal``
77 .. warning::
79 The default value ``./*.cabal`` only takes effect if there is no explicit
80 ``cabal.project`` file.
81 If you use such explicit file you *must* fill the field.
83 Specifies the list of package locations which contain the local
84 packages to be built by this project. Package locations can take the
85 following forms:
87 1. They can specify a Cabal file, or a directory containing a Cabal
88 file, e.g., ``packages: Cabal cabal-install/cabal-install.cabal``.
90 2. They can specify glob-style wildcards, which must match one or
91 more (a) directories containing a (single) Cabal file, (b) Cabal
92 files (extension ``.cabal``), or (c) tarballs which contain Cabal
93 packages (extension ``.tar.gz``).
94 For example, to match all Cabal files in all
95 subdirectories, as well as the Cabal projects in the parent
96 directories ``foo`` and ``bar``, use
97 ``packages: */*.cabal ../{foo,bar}/``
99 3. They can specify an ``http``, ``https`` or ``file``
100 URL, representing the path to a remote tarball to be downloaded
101 and built.
103 There is no command line variant of this field; see :issue:`3585`.
104 Note that the default value is only included if there is no
105 ``cabal.project`` file. The field is appendable which means there would be
106 no way to drop the default value if it was included.
108 .. cfg-field:: optional-packages: package location list (space or comma-separated)
109 :synopsis: Optional project packages.
111 :default: empty
113 Like :cfg-field:`packages`, specifies a list of package locations
114 containing local packages to be built. Unlike :cfg-field:`packages`,
115 if we glob for a package, it is permissible for the glob to match against
116 zero packages. The intended use-case for :cfg-field:`optional-packages`
117 is to make it so that vendored packages can be automatically picked up if
118 they are placed in a subdirectory, but not error if there aren't any.
120 There is no command line variant of this field.
122 .. cfg-field:: extra-packages: package list with version bounds (comma separated)
123 :synopsis: Adds external packages as local
125 :strike:`Specifies a list of external packages from Hackage which
126 should be considered local packages.` (Not implemented)
128 There is no command line variant of this field.
132 All local packages are *vendored*, in the sense that if other packages
133 (including external ones from Hackage) depend on a package with the name
134 of a local package, the local package is preferentially used.
135 For subdirectories to be considered local packages, the following setting
136 can be used::
138 packages: ./*.cabal
139 optional-packages: ./*/*.cabal
141 ...then any package can be vendored simply by making a checkout in the
142 top-level project directory, as might be seen in this hypothetical
143 directory layout::
145 foo.cabal
146 foo-helper/ # local package
147 unix/ # vendored external package
149 All of these options support globs. ``cabal build`` has its own glob
150 format:
152 - Anywhere in a path, as many times as you like, you can specify an
153 asterisk ``*`` wildcard. E.g., ``*/*.cabal`` matches all ``.cabal``
154 files in all immediate subdirectories. Like in glob(7), asterisks do
155 not match hidden files unless there is an explicit period, e.g.,
156 ``.*/foo.cabal`` will match ``.private/foo.cabal`` (but
157 ``*/foo.cabal`` will not).
159 - You can use braces to specify specific directories; e.g.,
160 ``{vendor,pkgs}/*.cabal`` matches all Cabal files in the ``vendor``
161 and ``pkgs`` subdirectories.
163 Formally, the format is described by the following BNF:
165 .. todo::
166 convert globbing grammar to proper ABNF_ syntax
168 .. code-block:: abnf
170 FilePathGlob ::= FilePathRoot FilePathGlobRel
171 FilePathRoot ::= {- empty -} # relative to cabal.project
172 | "/" # Unix root
173 | [a-zA-Z] ":" [/\\] # Windows root
174 | "~" # home directory
175 FilePathGlobRel ::= Glob "/" FilePathGlobRel # Unix directory
176 | Glob "\\" FilePathGlobRel # Windows directory
177 | Glob # file
178 | {- empty -} # trailing slash
179 Glob ::= GlobPiece *
180 GlobPiece ::= "*" # wildcard
181 | [^*{},/\\] * # literal string
182 | "\\" [*{},] # escaped reserved character
183 | "{" Glob "," ... "," Glob "}" # union (match any of these)
186 Specifying Packages from Remote Version Control Locations
187 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
189 Starting with Cabal 2.4, there is now a stanza
190 ``source-repository-package`` for specifying packages from an external
191 version control.
193 .. code-block:: cabal
195 packages: .
197 source-repository-package
198 type: git
199 location: https://github.com/hvr/HsYAML.git
200 tag: e70cf0c171c9a586b62b3f75d72f1591e4e6aaa1
202 source-repository-package
203 type: git
204 location: https://github.com/well-typed/cborg
205 tag: 3d274c14ca3077c3a081ba7ad57c5182da65c8c1
206 subdir: cborg
208 source-repository-package
209 type: git
210 location: https://github.com/haskell/network.git
211 tag: e76fdc753e660dfa615af6c8b6a2ad9ddf6afe70
212 post-checkout-command: autoreconf -i
214 cabal-install 3.4 sdists the ``source-repository-package`` repositories and uses resulting tarballs as project packages.
215 This allows sharing of packages across different projects.
217 .. cfg-field:: type: VCS kind
219 .. cfg-field:: location: VCS location (usually URL)
221 .. cfg-field:: tag: VCS tag
223 .. cfg-field:: subdir: subdirectory list
225 Use one or more subdirectories of the repository.
227 .. cfg-field:: post-checkout-command: command
229 Run command in the checked out repository, prior sdisting.
231 Global configuration options
232 ----------------------------
234 The following top-level configuration options are not specific to any
235 package, and thus apply globally:
238 .. cfg-field:: verbose: nat
239 --verbose=n, -vn
240 :synopsis: Build verbosity level.
242 :default: 1
244 Control the verbosity of ``cabal`` commands, valid values are from 0
245 to 3.
247 The command line variant of this field is ``--verbose=2``; a short
248 form ``-v2`` is also supported.
250 .. cfg-field:: jobs: nat or $ncpus
251 --jobs=n, -jn, --jobs=$ncpus
252 :synopsis: Number of builds running in parallel.
254 :default: 1
256 Run *nat* jobs simultaneously when building. If ``$ncpus`` is
257 specified, run the number of jobs equal to the number of CPUs.
258 Package building is often quite parallel, so turning on parallelism
259 can speed up build times quite a bit!
261 The command line variant of this field is ``--jobs=2``; a short form
262 ``-j2`` is also supported; a bare ``--jobs`` or ``-j`` is equivalent
263 to ``--jobs=$ncpus``.
265 .. cfg-field:: keep-going: boolean
266 --keep-going
267 :synopsis: Try to continue building on failure.
269 :default: False
271 If true, after a build failure, continue to build other unaffected
272 packages.
274 The command line variant of this field is ``--keep-going``.
276 .. option:: --builddir=DIR
278 Specifies the name of the directory where build products for
279 build will be stored; defaults to ``dist-newstyle``. If a
280 relative name is specified, this directory is resolved relative
281 to the root of the project (i.e., where the ``cabal.project``
282 file lives.)
284 This option cannot be specified via a ``cabal.project`` file.
286 .. _cmdoption-project-file:
287 .. option:: --project-file=FILE
289 Specifies the name of the project file used to specify the
290 rest of the top-level configuration; defaults to ``cabal.project``.
291 This name not only specifies the name of the main project file,
292 but also the auxiliary project files ``cabal.project.freeze``
293 and ``cabal.project.local``; for example, if you specify
294 ``--project-file=my.project``, then the other files that will
295 be probed are ``my.project.freeze`` and ``my.project.local``.
297 If the specified project file is a relative path, we will
298 look for the file relative to the current working directory,
299 and then for the parent directory, until the project file is
300 found or we have hit the top of the user's home directory.
302 This option cannot be specified via a ``cabal.project`` file.
304 .. option:: --ignore-project
306 Ignores the local ``cabal.project`` file and uses the default
307 configuration with the local ``foo.cabal`` file. Note that
308 if this flag is set while the ``--project-file`` flag is also
309 set then this flag will be ignored.
311 .. option:: --store-dir=DIR
313 Specifies the name of the directory of the global package store.
315 .. cfg-field:: package-dbs: package DB stack (comma separated)
316 --package-db=[clear, global, user, PATH]
317 :synopsis: PackageDB stack manipulation
318 :since: 3.7
320 There are three package databases involved with most builds:
322 global
323 Compiler installation of rts, base, etc.
324 store
325 Nix-style local build cache
326 in-place
327 Project-specific build directory
329 By default, the package stack you will have with v2 commands is:
331 ::
333 -- [global, store]
335 So all remote packages required by your project will be
336 registered in the store package db (because it is last).
338 When cabal starts building your local projects, it appends the in-place db
339 to the end:
341 ::
343 -- [global, store, in-place]
345 So your local packages get put in ``dist-newstyle`` instead of the store.
347 This flag manipulates the default prefix: ``[global, store]`` and accepts
348 paths, the special value ``global`` referring to the global package db, and
349 ``clear`` which removes all prior entries. For example,
351 ::
353 -- [global, store, foo]
354 package-dbs: foo
356 -- [foo]
357 package-dbs: clear, foo
359 -- [bar, baz]
360 package-dbs: clear, foo, clear, bar, baz
362 The command line variant of this flag is ``--package-db=DB`` which can be
363 specified multiple times.
365 Phase control
366 -------------
368 The following settings apply to commands that result in build actions
369 (``build``, ``run``, ``repl``, ``test``...), and control which phases of the
370 build are executed.
372 .. option:: --dry-run
374 Do not download, build, or install anything, only print what would happen.
376 .. option:: --only-configure
378 Instead of performing a full build just run the configure step.
379 Only accepted by the ``build`` command.
381 .. option:: --only-download
383 Do not build anything, only fetch the packages.
385 .. option:: --only-dependencies
387 Install only the dependencies necessary to build the given packages.
388 Not accepted by the ``repl`` command.
390 Solver configuration options
391 ----------------------------
393 The following settings control the behavior of the dependency solver:
395 .. cfg-field:: constraints: constraints list (comma separated)
396 --constraint="pkg >= 2.0", -c "pkg >= 2.0"
397 :synopsis: Extra dependencies constraints.
399 Add extra constraints to the version bounds, flag settings,
400 and other properties a solver can pick for a
401 package. For example:
403 ::
405 constraints: bar == 2.1
407 A package can be specified multiple times in ``constraints``, in
408 which case the specified constraints are intersected. This is
409 useful, since the syntax does not allow you to specify multiple
410 constraints at once. For example, to specify both version bounds and
411 flag assignments, you would write:
413 ::
415 constraints: bar == 2.1,
416 bar +foo -baz
418 Valid constraints take the same form as for the
419 :option:`runhaskell Setup.hs configure --constraint`
420 command line option.
422 .. cfg-field:: preferences: preference (comma separated)
423 --preference="pkg >= 2.0"
424 :synopsis: Preferred dependency versions.
426 Like :cfg-field:`constraints`, but the solver will attempt to satisfy
427 these preferences on a best-effort basis. The resulting install is locally
428 optimal with respect to preferences; specifically, no single package
429 could be replaced with a more preferred version that still satisfies
430 the hard constraints.
432 Operationally, preferences can cause the solver to attempt certain
433 version choices of a package before others, which can improve
434 dependency solver runtime.
436 One way to use :cfg-field:`preferences` is to take a known working set of
437 constraints (e.g., via ``cabal freeze``) and record them as
438 preferences. In this case, the solver will first attempt to use this
439 configuration, and if this violates hard constraints, it will try to
440 find the minimal number of upgrades to satisfy the hard constraints
441 again.
443 The command line variant of this field is
444 ``--preference="pkg >= 2.0"``; to specify multiple preferences, pass
445 the flag multiple times.
447 .. cfg-field:: allow-newer: none, all or list of scoped package names (space or comma separated)
448 --allow-newer, --allow-newer=[none,all,[scope:][^]pkg]
449 :synopsis: Lift dependencies upper bound constraints.
451 :default: ``none``
453 Allow the solver to pick more recent version of some packages than
454 would normally be permitted by the :pkg-field:`build-depends` bounds
455 of packages in the install plan. This option may be useful if the
456 dependency solver cannot otherwise find a valid install plan.
458 For example, to relax ``pkg``\ s :pkg-field:`build-depends` upper bound on
459 ``dep-pkg``, write a scoped package name of the form:
461 ::
463 allow-newer: pkg:dep-pkg
465 If the scope shall be limited to specific releases of ``pkg``, the
466 extended form as in
468 ::
470 allow-newer: pkg-1.2.3:dep-pkg, pkg-1.1.2:dep-pkg
472 can be used to limit the relaxation of dependencies on
473 ``dep-pkg`` by the ``pkg-1.2.3`` and ``pkg-1.1.2`` releases only.
475 The scoped syntax is recommended, as it is often only a single package
476 whose upper bound is misbehaving. In this case, the upper bounds of
477 other packages should still be respected; indeed, relaxing the bound
478 can break some packages which test the selected version of packages.
480 The syntax also allows to prefix the dependee package with a
481 modifier symbol to modify the scope/semantic of the relaxation
482 transformation in a additional ways. Currently only one modifier
483 symbol is defined, i.e. ``^`` (i.e. caret) which causes the
484 relaxation to be applied only to ``^>=`` operators and leave all other
485 version operators untouched.
487 However, in some situations (e.g., when attempting to build packages
488 on a new version of GHC), it is useful to disregard *all*
489 upper-bounds, with respect to a package or all packages. This can be
490 done by specifying just a package name, or using the keyword ``all``
491 to specify all packages:
493 ::
495 -- Disregard upper bounds involving the dependencies on
496 -- packages bar, baz. For quux only, relax
497 -- 'quux ^>= ...'-style constraints only.
498 allow-newer: bar, baz, ^quux
500 -- Disregard all upper bounds when dependency solving
501 allow-newer: all
503 -- Disregard all `^>=`-style upper bounds when dependency solving
504 allow-newer: ^all
507 For consistency, there is also the explicit wildcard scope syntax
508 ``*`` (or its alphabetic synonym ``all``). Consequently, the
509 examples above are equivalent to the explicitly scoped variants:
511 ::
513 allow-newer: all:bar, *:baz, *:^quux
515 allow-newer: *:*
516 allow-newer: all:all
518 allow-newer: *:^*
519 allow-newer: all:^all
521 In order to ignore all bounds specified by a package ``pkg-1.2.3``
522 you can combine scoping with a right-hand-side wildcard like so
524 ::
526 -- Disregard any upper bounds specified by pkg-1.2.3
527 allow-newer: pkg-1.2.3:*
529 -- Disregard only `^>=`-style upper bounds in pkg-1.2.3
530 allow-newer: pkg-1.2.3:^*
533 :cfg-field:`allow-newer` is often used in conjunction with a constraint
534 (in the :cfg-field:`constraints` field) forcing the usage of a specific,
535 newer version of a package.
537 The command line variant of this field is e.g. ``--allow-newer=bar``. A
538 bare ``--allow-newer`` is equivalent to ``--allow-newer=all``.
540 .. cfg-field:: allow-older: none, all, list of scoped package names (space or comma separated)
541 --allow-older, --allow-older=[none,all,[scope:][^]pkg]
542 :synopsis: Lift dependency lower bound constraints.
543 :since: 2.0
545 :default: ``none``
547 Like :cfg-field:`allow-newer`, but applied to lower bounds rather than
548 upper bounds.
550 The command line variant of this field is ``--allow-older=all``. A
551 bare ``--allow-older`` is equivalent to ``--allow-older=all``.
554 .. cfg-field:: index-state: HEAD, unix-timestamp, ISO8601 UTC timestamp.
555 :synopsis: Use source package index state as it existed at a previous time.
556 :since: 2.0
558 :default: ``HEAD``
560 This allows to change the source package index state the solver uses
561 to compute install-plans. This is particularly useful in
562 combination with freeze-files in order to also freeze the state the
563 package index was in at the time the install-plan was frozen.
565 ::
567 -- UNIX timestamp format example
568 index-state: @1474739268
570 -- ISO8601 UTC timestamp format example
571 -- This format is used by 'cabal configure'
572 -- for storing `--index-state` values.
573 index-state: 2016-09-24T17:47:48Z
575 -- Specify different index-states per package repository
576 -- Supported since 3.4
577 index-state:
578 , hackage.haskell.org 2020-05-06T22:33:27Z
579 , head.hackage 2020-04-29T04:11:05Z
581 .. cfg-field:: active-repositories: reponame1, reponame2
583 :synopsis: Specify active package repositories
584 :since: 3.4
586 :default: ``:rest``
588 Specifies which of the package repositories defined in the configuration
589 should be active. It's also useful for specifying the order and the way
590 active repositories are merged.
592 When searching for a certain version of a certain package name, the list of
593 active repositories is searched last-to-first.
595 For example, suppose hackage.haskell.org has versions 1.0 and 2.0 of
596 package X, and my-repository has version 2.0 of a similarly named package.
597 Then, with the following configuration:
599 ::
601 -- Force my-repository to be the first repository considered
602 active-repositories:
603 , hackage.haskell.org
604 , my-repository
606 version 2.0 of X will come from my-repository, and version 1.0 will come
607 from hackage.haskell.org.
609 If we want to make a repository the sole provider of certain packages, we
610 can put it last in the active repositories list, and add the :override
611 modifier.
613 For example, if we modify the previous example like this:
615 ::
617 active-repositories:
618 , hackage.haskell.org
619 , my-repository:override
621 then version 1.0 of package X won't be found in any case, because X is
622 present in my-repository only in version 2.0, and the :override forbids
623 searching for other versions of X further up the list.
625 :override has no effect for package names that aren't present in the
626 overriding repository.
628 The special repository reference :rest stands for "all the other repositories"
629 and can be useful to avoid lengthy lists of repository names:
631 ::
633 -- Force my-repository to be the first repository considered
634 active-repositories: :rest, my-repository
636 The special repository reference :none disables all repositories, effectively
637 putting cabal in "offline" mode:
639 ::
641 active-repositories: :none
644 .. cfg-field:: reject-unconstrained-dependencies: all, none
645 --reject-unconstrained-dependencies=[all|none]
646 :synopsis: Restrict the solver to packages that have constraints on them.
648 :default: none
649 :since: 2.6
651 By default, the dependency solver can include any package that it's
652 aware of in a build plan. If you wish to restrict the build plan to
653 a closed set of packages (e.g., from a freeze file), use this flag.
655 When set to `all`, all non-local packages that aren't goals must be
656 explicitly constrained. When set to `none`, the solver will
657 consider all packages.
660 Package configuration options
661 -----------------------------
663 Package options affect the building of specific packages. There are three
664 ways a package option can be specified:
666 - They can be specified at the top-level, in which case they apply only
667 to **local package**, or
669 - They can be specified inside a ``package`` stanza, in which case they
670 apply to the build of the package, whether or not it is local or
671 external.
673 - They can be specified inside an ``package *`` stanza, in which case they
674 apply to all packages, local ones from the project and also external
675 dependencies.
678 For example, the following options specify that :cfg-field:`optimization`
679 should be turned off for all local packages, and that ``bytestring`` (possibly
680 an external dependency) should be built with ``-fno-state-hack``::
682 optimization: False
684 package bytestring
685 ghc-options: -fno-state-hack
687 ``ghc-options`` is not specifically described in this documentation, but is one
688 of many fields for configuring programs. They take the form
689 ``progname-options`` and ``progname-location``, and can be set for all local
690 packages in a ``program-options`` stanza or under a package stanza.
692 On the command line, these options are applied to all local packages.
693 There is no per-package command line interface.
695 Some flags were added by more recent versions of the Cabal library. This
696 means that they are NOT supported by packages which use Custom setup
697 scripts that require a version of the Cabal library older than when the
698 feature was added.
700 .. cfg-field:: flags: list of +flagname or -flagname (space separated)
701 --flags="+foo -bar", -ffoo, -f-bar
702 :synopsis: Enable or disable package flags.
704 Force all flags specified as ``+flagname`` to be true, and all flags
705 specified as ``-flagname`` to be false. For example, to enable the
706 flag ``foo`` and disable ``bar``, set:
708 ::
710 flags: +foo -bar
712 Exactly one of + or - is required before each flag.
714 Flags are *per-package*, so it doesn't make much sense to specify
715 flags at the top-level, unless you happen to know that *all* of your
716 local packages support the same named flags. If a flag is not
717 supported by a package, it is ignored.
719 See also the solver configuration field :cfg-field:`constraints`.
721 The command line variant of this flag is ``--flags``. There is also
722 a shortened form ``-ffoo -f-bar``.
724 A common mistake is to say ``cabal build -fhans``, where
725 ``hans`` is a flag for a transitive dependency that is not in the
726 local package; in this case, the flag will be silently ignored. If
727 ``haskell-tor`` is the package you want this flag to apply to, try
728 ``--constraint="haskell-tor +hans"`` instead.
730 .. cfg-field:: with-compiler: executable
731 --with-compiler=executable
732 :synopsis: Path to compiler executable.
734 Specify the path to a particular compiler to be used. If not an
735 absolute path, it will be resolved according to the ``PATH``
736 environment. The type of the compiler (GHC, GHCJS, etc) must be
737 consistent with the setting of the :cfg-field:`compiler` field.
739 The most common use of this option is to specify a different version
740 of your compiler to be used; e.g., if you have ``ghc-7.8`` in your
741 path, you can specify ``with-compiler: ghc-7.8`` to use it.
743 This flag also sets the default value of :cfg-field:`with-hc-pkg`, using
744 the heuristic that it is named ``ghc-pkg-7.8`` (if your executable name
745 is suffixed with a version number), or is the executable named
746 ``ghc-pkg`` in the same directory as the ``ghc`` directory. If this
747 heuristic does not work, set :cfg-field:`with-hc-pkg` explicitly.
749 For inplace packages, ``cabal build`` maintains a separate build
750 directory for each version of GHC, so you can maintain multiple
751 build trees for different versions of GHC without clobbering each
752 other.
754 It's not possible to set :cfg-field:`with-compiler` on a
755 per-package basis.
757 The command line variant of this flag is
758 ``--with-compiler=ghc-7.8``; there is also a short version
759 ``-w ghc-7.8``.
761 .. cfg-field:: with-hc-pkg: executable
762 --with-hc-pkg=executable
763 :synopsis: Specifies package tool.
765 Specify the path to the package tool, e.g., ``ghc-pkg``. This
766 package tool must be compatible with the compiler specified by
767 :cfg-field:`with-compiler` (generally speaking, it should be precisely
768 the tool that was distributed with the compiler). If this option is
769 omitted, the default value is determined from :cfg-field:`with-compiler`.
771 The command line variant of this flag is
772 ``--with-hc-pkg=ghc-pkg-7.8``.
774 .. cfg-field:: optimization: nat
775 --enable-optimization
776 --disable-optimization
777 :synopsis: Build with optimization.
779 :default: ``1``
781 Build with optimization. This is appropriate for production use,
782 taking more time to build faster libraries and programs.
784 The optional *nat* value is the optimisation level. Some compilers
785 support multiple optimisation levels. The range is 0 to 2. Level 0
786 disables optimization, level 1 is the default. Level 2 is higher
787 optimisation if the compiler supports it. Level 2 is likely to lead
788 to longer compile times and bigger generated code. If you are not
789 planning to run code, turning off optimization will lead to better
790 build times and less code to be rebuilt when a module changes.
792 When optimizations are enabled, Cabal passes ``-O2`` to the C compiler.
794 We also accept ``True`` (equivalent to 1) and ``False`` (equivalent
795 to 0).
797 Note that as of GHC 8.0, GHC does not recompile when optimization
798 levels change (see :ghc-ticket:`10923`), so if
799 you change the optimization level for a local package you may need
800 to blow away your old build products in order to rebuild with the
801 new optimization level.
803 The command line variant of this flag is ``-O2`` (with ``-O1``
804 equivalent to ``-O``). There are also long-form variants
805 ``--enable-optimization`` and ``--disable-optimization``.
807 .. cfg-field:: configure-options: args (space separated)
808 --configure-option=arg
809 :synopsis: Options to pass to configure script.
811 A list of extra arguments to pass to the external ``./configure``
812 script, if one is used. This is only useful for packages which have
813 the ``Configure`` build type. See also the section on
814 :ref:`system-dependent parameters`.
816 The command line variant of this flag is ``--configure-option=arg``,
817 which can be specified multiple times to pass multiple options.
819 .. cfg-field:: compiler: ghc, ghcjs, jhc, lhc, uhc or haskell-suite
820 --compiler=compiler
821 :synopsis: Compiler to build with.
823 :default: ``ghc``
825 Specify the compiler toolchain to be used. This is independent of
826 ``with-compiler``, because the choice of toolchain affects Cabal's
827 build logic.
829 The command line variant of this flag is ``--compiler=ghc``.
831 It's not possible to set :cfg-field:`compiler` on a
832 per-package basis.
834 .. cfg-field:: tests: boolean
835 --enable-tests
836 --disable-tests
837 :synopsis: Build tests.
839 :default: ``False``
841 Force test suites to be enabled. For most users this should not be
842 needed, as we always attempt to solve for test suite dependencies,
843 even when this value is ``False``; furthermore, test suites are
844 automatically enabled if they are requested as a built target.
846 The command line variant of this flag is ``--enable-tests`` and
847 ``--disable-tests``.
849 .. cfg-field:: benchmarks: boolean
850 --enable-benchmarks
851 --disable-benchmarks
852 :synopsis: Build benchmarks.
854 :default: ``False``
856 Force benchmarks to be enabled. For most users this should not be
857 needed, as we always attempt to solve for benchmark dependencies,
858 even when this value is ``False``; furthermore, benchmarks are
859 automatically enabled if they are requested as a built target.
861 The command line variant of this flag is ``--enable-benchmarks`` and
862 ``--disable-benchmarks``.
864 .. cfg-field:: extra-prog-path: paths (newline or comma separated)
865 --extra-prog-path=PATH
866 :synopsis: Add directories to program search path.
867 :since: 1.18
869 A list of directories to search for extra required programs. Most
870 users should not need this, as programs like ``happy`` and ``alex``
871 will automatically be installed and added to the path. This can be
872 useful if a ``Custom`` setup script relies on an exotic extra
873 program.
875 The command line variant of this flag is ``--extra-prog-path=PATH``,
876 which can be specified multiple times.
878 .. cfg-field:: run-tests: boolean
879 --run-tests
880 :synopsis: Run package test suite upon installation.
882 :default: ``False``
884 Run the package test suite upon installation. This is useful for
885 saying "When this package is installed, check that the test suite
886 passes, terminating the rest of the build if it is broken."
888 .. warning::
890 One deficiency: the :cfg-field:`run-tests` setting of a package is NOT
891 recorded as part of the hash, so if you install something without
892 :cfg-field:`run-tests` and then turn on ``run-tests``, we won't
893 subsequently test the package. If this is causing you problems, give
894 us a shout.
896 The command line variant of this flag is ``--run-tests``.
898 Object code options
899 ^^^^^^^^^^^^^^^^^^^
901 .. cfg-field:: debug-info: integer
902 --enable-debug-info=<n>
903 --disable-debug-info
904 :synopsis: Build with debug info enabled.
905 :since: 1.22
907 :default: False
909 If the compiler (e.g., GHC 7.10 and later) supports outputing OS
910 native debug info (e.g., DWARF), setting ``debug-info: True`` will
911 instruct it to do so. See the GHC wiki page on :ghc-wiki:`DWARF`
912 for more information about this feature.
914 (This field also accepts numeric syntax, but until GHC 8.2 this didn't
915 do anything.)
917 The command line variant of this flag is ``--enable-debug-info`` and
918 ``--disable-debug-info``.
920 .. cfg-field:: split-sections: boolean
921 --enable-split-sections
922 --disable-split-sections
923 :synopsis: Use GHC's split sections feature.
924 :since: 2.2
926 :default: False
928 Use the GHC ``-split-sections`` feature when building the library. This
929 reduces the final size of the executables that use the library by
930 allowing them to link with only the bits that they use rather than
931 the entire library. The downside is that building the library takes
932 longer and uses a bit more memory.
934 This feature is supported by GHC 8.0 and later.
936 The command line variant of this flag is ``--enable-split-sections`` and
937 ``--disable-split-sections``.
939 .. cfg-field:: split-objs: boolean
940 --enable-split-objs
941 --disable-split-objs
942 :synopsis: Use GHC's split objects feature.
944 :default: False
946 Use the GHC ``-split-objs`` feature when building the library. This
947 reduces the final size of the executables that use the library by
948 allowing them to link with only the bits that they use rather than
949 the entire library. The downside is that building the library takes
950 longer and uses considerably more memory.
952 It is generally recommend that you use ``split-sections`` instead
953 of ``split-objs`` where possible.
955 The command line variant of this flag is ``--enable-split-objs`` and
956 ``--disable-split-objs``.
958 .. cfg-field:: executable-stripping: boolean
959 --enable-executable-stripping
960 --disable-executable-stripping
961 :synopsis: Strip installed programs.
963 :default: True
965 When installing binary executable programs, run the ``strip``
966 program on the binary. This can considerably reduce the size of the
967 executable binary file. It does this by removing debugging
968 information and symbols.
970 Not all Haskell implementations generate native binaries. For such
971 implementations this option has no effect.
973 If ``debug-info`` is set explicitly then ``executable-stripping`` is set
974 to ``False`` as otherwise all the debug symbols will be stripped.
976 The command line variant of this flag is
977 ``--enable-executable-stripping`` and
978 ``--disable-executable-stripping``.
980 .. cfg-field:: library-stripping: boolean
981 --enable-library-stripping
982 --disable-library-stripping
983 :synopsis: Strip installed libraries.
984 :since: 1.20
986 When installing binary libraries, run the ``strip`` program on the
987 binary, saving space on the file system. See also
988 ``executable-stripping``.
990 If ``debug-info`` is set explicitly then ``library-stripping`` is set
991 to ``False`` as otherwise all the debug symbols will be stripped.
993 The command line variant of this flag is
994 ``--enable-library-stripping`` and ``--disable-library-stripping``.
996 Executable options
997 ^^^^^^^^^^^^^^^^^^
999 .. cfg-field:: program-prefix: prefix
1000 --program-prefix=prefix
1001 :synopsis: Prepend prefix to program names.
1003 :strike:`Prepend *prefix* to installed program names.` (Currently
1004 implemented in a silly and not useful way. If you need this to work
1005 give us a shout.)
1007 *prefix* may contain the following path variables: ``$pkgid``,
1008 ``$pkg``, ``$version``, ``$compiler``, ``$os``, ``$arch``, ``$abi``,
1009 ``$abitag``
1011 The command line variant of this flag is ``--program-prefix=foo-``.
1013 .. cfg-field:: program-suffix: suffix
1014 --program-suffix=suffix
1015 :synopsis: Append refix to program names.
1017 :strike:`Append *suffix* to installed program names.` (Currently
1018 implemented in a silly and not useful way. If you need this to work
1019 give us a shout.)
1021 The most obvious use for this is to append the program's version
1022 number to make it possible to install several versions of a program
1023 at once: ``program-suffix: $version``.
1025 *suffix* may contain the following path variables: ``$pkgid``,
1026 ``$pkg``, ``$version``, ``$compiler``, ``$os``, ``$arch``, ``$abi``,
1027 ``$abitag``
1029 The command line variant of this flag is
1030 ``--program-suffix='$version'``.
1032 Dynamic linking options
1033 ^^^^^^^^^^^^^^^^^^^^^^^
1035 .. cfg-field:: shared: boolean
1036 --enable-shared
1037 --disable-shared
1038 :synopsis: Build shared library.
1040 :default: False
1042 Build shared library. This implies a separate compiler run to
1043 generate position independent code as required on most platforms.
1045 The command line variant of this flag is ``--enable-shared`` and
1046 ``--disable-shared``.
1048 .. cfg-field:: executable-dynamic: boolean
1049 --enable-executable-dynamic
1050 --disable-executable-dynamic
1051 :synopsis: Link executables dynamically.
1053 :default: False
1055 Link executables dynamically. The executable's library dependencies
1056 should be built as shared objects. This implies ``shared: True``
1057 unless ``shared: False`` is explicitly specified.
1059 The command line variant of this flag is
1060 ``--enable-executable-dynamic`` and
1061 ``--disable-executable-dynamic``.
1063 .. cfg-field:: library-for-ghci: boolean
1064 --enable-library-for-ghci
1065 --disable-library-for-ghci
1066 :synopsis: Build libraries suitable for use with GHCi.
1068 :default: True
1070 Build libraries suitable for use with GHCi. This involves an extra
1071 linking step after the build.
1073 Not all platforms support GHCi and indeed on some platforms, trying
1074 to build GHCi libs fails. In such cases, consider setting
1075 ``library-for-ghci: False``.
1077 The command line variant of this flag is
1078 ``--enable-library-for-ghci`` and ``--disable-library-for-ghci``.
1080 .. cfg-field:: relocatable:
1081 --relocatable
1082 :synopsis: Build relocatable package.
1083 :since: 1.22
1085 :default: False
1087 :strike:`Build a package which is relocatable.` (TODO: It is not
1088 clear what this actually does, or if it works at all.)
1090 The command line variant of this flag is ``--relocatable``.
1092 Static linking options
1093 ^^^^^^^^^^^^^^^^^^^^^^
1095 .. cfg-field:: static: boolean
1096 --enable-static
1097 --disable-static
1098 :synopsis: Build static library.
1101 :default: False
1103 Roll this and all dependent libraries into a combined ``.a`` archive.
1104 This uses GHCs ``-staticlib`` flag, which is available for iOS and with
1105 GHC 8.4 and later for other platforms as well.
1107 .. cfg-field:: executable-static: boolean
1108 --enable-executable-static
1109 --disable-executable-static
1110 :synopsis: Build fully static executables.
1113 :default: False
1115 Build fully static executables.
1116 This links all dependent libraries into executables statically,
1117 including libc.
1118 This passes ``-static`` and ``-optl=-static`` to GHC.
1120 Foreign function interface options
1121 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1123 .. cfg-field:: extra-include-dirs: directories (comma or newline separated list)
1124 --extra-include-dirs=DIR
1125 :synopsis: Adds C header search path.
1127 An extra directory to search for C header files. You can use this
1128 flag multiple times to get a list of directories.
1130 You might need to use this flag if you have standard system header
1131 files in a non-standard location that is not mentioned in the
1132 package's ``.cabal`` file. Using this option has the same affect as
1133 appending the directory *dir* to the :pkg-field:`include-dirs` field in each
1134 library and executable in the package's ``.cabal`` file. The
1135 advantage of course is that you do not have to modify the package at
1136 all. These extra directories will be used while building the package
1137 and for libraries it is also saved in the package registration
1138 information and used when compiling modules that use the library.
1140 The command line variant of this flag is
1141 ``--extra-include-dirs=DIR``, which can be specified multiple times.
1143 .. cfg-field:: extra-lib-dirs: directories (comma or newline separated list)
1144 --extra-lib-dirs=DIR
1145 :synopsis: Adds library search directory.
1147 An extra directory to search for system libraries files.
1149 The command line variant of this flag is ``--extra-lib-dirs=DIR``,
1150 which can be specified multiple times.
1152 .. cfg-field:: extra-framework-dirs: directories (comma or newline separated list)
1153 --extra-framework-dirs=DIR
1154 :synopsis: Adds framework search directory (OS X only).
1156 An extra directory to search for frameworks (OS X only).
1158 You might need to use this flag if you have standard system
1159 libraries in a non-standard location that is not mentioned in the
1160 package's ``.cabal`` file. Using this option has the same affect as
1161 appending the directory *dir* to the :cfg-field:`extra-lib-dirs` field in
1162 each library and executable in the package's ``.cabal`` file. The
1163 advantage of course is that you do not have to modify the package at
1164 all. These extra directories will be used while building the package
1165 and for libraries it is also saved in the package registration
1166 information and used when compiling modules that use the library.
1168 The command line variant of this flag is
1169 ``--extra-framework-dirs=DIR``, which can be specified multiple
1170 times.
1172 Profiling options
1173 ^^^^^^^^^^^^^^^^^
1175 .. cfg-field:: profiling: boolean
1176 --enable-profiling
1177 --disable-profiling
1178 :synopsis: Enable profiling builds.
1179 :since: 1.22
1181 :default: False
1183 Build libraries and executables with profiling enabled (for
1184 compilers that support profiling as a separate mode). It is only
1185 necessary to specify :cfg-field:`profiling` for the specific package you
1186 want to profile; ``cabal build`` will ensure that all of its
1187 transitive dependencies are built with profiling enabled.
1189 To enable profiling for only libraries or executables, see
1190 :cfg-field:`library-profiling` and :cfg-field:`executable-profiling`.
1192 For useful profiling, it can be important to control precisely what
1193 cost centers are allocated; see :cfg-field:`profiling-detail`.
1195 The command line variant of this flag is ``--enable-profiling`` and
1196 ``--disable-profiling``.
1198 .. cfg-field:: profiling-detail: level
1199 --profiling-detail=level
1200 :synopsis: Profiling detail level.
1201 :since: 1.24
1203 Some compilers that support profiling, notably GHC, can allocate
1204 costs to different parts of the program and there are different
1205 levels of granularity or detail with which this can be done. In
1206 particular for GHC this concept is called "cost centers", and GHC
1207 can automatically add cost centers, and can do so in different ways.
1209 This flag covers both libraries and executables, but can be
1210 overridden by the ``library-profiling-detail`` field.
1212 Currently this setting is ignored for compilers other than GHC. The
1213 levels that cabal currently supports are:
1215 default
1216 For GHC this uses ``exported-functions`` for libraries and
1217 ``toplevel-functions`` for executables.
1218 none
1219 No costs will be assigned to any code within this component.
1220 exported-functions
1221 Costs will be assigned at the granularity of all top level
1222 functions exported from each module. In GHC, this
1223 is for non-inline functions. Corresponds to ``-fprof-auto-exported``.
1224 toplevel-functions
1225 Costs will be assigned at the granularity of all top level
1226 functions in each module, whether they are exported from the
1227 module or not. In GHC specifically, this is for non-inline
1228 functions. Corresponds to ``-fprof-auto-top``.
1229 all-functions
1230 Costs will be assigned at the granularity of all functions in
1231 each module, whether top level or local. In GHC specifically,
1232 this is for non-inline toplevel or where-bound functions or
1233 values. Corresponds to ``-fprof-auto``.
1235 The command line variant of this flag is
1236 ``--profiling-detail=none``.
1238 .. cfg-field:: library-profiling-detail: level
1239 --library-profiling-detail=level
1240 :synopsis: Libraries profiling detail level.
1241 :since: 1.24
1243 Like :cfg-field:`profiling-detail`, but applied only to libraries
1245 The command line variant of this flag is
1246 ``--library-profiling-detail=none``.
1248 .. cfg-field:: library-vanilla: boolean
1249 --enable-library-vanilla
1250 --disable-library-vanilla
1251 :synopsis: Build libraries without profiling.
1253 :default: True
1255 Build ordinary libraries (as opposed to profiling libraries).
1256 Mostly, you can set this to False to avoid building ordinary
1257 libraries when you are profiling.
1259 The command line variant of this flag is
1260 ``--enable-library-vanilla`` and ``--disable-library-vanilla``.
1262 .. cfg-field:: library-profiling: boolean
1263 --enable-library-profiling
1264 --disable-library-profiling
1265 :synopsis: Build libraries with profiling enabled.
1266 :since: 1.22
1268 :default: False
1270 Build libraries with profiling enabled. You probably want
1271 to use :cfg-field:`profiling` instead.
1273 The command line variant of this flag is
1274 ``--enable-library-profiling`` and ``--disable-library-profiling``.
1276 .. cfg-field:: executable-profiling: boolean
1277 --enable-executable-profiling
1278 --disable-executable-profiling
1279 :synopsis: Build executables with profiling enabled.
1280 :since: 1.22
1282 :default: False
1284 Build executables with profiling enabled. You probably want
1285 to use :cfg-field:`profiling` instead.
1287 The command line variant of this flag is
1288 ``--enable-executable-profiling`` and
1289 ``--disable-executable-profiling``.
1291 Coverage options
1292 ^^^^^^^^^^^^^^^^
1294 .. cfg-field:: coverage: boolean
1295 --enable-coverage
1296 --disable-coverage
1297 :synopsis: Build with coverage enabled.
1298 :since: 1.22
1300 :default: False
1302 Build libraries and executables (including test suites) with Haskell
1303 Program Coverage enabled. Running the test suites will automatically
1304 generate coverage reports with HPC.
1306 The command line variant of this flag is ``--enable-coverage`` and
1307 ``--disable-coverage``.
1309 .. cfg-field:: library-coverage: boolean
1310 --enable-library-coverage
1311 --disable-library-coverage
1312 :since: 1.22
1313 :deprecated:
1315 :default: False
1317 Deprecated, use :cfg-field:`coverage`.
1319 The command line variant of this flag is
1320 ``--enable-library-coverage`` and ``--disable-library-coverage``.
1322 Haddock options
1323 ^^^^^^^^^^^^^^^
1325 .. cfg-field:: documentation: boolean
1326 --enable-documentation
1327 --disable-documentation
1328 :synopsis: Enable building of documentation.
1330 :default: False
1332 Enables building of Haddock documentation.
1333 Implied when calling ``cabal haddock``.
1335 The command line variant of this flag is ``--enable-documentation``
1336 and ``--disable-documentation``.
1338 ``documentation: true`` does not imply
1339 :cfg-field:`haddock-all`,
1340 :cfg-field:`haddock-benchmarks`,
1341 :cfg-field:`haddock-executables`,
1342 :cfg-field:`haddock-internal` or
1343 :cfg-field:`haddock-tests`.
1344 These need to be enabled separately if desired.
1346 .. cfg-field:: doc-index-file: templated path
1347 --doc-index-file=TEMPLATE
1348 :synopsis: Path to haddock templates.
1350 A central index of Haddock API documentation (template cannot use
1351 ``$pkgid``), which should be updated as documentation is built.
1353 The following commands are equivalent to ones that would be passed when
1354 running ``setup haddock``.
1356 .. cfg-field:: haddock-hoogle: boolean
1357 --haddock-hoogle
1358 :synopsis: Generate Hoogle file.
1360 :default: False
1362 Generate a text file which can be converted by Hoogle_
1363 into a database for searching.
1364 This is equivalent to running ``haddock`` with the ``--hoogle`` flag.
1366 .. cfg-field:: haddock-html: boolean
1367 --haddock-html
1368 :synopsis: Build HTML documentation.
1370 :default: True
1372 Build HTML documentation.
1374 .. cfg-field:: haddock-quickjump: boolean
1375 --haddock-quickjump
1376 :synopsis: Generate Quickjump file.
1378 :default: False
1380 Generate an index for interactive documentation navigation.
1381 This is equivalent to running ``haddock`` with the ``--quickjump`` flag.
1383 .. cfg-field:: haddock-html-location: templated path
1384 --haddock-html-location=TEMPLATE
1385 :synopsis: Haddock HTML templates location.
1387 Specify a template for the location of HTML documentation for
1388 prerequisite packages. The substitutions are applied to the template
1389 to obtain a location for each package, which will be used by
1390 hyperlinks in the generated documentation. For example, the
1391 following command generates links pointing at Hackage pages:
1393 ::
1395 html-location: http://hackage.haskell.org/packages/archive/$pkg/latest/doc/html
1397 If passed on the command line,
1398 the argument may be quoted to prevent substitution by the shell.
1400 ::
1402 --html-location='http://hackage.haskell.org/packages/archive/$pkg/latest/doc/html'
1404 If this option is omitted, the location for each package is obtained
1405 using the package tool (e.g. ``ghc-pkg``).
1407 .. cfg-field:: haddock-executables: boolean
1408 --haddock-executables
1409 :synopsis: Generate documentation for executables.
1411 :default: False
1413 Run haddock on all executable programs.
1415 .. cfg-field:: haddock-tests: boolean
1416 --haddock-tests
1417 :synopsis: Generate documentation for tests.
1419 :default: False
1421 Run haddock on all test suites.
1423 .. cfg-field:: haddock-benchmarks: boolean
1424 --haddock-benchmarks
1425 :synopsis: Generate documentation for benchmarks.
1427 :default: False
1429 Run haddock on all benchmarks.
1431 .. cfg-field:: haddock-internal: boolean
1432 --haddock-internal
1433 :synopsis: Generate documentation for internal modules
1435 :default: False
1437 Build haddock documentation which includes unexposed modules and
1438 symbols.
1440 .. cfg-field:: haddock-all: boolean
1441 --haddock-all
1442 :synopsis: Generate documentation for everything
1444 :default: False
1446 Run haddock on all components.
1448 .. cfg-field:: haddock-css: path
1449 --haddock-css=PATH
1450 :synopsis: Location of Haddock CSS file.
1452 The CSS file that should be used to style the generated
1453 documentation (overriding haddock's default).
1455 .. cfg-field:: haddock-hyperlink-source: boolean
1456 --haddock-hyperlink-source
1457 :synopsis: Generate hyperlinked source code for documentation
1459 :default: False
1461 Generated hyperlinked source code using `HsColour`_, and have
1462 Haddock documentation link to it.
1463 This is equivalent to running ``haddock`` with the ``--hyperlinked-source`` flag.
1465 .. cfg-field:: haddock-hscolour-css: path
1466 --haddock-hscolour-css=PATH
1467 :synopsis: Location of CSS file for HsColour
1469 The CSS file that should be used to style the generated hyperlinked
1470 source code (from `HsColour`_).
1472 .. cfg-field:: haddock-contents-location: URL
1473 --haddock-contents-location=URL
1474 :synopsis: URL for contents page.
1476 A baked-in URL to be used as the location for the contents page.
1478 .. cfg-field:: haddock-keep-temp-files: boolean
1479 :synopsis: Keep temporary Haddock files.
1481 Keep temporary files.
1483 There is no command line variant of this flag.
1485 .. cfg-field:: open: boolean
1486 --open
1487 :synopsis: Open generated documentation in-browser.
1489 When generating HTML documentation, attempt to open it in a browser
1490 when complete. This will use ``xdg-open`` on Linux and BSD systems,
1491 ``open`` on macOS, and ``start`` on Windows.
1493 Advanced global configuration options
1494 -------------------------------------
1496 .. cfg-field:: write-ghc-environment-files: always, never, or ghc8.4.4+
1497 --write-ghc-environment-files=policy
1498 :synopsis: Whether a ``.ghc.environment`` should be created after a successful build.
1500 :default: ``never``
1502 Whether a `GHC package environment file <https://downloads.haskell.org/~ghc/master/users-guide/packages.html#package-environments>`_
1503 should be created after a successful build.
1505 Since Cabal 3.0, defaults to ``never``. Before that, defaulted to
1506 creating them only when compiling with GHC 8.4.4 and older (GHC
1507 8.4.4 `is the first version
1508 <https://gitlab.haskell.org/ghc/ghc/-/issues/13753>`_ that supports
1509 the ``-package-env -`` option that allows ignoring the package
1510 environment files).
1512 .. cfg-field:: build-info: True, False
1513 --enable-build-info
1514 --disable-build-info
1515 :synopsis: Whether build information for each individual component should be
1516 written in a machine readable format.
1518 :default: ``False``
1520 Enable generation of build information for Cabal components. Contains very
1521 detailed information on how to build an individual component, such as
1522 compiler version, modules of a component and how to compile the component.
1524 The output format is in json, and the exact location can be discovered from
1525 ``plan.json``, where it is identified by ``build-info`` within the items in
1526 the ``install-plan``.
1527 Note, that this field in ``plan.json`` can be ``null``, if and only if
1528 ``build-type: Custom`` is set, and the ``Cabal`` version is too
1529 old (i.e. ``< 3.7``).
1530 If the field is missing entirely, the component is not a local one, thus,
1531 no ``build-info`` exists for that particular component within the
1532 ``install-plan``.
1534 .. note::
1535 The format and fields of the generated build information is currently experimental,
1536 in the future we might add or remove fields, depending on the needs of other tooling.
1539 .. cfg-field:: http-transport: curl, wget, powershell, or plain-http
1540 --http-transport=transport
1541 :synopsis: Transport to use with http(s) requests.
1543 :default: ``curl``
1545 Set a transport to be used when making http(s) requests.
1547 The command line variant of this field is ``--http-transport=curl``.
1549 .. cfg-field:: ignore-expiry: boolean
1550 --ignore-expiry
1551 :synopsis: Ignore Hackage expiration dates.
1553 :default: False
1555 If ``True``, we will ignore expiry dates on metadata from Hackage.
1557 In general, you should not set this to ``True`` as it will leave you
1558 vulnerable to stale cache attacks. However, it may be temporarily
1559 useful if the main Hackage server is down, and we need to rely on
1560 mirrors which have not been updated for longer than the expiry
1561 period on the timestamp.
1563 The command line variant of this field is ``--ignore-expiry``.
1565 .. cfg-field:: remote-repo-cache: directory
1566 --remote-repo-cache=DIR
1567 :synopsis: Location of packages cache.
1569 :default: ``~/.cabal/packages``
1571 :strike:`The location where packages downloaded from remote
1572 repositories will be cached.` Not implemented yet.
1574 The command line variant of this flag is
1575 ``--remote-repo-cache=DIR``.
1577 .. cfg-field:: logs-dir: directory
1578 --logs-dir=DIR
1579 :synopsis: Directory to store build logs.
1581 :default: ``~/.cabal/logs``
1583 :strike:`The location where build logs for packages are stored.`
1584 Not implemented yet.
1586 The command line variant of this flag is ``--logs-dir=DIR``.
1588 .. cfg-field:: build-summary: template filepath
1589 --build-summary=TEMPLATE
1590 :synopsis: Build summaries location.
1592 :default: ``~/.cabal/logs/build.log``
1594 :strike:`The file to save build summaries.` Not implemented yet.
1596 Valid variables which can be used in the path are ``$pkgid``,
1597 ``$compiler``, ``$os`` and ``$arch``.
1599 The command line variant of this flag is
1600 ``--build-summary=TEMPLATE``.
1602 Undocumented fields: ``root-cmd``, ``symlink-bindir``, ``build-log``,
1603 ``remote-build-reporting``, ``report-planned-failure``, ``offline``.
1605 Advanced solver options
1606 ^^^^^^^^^^^^^^^^^^^^^^^
1608 Most users generally won't need these.
1610 .. cfg-field:: solver: modular
1611 --solver=modular
1612 :synopsis: Which solver to use.
1614 This field is reserved to allow the specification of alternative
1615 dependency solvers. At the moment, the only accepted option is
1616 ``modular``.
1618 The command line variant of this field is ``--solver=modular``.
1620 .. cfg-field:: max-backjumps: nat
1621 --max-backjumps=N
1622 :synopsis: Maximum number of solver backjumps.
1624 :default: 4000
1626 Maximum number of backjumps (backtracking multiple steps) allowed
1627 while solving. Set -1 to allow unlimited backtracking, and 0 to
1628 disable backtracking completely.
1630 The command line variant of this field is ``--max-backjumps=4000``.
1632 .. cfg-field:: reorder-goals: boolean
1633 --reorder-goals
1634 --no-reorder-goals
1635 :synopsis: Allow solver to reorder goals.
1637 :default: False
1639 When enabled, the solver will reorder goals according to certain
1640 heuristics. Slows things down on average, but may make backtracking
1641 faster for some packages. It's unlikely to help for small projects,
1642 but for big install plans it may help you find a plan when otherwise
1643 this is not possible. See :issue:`1780` for more commentary.
1645 The command line variant of this field is ``--(no-)reorder-goals``.
1647 .. cfg-field:: count-conflicts: boolean
1648 --count-conflicts
1649 --no-count-conflicts
1650 :synopsis: Solver prefers versions with less conflicts.
1652 :default: True
1654 Try to speed up solving by preferring goals that are involved in a
1655 lot of conflicts.
1657 The command line variant of this field is
1658 ``--(no-)count-conflicts``.
1660 .. cfg-field:: fine-grained-conflicts: boolean
1661 --fine-grained-conflicts
1662 --no-fine-grained-conflicts
1663 :synopsis: Skip a version of a package if it does not resolve any conflicts
1664 encountered in the last version (solver optimization).
1666 :default: True
1668 When enabled, the solver will skip a version of a package if it does not
1669 resolve any of the conflicts encountered in the last version of that
1670 package. For example, if ``foo-1.2`` depended on ``bar``, and the solver
1671 couldn't find consistent versions for ``bar``'s dependencies, then the
1672 solver would skip ``foo-1.1`` if it also depended on ``bar``.
1674 The command line variant of this field is
1675 ``--(no-)fine-grained-conflicts``.
1677 .. cfg-field:: minimize-conflict-set: boolean
1678 --minimize-conflict-set
1679 --no-minimize-conflict-set
1680 :synopsis: Try to improve the solver error message when there is no
1681 solution.
1683 :default: False
1685 When there is no solution, try to improve the solver error message
1686 by finding a minimal conflict set. This option may increase run
1687 time significantly, so it is off by default.
1689 The command line variant of this field is
1690 ``--(no-)minimize-conflict-set``.
1692 .. cfg-field:: strong-flags: boolean
1693 --strong-flags
1694 --no-strong-flags
1695 :synopsis: Do not defer flag choices when solving.
1697 :default: False
1699 Do not defer flag choices. (TODO: Better documentation.)
1701 The command line variant of this field is ``--(no-)strong-flags``.
1703 .. cfg-field:: allow-boot-library-installs: boolean
1704 --allow-boot-library-installs
1705 --no-allow-boot-library-installs
1706 :synopsis: Allow cabal to install or upgrade any package.
1708 :default: False
1710 By default, the dependency solver doesn't allow ``base``,
1711 ``ghc-prim``, ``integer-simple``, ``integer-gmp``, and
1712 ``template-haskell`` to be installed or upgraded. This flag
1713 removes the restriction.
1715 The command line variant of this field is
1716 ``--(no-)allow-boot-library-installs``.
1718 .. cfg-field:: cabal-lib-version: version
1719 --cabal-lib-version=version
1720 :synopsis: Version of Cabal library used to build package.
1722 This field selects the version of the Cabal library which should be
1723 used to build packages. This option is intended primarily for
1724 internal development use (e.g., forcing a package to build with a
1725 newer version of Cabal, to test a new version of Cabal.) (TODO:
1726 Specify its semantics more clearly.)
1728 The command line variant of this field is
1729 ``--cabal-lib-version=1.24.0.1``.
1731 .. cfg-field:: prefer-oldest: boolean
1732 --prefer-oldest
1733 --no-prefer-oldest
1734 :synopsis: Prefer the oldest versions of packages available.
1735 :since: 3.8
1737 :default: False
1739 By default, when solver has a choice of multiple versions of the same
1740 package, it will first try to derive a build plan with the latest
1741 version. This flag switches the behaviour, making the solver
1742 to prefer the oldest packages available.
1744 The primary use case is to help users in establishing lower bounds
1745 of upstream dependencies.
1747 The command line variant of this field is ``--(no-)prefer-oldest``.
1749 .. include:: references.inc