update jinja2 per CVE-2024-34064
[cabal.git] / doc / cabal-project-description-file.rst
blobb76d383daccb1ae4b819852e4d83b01ec9d19fbd
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):
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. :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.
46     .. warning::
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
51       of a project.
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.
57       - :samp:`os({name})`
58       - :samp:`arch({name})`
59       - :samp:`impl({compiler})`
60       - ``true``
61       - ``false``
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:
68     if(os(darwin))
69       optimization: False
70     elif(os(freebsd))
71       packages: freebsd/*.cabal
72     else
73       optimization: True
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
90 project are:
92 .. cfg-field:: packages: package location list (space or comma separated)
93     :synopsis: Project packages.
95     :default: ``./*.cabal``
97     .. warning::
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
105     following forms:
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
121        and built.
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.
131     :default: empty
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
158 can be used::
160     packages: ./*.cabal
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
165 directory layout::
167     foo.cabal
168     foo-helper/     # local package
169     unix/           # vendored external package
171 All of these options support globs. ``cabal build`` has its own glob
172 format:
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:
187 .. todo::
188     convert globbing grammar to proper ABNF_ syntax
190 .. code-block:: abnf
192     RootedGlob    ::= FilePathRoot Glob
193     FilePathRoot    ::= {- empty -}        # relative to cabal.project
194                       | "/"                # Unix root
195                       | [a-zA-Z] ":" [/\\] # Windows root
196                       | "~"                # home directory
197     Glob ::= GlobPieces [/\\] Glob   # Unix or Windows directory
198            | "..[**/\\]"  GlobPieces # Recursive directory glob
199            | GlobPieces              # file
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
217 Hackage.
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
229     packages: .
231     source-repository-package
232         type: git
233         location: https://github.com/hvr/HsYAML.git
234         tag: e70cf0c171c9a586b62b3f75d72f1591e4e6aaa1
236     source-repository-package
237         type: git
238         location: https://github.com/well-typed/cborg
239         tag: 3d274c14ca3077c3a081ba7ad57c5182da65c8c1
240         subdir: cborg
242     source-repository-package
243         type: git
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]
260     }
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
295                -v[n], --verbose[=n]
296     :synopsis: Build verbosity level.
298     :default: 1
300     Control the verbosity of ``cabal`` commands, valid values are from 0
301     to 3.
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.
310     :default: 1
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
322                 --semaphore
323                 --no-semaphore
324     :synopsis: Use GHC's support for semaphore based parallelism.
326     :default: False
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
338                 --keep-going
339     :synopsis: Try to continue building on failure.
341     :default: False
343     If true, after a build failure, continue to build other unaffected
344     packages.
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``
354     file lives.)
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
402     :since: 3.7
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:
411     global
412         Compiler installation of rts, base, etc.
413     store
414         Nix-style local build cache
415     in-place
416         Project-specific build directory
418     By default, the initial package stack prefix you will have with v2 commands is:
420     ::
422         -- prefix = [global]
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.
430     ::
432         -- prefix ++ [store]
434     When cabal builds your local projects, packages are registered into the local
435     in-place package database.
437     ::
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,
445     ::
447         -- prefix = [global, foo]
448         package-dbs: foo
450         -- prefix = [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.
459 Phase control
460 -------------
462 The following settings apply to commands that result in build actions
463 (``build``, ``run``, ``repl``, ``test``...), and control which phases of the
464 build are executed.
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:
498     ::
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:
508     ::
510         constraints:
511             bar == 2.1
512           , bar +foo -baz
514     This is equivalent to writing constraints and :cfg-field:`flags` separately:
516     ::
518         constraints: bar == 2.1
519         package bar
520           flags: +foo -baz
522     Valid constraints take the same form as for the
523     :option:`runhaskell Setup.hs configure --constraint`
524     command line option.
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
546     again.
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.
556     :default: ``none``
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:
566     ::
568         allow-newer: pkg:dep-pkg
570     If the scope shall be limited to specific releases of ``pkg``, the
571     extended form as in
573     ::
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:
598     ::
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
606         allow-newer: all
608         -- Disregard all `^>=`-style upper bounds when dependency solving
609         allow-newer: ^all
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:
616     ::
618         allow-newer: all:bar, *:baz, *:^quux
620         allow-newer: *:*
621         allow-newer: all:all
623         allow-newer: *:^*
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
629     ::
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.
648     :since: 2.0
650     :default: ``none``
652     Like :cfg-field:`allow-newer`, but applied to lower bounds rather than
653     upper bounds.
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.
661    :since: 2.0
663    :default: ``HEAD``
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.
670    ::
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
682       index-state:
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
689     :since: 3.4
691     :default: ``:rest``
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:
704     ::
706       -- Force my-repository to be the first repository considered
707       active-repositories:
708         , hackage.haskell.org
709         , my-repository
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
716     modifier.
718     For example, if we modify the previous example like this:
720     ::
722       active-repositories:
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:
736     ::
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:
744     ::
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.
753    :default: none
754    :since: 2.6
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
776    external.
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
780    dependencies.
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``::
787     optimization: False
789     package bytestring
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
803 feature was added.
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:
814     ::
816         flags: +foo -bar
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
857     other.
859     It's not possible to set :cfg-field:`with-compiler` on a
860     per-package basis.
862     The command line variant of this flag is
863     ``--with-compiler=ghc-7.8``; there is also a short version
864     ``-w ghc-7.8``.
866 .. cfg-field:: with-hc-pkg: PATH
867                --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.
884     :default: ``1``
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
900     to 0).
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
925                --compiler=compiler
926     :synopsis: Compiler to build with.
928     :default: ``ghc``
930     Specify the compiler toolchain to be used. This is independent of
931     ``with-compiler``, because the choice of toolchain affects Cabal's
932     build logic.
934     The command line variant of this flag is ``--compiler=ghc``.
936     It's not possible to set :cfg-field:`compiler` on a
937     per-package basis.
939 .. cfg-field:: tests: boolean
940                --enable-tests
941                --disable-tests
942     :synopsis: Build tests.
944     :default: ``False``
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
952     ``--disable-tests``.
954 .. cfg-field:: benchmarks: boolean
955                --enable-benchmarks
956                --disable-benchmarks
957     :synopsis: Build benchmarks.
959     :default: ``False``
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.
973     :since: 1.18
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
979     program.
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
986     program search path.
988 .. cfg-field:: run-tests: boolean
989                --run-tests
990     :synopsis: Run package test suite during installation.
992     :default: ``False``
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."
998     .. warning::
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
1004       us a shout.
1006     The command line variant of this flag is ``--run-tests``.
1008 Object code options
1009 ^^^^^^^^^^^^^^^^^^^
1011 .. cfg-field:: debug-info: integer
1012                --enable-debug-info[=n]
1013                --disable-debug-info
1014     :synopsis: Build with debug info enabled.
1015     :since: 1.22
1017     :default: False
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
1025     do anything.)
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.
1034     :since: 2.2
1036     :default: False
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
1050                --enable-split-objs
1051                --disable-split-objs
1052     :synopsis: Use GHC's split objects feature.
1054     :default: False
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.
1073     :default: True
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.
1094     :since: 1.20
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``.
1106 Executable options
1107 ^^^^^^^^^^^^^^^^^^
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
1115     give us a shout.)
1117     *prefix* may contain the following path variables: ``$pkgid``,
1118     ``$pkg``, ``$version``, ``$compiler``, ``$os``, ``$arch``, ``$abi``,
1119     ``$abitag``
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
1129     give us a shout.)
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``,
1137     ``$abitag``
1139     The command line variant of this flag is
1140     ``--program-suffix='$version'``.
1142 Dynamic linking options
1143 ^^^^^^^^^^^^^^^^^^^^^^^
1145 .. cfg-field:: shared: boolean
1146                --enable-shared
1147                --disable-shared
1148     :synopsis: Build shared library.
1150     :default: False
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.
1163     :default: False
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.
1178     :default: True
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:
1191                --relocatable
1192     :synopsis: Build relocatable package.
1193     :since: 1.22
1195     :default: False
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
1206                --enable-static
1207                --disable-static
1208     :synopsis: Build static library.
1211     :default: False
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.
1223     :default: False
1225     Build fully static executables.
1226     This links all dependent libraries into executables statically,
1227     including libc.
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
1280     times.
1282 Profiling options
1283 ^^^^^^^^^^^^^^^^^
1285 .. cfg-field:: profiling: boolean
1286                --enable-profiling
1287                --disable-profiling
1288     :synopsis: Enable profiling builds.
1289     :since: 1.22
1291     :default: False
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.
1311     :since: 1.24
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:
1325     default
1326         For GHC this uses ``exported-functions`` for libraries and
1327         ``toplevel-functions`` for executables.
1328     none
1329         No costs will be assigned to any code within this component.
1330     exported-functions
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``.
1334     toplevel-functions
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``.
1339     all-functions
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``.
1344     late-toplevel
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.
1350     late
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.
1359     :since: 1.24
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.
1371     :default: True
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.
1384     :since: 1.22
1386     :default: False
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.
1398     :since: 1.22
1400     :default: False
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``.
1409 Coverage options
1410 ^^^^^^^^^^^^^^^^
1412 .. cfg-field:: coverage: boolean
1413                --enable-coverage
1414                --disable-coverage
1415     :synopsis: Build with coverage enabled.
1416     :since: 1.22
1418     :default: False
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
1430     :since: 1.22
1431     :deprecated:
1433     :default: False
1435     Deprecated, use :cfg-field:`coverage`.
1437     The command line variant of this flag is
1438     ``--enable-library-coverage`` and ``--disable-library-coverage``.
1440 Haddock options
1441 ^^^^^^^^^^^^^^^
1443 .. cfg-field:: documentation: boolean
1444                --enable-documentation
1445                --disable-documentation
1446     :synopsis: Enable building of documentation.
1448     :default: False
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
1475                --haddock-hoogle
1476     :synopsis: Generate Hoogle file.
1478     :default: False
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
1485                --haddock-html
1486     :synopsis: Build HTML documentation.
1488     :default: True
1490     Build HTML documentation.
1492 .. cfg-field:: haddock-quickjump: boolean
1493                --haddock-quickjump
1494     :synopsis: Generate Quickjump file.
1496     :default: False
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:
1511     ::
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.
1518     ::
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.
1529     :default: False
1531     Run haddock on all executable programs.
1533 .. cfg-field:: haddock-tests: boolean
1534                --haddock-tests
1535     :synopsis: Generate documentation for tests.
1537     :default: False
1539     Run haddock on all test suites.
1541 .. cfg-field:: haddock-benchmarks: boolean
1542                --haddock-benchmarks
1543     :synopsis: Generate documentation for benchmarks.
1545     :default: False
1547     Run haddock on all benchmarks.
1549 .. cfg-field:: haddock-internal: boolean
1550                --haddock-internal
1551     :synopsis: Generate documentation for internal modules
1553     :default: False
1555     Build haddock documentation which includes unexposed modules and
1556     symbols.
1558 .. cfg-field:: haddock-all: boolean
1559                --haddock-all
1560     :synopsis: Generate documentation for everything
1562     :default: False
1564     Run haddock on all components.
1566 .. cfg-field:: haddock-css: PATH
1567                --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
1577     :default: False
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
1611     next releases.
1613 .. cfg-field:: open: boolean
1614                --open
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.
1628     :default: ``never``
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
1638     environment files).
1640 .. cfg-field:: build-info: True, False
1641                --enable-build-info
1642                --disable-build-info
1643     :synopsis: Whether build information for each individual component should be
1644                written in a machine readable format.
1646     :default: ``False``
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
1660     ``install-plan``.
1662     .. note::
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.
1671     :default: ``curl``
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
1684                --ignore-expiry
1685     :synopsis: Ignore Hackage expiration dates.
1687     :default: False
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
1706     cached.
1708     The command line variant of this flag is
1709     ``--remote-repo-cache=DIR``.
1711 .. cfg-field:: logs-dir: directory
1712                --logs-dir=DIR
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
1745                --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
1750     ``modular``.
1752     The command line variant of this field is ``--solver=modular``.
1754 .. cfg-field:: max-backjumps: nat
1755                --max-backjumps=N
1756     :synopsis: Maximum number of solver backjumps.
1758     :default: 4000
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
1767                --reorder-goals
1768                --no-reorder-goals
1769     :synopsis: Allow solver to reorder goals.
1771     :default: False
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
1782                --count-conflicts
1783                --no-count-conflicts
1784     :synopsis: Solver prefers versions with less conflicts.
1786     :default: True
1788     Try to speed up solving by preferring goals that are involved in a
1789     lot of conflicts.
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).
1800     :default: True
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
1815                solution.
1817     :default: False
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
1827                --strong-flags
1828                --no-strong-flags
1829     :synopsis: Do not defer flag choices when solving.
1831     :default: False
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.
1842     :default: False
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
1866                --prefer-oldest
1867                --no-prefer-oldest
1868     :synopsis: Prefer the oldest versions of packages available.
1869     :since:    3.10
1871     :default:  False
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