8 GHC provides the commands ``runhaskell`` and ``runghc`` (they are equivalent)
9 to allow you to run Haskell programs without first having to compile them
10 (scripts). The low-level Cabal interface is implemented using ``Setup.hs``
11 scripts. You should prefer using higher level interface provided by nix-style
12 builds. However, the documentation of the low level interface below may be helpful
13 to high level interface users as well, because it delves into internal details
14 common to both and omitted elsewhere.
18 $ runhaskell Setup.hs [command] [option...]
20 For the summary of the ``Setup.hs`` script's command syntax, run:
24 $ runhaskell Setup.hs --help
26 Building and installing a system package
27 ----------------------------------------
31 $ runhaskell Setup.hs configure --ghc
32 $ runhaskell Setup.hs build
33 $ runhaskell Setup.hs install
35 The first line readies the system to build the tool using GHC; for
36 example, it checks that GHC exists on the system. The second line
37 performs the actual building, while the last both copies the build
38 results to some permanent place and registers the package with GHC.
42 Global installing of packages is not recommended.
43 The :ref:`nix-style-builds` is the preferred way of building and installing
46 Creating a binary package
47 -------------------------
49 When creating binary packages (e.g. for Red Hat or Debian) one needs to
50 create a tarball that can be sent to another system for unpacking in the
55 $ runhaskell Setup.hs configure --prefix=/usr
56 $ runhaskell Setup.hs build
57 $ runhaskell Setup.hs copy --destdir=/tmp/mypkg
58 $ tar -czf mypkg.tar.gz /tmp/mypkg/
60 If the package contains a library, you need two additional steps:
64 $ runhaskell Setup.hs register --gen-script
65 $ runhaskell Setup.hs unregister --gen-script
67 This creates shell scripts ``register.sh`` and ``unregister.sh``, which
68 must also be sent to the target system. After unpacking there, the
69 package must be registered by running the ``register.sh`` script. The
70 ``unregister.sh`` script would be used in the uninstall procedure of the
71 package. Similar steps may be used for creating binary packages for
74 The following options are understood by all commands:
78 .. option:: --help, -h or -?
80 List the available options for the command.
82 .. option:: --verbose=n or -v n
84 Set the verbosity level (0-3). The normal level is 1; a missing *n*
87 There is also an extended version of this command which can be
88 used to fine-tune the verbosity of output. It takes the
89 form ``[silent|normal|verbose|debug]``\ *flags*, where *flags*
90 is a list of ``+`` flags which toggle various aspects of
91 output. At the moment, only ``+callsite`` and ``+callstack``
92 are supported, which respectively toggle call site and call
93 stack printing (these are only supported if Cabal
94 is built with a sufficiently recent GHC.)
96 The various commands and the additional options they support are
97 described below. In the simple build infrastructure, any other options
98 will be reported as errors.
102 runhaskell Setup.hs configure
103 -----------------------------
105 .. program:: runhaskell Setup.hs configure
107 Prepare to build the package. Typically, this step checks that the
108 target platform is capable of building the package, and discovers
109 platform-specific features that are needed during the build.
111 The user may also adjust the behaviour of later stages using the options
112 listed in the following subsections. In the simple build infrastructure,
113 the values supplied via these options are recorded in a private file
114 read by later stages.
116 If a user-supplied ``configure`` script is run (see the section on
117 :ref:`system-dependent parameters` or
118 on :ref:`more-complex-packages`), it is
119 passed the :option:`--with-hc-pkg`, :option:`--prefix`, :option:`--bindir`,
120 :option:`--libdir`, :option:`--dynlibdir`, :option:`--datadir`, :option:`--libexecdir` and
121 :option:`--sysconfdir` options. In addition the value of the
122 :option:`--with-compiler` option is passed in a :option:`--with-hc-pkg` option
123 and all options specified with :option:`--configure-option` are passed on.
126 `GNU autoconf places restrictions on paths, including the directory
127 that the package is built from.
128 <https://www.gnu.org/software/autoconf/manual/autoconf.html#File-System-Conventions>`_
129 The errors produced when this happens can be obscure; Cabal attempts to
130 detect and warn in this situation, but it is not perfect.
132 In Cabal 2.0, support for a single positional argument was added to
133 ``runhaskell Setup.hs configure`` This makes Cabal configure the specific component to
134 be configured. Specified names can be qualified with ``lib:`` or
135 ``exe:`` in case just a name is ambiguous (as would be the case for a
136 package named ``p`` which has a library and an executable named ``p``.)
137 This has the following effects:
139 - Subsequent invocations of ``cabal build``, ``register``, etc. operate only
140 on the configured component.
142 - Cabal requires all "internal" dependencies (e.g., an executable
143 depending on a library defined in the same package) must be found in
144 the set of databases via :option:`--package-db` (and related flags): these
145 dependencies are assumed to be up-to-date. A dependency can be
146 explicitly specified using :option:`--dependency` simply by giving the name
147 of the sublibrary; e.g., the dependency for a sublibrary
148 named ``foo`` is given as
149 ``--dependency=Lib:foo=foo-0.1-abc``.
151 - Only the dependencies needed for the requested component are
152 required. Similarly, when :option:`--exact-configuration` is specified,
153 it's only necessary to specify :option:`--dependency` for the component.
154 (As mentioned previously, you *must* specify internal dependencies as
157 - Internal ``build-tool-depends`` and ``build-tools`` dependencies are expected
158 to be in the ``PATH`` upon subsequent invocations of ``setup``.
160 Full details can be found in the `Componentized Cabal
161 proposal <https://github.com/ezyang/ghc-proposals/blob/master/proposals/0000-componentized-cabal.rst>`__.
163 Programs used for building
164 ^^^^^^^^^^^^^^^^^^^^^^^^^^
166 The following options govern the programs used to process the source
169 .. option:: -g, --ghc
174 Specify which Haskell implementation to use to build the package. At
175 most one of these flags may be given. If none is given, the
176 implementation under which the setup script was compiled or
179 .. option:: -w PATH or -wPATH, --with-compiler=PATH
181 Specify the path to a particular compiler. If given, this must match
182 the implementation selected above. The default is to search for the
183 usual name of the selected implementation.
185 This flag also sets the default value of the :option:`--with-hc-pkg`
186 option to the package tool for this compiler. Check the output of
187 ``runhaskell Setup.hs configure -v`` to ensure that it finds the right package
188 tool (or use :option:`--with-hc-pkg` explicitly).
190 .. option:: --with-hc-pkg=PATH
192 Specify the path to the package tool, e.g. ``ghc-pkg``. The package
193 tool must be compatible with the compiler specified by
194 :option:`--with-compiler`. If this option is omitted, the default value is
195 determined from the compiler selected.
197 .. option:: --with-PROG=PATH
199 Specify the path to the program *prog*. Any program known to Cabal
200 can be used in place of *prog*. It can either be a fully path or the
201 name of a program that can be found on the program search path. For
202 example: ``--with-ghc=ghc-6.6.1`` or
203 ``--with-cpphs=/usr/local/bin/cpphs``. The full list of accepted
204 programs is not enumerated in this user guide. Rather, run
205 ``cabal install --help`` to view the list.
207 .. option:: --PROG-options=OPTS
209 Specify additional options to the program *prog*. Any program known
210 to Cabal can be used in place of *prog*. For example:
211 ``--alex-options="--template=mytemplatedir/"``. The *options* is
212 split into program options based on spaces. Any options containing
213 embedded spaced need to be quoted, for example
214 ``--foo-options='--bar="C:\Program File\Bar"'``. As an alternative
215 that takes only one option at a time but avoids the need to quote,
216 use :option:`--PROG-option` instead.
218 .. option:: --PROG-option=OPT
220 Specify a single additional option to the program *prog*. For
221 passing an option that contains embedded spaces, such as a file name
222 with embedded spaces, using this rather than :option:`--PROG-options`
223 means you do not need an additional level of quoting. Of course if you
224 are using a command shell you may still need to quote, for example
225 ``--foo-options="--bar=C:\Program File\Bar"``.
227 All of the options passed with either :option:`--PROG-options`
228 or :option:`--PROG-option` are passed in the order they were
229 specified on the configure command line.
234 The following options govern the location of installed files from a
237 .. option:: --prefix=DIR
239 The root of the installation. For example for a global install you
240 might use ``/usr/local`` on a Unix system, or ``C:\Program Files``
241 on a Windows system. The other installation paths are usually
242 subdirectories of *prefix*, but they don't have to be.
244 In the simple build system, *dir* may contain the following path
245 variables: ``$pkgid``, ``$pkg``, ``$version``, ``$compiler``,
246 ``$os``, ``$arch``, ``$abi``, ``$abitag``
248 .. option:: --bindir=DIR
250 Executables that the user might invoke are installed here.
252 In the simple build system, *dir* may contain the following path
253 variables: ``$prefix``, ``$pkgid``, ``$pkg``, ``$version``,
254 ``$compiler``, ``$os``, ``$arch``, ``$abi``, ``$abitag``
256 .. option:: --libdir=DIR
258 Object-code libraries are installed here.
260 In the simple build system, *dir* may contain the following path
261 variables: ``$prefix``, ``$bindir``, ``$pkgid``, ``$pkg``,
262 ``$version``, ``$compiler``, ``$os``, ``$arch``, ``$abi``,
265 .. option:: --dynlibdir=DIR
267 Dynamic libraries are installed here.
269 By default, this is set to `$libdir/$abi`, which is usually not equal to
270 `$libdir/$libsubdir`.
272 In the simple build system, *dir* may contain the following path
273 variables: ``$prefix``, ``$bindir``, ``$libdir``, ``$pkgid``, ``$pkg``,
274 ``$version``, ``$compiler``, ``$os``, ``$arch``, ``$abi``,
277 .. option:: --libexecdir=DIR
279 Executables that are not expected to be invoked directly by the user
282 In the simple build system, *dir* may contain the following path
283 variables: ``$prefix``, ``$bindir``, ``$libdir``, ``$libsubdir``,
284 ``$pkgid``, ``$pkg``, ``$version``, ``$compiler``, ``$os``,
285 ``$arch``, ``$abi``, ``$abitag``
287 .. option:: --datadir=DIR
289 Architecture-independent data files are installed here.
291 In the simple build system, *dir* may contain the following path
292 variables: ``$prefix``, ``$bindir``, ``$libdir``, ``$libsubdir``,
293 ``$pkgid``, ``$pkg``, ``$version``, ``$compiler``, ``$os``,
294 ``$arch``, ``$abi``, ``$abitag``
296 .. option:: --sysconfdir=DIR
298 Installation directory for the configuration files.
300 In the simple build system, *dir* may contain the following path
301 variables: ``$prefix``, ``$bindir``, ``$libdir``, ``$libsubdir``,
302 ``$pkgid``, ``$pkg``, ``$version``, ``$compiler``, ``$os``,
303 ``$arch``, ``$abi``, ``$abitag``
305 In addition the simple build system supports the following installation
308 .. option:: --libsubdir=DIR
310 A subdirectory of *libdir* in which libraries are actually installed. For
311 example, in the simple build system on Unix, the default *libdir* is
312 ``/usr/local/lib``, and *libsubdir* contains the compiler ABI and package
314 e.g. ``x86_64-linux-ghc-8.0.2/mypkg-0.1.0-IxQNmCA7qrSEQNkoHSF7A``, so
315 libraries would be installed in
316 ``/usr/local/lib/x86_64-linux-ghc-8.0.2/mypkg-0.1.0-IxQNmCA7qrSEQNkoHSF7A/``.
318 *dir* may contain the following path variables: ``$pkgid``,
319 ``$pkg``, ``$version``, ``$compiler``, ``$os``, ``$arch``, ``$abi``,
322 .. option:: --libexecsubdir=DIR
324 A subdirectory of *libexecdir* in which private executables are
325 installed. For example, in the simple build system on Unix, the default
326 *libexecdir* is ``/usr/local/libexec``, and *libsubdir* is
327 ``x86_64-linux-ghc-8.0.2/mypkg-0.1.0``, so private executables would be
328 installed in ``/usr/local/libexec/x86_64-linux-ghc-8.0.2/mypkg-0.1.0/``
330 *dir* may contain the following path variables: ``$pkgid``,
331 ``$pkg``, ``$version``, ``$compiler``, ``$os``, ``$arch``, ``$abi``,
334 .. option:: --datasubdir=DIR
336 A subdirectory of *datadir* in which data files are actually
339 *dir* may contain the following path variables: ``$pkgid``,
340 ``$pkg``, ``$version``, ``$compiler``, ``$os``, ``$arch``, ``$abi``,
343 .. option:: --docdir=DIR
345 Documentation files are installed relative to this directory.
347 *dir* may contain the following path variables: ``$prefix``,
348 ``$bindir``, ``$libdir``, ``$libsubdir``, ``$datadir``,
349 ``$datasubdir``, ``$pkgid``, ``$pkg``, ``$version``, ``$compiler``,
350 ``$os``, ``$arch``, ``$abi``, ``$abitag``
352 .. option:: --htmldir=DIR
354 HTML documentation files are installed relative to this directory.
356 *dir* may contain the following path variables: ``$prefix``,
357 ``$bindir``, ``$libdir``, ``$libsubdir``, ``$datadir``,
358 ``$datasubdir``, ``$docdir``, ``$pkgid``, ``$pkg``, ``$version``,
359 ``$compiler``, ``$os``, ``$arch``, ``$abi``, ``$abitag``
361 .. option:: --program-prefix=PREFIX
363 Prepend *prefix* to installed program names.
365 *prefix* may contain the following path variables: ``$pkgid``,
366 ``$pkg``, ``$version``, ``$compiler``, ``$os``, ``$arch``, ``$abi``,
369 .. option:: --program-suffix=SUFFIX
371 Append *suffix* to installed program names. The most obvious use for
372 this is to append the program's version number to make it possible
373 to install several versions of a program at once:
374 ``--program-suffix='$version'``.
376 *suffix* may contain the following path variables: ``$pkgid``,
377 ``$pkg``, ``$version``, ``$compiler``, ``$os``, ``$arch``, ``$abi``,
380 Path variables in the simple build system
381 """""""""""""""""""""""""""""""""""""""""
383 For the simple build system, there are a number of variables that can be
384 used when specifying installation paths. The defaults are also specified
385 in terms of these variables. A number of the variables are actually for
386 other paths, like ``$prefix``. This allows paths to be specified
387 relative to each other rather than as absolute paths, which is important
388 for building relocatable packages (see :ref:`prefix independence`).
391 The path variable that stands for the root of the installation. For
392 an installation to be relocatable, all other installation paths must
393 be relative to the ``$prefix`` variable.
395 The path variable that expands to the path given by the :option:`--bindir`
396 configure option (or the default).
398 As above but for :option:`--libdir`
400 As above but for :option:`--libsubdir`
402 As above but for :option:`--dynlibdir`
404 As above but for :option:`--datadir`
406 As above but for :option:`--datasubdir`
408 As above but for :option:`--docdir`
410 The name and version of the package, e.g. ``mypkg-0.2``
412 The name of the package, e.g. ``mypkg``
414 The version of the package, e.g. ``0.2``
416 The compiler being used to build the package, e.g. ``ghc-6.6.1``
418 The operating system of the computer being used to build the
419 package, e.g. ``linux``, ``windows``, ``osx``, ``freebsd`` or
422 The architecture of the computer being used to build the package,
423 e.g. ``i386``, ``x86_64``, ``ppc`` or ``sparc``
425 An optional tag that a compiler can use for telling incompatible
426 ABI's on the same architecture apart. GHCJS encodes the underlying
427 GHC version in the ABI tag.
429 A shortcut for getting a path that completely identifies the
430 platform in terms of binary compatibility. Expands to the same value
431 as ``$arch-$os-compiler-$abitag`` if the compiler uses an abi tag,
432 ``$arch-$os-$compiler`` if it doesn't.
434 Paths in the simple build system
435 """"""""""""""""""""""""""""""""
437 For the simple build system, the following defaults apply:
439 .. list-table:: Default installation paths
444 * - :option:`--prefix` (global)
446 - ``%PROGRAMFILES%\Haskell``
447 * - :option:`--prefix` (per-user)
449 - ``%APPDATA%\cabal``
450 * - :option:`--bindir`
453 * - :option:`--libdir`
456 * - :option:`--libsubdir` (others)
457 - ``$pkgid/$compiler``
458 - ``$pkgid\$compiler``
459 * - :option:`--dynlibdir`
462 * - :option:`--libexecdir`
463 - ``$prefix/libexec``
465 * - :option:`--datadir` (executable)
468 * - :option:`--datadir` (library)
470 - ``%PROGRAMFILES%\Haskell``
471 * - :option:`--datasubdir`
474 * - :option:`--docdir`
475 - ``$datadir/doc/$pkgid``
476 - ``$prefix\doc\$pkgid``
477 * - :option:`--sysconfdir`
480 * - :option:`--htmldir`
483 * - :option:`--program-prefix`
486 * - :option:`--program-suffix`
490 .. _prefix independence:
495 On Windows it is possible to obtain the pathname of the running program.
496 This means that we can construct an installable executable package that
497 is independent of its absolute install location. The executable can find
498 its auxiliary files by finding its own path and knowing the location of
499 the other files relative to ``$bindir``. Prefix independence is
500 particularly useful: it means the user can choose the install location
501 (i.e. the value of ``$prefix``) at install-time, rather than having to
502 bake the path into the binary when it is built.
504 In order to achieve this, we require that for an executable on Windows,
505 all of ``$bindir``, ``$libdir``, ``$dynlibdir``, ``$datadir`` and ``$libexecdir`` begin
506 with ``$prefix``. If this is not the case then the compiled executable
507 will have baked-in all absolute paths.
509 The application need do nothing special to achieve prefix independence.
510 If it finds any files using ``getDataFileName`` and the :ref:`other functions
511 provided for the purpose <accessing-data-files>`,
512 the files will be accessed relative to the location of the current
515 A library cannot (currently) be prefix independent, because it will be
516 linked into an executable whose file system location bears no relation
517 to the library package.
519 .. _controlling flag assignments:
521 Controlling Flag Assignments
522 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
524 Flag assignments (see :ref:`resolution-of-conditions-and-flags`)
525 can be controlled with the following command line options.
527 .. option:: -f flagname or -f -flagname
529 Force the specified flag to ``true`` or ``false`` (if preceded with
530 a ``-``). Later specifications for the same flags will override
531 earlier, i.e., specifying ``-fdebug -f-debug`` is equivalent to
534 .. option:: --flags=flagspecs
536 Same as ``-f``, but allows specifying multiple flag assignments at
537 once. The parameter is a space-separated list of flag names (to
538 force a flag to ``true``), optionally preceded by a ``-`` (to force
539 a flag to ``false``). For example,
540 ``--flags="debug -feature1 feature2"`` is equivalent to
541 ``-fdebug -f-feature1 -ffeature2``.
546 .. option:: --enable-tests
548 Build the test suites defined in the package description file during
549 the ``build`` stage. Check for dependencies required by the test
550 suites. If the package is configured with this option, it will be
551 possible to run the test suites with the ``test`` command after the
554 .. option:: --disable-tests
556 (default) Do not build any test suites during the ``build`` stage.
557 Do not check for dependencies required only by the test suites. It
558 will not be possible to invoke the ``test`` command without
559 reconfiguring the package.
561 .. option:: --enable-coverage
563 Build libraries and executables (including test suites) with Haskell
564 Program Coverage enabled. Running the test suites will automatically
565 generate coverage reports with HPC.
567 .. option:: --disable-coverage
569 (default) Do not enable Haskell Program Coverage.
571 Miscellaneous options
572 ^^^^^^^^^^^^^^^^^^^^^
576 Does a per-user installation. This changes the `default installation
577 prefix <#paths-in-the-simple-build-system>`__. It also allow
578 dependencies to be satisfied by the user's package database, in
579 addition to the global database. This also implies a default of
580 ``--user`` for any subsequent ``install`` command, as packages
581 registered in the global database should not depend on packages
582 registered in a user's database.
586 (default) Does a global installation. In this case package
587 dependencies must be satisfied by the global package database. All
588 packages in the user's package database will be ignored. Typically
589 the final installation step will require administrative privileges.
591 .. option:: --package-db=DB
593 Allows package dependencies to be satisfied from this additional
594 package database *db* in addition to the global package database.
595 All packages in the user's package database will be ignored. The
596 interpretation of *db* is implementation-specific. Typically it will
597 be a file or directory. Not all implementations support arbitrary
600 This pushes an extra db onto the db stack. The :option:`--global` and
601 :option:`--user` mode switches add the respective [Global] and [Global,
602 User] dbs to the initial stack. There is a compiler-implementation
603 constraint that the global db must appear first in the stack, and if
604 the user one appears at all, it must appear immediately after the
607 To reset the stack, use ``--package-db=clear``.
609 .. option:: --ipid=IPID
611 Specifies the *installed package identifier* of the package to be
612 built; this identifier is passed on to GHC and serves as the basis
613 for linker symbols and the ``id`` field in a ``ghc-pkg``
614 registration. When a package has multiple components, the actual
615 component identifiers are derived off of this identifier. E.g., a
616 sublibrary ``foo`` from package ``p-0.1-abcd`` will get the
617 identifier ``p-0.1-abcd-foo``.
619 .. option:: --cid=CID
621 Specifies the *component identifier* of the component being built;
622 this is only valid if you are configuring a single component.
624 .. option:: -O[n], --enable-optimization[=n]
626 (default) Build with optimization flags (if available). This is
627 appropriate for production use, taking more time to build faster
628 libraries and programs.
630 The optional *n* value is the optimisation level. Some compilers
631 support multiple optimisation levels. The range is 0 to 2. Level 0
632 is equivalent to :option:`--disable-optimization`, level 1 is the
633 default if no *n* parameter is given. Level 2 is higher optimisation
634 if the compiler supports it. Level 2 is likely to lead to longer
635 compile times and bigger generated code.
637 When optimizations are enabled, Cabal passes ``-O2`` to the C compiler.
639 .. option:: --disable-optimization
641 Build without optimization. This is suited for development: building
642 will be quicker, but the resulting library or programs will be
645 .. option:: --enable-profiling
647 Build libraries and executables with profiling enabled (for
648 compilers that support profiling as a separate mode). For this to
649 work, all libraries used by this package must also have been built
650 with profiling support. For libraries this involves building an
651 additional instance of the library in addition to the normal
652 non-profiling instance. For executables it changes the single
653 executable to be built in profiling mode.
655 This flag covers both libraries and executables, but can be
656 overridden by the :option:`--enable-library-profiling` flag.
658 See also the :option:`--profiling-detail` flag below.
660 .. option:: --disable-profiling
662 (default) Do not enable profiling in generated libraries and
665 .. option:: -p, --enable-library-profiling
667 As with :option:`--enable-profiling` above, but it applies only for
668 libraries. So this generates an additional profiling instance of the
669 library in addition to the normal non-profiling instance.
671 The :option:`--enable-profiling` flag controls the profiling mode for both
672 libraries and executables, but if different modes are desired for
673 libraries versus executables then use :option:`--enable-library-profiling`
676 .. option:: --disable-library-profiling
678 (default) Do not generate an additional profiling version of the library.
680 .. option:: --profiling-detail=level
682 Some compilers that support profiling, notably GHC, can allocate
683 costs to different parts of the program and there are different
684 levels of granularity or detail with which this can be done. In
685 particular for GHC this concept is called "cost centers", and GHC
686 can automatically add cost centers, and can do so in different ways.
688 This flag covers both libraries and executables, but can be
689 overridden by the :option:`--library-profiling-detail` flag.
691 Currently this setting is ignored for compilers other than GHC. The
692 levels that cabal currently supports are:
695 For GHC this uses ``exported-functions`` for libraries and
696 ``toplevel-functions`` for executables.
698 No costs will be assigned to any code within this component.
700 Costs will be assigned at the granularity of all top level
701 functions exported from each module. In GHC specifically, this
702 is for non-inline functions.
704 Costs will be assigned at the granularity of all top level
705 functions in each module, whether they are exported from the
706 module or not. In GHC specifically, this is for non-inline
709 Costs will be assigned at the granularity of all functions in
710 each module, whether top level or local. In GHC specifically,
711 this is for non-inline toplevel or where-bound functions or
714 This flag is new in Cabal-1.24. Prior versions used the equivalent
717 .. option:: --library-profiling-detail=level
719 As with :option:`--profiling-detail` above, but it applies only for
722 The level for both libraries and executables is set by the
723 :option:`--profiling-detail` flag, but if different levels are desired
724 for libraries versus executables then use
725 :option:`--library-profiling-detail` as well.
727 .. option:: --enable-library-vanilla
729 (default) Build ordinary libraries (as opposed to profiling
730 libraries). This is independent of the
731 :option:`--enable-library-profiling` option. If you enable both, you get
734 .. option:: --disable-library-vanilla
736 Do not build ordinary libraries. This is useful in conjunction with
737 :option:`--enable-library-profiling` to build only profiling libraries,
738 rather than profiling and ordinary libraries.
740 .. option:: --enable-library-for-ghci
742 (default) Build libraries suitable for use with GHCi.
744 .. option:: --disable-library-for-ghci
746 Not all platforms support GHCi and indeed on some platforms, trying
747 to build GHCi libs fails. In such cases this flag can be used as a
750 .. option:: --enable-split-objs
752 Use the GHC ``-split-objs`` feature when building the library. This
753 reduces the final size of the executables that use the library by
754 allowing them to link with only the bits that they use rather than
755 the entire library. The downside is that building the library takes
756 longer and uses considerably more memory.
758 .. option:: --disable-split-objs
760 (default) Do not use the GHC ``-split-objs`` feature. This makes
761 building the library quicker but the final executables that use the
762 library will be larger.
764 .. option:: --enable-executable-stripping
766 (default) When installing binary executable programs, run the
767 ``strip`` program on the binary. This can considerably reduce the
768 size of the executable binary file. It does this by removing
769 debugging information and symbols. While such extra information is
770 useful for debugging C programs with traditional debuggers it is
771 rarely helpful for debugging binaries produced by Haskell compilers.
773 Not all Haskell implementations generate native binaries. For such
774 implementations this option has no effect.
776 .. option:: --disable-executable-stripping
778 Do not strip binary executables during installation. You might want
779 to use this option if you need to debug a program using gdb, for
780 example if you want to debug the C parts of a program containing
781 both Haskell and C code. Another reason is if your are building a
782 package for a system which has a policy of managing the stripping
783 itself (such as some Linux distributions).
785 .. option:: --enable-shared
787 Build shared library. This implies a separate compiler run to
788 generate position independent code as required on most platforms.
790 .. option:: --disable-shared
792 (default) Do not build shared library.
794 .. option:: --enable-static
796 Build a static library. This passes ``-staticlib`` to GHC (available
797 for iOS, and with 8.4 more platforms). The result is an archive ``.a``
798 containing all dependent haskell libraries combined.
800 .. option:: --disable-static
802 (default) Do not build a static library.
804 .. option:: --enable-executable-dynamic
806 Link dependent Haskell libraries into executables dynamically.
807 The executable's library dependencies must have been
808 built as shared objects. This implies :option:`--enable-shared`
809 unless :option:`--disable-shared` is explicitly specified.
811 .. option:: --disable-executable-dynamic
813 (default) Link dependent Haskell libraries into executables statically.
814 Non-Haskell (C) libraries are still linked dynamically, including libc,
815 so the result is still not a fully static executable
816 unless :option:`--enable-executable-static` is given.
818 .. option:: --enable-executable-static
820 Build fully static executables.
821 This links all dependent libraries into executables statically,
824 .. option:: --disable-executable-static
826 (default) Do not build fully static executables.
828 .. option:: --configure-option=str
830 An extra option to an external ``configure`` script, if one is used
831 (see the section on :ref:`system-dependent parameters`).
832 There can be several of these options.
834 .. option:: --extra-include-dirs=PATH
836 An extra directory to search for C header files. You can use this
837 flag multiple times to get a list of directories.
839 You might need to use this flag if you have standard system header
840 files in a non-standard location that is not mentioned in the
841 package's ``.cabal`` file. Using this option has the same effect as
842 appending the directory *dir* to the ``include-dirs`` field in each
843 library and executable in the package's ``.cabal`` file. The
844 advantage of course is that you do not have to modify the package at
845 all. These extra directories will be used while building the package
846 and for libraries it is also saved in the package registration
847 information and used when compiling modules that use the library.
849 .. option:: --extra-lib-dirs=PATH
851 An extra directory to search for system libraries files. You can use
852 this flag multiple times to get a list of directories.
854 .. option:: --extra-framework-dirs=PATH
856 An extra directory to search for frameworks (OS X only). You can use
857 this flag multiple times to get a list of directories.
859 You might need to use this flag if you have standard system
860 libraries in a non-standard location that is not mentioned in the
861 package's ``.cabal`` file. Using this option has the same affect as
862 appending the directory *dir* to the ``extra-lib-dirs`` field in
863 each library and executable in the package's ``.cabal`` file. The
864 advantage of course is that you do not have to modify the package at
865 all. These extra directories will be used while building the package
866 and for libraries it is also saved in the package registration
867 information and used when compiling modules that use the library.
869 .. option:: --dependency[=pkgname=IPID]
871 Specify that a particular dependency should used for a particular
872 package name. In particular, it declares that any reference to
873 *pkgname* in a :pkg-field:`build-depends` should be resolved to
876 .. option:: --promised-dependency[=pkgname=IPID]
878 Very much like ``--dependency`` but the package doesn't need to already
879 be installed. This is useful when attempting to start multiple component
880 sessions with cabal's multi-repl or projects such as Haskell Language Server.
882 Several checks which are enabled for ``--dependency``s are disabled for promised
883 dependencies, so prefer to use ``--dependency`` if you know that the dependency
884 is already installed.
886 .. option:: --exact-configuration
888 This changes Cabal to require every dependency be explicitly
889 specified using :option:`--dependency`, rather than use Cabal's (very
890 simple) dependency solver. This is useful for programmatic use of
891 Cabal's API, where you want to error if you didn't specify enough
892 :option:`--dependency` flags.
895 .. option:: -c CONSTRAINT or -cCONSTRAINT, --constraint=CONSTRAINT
897 Restrict solutions involving a package to given version
898 bounds, flag settings, and other properties.
900 The following considers only install plans where ``bar``,
901 if used, is restricted to version 2.1:
905 $ cabal install --constraint="bar == 2.1"
907 The following prevents ``bar`` from being used at all:
911 $ cabal install --constraint="bar <0"
913 Version bounds have the same syntax as :pkg-field:`build-depends`.
914 Yet extra pseudo version bounds are available here in addition:
916 - ``installed`` to fix a package to the already installed version.
917 Often useful for GHC-supplied packages in combination with :cfg-field:`allow-newer`,
918 e.g., ``--allow-newer='*:base' --constraint='base installed'``.
920 - ``source`` to fix a package to the local source copy.
924 # Require that a version of bar be used that is already installed in
925 # the global package database.
926 $ cabal install --constraint="bar installed"
928 # Require the local source copy of bar to be used.
929 # (Note: By default, if we have a local package we will
930 # automatically use it, so it will generally not be necessary to
932 $ cabal install --constraint="bar source"
934 Further, we can specify flag assignments with ``+FLAG`` and ``-FLAG``
935 or enable test (``test``) and benchmark (``bench``) suites:
939 # Require bar to be installed with the foo flag turned on and
940 # the baz flag turned off.
941 $ cabal install --constraint="bar +foo -baz"
943 # Require that bar have test suites and benchmarks enabled.
944 $ cabal install --constraint="bar test" --constraint="bar bench"
946 To specify multiple constraints, you may pass the
947 ``constraint`` option multiple times.
949 By default, constraints only apply to build dependencies
950 (:pkg-field:`build-depends`), build dependencies of build
951 dependencies, and so on. Constraints normally do not apply to
952 dependencies of the ``Setup.hs`` script of any package
953 (:pkg-field:`custom-setup:setup-depends`) nor do they apply to build tools
954 (:pkg-field:`build-tool-depends`) or the dependencies of build
955 tools. To explicitly apply a constraint to a setup or build
956 tool dependency, you can add a qualifier ``setup`` or ``any``
957 to the constraint as follows:
961 # Example use of the 'any' qualifier. This constraint
962 # applies to package bar anywhere in the dependency graph.
963 $ cabal install --constraint="any.bar == 1.0"
967 # Example uses of 'setup' qualifiers.
969 # This constraint applies to package bar when it is a
970 # dependency of any Setup.hs script.
971 $ cabal install --constraint="setup.bar == 1.0"
973 # This constraint applies to package bar when it is a
974 # dependency of the Setup.hs script of package foo.
975 $ cabal install --constraint="foo:setup.bar == 1.0"
977 .. TODO: Uncomment this example once we decide on a syntax for 'exe'.
978 .. # Example use of the 'exe' (executable build tool)
979 # qualifier. This constraint applies to package baz when it
980 # is a dependency of the build tool bar being used to
982 $ cabal install --constraint="foo:bar:exe.baz == 1.0"
984 .. option:: --disable-response-files
986 Enable workaround for older versions of programs such as ``ar`` or
987 ``ld`` that do not support response file arguments (i.e. ``@file``
988 arguments). You may want this flag only if you specify custom ar
989 executable. For system ``ar`` or the one bundled with ``ghc`` on
990 Windows the ``cabal`` should do the right thing and hence should
991 normally not require this flag.
995 runhaskell Setup.hs build
996 -------------------------
998 Perform any preprocessing or compilation needed to make this package
999 ready for installation.
1001 This command takes the following options:
1003 .. program:: runhaskell Setup.hs build
1005 .. option:: --PROG-options=OPTS, --PROG-option=OPT
1007 These are mostly the same as the `options configure
1008 step <#setup-configure>`__. Unlike the options specified at the
1009 configure step, any program options specified at the build step are
1010 not persistent but are used for that invocation only. The options
1011 specified at the build step are in addition not in replacement of
1012 any options specified at the configure step.
1016 runhaskell Setup.hs haddock
1017 ---------------------------
1019 .. program:: runhaskell Setup.hs haddock
1021 Build the documentation for the package using Haddock_.
1022 By default, only the documentation for the exposed modules is generated
1023 (but see the :option:`--executables` and :option:`--internal` flags below).
1025 This command takes the following options:
1027 .. option:: --hoogle
1029 Generate a file ``dist/doc/html/``\ *pkgid*\ ``.txt``, which can be
1030 converted by Hoogle_ into a
1031 database for searching. This is equivalent to running Haddock_
1032 with the ``--hoogle`` flag.
1034 .. option:: --html-location=url
1036 Specify a template for the location of HTML documentation for
1037 prerequisite packages. The substitutions (`see
1038 listing <#paths-in-the-simple-build-system>`__) are applied to the
1039 template to obtain a location for each package, which will be used
1040 by hyperlinks in the generated documentation. For example, the
1041 following command generates links pointing at Hackage_ pages:
1045 $ runhaskell Setup.hs haddock \
1046 --html-location='http://hackage.haskell.org/packages/archive/$pkg/latest/doc/html'
1048 Here the argument is quoted to prevent substitution by the shell. If
1049 this option is omitted, the location for each package is obtained
1050 using the package tool (e.g. ``ghc-pkg``).
1052 .. option:: --executables
1054 Also run Haddock_ for the modules of all the executable programs. By default
1055 Haddock_ is run only on the exported modules.
1057 .. option:: --internal
1059 Run Haddock_ for the all
1060 modules, including unexposed ones, and make
1061 Haddock_ generate documentation
1062 for unexported symbols as well.
1064 .. option:: --css=path
1066 The argument *path* denotes a CSS file, which is passed to
1067 Haddock_ and used to set the
1068 style of the generated documentation. This is only needed to
1069 override the default style that
1072 .. option:: --hyperlink-source
1074 Generate Haddock_ documentation integrated with HsColour_ . First,
1075 HsColour_ is run to generate colourised code. Then Haddock_ is run to
1076 generate HTML documentation. Each entity shown in the documentation is
1077 linked to its definition in the colourised code.
1079 .. option:: --hscolour-css=path
1081 The argument *path* denotes a CSS file, which is passed to HsColour_ as in
1085 $ runhaskell Setup.hs hscolour --css=*path*
1089 runhaskell Setup.hs hscolour
1090 ----------------------------
1092 Produce colourised code in HTML format using HsColour_. Colourised code for
1093 exported modules is put in ``dist/doc/html/``\ *pkgid*\ ``/src``.
1095 This command takes the following options:
1097 .. program:: runhaskell Setup.hs hscolour
1099 .. option:: --executables
1101 Also run HsColour_ on the sources of all executable programs. Colourised
1102 code is put in ``dist/doc/html/``\ *pkgid*/*executable*\ ``/src``.
1104 .. option:: --css=path
1106 Use the given CSS file for the generated HTML files. The CSS file
1107 defines the colours used to colourise code. Note that this copies
1108 the given CSS file to the directory with the generated HTML files
1109 (renamed to ``hscolour.css``) rather than linking to it.
1113 runhaskell Setup.hs install
1114 ---------------------------
1116 .. program:: runhaskell Setup.hs install
1118 Copy the files into the install locations and (for library packages)
1119 register the package with the compiler, i.e. make the modules it
1120 contains available to programs.
1122 Additionally for GHC the ``extra-compilation-artifacts`` directory is copied if present.
1123 GHC plugins can store extra data in subfolders.
1124 (e.g. *extra-compilation-artifacts/PLUGIN_NAME/HS_MODULE.txt*)
1126 The `install locations <#installation-paths>`__ are determined by
1127 options to `runhaskell Setup.hs configure`_.
1129 This command takes the following options:
1131 .. option:: --global
1133 Register this package in the system-wide database. (This is the
1134 default, unless the :option:`runhaskell Setup.hs configure --user` option was supplied
1135 to the ``configure`` command.)
1139 Register this package in the user's local package database. (This is
1140 the default if the :option:`runhaskell Setup.hs configure --user` option was supplied
1141 to the ``configure`` command.)
1145 runhaskell Setup.hs copy
1146 ------------------------
1148 Copy the files without registering them. This command is mainly of use
1149 to those creating binary packages.
1151 This command takes the following option:
1153 .. program:: runhaskell Setup.hs copy
1155 .. option:: --destdir=path
1157 Specify the directory under which to place installed files. If this is
1158 not given, then the root directory is assumed.
1162 runhaskell Setup.hs register
1163 ----------------------------
1165 Register this package with the compiler, i.e. make the modules it
1166 contains available to programs. This only makes sense for library
1167 packages. Note that the ``install`` command incorporates this action.
1168 The main use of this separate command is in the post-installation step
1169 for a binary package.
1171 This command takes the following options:
1173 .. program:: runhaskell Setup.hs register
1175 .. option:: --global
1177 Register this package in the system-wide database. (This is the
1182 Register this package in the user's local package database.
1184 .. option:: --gen-script
1186 Instead of registering the package, generate a script containing
1187 commands to perform the registration. On Unix, this file is called
1188 ``register.sh``, on Windows, ``register.bat``. This script might be
1189 included in a binary bundle, to be run after the bundle is unpacked
1190 on the target system.
1192 .. option:: --gen-pkg-config[=path]
1194 Instead of registering the package, generate a package registration
1195 file (or directory, in some circumstances). This only applies to
1196 compilers that support package registration files which at the
1197 moment is only GHC. The file should be used with the compiler's
1198 mechanism for registering packages. This option is mainly intended
1199 for packaging systems. If possible use the :option:`--gen-script` option
1200 instead since it is more portable across Haskell implementations.
1201 The *path* is optional and can be used to specify a particular
1202 output file to generate. Otherwise, by default the file is the
1203 package name and version with a ``.conf`` extension.
1205 This option outputs a directory if the package requires multiple
1206 registrations: this can occur if internal/convenience libraries are
1207 used. These configuration file names are sorted so that they can be
1208 registered in order.
1210 .. option:: --inplace
1212 Registers the package for use directly from the build tree, without
1213 needing to install it. This can be useful for testing: there's no
1214 need to install the package after modifying it, just recompile and
1217 This flag does not create a build-tree-local package database. It
1218 still registers the package in one of the user or global databases.
1220 However, there are some caveats. It only works with GHC (currently).
1221 It only works if your package doesn't depend on having any
1222 supplemental files installed --- plain Haskell libraries should be
1225 .. _setup-unregister:
1227 runhaskell Setup.hs unregister
1228 ------------------------------
1230 .. program:: runhaskell Setup.hs unregister
1232 Deregister this package with the compiler.
1234 This command takes the following options:
1236 .. option:: --global
1238 Deregister this package in the system-wide database. (This is the
1243 Deregister this package in the user's local package database.
1245 .. option:: --gen-script
1247 Instead of deregistering the package, generate a script containing
1248 commands to perform the deregistration. On Unix, this file is called
1249 ``unregister.sh``, on Windows, ``unregister.bat``. This script might
1250 be included in a binary bundle, to be run on the target system.
1254 runhaskell Setup.hs clean
1255 -------------------------
1257 Remove any local files created during the ``configure``, ``build``,
1258 ``haddock``, ``register`` or ``unregister`` steps, and also any files
1259 and directories listed in the :pkg-field:`extra-tmp-files` field.
1261 This command takes the following options:
1263 .. program:: runhaskell Setup.hs clean
1265 .. option:: --save-configure, -s
1267 Keeps the configuration information so it is not necessary to run
1268 the configure step again before building.
1272 runhaskell Setup.hs test
1273 ------------------------
1275 Run the test suites specified in the package description file. Aside
1276 from the following flags, Cabal accepts the name of one or more test
1277 suites on the command line after ``test``. When supplied, Cabal will run
1278 only the named test suites, otherwise, Cabal will run all test suites in
1281 .. program:: runhaskell Setup.hs test
1283 .. option:: --builddir=DIR
1285 The directory where Cabal puts generated build files (default:
1286 ``dist``). Test logs will be located in the ``test`` subdirectory.
1288 .. option:: --test-log=TEMPLATE
1290 The template used to name human-readable test logs; the path is
1291 relative to ``dist/test``. By default, logs are named according to
1292 the template ``$pkgid-$test-suite.log``, so that each test suite
1293 will be logged to its own human-readable log file. Template
1294 variables allowed are: ``$pkgid``, ``$compiler``, ``$os``,
1295 ``$arch``, ``$abi``, ``$abitag``, ``$test-suite``, and ``$result``.
1297 .. option:: --test-machine-log=TEMPLATE
1299 The path to the machine-readable log, relative to ``dist/test``. The
1300 default template is ``$pkgid.log``. Template variables allowed are:
1301 ``$pkgid``, ``$compiler``, ``$os``, ``$arch``, ``$abi``, ``$abitag``
1304 .. option:: --test-show-details=FILTER
1306 Determines if the results of individual test cases are shown on the
1307 terminal. May be ``always`` (always show), ``never`` (never show),
1308 ``failures`` (show only failed results), ``streaming`` (show all
1309 results in real time) and ``direct`` (same as ``streaming`` but no log
1310 file and possibly prettier).
1312 Default value is ``direct``: it leaves test output untouched and does not
1313 produce a log. This allows for colored output, which is popular with testing
1314 frameworks. (On the other hand, ``streaming`` creates a log but looses
1317 .. option:: --test-options=TEMPLATES
1319 Give extra options to the test executables.
1321 .. option:: --test-option=TEMPLATE
1323 Give an extra option to the test executables. There is no need to
1324 quote options containing spaces because a single option is assumed,
1325 so options will not be split on spaces.
1327 .. option:: --test-wrapper=FILE
1329 The wrapper script/application used to setup and tear down the test
1330 execution context. The text executable path and test arguments are
1331 passed as arguments to the wrapper and it is expected that the wrapper
1332 will return the test's return code, as well as a copy of stdout/stderr.
1336 runhaskell Setup.hs bench
1337 -------------------------
1339 Run the benchmarks specified in the package description file. Aside
1340 from the following flags, Cabal accepts the name of one or more benchmarks
1341 on the command line after ``bench``. When supplied, Cabal will run
1342 only the named benchmarks, otherwise, Cabal will run all benchmarks in
1345 .. option:: --benchmark-options=TEMPLATES
1347 Give extra options to the benchmark executables.
1349 .. option:: --benchmark-option=TEMPLATE
1351 Give an extra option to the benchmark executables. There is no need to
1352 quote options containing spaces because a single option is assumed,
1353 so options will not be split on spaces.
1357 runhaskell Setup.hs sdist
1358 -------------------------
1360 Create a system- and compiler-independent source distribution in a file
1361 *package*-*version*\ ``.tar.gz`` in the ``dist`` subdirectory, for
1362 distribution to package builders. When unpacked, the commands listed in
1363 this section will be available.
1365 The files placed in this distribution are the package description file,
1366 the setup script, the sources of the modules named in the package
1367 description file, and files named in the ``license-file``, ``main-is``,
1368 ``c-sources``, ``asm-sources``, ``cmm-sources``, ``js-sources``,
1369 ``data-files``, ``extra-source-files`` and ``extra-doc-files`` fields.
1371 This command takes the following option:
1373 .. program:: runhaskell Setup.hs sdist
1375 .. option:: --snapshot
1377 Append today's date (in "YYYYMMDD" format) to the version number for
1378 the generated source package. The original package is unaffected.
1381 .. include:: references.inc