1 Project Description — cabal.project File
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):
13 with-compiler: /opt/ghc/8.0.1/bin/ghc
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
27 1. :ref:`The user-wide global configuration <config-file-discovery>` (default: ``~/.config/cabal/config``)
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 and
44 imports in ``cabal.project`` files.
48 While :ref:`conditional blocks<conditional-blocks>` can appear anywhere
49 within component or common sections of a package, their placement within a
50 project is restricted. Conditions may only be introduced at the top level
53 Of the :ref:`condition tests<conditions>`, only packages can test for
54 flags. Projects can test for operating system, architecture, compiler and
55 the boolean constants.
58 - :samp:`arch({name})`
59 - :samp:`impl({compiler})`
63 Imports may specify local filepaths or remote urls, and may reference either
64 cabal.project files or v1-style cabal.config freeze files. As a usage example:
71 packages: freebsd/*.cabal
75 import: https://some.remote.source/subdir/cabal.config
77 import: relativepath/extra-project.project
79 import: /absolutepath/some-project.project
81 Using conditionals will force cabal to find a ghc to derive
82 architecture and version information from, which will force some
83 commands (update, sdist) to require ghc present where otherwise it
84 would not be necessitated.
86 Specifying the local packages
87 -----------------------------
89 The following top-level options specify what the local packages of a
92 .. cfg-field:: packages: package location list (space or comma separated)
93 :synopsis: Project packages.
95 :default: ``./*.cabal``
99 The default value ``./*.cabal`` only takes effect if there is no explicit
100 ``cabal.project`` file.
101 If you use such explicit file you *must* fill the field.
103 Specifies the list of package locations which contain the local
104 packages to be built by this project. Package locations can take the
107 1. They can specify a Cabal file, or a directory containing a Cabal
108 file, e.g., ``packages: Cabal cabal-install/cabal-install.cabal``.
110 2. They can specify glob-style wildcards, which must match one or
111 more (a) directories containing a (single) Cabal file, (b) Cabal
112 files (extension ``.cabal``), or (c) tarballs which contain Cabal
113 packages (extension ``.tar.gz``).
114 For example, to match all Cabal files in all
115 subdirectories, as well as the Cabal projects in the parent
116 directories ``foo`` and ``bar``, use
117 ``packages: */*.cabal ../{foo,bar}/``
119 3. They can specify an ``http``, ``https`` or ``file``
120 URL, representing the path to a remote tarball to be downloaded
123 There is no command line variant of this field; see :issue:`3585`.
124 Note that the default value is only included if there is no
125 ``cabal.project`` file. The field is appendable which means there would be
126 no way to drop the default value if it was included.
128 .. cfg-field:: optional-packages: package location list (space or comma-separated)
129 :synopsis: Optional project packages.
133 Like :cfg-field:`packages`, specifies a list of package locations
134 containing local packages to be built. Unlike :cfg-field:`packages`,
135 if we glob for a package, it is permissible for the glob to match against
136 zero packages. The intended use-case for :cfg-field:`optional-packages`
137 is to make it so that vendored packages can be automatically picked up if
138 they are placed in a subdirectory, but not error if there aren't any.
140 There is no command line variant of this field.
142 .. cfg-field:: extra-packages: package list with version bounds (comma separated)
143 :synopsis: Adds external packages as local
145 Specifies a list of external packages from Hackage, which
146 should be considered local packages. The motivation for
147 :cfg-field:`extra-packages` is making libraries that are not
148 dependencies of any package in the project available for use in ghci.
150 There is no command line variant of this field.
154 All local packages are *vendored*, in the sense that if other packages
155 (including external ones from Hackage) depend on a package with the name
156 of a local package, the local package is preferentially used.
157 For subdirectories to be considered local packages, the following setting
161 optional-packages: ./*/*.cabal
163 ...then any package can be vendored simply by making a checkout in the
164 top-level project directory, as might be seen in this hypothetical
168 foo-helper/ # local package
169 unix/ # vendored external package
171 All of these options support globs. ``cabal build`` has its own glob
174 - Anywhere in a path, as many times as you like, you can specify an
175 asterisk ``*`` wildcard. E.g., ``*/*.cabal`` matches all ``.cabal``
176 files in all immediate subdirectories. Like in glob(7), asterisks do
177 not match hidden files unless there is an explicit period, e.g.,
178 ``.*/foo.cabal`` will match ``.private/foo.cabal`` (but
179 ``*/foo.cabal`` will not).
181 - You can use braces to specify specific directories; e.g.,
182 ``{vendor,pkgs}/*.cabal`` matches all Cabal files in the ``vendor``
183 and ``pkgs`` subdirectories.
185 Formally, the format is described by the following BNF:
188 convert globbing grammar to proper ABNF_ syntax
192 RootedGlob ::= FilePathRoot Glob
193 FilePathRoot ::= {- empty -} # relative to cabal.project
195 | [a-zA-Z] ":" [/\\] # Windows root
196 | "~" # home directory
197 Glob ::= GlobPieces [/\\] Glob # Unix or Windows directory
198 | "..[**/\\]" GlobPieces # Recursive directory glob
200 | [/\\] # trailing slash
201 GlobPieces ::= GlobPiece *
202 GlobPiece ::= "*" # wildcard
203 | [^*{},/\\] * # literal string
204 | "\\" [*{},] # escaped reserved character
205 | "{" Glob "," ... "," Glob "}" # union (match any of these)
208 .. _pkg-consume-source:
210 Taking a dependency from a *source code* repository
211 ---------------------------------------------------
213 Since version 2.4, the ``source-repository-package`` stanza allows for
214 specifying packages in a remote version control system that cabal should
215 consider during package retrieval. This allows use of a package from a
216 remote version control system, rather than looking for that package in
219 Since version 3.4, cabal-install creates tarballs for each package coming from a
220 ``source-repository-package`` stanza (effectively applying cabal sdists to such
221 packages). It gathers the names of the packages from the appropriate ``.cabal``
222 file in the version control repository, and allows their use just like Hackage
223 or locally defined packages.
225 There is no command line variant of this stanza.
227 .. code-block:: cabal
231 source-repository-package
233 location: https://github.com/hvr/HsYAML.git
234 tag: e70cf0c171c9a586b62b3f75d72f1591e4e6aaa1
236 source-repository-package
238 location: https://github.com/well-typed/cborg
239 tag: 3d274c14ca3077c3a081ba7ad57c5182da65c8c1
242 source-repository-package
244 location: https://github.com/haskell/network.git
245 tag: e76fdc753e660dfa615af6c8b6a2ad9ddf6afe70
246 post-checkout-command: autoreconf -i
248 .. _source-repository-package-fields:
250 The :ref:`VCS fields<vcs-fields>` of ``source-repository-package`` are:
253 data SourceRepositoryPackage f = SourceRepositoryPackage
254 { srpType :: !RepoType
255 , srpLocation :: !String
256 , srpTag :: !(Maybe String)
257 , srpBranch :: !(Maybe String)
258 , srpSubdir :: !(f FilePath)
259 , srpCommand :: ![String]
262 .. cfg-field:: type: VCS kind
264 This field is required.
266 .. cfg-field:: location: VCS location
268 This field is required.
270 .. cfg-field:: branch: VCS branch
272 This field is optional.
274 .. cfg-field:: tag: VCS tag
276 This field is optional.
278 .. cfg-field:: subdir: VCS subdirectory list
280 Look in one or more subdirectories of the repository for cabal files, rather
281 than the root. This field is optional.
283 .. cfg-field:: post-checkout-command: command
285 Run command in the checked out repository, prior sdisting.
287 Global configuration options
288 ----------------------------
290 The following top-level configuration options are not specific to any
291 package, and thus apply globally:
294 .. cfg-field:: verbose: nat
296 :synopsis: Build verbosity level.
300 Control the verbosity of ``cabal`` commands, valid values are from 0
303 The command line variant of this field is ``--verbose=2``; a short
304 form ``-v2`` is also supported.
306 .. cfg-field:: jobs: nat or $ncpus
307 -j[NUM], --jobs[=NUM], --jobs=$ncpus
308 :synopsis: Number of builds running in parallel.
312 Run *nat* jobs simultaneously when building. If ``$ncpus`` is
313 specified, run the number of jobs equal to the number of CPUs.
314 Package building is often quite parallel, so turning on parallelism
315 can speed up build times quite a bit!
317 The command line variant of this field is ``--jobs=2``; a short form
318 ``-j2`` is also supported; a bare ``--jobs`` or ``-j`` is equivalent
319 to ``--jobs=$ncpus``.
321 .. cfg-field:: semaphore: boolean
324 :synopsis: Use GHC's support for semaphore based parallelism.
328 This option instructs cabal to control parallelism by creating a new system semaphore,
329 whose number of tokens is specified by ``--jobs`` (or ``-j``).
330 This semaphore is passed to GHC, which allows it to use any leftover parallelism
331 that ``cabal-install`` is not using.
333 Requires ``ghc >= 9.8``.
335 The command line variant of this field is ``--semaphore``.
337 .. cfg-field:: keep-going: boolean
339 :synopsis: Try to continue building on failure.
343 If true, after a build failure, continue to build other unaffected
346 The command line variant of this field is ``--keep-going``.
348 .. option:: --builddir=DIR
350 Specifies the name of the directory where build products for
351 build will be stored; defaults to ``dist-newstyle``. If a
352 relative name is specified, this directory is resolved relative
353 to the root of the project (i.e., where the ``cabal.project``
356 This option can only be specified from the command line.
358 .. _cmdoption-project-dir:
359 .. option:: --project-dir=DIR
361 Specifies the path of the project directory. If a relative
362 :ref:`project-file<cmdoption-project-file>` path is also specified,
363 it will be resolved relative to this directory.
365 The project directory does not need to contain a ``cabal.project`` file.
367 This option can only be specified from the command line.
369 .. _cmdoption-project-file:
370 .. option:: --project-file=FILE
372 Specifies the path and name of the project file used to specify the
373 rest of the top-level configuration; defaults to ``cabal.project``.
374 This name not only specifies the name of the main project file,
375 but also the auxiliary project files ``cabal.project.freeze``
376 and ``cabal.project.local``; for example, if you specify
377 ``--project-file=my.project``, then the other files that will
378 be probed are ``my.project.freeze`` and ``my.project.local``.
380 If :ref:`project-dir<cmdoption-project-dir>` is not specified,
381 and the path is relative, we will
382 look for the file relative to the current working directory,
383 and then for the parent directory, until the project file is
384 found or we have hit the top of the user's home directory.
386 This option can only be specified from the command line.
388 .. option:: -z, --ignore-project
390 Ignores the local ``cabal.project`` file and uses the default
391 configuration with the local ``foo.cabal`` file. Note that
392 this flag will be ignored if either of the ``--project-dir`` or
393 ``--project-file`` flags are also set.
395 .. option:: --store-dir=DIR
397 Specifies the name of the directory of the global package store.
399 .. cfg-field:: package-dbs: package DB stack (comma separated)
400 --package-db=[clear, global, user, PATH]
401 :synopsis: PackageDB stack manipulation
404 By modifying ``package-dbs`` you can modify the default package environment
405 which ``cabal`` will see. The package databases you add using ``package-dbs``
406 will not be written into and only used as immutable package stores to initialise
407 the environment with additional packages that ``cabal`` can choose to use.
409 There are three package databases involved with most builds:
412 Compiler installation of rts, base, etc.
414 Nix-style local build cache
416 Project-specific build directory
418 By default, the initial package stack prefix you will have with v2 commands is:
424 So the initial set of packages which is used by cabal is just the packages
425 installed in the global package database which comes with ``ghc``.
427 When cabal builds a package it will start populating the ``store`` package database,
428 whose packages will then be subsequently be available to be used in future runs.
434 When cabal builds your local projects, packages are registered into the local
435 in-place package database.
439 -- prefix ++ [store, in-place]
441 This flag manipulates the default prefix: ``[global]`` and accepts
442 paths, the special value ``global`` referring to the global package db, and
443 ``clear`` which removes all prior entries. For example,
447 -- prefix = [global, foo]
451 package-dbs: clear, foo
453 -- prefix = [bar, baz]
454 package-dbs: clear, foo, clear, bar, baz
456 The command line variant of this flag is ``--package-db=DB`` which can be
457 specified multiple times.
462 The following settings apply to commands that result in build actions
463 (``build``, ``run``, ``repl``, ``test``...), and control which phases of the
466 .. option:: --dry-run
468 Do not download, build, or install anything, only print what would happen.
470 .. option:: --only-configure
472 Instead of performing a full build just run the configure step.
473 Only accepted by the ``build`` command.
475 .. option:: --only-download
477 Do not build anything, only fetch the packages.
479 .. option:: --only-dependencies
481 Install only the dependencies necessary to build the given packages.
482 Not accepted by the ``repl`` command.
484 Solver configuration options
485 ----------------------------
487 The following settings control the behavior of the dependency solver:
489 .. cfg-field:: constraints: CONSTRAINT (comma separated list)
490 -c CONSTRAINT or -cCONSTRAINT, --constraint=CONSTRAINT
491 --constraint="pkg >= 2.0", -c "pkg >= 2.0"
492 :synopsis: Extra dependencies constraints.
494 Add extra constraints to the version bounds, flag settings,
495 and other properties a solver can pick for a
496 package. For example:
500 constraints: bar == 2.1
502 A package can be specified multiple times in ``constraints``, in
503 which case the specified constraints are intersected. This is
504 useful, since the syntax does not allow you to specify multiple
505 constraints at once. For example, to specify both version bounds and
506 flag assignments, you would write:
514 This is equivalent to writing constraints and :cfg-field:`flags` separately:
518 constraints: bar == 2.1
522 Valid constraints take the same form as for the
523 :option:`runhaskell Setup.hs configure --constraint`
526 .. cfg-field:: preferences: CONSTRAINT (comma separated list)
527 --preference=CONSTRAINT
528 --preference="pkg >= 2.0"
529 :synopsis: Preferred dependency versions.
531 Like :cfg-field:`constraints`, but the solver will attempt to satisfy
532 these preferences on a best-effort basis. The resulting install is locally
533 optimal with respect to preferences; specifically, no single package
534 could be replaced with a more preferred version that still satisfies
535 the hard constraints.
537 Operationally, preferences can cause the solver to attempt certain
538 version choices of a package before others, which can improve
539 dependency solver runtime.
541 One way to use :cfg-field:`preferences` is to take a known working set of
542 constraints (e.g., via ``cabal freeze``) and record them as
543 preferences. In this case, the solver will first attempt to use this
544 configuration, and if this violates hard constraints, it will try to
545 find the minimal number of upgrades to satisfy the hard constraints
548 The command line variant of this field is
549 ``--preference="pkg >= 2.0"``; to specify multiple preferences, pass
550 the flag multiple times.
552 .. cfg-field:: allow-newer: none, all or list of scoped package names (space or comma separated)
553 --allow-newer, --allow-newer=[none,all,[scope:][^]pkg]
554 :synopsis: Lift dependencies upper bound constraints.
558 Allow the solver to pick more recent version of some packages than
559 would normally be permitted by the :pkg-field:`build-depends` bounds
560 of packages in the install plan. This option may be useful if the
561 dependency solver cannot otherwise find a valid install plan.
563 For example, to relax ``pkg``\ s :pkg-field:`build-depends` upper bound on
564 ``dep-pkg``, write a scoped package name of the form:
568 allow-newer: pkg:dep-pkg
570 If the scope shall be limited to specific releases of ``pkg``, the
575 allow-newer: pkg-1.2.3:dep-pkg, pkg-1.1.2:dep-pkg
577 can be used to limit the relaxation of dependencies on
578 ``dep-pkg`` by the ``pkg-1.2.3`` and ``pkg-1.1.2`` releases only.
580 The scoped syntax is recommended, as it is often only a single package
581 whose upper bound is misbehaving. In this case, the upper bounds of
582 other packages should still be respected; indeed, relaxing the bound
583 can break some packages which test the selected version of packages.
585 The syntax also allows to prefix the dependee package with a
586 modifier symbol to modify the scope/semantic of the relaxation
587 transformation in a additional ways. Currently only one modifier
588 symbol is defined, i.e. ``^`` (i.e. caret) which causes the
589 relaxation to be applied only to ``^>=`` operators and leave all other
590 version operators untouched.
592 However, in some situations (e.g., when attempting to build packages
593 on a new version of GHC), it is useful to disregard *all*
594 upper-bounds, with respect to a package or all packages. This can be
595 done by specifying just a package name, or using the keyword ``all``
596 to specify all packages:
600 -- Disregard upper bounds involving the dependencies on
601 -- packages bar, baz. For quux only, relax
602 -- 'quux ^>= ...'-style constraints only.
603 allow-newer: bar, baz, ^quux
605 -- Disregard all upper bounds when dependency solving
608 -- Disregard all `^>=`-style upper bounds when dependency solving
612 For consistency, there is also the explicit wildcard scope syntax
613 ``*`` (or its alphabetic synonym ``all``). Consequently, the
614 examples above are equivalent to the explicitly scoped variants:
618 allow-newer: all:bar, *:baz, *:^quux
624 allow-newer: all:^all
626 In order to ignore all bounds specified by a package ``pkg-1.2.3``
627 you can combine scoping with a right-hand-side wildcard like so
631 -- Disregard any upper bounds specified by pkg-1.2.3
632 allow-newer: pkg-1.2.3:*
634 -- Disregard only `^>=`-style upper bounds in pkg-1.2.3
635 allow-newer: pkg-1.2.3:^*
638 :cfg-field:`allow-newer` is often used in conjunction with a constraint
639 (in the :cfg-field:`constraints` field) forcing the usage of a specific,
640 newer version of a package.
642 The command line variant of this field is e.g. ``--allow-newer=bar``. A
643 bare ``--allow-newer`` is equivalent to ``--allow-newer=all``.
645 .. cfg-field:: allow-older: none, all, list of scoped package names (space or comma separated)
646 --allow-older, --allow-older=[none,all,[scope:][^]pkg]
647 :synopsis: Lift dependency lower bound constraints.
652 Like :cfg-field:`allow-newer`, but applied to lower bounds rather than
655 The command line variant of this field is ``--allow-older=all``. A
656 bare ``--allow-older`` is equivalent to ``--allow-older=all``.
659 .. cfg-field:: index-state: HEAD, unix-timestamp, ISO8601 UTC timestamp.
660 :synopsis: Use source package index state as it existed at a previous time.
665 This allows to change the source package index state the solver uses
666 to compute install-plans. This is particularly useful in
667 combination with freeze-files in order to also freeze the state the
668 package index was in at the time the install-plan was frozen.
672 -- UNIX timestamp format example
673 index-state: @1474739268
675 -- ISO8601 UTC timestamp format example
676 -- This format is used by 'cabal configure'
677 -- for storing `--index-state` values.
678 index-state: 2016-09-24T17:47:48Z
680 -- Specify different index-states per package repository
681 -- Supported since 3.4
683 , hackage.haskell.org 2020-05-06T22:33:27Z
684 , head.hackage 2020-04-29T04:11:05Z
686 .. cfg-field:: active-repositories: reponame1, reponame2
688 :synopsis: Specify active package repositories
693 Specifies which of the package repositories defined in the configuration
694 should be active. It's also useful for specifying the order and the way
695 active repositories are merged.
697 When searching for a certain version of a certain package name, the list of
698 active repositories is searched last-to-first.
700 For example, suppose hackage.haskell.org has versions 1.0 and 2.0 of
701 package X, and my-repository has version 2.0 of a similarly named package.
702 Then, with the following configuration:
706 -- Force my-repository to be the first repository considered
708 , hackage.haskell.org
711 version 2.0 of X will come from my-repository, and version 1.0 will come
712 from hackage.haskell.org.
714 If we want to make a repository the sole provider of certain packages, we
715 can put it last in the active repositories list, and add the :override
718 For example, if we modify the previous example like this:
723 , hackage.haskell.org
724 , my-repository:override
726 then version 1.0 of package X won't be found in any case, because X is
727 present in my-repository only in version 2.0, and the :override forbids
728 searching for other versions of X further up the list.
730 :override has no effect for package names that aren't present in the
731 overriding repository.
733 The special repository reference :rest stands for "all the other repositories"
734 and can be useful to avoid lengthy lists of repository names:
738 -- Force my-repository to be the first repository considered
739 active-repositories: :rest, my-repository
741 The special repository reference :none disables all repositories, effectively
742 putting cabal in "offline" mode:
746 active-repositories: :none
749 .. cfg-field:: reject-unconstrained-dependencies: all, none
750 --reject-unconstrained-dependencies=[all|none]
751 :synopsis: Restrict the solver to packages that have constraints on them.
756 By default, the dependency solver can include any package that it's
757 aware of in a build plan. If you wish to restrict the build plan to
758 a closed set of packages (e.g., from a freeze file), use this flag.
760 When set to `all`, all non-local packages that aren't goals must be
761 explicitly constrained. When set to `none`, the solver will
762 consider all packages.
765 Package configuration options
766 -----------------------------
768 Package options affect the building of specific packages. There are three
769 ways a package option can be specified:
771 - They can be specified at the top-level, in which case they apply only
772 to **local package**, or
774 - They can be specified inside a ``package`` stanza, in which case they
775 apply to the build of the package, whether or not it is local or
778 - They can be specified inside an ``package *`` stanza, in which case they
779 apply to all packages, local ones from the project and also external
783 For example, the following options specify that :cfg-field:`optimization`
784 should be turned off for all local packages, and that ``bytestring`` (possibly
785 an external dependency) should be built with ``-fno-state-hack``::
790 ghc-options: -fno-state-hack
792 ``ghc-options`` is not specifically described in this documentation, but is one
793 of many fields for configuring programs. They take the form
794 ``progname-options`` and ``progname-location``, and can be set for all local
795 packages in a ``program-options`` stanza or under a package stanza.
797 On the command line, these options are applied to all local packages.
798 There is no per-package command line interface.
800 Some flags were added by more recent versions of the Cabal library. This
801 means that they are NOT supported by packages which use Custom setup
802 scripts that require a version of the Cabal library older than when the
805 .. cfg-field:: flags: list of +flagname or -flagname (space separated)
806 -f FLAGS or -fFLAGS, --flags=FLAGS
807 --flags="+foo -bar", -ffoo, -f-bar
808 :synopsis: Enable or disable package flags.
810 Force all flags specified as ``+flagname`` to be true, and all flags
811 specified as ``-flagname`` to be false. For example, to enable the
812 flag ``foo`` and disable ``bar``, set:
818 Exactly one of + or - is required before each flag.
820 Flags are *per-package*, so it doesn't make much sense to specify
821 flags at the top-level, unless you happen to know that *all* of your
822 local packages support the same named flags. If a flag is not
823 supported by a package, it is ignored.
825 The command line variant of this flag is ``--flags``. There is also
826 a shortened form ``-ffoo -f-bar``.
828 A common mistake is to say ``cabal build -fhans``, where
829 ``hans`` is a flag for a transitive dependency that is not in the
830 local package; in this case, the flag will be silently ignored. If
831 ``haskell-tor`` is the package you want this flag to apply to, try
832 ``--constraint="haskell-tor +hans"`` instead. Flags can be specified as
833 package :cfg-field:`constraints`.
835 .. cfg-field:: with-compiler: PATH
836 -w PATH or -wPATH, --with-compiler=PATH
837 :synopsis: Path to compiler executable.
839 Specify the path to a particular compiler to be used. If not an
840 absolute path, it will be resolved according to the ``PATH``
841 environment. The type of the compiler (GHC, GHCJS, etc) must be
842 consistent with the setting of the :cfg-field:`compiler` field.
844 The most common use of this option is to specify a different version
845 of your compiler to be used; e.g., if you have ``ghc-7.8`` in your
846 path, you can specify ``with-compiler: ghc-7.8`` to use it.
848 This flag also sets the default value of :cfg-field:`with-hc-pkg`, using
849 the heuristic that it is named ``ghc-pkg-7.8`` (if your executable name
850 is suffixed with a version number), or is the executable named
851 ``ghc-pkg`` in the same directory as the ``ghc`` directory. If this
852 heuristic does not work, set :cfg-field:`with-hc-pkg` explicitly.
854 For inplace packages, ``cabal build`` maintains a separate build
855 directory for each version of GHC, so you can maintain multiple
856 build trees for different versions of GHC without clobbering each
859 It's not possible to set :cfg-field:`with-compiler` on a
862 The command line variant of this flag is
863 ``--with-compiler=ghc-7.8``; there is also a short version
866 .. cfg-field:: with-hc-pkg: PATH
868 :synopsis: Path to package tool.
870 Specify the path to the package tool, e.g., ``ghc-pkg``. This
871 package tool must be compatible with the compiler specified by
872 :cfg-field:`with-compiler` (generally speaking, it should be precisely
873 the tool that was distributed with the compiler). If this option is
874 omitted, the default value is determined from :cfg-field:`with-compiler`.
876 The command line variant of this flag is
877 ``--with-hc-pkg=ghc-pkg-7.8``.
879 .. cfg-field:: optimization: nat
880 -O[n], --enable-optimization[=n]
881 --disable-optimization
882 :synopsis: Build with optimization.
886 Build with optimization. This is appropriate for production use,
887 taking more time to build faster libraries and programs.
889 The optional *nat* value is the optimisation level. Some compilers
890 support multiple optimisation levels. The range is 0 to 2. Level 0
891 disables optimization, level 1 is the default. Level 2 is higher
892 optimisation if the compiler supports it. Level 2 is likely to lead
893 to longer compile times and bigger generated code. If you are not
894 planning to run code, turning off optimization will lead to better
895 build times and less code to be rebuilt when a module changes.
897 When optimizations are enabled, Cabal passes ``-O2`` to the C compiler.
899 We also accept ``True`` (equivalent to 1) and ``False`` (equivalent
902 Note that as of GHC 8.0, GHC does not recompile when optimization
903 levels change (see :ghc-ticket:`10923`), so if
904 you change the optimization level for a local package you may need
905 to blow away your old build products in order to rebuild with the
906 new optimization level.
908 The command line variant of this flag is ``-O2`` (with ``-O1``
909 equivalent to ``-O``). There are also long-form variants
910 ``--enable-optimization`` and ``--disable-optimization``.
912 .. cfg-field:: configure-options: OPT (space separated list)
913 --configure-option=OPT
914 :synopsis: Options to pass to configure script.
916 A list of extra arguments to pass to the external ``./configure``
917 script, if one is used. This is only useful for packages which have
918 the ``Configure`` build type. See also the section on
919 :ref:`system-dependent parameters`.
921 The command line variant of this flag is ``--configure-option=arg``,
922 which can be specified multiple times to pass multiple options.
924 .. cfg-field:: compiler: ghc, ghcjs, jhc, lhc, uhc or haskell-suite
926 :synopsis: Compiler to build with.
930 Specify the compiler toolchain to be used. This is independent of
931 ``with-compiler``, because the choice of toolchain affects Cabal's
934 The command line variant of this flag is ``--compiler=ghc``.
936 It's not possible to set :cfg-field:`compiler` on a
939 .. cfg-field:: tests: boolean
942 :synopsis: Build tests.
946 Force test suites to be enabled. For most users this should not be
947 needed, as we always attempt to solve for test suite dependencies,
948 even when this value is ``False``; furthermore, test suites are
949 automatically enabled if they are requested as a built target.
951 The command line variant of this flag is ``--enable-tests`` and
954 .. cfg-field:: benchmarks: boolean
957 :synopsis: Build benchmarks.
961 Force benchmarks to be enabled. For most users this should not be
962 needed, as we always attempt to solve for benchmark dependencies,
963 even when this value is ``False``; furthermore, benchmarks are
964 automatically enabled if they are requested as a built target.
966 The command line variant of this flag is ``--enable-benchmarks`` and
967 ``--disable-benchmarks``.
969 .. _cmdoption-extra-prog-path:
970 .. cfg-field:: extra-prog-path: PATH (newline or comma separated list)
971 --extra-prog-path=PATH
972 :synopsis: Add directories to program search path.
975 A list of directories to search for extra required programs. Most
976 users should not need this, as programs like ``happy`` and ``alex``
977 will automatically be installed and added to the path. This can be
978 useful if a ``Custom`` setup script relies on an exotic extra
981 The command line variant of this flag is ``--extra-prog-path=PATH``,
982 which can be specified multiple times.
984 When specifying :ref:`--http-transport<cmdoption-http-transport>` from the
985 command line, only extra-prog-path from the command line are added to the
988 .. cfg-field:: run-tests: boolean
990 :synopsis: Run package test suite during installation.
994 Run the package test suite during installation. This is useful for
995 saying "When this package is installed, check that the test suite
996 passes, terminating the rest of the build if it is broken."
1000 One deficiency: the :cfg-field:`run-tests` setting of a package is NOT
1001 recorded as part of the hash, so if you install something without
1002 :cfg-field:`run-tests` and then turn on ``run-tests``, we won't
1003 subsequently test the package. If this is causing you problems, give
1006 The command line variant of this flag is ``--run-tests``.
1011 .. cfg-field:: debug-info: integer
1012 --enable-debug-info[=n]
1013 --disable-debug-info
1014 :synopsis: Build with debug info enabled.
1019 If the compiler (e.g., GHC 7.10 and later) supports outputting OS
1020 native debug info (e.g., DWARF), setting ``debug-info: True`` will
1021 instruct it to do so. See the GHC wiki page on :ghc-wiki:`DWARF`
1022 for more information about this feature.
1024 (This field also accepts numeric syntax, but until GHC 8.2 this didn't
1027 The command line variant of this flag is ``--enable-debug-info`` and
1028 ``--disable-debug-info``.
1030 .. cfg-field:: split-sections: boolean
1031 --enable-split-sections
1032 --disable-split-sections
1033 :synopsis: Use GHC's split sections feature.
1038 Use the GHC ``-split-sections`` feature when building the library. This
1039 reduces the final size of the executables that use the library by
1040 allowing them to link with only the bits that they use rather than
1041 the entire library. The downside is that building the library takes
1042 longer and uses a bit more memory.
1044 This feature is supported by GHC 8.0 and later.
1046 The command line variant of this flag is ``--enable-split-sections`` and
1047 ``--disable-split-sections``.
1049 .. cfg-field:: split-objs: boolean
1051 --disable-split-objs
1052 :synopsis: Use GHC's split objects feature.
1056 Use the GHC ``-split-objs`` feature when building the library. This
1057 reduces the final size of the executables that use the library by
1058 allowing them to link with only the bits that they use rather than
1059 the entire library. The downside is that building the library takes
1060 longer and uses considerably more memory.
1062 It is generally recommend that you use ``split-sections`` instead
1063 of ``split-objs`` where possible.
1065 The command line variant of this flag is ``--enable-split-objs`` and
1066 ``--disable-split-objs``.
1068 .. cfg-field:: executable-stripping: boolean
1069 --enable-executable-stripping
1070 --disable-executable-stripping
1071 :synopsis: Strip installed programs.
1075 When installing binary executable programs, run the ``strip``
1076 program on the binary. This can considerably reduce the size of the
1077 executable binary file. It does this by removing debugging
1078 information and symbols.
1080 Not all Haskell implementations generate native binaries. For such
1081 implementations this option has no effect.
1083 If ``debug-info`` is set explicitly then ``executable-stripping`` is set
1084 to ``False`` as otherwise all the debug symbols will be stripped.
1086 The command line variant of this flag is
1087 ``--enable-executable-stripping`` and
1088 ``--disable-executable-stripping``.
1090 .. cfg-field:: library-stripping: boolean
1091 --enable-library-stripping
1092 --disable-library-stripping
1093 :synopsis: Strip installed libraries.
1096 When installing binary libraries, run the ``strip`` program on the
1097 binary, saving space on the file system. See also
1098 ``executable-stripping``.
1100 If ``debug-info`` is set explicitly then ``library-stripping`` is set
1101 to ``False`` as otherwise all the debug symbols will be stripped.
1103 The command line variant of this flag is
1104 ``--enable-library-stripping`` and ``--disable-library-stripping``.
1109 .. cfg-field:: program-prefix: PREFIX
1110 --program-prefix=PREFIX
1111 :synopsis: Prepend prefix to program names.
1113 :strike:`Prepend *prefix* to installed program names.` (Currently
1114 implemented in a silly and not useful way. If you need this to work
1117 *prefix* may contain the following path variables: ``$pkgid``,
1118 ``$pkg``, ``$version``, ``$compiler``, ``$os``, ``$arch``, ``$abi``,
1121 The command line variant of this flag is ``--program-prefix=foo-``.
1123 .. cfg-field:: program-suffix: SUFFIX
1124 --program-suffix=SUFFIX
1125 :synopsis: Append refix to program names.
1127 :strike:`Append *suffix* to installed program names.` (Currently
1128 implemented in a silly and not useful way. If you need this to work
1131 The most obvious use for this is to append the program's version
1132 number to make it possible to install several versions of a program
1133 at once: ``program-suffix: $version``.
1135 *suffix* may contain the following path variables: ``$pkgid``,
1136 ``$pkg``, ``$version``, ``$compiler``, ``$os``, ``$arch``, ``$abi``,
1139 The command line variant of this flag is
1140 ``--program-suffix='$version'``.
1142 Dynamic linking options
1143 ^^^^^^^^^^^^^^^^^^^^^^^
1145 .. cfg-field:: shared: boolean
1148 :synopsis: Build shared library.
1152 Build shared library. This implies a separate compiler run to
1153 generate position independent code as required on most platforms.
1155 The command line variant of this flag is ``--enable-shared`` and
1156 ``--disable-shared``.
1158 .. cfg-field:: executable-dynamic: boolean
1159 --enable-executable-dynamic
1160 --disable-executable-dynamic
1161 :synopsis: Link executables dynamically.
1165 Link executables dynamically. The executable's library dependencies
1166 should be built as shared objects. This implies ``shared: True``
1167 unless ``shared: False`` is explicitly specified.
1169 The command line variant of this flag is
1170 ``--enable-executable-dynamic`` and
1171 ``--disable-executable-dynamic``.
1173 .. cfg-field:: library-for-ghci: boolean
1174 --enable-library-for-ghci
1175 --disable-library-for-ghci
1176 :synopsis: Build libraries suitable for use with GHCi.
1180 Build libraries suitable for use with GHCi. This involves an extra
1181 linking step after the build.
1183 Not all platforms support GHCi and indeed on some platforms, trying
1184 to build GHCi libs fails. In such cases, consider setting
1185 ``library-for-ghci: False``.
1187 The command line variant of this flag is
1188 ``--enable-library-for-ghci`` and ``--disable-library-for-ghci``.
1190 .. cfg-field:: relocatable:
1192 :synopsis: Build relocatable package.
1197 :strike:`Build a package which is relocatable.` (TODO: It is not
1198 clear what this actually does, or if it works at all.)
1200 The command line variant of this flag is ``--relocatable``.
1202 Static linking options
1203 ^^^^^^^^^^^^^^^^^^^^^^
1205 .. cfg-field:: static: boolean
1208 :synopsis: Build static library.
1213 Roll this and all dependent libraries into a combined ``.a`` archive.
1214 This uses GHCs ``-staticlib`` flag, which is available for iOS and with
1215 GHC 8.4 and later for other platforms as well.
1217 .. cfg-field:: executable-static: boolean
1218 --enable-executable-static
1219 --disable-executable-static
1220 :synopsis: Build fully static executables.
1225 Build fully static executables.
1226 This links all dependent libraries into executables statically,
1228 This passes ``-static`` and ``-optl=-static`` to GHC.
1230 Foreign function interface options
1231 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1233 .. cfg-field:: extra-include-dirs: directories (comma or newline separated list)
1234 --extra-include-dirs=DIR
1235 :synopsis: Adds C header search path.
1237 An extra directory to search for C header files. You can use this
1238 flag multiple times to get a list of directories.
1240 You might need to use this flag if you have standard system header
1241 files in a non-standard location that is not mentioned in the
1242 package's ``.cabal`` file. Using this option has the same affect as
1243 appending the directory *dir* to the :pkg-field:`include-dirs` field in each
1244 library and executable in the package's ``.cabal`` file. The
1245 advantage of course is that you do not have to modify the package at
1246 all. These extra directories will be used while building the package
1247 and for libraries it is also saved in the package registration
1248 information and used when compiling modules that use the library.
1250 The command line variant of this flag is
1251 ``--extra-include-dirs=DIR``, which can be specified multiple times.
1253 .. cfg-field:: extra-lib-dirs: directories (comma or newline separated list)
1254 --extra-lib-dirs=DIR
1255 :synopsis: Adds library search directory.
1257 An extra directory to search for system libraries files.
1259 The command line variant of this flag is ``--extra-lib-dirs=DIR``,
1260 which can be specified multiple times.
1262 .. cfg-field:: extra-framework-dirs: directories (comma or newline separated list)
1263 --extra-framework-dirs=DIR
1264 :synopsis: Adds framework search directory (OS X only).
1266 An extra directory to search for frameworks (OS X only).
1268 You might need to use this flag if you have standard system
1269 libraries in a non-standard location that is not mentioned in the
1270 package's ``.cabal`` file. Using this option has the same affect as
1271 appending the directory *dir* to the :cfg-field:`extra-lib-dirs` field in
1272 each library and executable in the package's ``.cabal`` file. The
1273 advantage of course is that you do not have to modify the package at
1274 all. These extra directories will be used while building the package
1275 and for libraries it is also saved in the package registration
1276 information and used when compiling modules that use the library.
1278 The command line variant of this flag is
1279 ``--extra-framework-dirs=DIR``, which can be specified multiple
1285 .. cfg-field:: profiling: boolean
1288 :synopsis: Enable profiling builds.
1293 Build libraries and executables with profiling enabled (for
1294 compilers that support profiling as a separate mode). It is only
1295 necessary to specify :cfg-field:`profiling` for the specific package you
1296 want to profile; ``cabal build`` will ensure that all of its
1297 transitive dependencies are built with profiling enabled.
1299 To enable profiling for only libraries or executables, see
1300 :cfg-field:`library-profiling` and :cfg-field:`executable-profiling`.
1302 For useful profiling, it can be important to control precisely what
1303 cost centers are allocated; see :cfg-field:`profiling-detail`.
1305 The command line variant of this flag is ``--enable-profiling`` and
1306 ``--disable-profiling``.
1308 .. cfg-field:: profiling-detail: level
1309 --profiling-detail=level
1310 :synopsis: Profiling detail level.
1313 Some compilers that support profiling, notably GHC, can allocate
1314 costs to different parts of the program and there are different
1315 levels of granularity or detail with which this can be done. In
1316 particular for GHC this concept is called "cost centers", and GHC
1317 can automatically add cost centers, and can do so in different ways.
1319 This flag covers both libraries and executables, but can be
1320 overridden by the ``library-profiling-detail`` field.
1322 Currently this setting is ignored for compilers other than GHC. The
1323 levels that cabal currently supports are:
1326 For GHC this uses ``exported-functions`` for libraries and
1327 ``toplevel-functions`` for executables.
1329 No costs will be assigned to any code within this component.
1331 Costs will be assigned at the granularity of all top level
1332 functions exported from each module. In GHC, this
1333 is for non-inline functions. Corresponds to ``-fprof-auto-exported``.
1335 Costs will be assigned at the granularity of all top level
1336 functions in each module, whether they are exported from the
1337 module or not. In GHC specifically, this is for non-inline
1338 functions. Corresponds to ``-fprof-auto-top``.
1340 Costs will be assigned at the granularity of all functions in
1341 each module, whether top level or local. In GHC specifically,
1342 this is for non-inline toplevel or where-bound functions or
1343 values. Corresponds to ``-fprof-auto``.
1345 Like top-level but costs will be assigned to top level definitions after
1346 optimization. This lowers profiling overhead massively while giving similar
1347 levels of detail as toplevle-functions. However it means functions introduced
1348 by GHC during optimization will show up in profiles as well.
1349 Corresponds to ``-fprof-late`` if supported and ``-fprof-auto-top`` otherwise.
1351 Currently an alias for late-toplevel
1353 The command line variant of this flag is
1354 ``--profiling-detail=none``.
1356 .. cfg-field:: library-profiling-detail: level
1357 --library-profiling-detail=level
1358 :synopsis: Libraries profiling detail level.
1361 Like :cfg-field:`profiling-detail`, but applied only to libraries
1363 The command line variant of this flag is
1364 ``--library-profiling-detail=none``.
1366 .. cfg-field:: library-vanilla: boolean
1367 --enable-library-vanilla
1368 --disable-library-vanilla
1369 :synopsis: Build libraries without profiling.
1373 Build ordinary libraries (as opposed to profiling libraries).
1374 Mostly, you can set this to False to avoid building ordinary
1375 libraries when you are profiling.
1377 The command line variant of this flag is
1378 ``--enable-library-vanilla`` and ``--disable-library-vanilla``.
1380 .. cfg-field:: library-profiling: boolean
1381 --enable-library-profiling
1382 --disable-library-profiling
1383 :synopsis: Build libraries with profiling enabled.
1388 Build libraries with profiling enabled. You probably want
1389 to use :cfg-field:`profiling` instead.
1391 The command line variant of this flag is
1392 ``--enable-library-profiling`` and ``--disable-library-profiling``.
1394 .. cfg-field:: executable-profiling: boolean
1395 --enable-executable-profiling
1396 --disable-executable-profiling
1397 :synopsis: Build executables with profiling enabled.
1402 Build executables with profiling enabled. You probably want
1403 to use :cfg-field:`profiling` instead.
1405 The command line variant of this flag is
1406 ``--enable-executable-profiling`` and
1407 ``--disable-executable-profiling``.
1412 .. cfg-field:: coverage: boolean
1415 :synopsis: Build with coverage enabled.
1420 Build libraries and executables (including test suites) with Haskell
1421 Program Coverage enabled. Running the test suites will automatically
1422 generate coverage reports with HPC.
1424 The command line variant of this flag is ``--enable-coverage`` and
1425 ``--disable-coverage``.
1427 .. cfg-field:: library-coverage: boolean
1428 --enable-library-coverage
1429 --disable-library-coverage
1435 Deprecated, use :cfg-field:`coverage`.
1437 The command line variant of this flag is
1438 ``--enable-library-coverage`` and ``--disable-library-coverage``.
1443 .. cfg-field:: documentation: boolean
1444 --enable-documentation
1445 --disable-documentation
1446 :synopsis: Enable building of documentation.
1450 Enables building of Haddock documentation.
1451 Implied when calling ``cabal haddock``.
1453 The command line variant of this flag is ``--enable-documentation``
1454 and ``--disable-documentation``.
1456 ``documentation: true`` does not imply
1457 :cfg-field:`haddock-all`,
1458 :cfg-field:`haddock-benchmarks`,
1459 :cfg-field:`haddock-executables`,
1460 :cfg-field:`haddock-internal` or
1461 :cfg-field:`haddock-tests`.
1462 These need to be enabled separately if desired.
1464 .. cfg-field:: doc-index-file: templated path
1465 --doc-index-file=TEMPLATE
1466 :synopsis: Path to haddock templates.
1468 A central index of Haddock API documentation (template cannot use
1469 ``$pkgid``), which should be updated as documentation is built.
1471 The following commands are equivalent to ones that would be passed when
1472 running ``setup haddock``.
1474 .. cfg-field:: haddock-hoogle: boolean
1476 :synopsis: Generate Hoogle file.
1480 Generate a text file which can be converted by Hoogle_
1481 into a database for searching.
1482 This is equivalent to running ``haddock`` with the ``--hoogle`` flag.
1484 .. cfg-field:: haddock-html: boolean
1486 :synopsis: Build HTML documentation.
1490 Build HTML documentation.
1492 .. cfg-field:: haddock-quickjump: boolean
1494 :synopsis: Generate Quickjump file.
1498 Generate an index for interactive documentation navigation.
1499 This is equivalent to running ``haddock`` with the ``--quickjump`` flag.
1501 .. cfg-field:: haddock-html-location: URL (templated path)
1502 --haddock-html-location=URL
1503 :synopsis: Location of HTML documentation for prerequisite packages.
1505 Specify a template for the location of HTML documentation for
1506 prerequisite packages. The substitutions are applied to the template
1507 to obtain a location for each package, which will be used by
1508 hyperlinks in the generated documentation. For example, the
1509 following command generates links pointing at Hackage pages:
1513 html-location: http://hackage.haskell.org/packages/archive/$pkg/latest/doc/html
1515 If passed on the command line,
1516 the argument may be quoted to prevent substitution by the shell.
1520 --html-location='http://hackage.haskell.org/packages/archive/$pkg/latest/doc/html'
1522 If this option is omitted, the location for each package is obtained
1523 using the package tool (e.g. ``ghc-pkg``).
1525 .. cfg-field:: haddock-executables: boolean
1526 --haddock-executables
1527 :synopsis: Generate documentation for executables.
1531 Run haddock on all executable programs.
1533 .. cfg-field:: haddock-tests: boolean
1535 :synopsis: Generate documentation for tests.
1539 Run haddock on all test suites.
1541 .. cfg-field:: haddock-benchmarks: boolean
1542 --haddock-benchmarks
1543 :synopsis: Generate documentation for benchmarks.
1547 Run haddock on all benchmarks.
1549 .. cfg-field:: haddock-internal: boolean
1551 :synopsis: Generate documentation for internal modules
1555 Build haddock documentation which includes unexposed modules and
1558 .. cfg-field:: haddock-all: boolean
1560 :synopsis: Generate documentation for everything
1564 Run haddock on all components.
1566 .. cfg-field:: haddock-css: PATH
1568 :synopsis: Location of Haddock CSS file.
1570 The CSS file that should be used to style the generated
1571 documentation (overriding haddock's default).
1573 .. cfg-field:: haddock-hyperlink-source: boolean
1574 --haddock-hyperlink-source
1575 :synopsis: Generate hyperlinked source code for documentation
1579 Generated hyperlinked source code using `HsColour`_, and have
1580 Haddock documentation link to it.
1581 This is equivalent to running ``haddock`` with the ``--hyperlinked-source`` flag.
1583 .. cfg-field:: haddock-hscolour-css: PATH
1584 --haddock-hscolour-css=PATH
1585 :synopsis: Location of CSS file for HsColour
1587 The CSS file that should be used to style the generated hyperlinked
1588 source code (from `HsColour`_).
1590 .. cfg-field:: haddock-contents-location: URL
1591 --haddock-contents-location=URL
1592 :synopsis: URL for contents page.
1594 A baked-in URL to be used as the location for the contents page.
1596 .. cfg-field:: haddock-keep-temp-files: boolean
1597 :synopsis: Keep temporary Haddock files.
1599 Keep temporary files.
1601 There is no command line variant of this flag.
1603 .. cfg-field:: haddock-output-dir: DIR
1604 --haddock-output-dir=DIR
1605 :synopsis: Generate haddock documentation into this directory.
1607 Generate haddock documentation into this directory instead of the default
1608 location next to other build products.
1610 This flag is provided as a technology preview and is subject to change in the
1613 .. cfg-field:: open: boolean
1615 :synopsis: Open generated documentation in-browser.
1617 When generating HTML documentation, attempt to open it in a browser
1618 when complete. This will use ``xdg-open`` on Linux and BSD systems,
1619 ``open`` on macOS, and ``start`` on Windows.
1621 Advanced global configuration options
1622 -------------------------------------
1624 .. cfg-field:: write-ghc-environment-files: always, never, or ghc8.4.4+
1625 --write-ghc-environment-files=always\|never\|ghc8.4.4+
1626 :synopsis: Whether a ``.ghc.environment`` should be created after a successful build.
1630 Whether a `GHC package environment file <https://downloads.haskell.org/~ghc/master/users-guide/packages.html#package-environments>`_
1631 should be created after a successful build.
1633 Since Cabal 3.0, defaults to ``never``. Before that, defaulted to
1634 creating them only when compiling with GHC 8.4.4 and older (GHC
1635 8.4.4 `is the first version
1636 <https://gitlab.haskell.org/ghc/ghc/-/issues/13753>`_ that supports
1637 the ``-package-env -`` option that allows ignoring the package
1640 .. cfg-field:: build-info: True, False
1642 --disable-build-info
1643 :synopsis: Whether build information for each individual component should be
1644 written in a machine readable format.
1648 Enable generation of build information for Cabal components. Contains very
1649 detailed information on how to build an individual component, such as
1650 compiler version, modules of a component and how to compile the component.
1652 The output format is in json, and the exact location can be discovered from
1653 ``plan.json``, where it is identified by ``build-info`` within the items in
1654 the ``install-plan``.
1655 Note, that this field in ``plan.json`` can be ``null``, if and only if
1656 ``build-type: Custom`` is set, and the ``Cabal`` version is too
1657 old (i.e. ``< 3.7``).
1658 If the field is missing entirely, the component is not a local one, thus,
1659 no ``build-info`` exists for that particular component within the
1663 The format and fields of the generated build information is currently experimental,
1664 in the future we might add or remove fields, depending on the needs of other tooling.
1666 .. _cmdoption-http-transport:
1667 .. cfg-field:: http-transport: curl, wget, powershell, or plain-http
1668 --http-transport=transport
1669 :synopsis: Transport to use with http(s) requests.
1673 Set a transport to be used when making http(s) requests.
1675 The command line variant of this field is ``--http-transport=curl``.
1677 If the project configuration imports remote urls, the user can only specify
1678 the http-transport option from the command line.
1680 When specifying the http-transport from the command line, the program
1681 search path can only be influenced using :ref:`--extra-prog-path<cmdoption-extra-prog-path>`.
1683 .. cfg-field:: ignore-expiry: boolean
1685 :synopsis: Ignore Hackage expiration dates.
1689 If ``True``, we will ignore expiry dates on metadata from Hackage.
1691 In general, you should not set this to ``True`` as it will leave you
1692 vulnerable to stale cache attacks. However, it may be temporarily
1693 useful if the main Hackage server is down, and we need to rely on
1694 mirrors which have not been updated for longer than the expiry
1695 period on the timestamp.
1697 The command line variant of this field is ``--ignore-expiry``.
1699 .. cfg-field:: remote-repo-cache: directory
1700 --remote-repo-cache=DIR
1701 :synopsis: Location of packages cache.
1703 :default: ``~/.cabal/packages``
1705 The location where packages downloaded from remote repositories will be
1708 The command line variant of this flag is
1709 ``--remote-repo-cache=DIR``.
1711 .. cfg-field:: logs-dir: directory
1713 :synopsis: Directory to store build logs.
1715 :default: ``~/.cabal/logs``
1717 :strike:`The location where build logs for packages are stored.`
1718 Not implemented yet.
1720 The command line variant of this flag is ``--logs-dir=DIR``.
1722 .. cfg-field:: build-summary: template filepath
1723 --build-summary=TEMPLATE
1724 :synopsis: Build summaries location.
1726 :default: ``~/.cabal/logs/build.log``
1728 :strike:`The file to save build summaries.` Not implemented yet.
1730 Valid variables which can be used in the path are ``$pkgid``,
1731 ``$compiler``, ``$os`` and ``$arch``.
1733 The command line variant of this flag is
1734 ``--build-summary=TEMPLATE``.
1736 Undocumented fields: ``root-cmd``, ``symlink-bindir``, ``build-log``,
1737 ``remote-build-reporting``, ``report-planned-failure``, ``offline``.
1739 Advanced solver options
1740 ^^^^^^^^^^^^^^^^^^^^^^^
1742 Most users generally won't need these.
1744 .. cfg-field:: solver: SOLVER
1746 :synopsis: Which solver to use.
1748 This field is reserved to allow the specification of alternative
1749 dependency solvers. At the moment, the only accepted option is
1752 The command line variant of this field is ``--solver=modular``.
1754 .. cfg-field:: max-backjumps: nat
1756 :synopsis: Maximum number of solver backjumps.
1760 Maximum number of backjumps (backtracking multiple steps) allowed
1761 while solving. Set -1 to allow unlimited backtracking, and 0 to
1762 disable backtracking completely.
1764 The command line variant of this field is ``--max-backjumps=4000``.
1766 .. cfg-field:: reorder-goals: boolean
1769 :synopsis: Allow solver to reorder goals.
1773 When enabled, the solver will reorder goals according to certain
1774 heuristics. Slows things down on average, but may make backtracking
1775 faster for some packages. It's unlikely to help for small projects,
1776 but for big install plans it may help you find a plan when otherwise
1777 this is not possible. See :issue:`1780` for more commentary.
1779 The command line variant of this field is ``--(no-)reorder-goals``.
1781 .. cfg-field:: count-conflicts: boolean
1783 --no-count-conflicts
1784 :synopsis: Solver prefers versions with less conflicts.
1788 Try to speed up solving by preferring goals that are involved in a
1791 The command line variant of this field is
1792 ``--(no-)count-conflicts``.
1794 .. cfg-field:: fine-grained-conflicts: boolean
1795 --fine-grained-conflicts
1796 --no-fine-grained-conflicts
1797 :synopsis: Skip a version of a package if it does not resolve any conflicts
1798 encountered in the last version (solver optimization).
1802 When enabled, the solver will skip a version of a package if it does not
1803 resolve any of the conflicts encountered in the last version of that
1804 package. For example, if ``foo-1.2`` depended on ``bar``, and the solver
1805 couldn't find consistent versions for ``bar``'s dependencies, then the
1806 solver would skip ``foo-1.1`` if it also depended on ``bar``.
1808 The command line variant of this field is
1809 ``--(no-)fine-grained-conflicts``.
1811 .. cfg-field:: minimize-conflict-set: boolean
1812 --minimize-conflict-set
1813 --no-minimize-conflict-set
1814 :synopsis: Try to improve the solver error message when there is no
1819 When there is no solution, try to improve the solver error message
1820 by finding a minimal conflict set. This option may increase run
1821 time significantly, so it is off by default.
1823 The command line variant of this field is
1824 ``--(no-)minimize-conflict-set``.
1826 .. cfg-field:: strong-flags: boolean
1829 :synopsis: Do not defer flag choices when solving.
1833 Do not defer flag choices. (TODO: Better documentation.)
1835 The command line variant of this field is ``--(no-)strong-flags``.
1837 .. cfg-field:: allow-boot-library-installs: boolean
1838 --allow-boot-library-installs
1839 --no-allow-boot-library-installs
1840 :synopsis: Allow cabal to install or upgrade any package.
1844 By default, the dependency solver doesn't allow ``base``,
1845 ``ghc-prim``, ``integer-simple``, ``integer-gmp``, and
1846 ``template-haskell`` to be installed or upgraded. This flag
1847 removes the restriction.
1849 The command line variant of this field is
1850 ``--(no-)allow-boot-library-installs``.
1852 .. cfg-field:: cabal-lib-version: VERSION
1853 --cabal-lib-version=VERSION
1854 :synopsis: Version of Cabal library used to build package.
1856 This field selects the version of the Cabal library which should be
1857 used to build packages. This option is intended primarily for
1858 internal development use (e.g., forcing a package to build with a
1859 newer version of Cabal, to test a new version of Cabal.) (TODO:
1860 Specify its semantics more clearly.)
1862 The command line variant of this field is
1863 ``--cabal-lib-version=1.24.0.1``.
1865 .. cfg-field:: prefer-oldest: boolean
1868 :synopsis: Prefer the oldest versions of packages available.
1873 By default, when solver has a choice of multiple versions of the same
1874 package, it will first try to derive a build plan with the latest
1875 version. This flag switches the behaviour, making the solver
1876 to prefer the oldest packages available.
1878 The primary use case is to help users in establishing lower bounds
1879 of upstream dependencies.
1881 The command line variant of this field is ``--(no-)prefer-oldest``.
1883 .. include:: references.inc