From 3752c3e5edc3c19b7262cdb0b70f4e0539b46362 Mon Sep 17 00:00:00 2001 From: Oleg Grenrus Date: Sat, 4 Apr 2020 13:08:51 +0300 Subject: [PATCH] Separate reference parts from tutorial parts --- Cabal/doc/buildinfo-fields-reference.rst | 5 +- Cabal/doc/cabal-commands.rst | 392 +++ Cabal/doc/cabal-package.rst | 3281 +++++++++++++++++++++ Cabal/doc/cabal-project.rst | 1526 ++++++++++ Cabal/doc/developing-packages.rst | 3282 ---------------------- Cabal/doc/index.rst | 8 +- Cabal/doc/installing-packages.rst | 1448 +--------- Cabal/doc/nix-integration.rst | 5 + Cabal/doc/nix-local-build-overview.rst | 4 +- Cabal/doc/nix-local-build.rst | 1922 ------------- Cabal/doc/setup-commands.rst | 1422 ++++++++++ 11 files changed, 6638 insertions(+), 6657 deletions(-) create mode 100644 Cabal/doc/cabal-commands.rst create mode 100644 Cabal/doc/cabal-package.rst create mode 100644 Cabal/doc/cabal-project.rst create mode 100644 Cabal/doc/setup-commands.rst diff --git a/Cabal/doc/buildinfo-fields-reference.rst b/Cabal/doc/buildinfo-fields-reference.rst index b36f58d706f..be0e1584124 100644 --- a/Cabal/doc/buildinfo-fields-reference.rst +++ b/Cabal/doc/buildinfo-fields-reference.rst @@ -1,8 +1,7 @@ .. _buildinfo-field-reference: -================================================== - BuildInfo field reference -================================================== +Field Syntax Reference +====================== Notation --------------- diff --git a/Cabal/doc/cabal-commands.rst b/Cabal/doc/cabal-commands.rst new file mode 100644 index 00000000000..048d973c454 --- /dev/null +++ b/Cabal/doc/cabal-commands.rst @@ -0,0 +1,392 @@ +cabal-install Commands +====================== + +We now give an in-depth description of all the commands, describing the +arguments and flags they accept. + +cabal v2-configure +------------------- + +``cabal v2-configure`` takes a set of arguments and writes a +``cabal.project.local`` file based on the flags passed to this command. +``cabal v2-configure FLAGS; cabal new-build`` is roughly equivalent to +``cabal v2-build FLAGS``, except that with ``new-configure`` the flags +are persisted to all subsequent calls to ``v2-build``. + +``cabal v2-configure`` is intended to be a convenient way to write out +a ``cabal.project.local`` for simple configurations; e.g., +``cabal v2-configure -w ghc-7.8`` would ensure that all subsequent +builds with ``cabal v2-build`` are performed with the compiler +``ghc-7.8``. For more complex configuration, we recommend writing the +``cabal.project.local`` file directly (or placing it in +``cabal.project``!) + +``cabal v2-configure`` inherits options from ``Cabal``. semantics: + +- Any flag accepted by ``./Setup configure``. + +- Any flag accepted by ``cabal configure`` beyond + ``./Setup configure``, namely ``--cabal-lib-version``, + ``--constraint``, ``--preference`` and ``--solver.`` + +- Any flag accepted by ``cabal install`` beyond ``./Setup configure``. + +- Any flag accepted by ``./Setup haddock``. + +The options of all of these flags apply only to *local* packages in a +project; this behavior is different than that of ``cabal install``, +which applies flags to every package that would be built. The motivation +for this is to avoid an innocuous addition to the flags of a package +resulting in a rebuild of every package in the store (which might need +to happen if a flag actually applied to every transitive dependency). To +apply options to an external package, use a ``package`` stanza in a +``cabal.project`` file. + +cabal v2-update +---------------- + +``cabal v2-update`` updates the state of the package index. If the +project contains multiple remote package repositories it will update +the index of all of them (e.g. when using overlays). + +Some examples: + +:: + + $ cabal v2-update # update all remote repos + $ cabal v2-update head.hackage # update only head.hackage + +cabal v2-build +--------------- + +``cabal v2-build`` takes a set of targets and builds them. It +automatically handles building and installing any dependencies of these +targets. + +A target can take any of the following forms: + +- A package target: ``package``, which specifies that all enabled + components of a package to be built. By default, test suites and + benchmarks are *not* enabled, unless they are explicitly requested + (e.g., via ``--enable-tests``.) + +- A component target: ``[package:][ctype:]component``, which specifies + a specific component (e.g., a library, executable, test suite or + benchmark) to be built. + +- All packages: ``all``, which specifies all packages within the project. + +- Components of a particular type: ``package:ctypes``, ``all:ctypes``: + which specifies all components of the given type. Where valid + ``ctypes`` are: + + - ``libs``, ``libraries``, + - ``flibs``, ``foreign-libraries``, + - ``exes``, ``executables``, + - ``tests``, + - ``benches``, ``benchmarks``. + +In component targets, ``package:`` and ``ctype:`` (valid component types +are ``lib``, ``flib``, ``exe``, ``test`` and ``bench``) can be used to +disambiguate when multiple packages define the same component, or the +same component name is used in a package (e.g., a package ``foo`` +defines both an executable and library named ``foo``). We always prefer +interpreting a target as a package name rather than as a component name. + +Some example targets: + +:: + + $ cabal v2-build lib:foo-pkg # build the library named foo-pkg + $ cabal v2-build foo-pkg:foo-tests # build foo-tests in foo-pkg + +(There is also syntax for specifying module and file targets, but it +doesn't currently do anything.) + +Beyond a list of targets, ``cabal v2-build`` accepts all the flags that +``cabal v2-configure`` takes. Most of these flags are only taken into +consideration when building local packages; however, some flags may +cause extra store packages to be built (for example, +``--enable-profiling`` will automatically make sure profiling libraries +for all transitive dependencies are built and installed.) + +In addition ``cabal v2-build`` accepts these flags: + +- ``--only-configure``: When given we will forgoe performing a full build and + abort after running the configure phase of each target package. + + +cabal v2-repl +-------------- + +``cabal v2-repl TARGET`` loads all of the modules of the target into +GHCi as interpreted bytecode. In addition to ``cabal v2-build``'s flags, +it takes an additional ``--repl-options`` flag. + +To avoid ``ghci`` specific flags from triggering unneeded global rebuilds these +flags are now stripped from the internal configuration. As a result +``--ghc-options`` will no longer (reliably) work to pass flags to ``ghci`` (or +other repls). Instead, you should use the new ``--repl-options`` flag to +specify these options to the invoked repl. (This flag also works on ``cabal +repl`` and ``Setup repl`` on sufficiently new versions of Cabal.) + +Currently, it is not supported to pass multiple targets to ``v2-repl`` +(``v2-repl`` will just successively open a separate GHCi session for +each target.) + +It also provides a way to experiment with libraries without needing to download +them manually or to install them globally. + +This command opens a REPL with the current default target loaded, and a version +of the ``vector`` package matching that specification exposed. + +:: + + $ cabal v2-repl --build-depends "vector >= 0.12 && < 0.13" + +Both of these commands do the same thing as the above, but only exposes ``base``, +``vector``, and the ``vector`` package's transitive dependencies even if the user +is in a project context. + +:: + + $ cabal v2-repl --ignore-project --build-depends "vector >= 0.12 && < 0.13" + $ cabal v2-repl --project='' --build-depends "vector >= 0.12 && < 0.13" + +This command would add ``vector``, but not (for example) ``primitive``, because +it only includes the packages specified on the command line (and ``base``, which +cannot be excluded for technical reasons). + +:: + + $ cabal v2-repl --build-depends vector --no-transitive-deps + +cabal v2-run +------------- + +``cabal v2-run [TARGET [ARGS]]`` runs the executable specified by the +target, which can be a component, a package or can be left blank, as +long as it can uniquely identify an executable within the project. +Tests and benchmarks are also treated as executables. + +See `the v2-build section <#cabal-new-build>`__ for the target syntax. + +Except in the case of the empty target, the strings after it will be +passed to the executable as arguments. + +If one of the arguments starts with ``-`` it will be interpreted as +a cabal flag, so if you need to pass flags to the executable you +have to separate them with ``--``. + +:: + + $ cabal v2-run target -- -a -bcd --argument + +'v2-run' also supports running script files that use a certain format. With +a script that looks like: + +:: + + #!/usr/bin/env cabal + {- cabal: + build-depends: base ^>= 4.11 + , shelly ^>= 1.8.1 + -} + + main :: IO () + main = do + ... + +It can either be executed like any other script, using ``cabal`` as an +interpreter, or through this command: + +:: + + $ cabal v2-run script.hs + $ cabal v2-run script.hs -- --arg1 # args are passed like this + +cabal v2-freeze +---------------- + +``cabal v2-freeze`` writes out a **freeze file** which records all of +the versions and flags which that are picked by the solver under the +current index and flags. Default name of this file is +``cabal.project.freeze`` but in combination with a +``--project-file=my.project`` flag (see :ref:`project-file +`) +the name will be ``my.project.freeze``. +A freeze file has the same syntax as ``cabal.project`` and looks +something like this: + +.. highlight:: cabal + +:: + + constraints: HTTP ==4000.3.3, + HTTP +warp-tests -warn-as-error -network23 +network-uri -mtl1 -conduit10, + QuickCheck ==2.9.1, + QuickCheck +templatehaskell, + -- etc... + + +For end-user executables, it is recommended that you distribute the +``cabal.project.freeze`` file in your source repository so that all +users see a consistent set of dependencies. For libraries, this is not +recommended: users often need to build against different versions of +libraries than what you developed against. + +cabal v2-bench +--------------- + +``cabal v2-bench [TARGETS] [OPTIONS]`` runs the specified benchmarks +(all the benchmarks in the current package by default), first ensuring +they are up to date. + +cabal v2-test +-------------- + +``cabal v2-test [TARGETS] [OPTIONS]`` runs the specified test suites +(all the test suites in the current package by default), first ensuring +they are up to date. + +cabal v2-haddock +----------------- + +``cabal v2-haddock [FLAGS] [TARGET]`` builds Haddock documentation for +the specified packages within the project. + +If a target is not a library :cfg-field:`haddock-benchmarks`, +:cfg-field:`haddock-executables`, :cfg-field:`haddock-internal`, +:cfg-field:`haddock-tests` will be implied as necessary. + +cabal v2-exec +--------------- + +``cabal v2-exec [FLAGS] [--] COMMAND [--] [ARGS]`` runs the specified command +using the project's environment. That is, passing the right flags to compiler +invocations and bringing the project's executables into scope. + +cabal v2-install +----------------- + +``cabal v2-install [FLAGS] PACKAGES`` builds the specified packages and +symlinks/copies their executables in ``installdir`` (usually ``~/.cabal/bin``). + +For example this command will build the latest ``cabal-install`` and symlink +its ``cabal`` executable: + +:: + + $ cabal v2-install cabal-install + +In addition, it's possible to use ``cabal v2-install`` to install components +of a local project. For example, with an up-to-date Git clone of the Cabal +repository, this command will build cabal-install HEAD and symlink the +``cabal`` executable: + +:: + + $ cabal v2-install exe:cabal + +Where symlinking is not possible (eg. on some Windows versions) the ``copy`` +method is used by default. You can specify the install method +by using ``--install-method`` flag: + +:: + + $ cabal v2-install exe:cabal --install-method=copy --installdir=$HOME/bin + +Note that copied executables are not self-contained, since they might use +data-files from the store. + +It is also possible to "install" libraries using the ``--lib`` flag. For +example, this command will build the latest Cabal library and install it: + +:: + + $ cabal v2-install --lib Cabal + +This works by managing GHC environments. By default, it is writing to the +global environment in ``~/.ghc/$ARCH-$OS-$GHCVER/environments/default``. +``v2-install`` provides the ``--package-env`` flag to control which of +these environments is modified. + +This command will modify the environment file in the current directory: + +:: + + $ cabal v2-install --lib Cabal --package-env . + +This command will modify the environment file in the ``~/foo`` directory: + +:: + + $ cabal v2-install --lib Cabal --package-env foo/ + +Do note that the results of the previous two commands will be overwritten by +the use of other v2-style commands, so it is not recommended to use them inside +a project directory. + +This command will modify the environment in the "local.env" file in the +current directory: + +:: + + $ cabal v2-install --lib Cabal --package-env local.env + +This command will modify the ``myenv`` named global environment: + +:: + + $ cabal v2-install --lib Cabal --package-env myenv + +If you wish to create a named environment file in the current directory where +the name does not contain an extension, you must reference it as ``./myenv``. + +You can learn more about how to use these environments in `this section of the +GHC manual `_. + +cabal v2-clean +--------------- + +``cabal v2-clean [FLAGS]`` cleans up the temporary files and build artifacts +stored in the ``dist-newstyle`` folder. + +By default, it removes the entire folder, but it can also spare the configuration +and caches if the ``--save-config`` option is given, in which case it only removes +the build artefacts (``.hi``, ``.o`` along with any other temporary files generated +by the compiler, along with the build output). + +cabal v2-sdist +--------------- + +``cabal v2-sdist [FLAGS] [TARGETS]`` takes the crucial files needed to build ``TARGETS`` +and puts them into an archive format ready for upload to Hackage. These archives are stable +and two archives of the same format built from the same source will hash to the same value. + +``cabal v2-sdist`` takes the following flags: + +- ``-l``, ``--list-only``: Rather than creating an archive, lists files that would be included. + Output is to ``stdout`` by default. The file paths are relative to the project's root + directory. + +- ``-o``, ``--output-dir``: Sets the output dir, if a non-default one is desired. The default is + ``dist-newstyle/sdist/``. ``--output-dir -`` will send output to ``stdout`` + unless multiple archives are being created. + +- ``-z``, ``--null``: Only used with ``--list-only``. Separates filenames with a NUL + byte instead of newlines. + +``v2-sdist`` is inherently incompatible with sdist hooks, not due to implementation but due +to fundamental core invariants (same source code should result in the same tarball, byte for +byte) that must be satisfied for it to function correctly in the larger v2-build ecosystem. +``autogen-modules`` is able to replace uses of the hooks to add generated modules, along with +the custom publishing of Haddock documentation to Hackage. + +.. warning:: + + Packages that use Backpack will stop working if uploaded to + Hackage, due to `issue #6005 `_. + While this is happening, we recommend not uploading these packages + to Hackage (and instead referencing the package directly + as a ``source-repository-package``). diff --git a/Cabal/doc/cabal-package.rst b/Cabal/doc/cabal-package.rst new file mode 100644 index 00000000000..7ce2539e4cc --- /dev/null +++ b/Cabal/doc/cabal-package.rst @@ -0,0 +1,3281 @@ +Package Description +=================== + +The Cabal package is the unit of distribution. When installed, its +purpose is to make available: + +- One or more Haskell programs. + +- At most one library, exposing a number of Haskell modules. + +However having both a library and executables in a package does not work +very well; if the executables depend on the library, they must +explicitly list all the modules they directly or indirectly import from +that library. Fortunately, starting with Cabal 1.8.0.4, executables can +also declare the package that they are in as a dependency, and Cabal +will treat them as if they were in another package that depended on the +library. + +Internally, the package may consist of much more than a bunch of Haskell +modules: it may also have C source code and header files, source code +meant for preprocessing, documentation, test cases, auxiliary tools etc. + +A package is identified by a globally-unique *package name*, which +consists of one or more alphanumeric words separated by hyphens. To +avoid ambiguity, each of these words should contain at least one letter. +Chaos will result if two distinct packages with the same name are +installed on the same system. A particular version of the package is +distinguished by a *version number*, consisting of a sequence of one or +more integers separated by dots. These can be combined to form a single +text string called the *package ID*, using a hyphen to separate the name +from the version, e.g. "``HUnit-1.1``". + +.. Note:: + + Packages are not part of the Haskell language; they simply + populate the hierarchical space of module names. In GHC 6.6 and later a + program may contain multiple modules with the same name if they come + from separate packages; in all other current Haskell systems packages + may not overlap in the modules they provide, including hidden modules. + +Creating a package +------------------ + +Suppose you have a directory hierarchy containing the source files that +make up your package. You will need to add two more files to the root +directory of the package: + +:file:`{package-name}.cabal` + a Unicode UTF-8 text file containing a package description. For + details of the syntax of this file, see the section on + `package descriptions`_. + +:file:`Setup.hs` + a single-module Haskell program to perform various setup tasks (with + the interface described in the section on :ref:`installing-packages`). + This module should import only modules that will be present in all Haskell + implementations, including modules of the Cabal library. The content of + this file is determined by the :pkg-field:`build-type` setting in the + ``.cabal`` file. In most cases it will be trivial, calling on the Cabal + library to do most of the work. + +Once you have these, you can create a source bundle of this directory +for distribution. Building of the package is discussed in the section on +:ref:`installing-packages`. + +One of the purposes of Cabal is to make it easier to build a package +with different Haskell implementations. So it provides abstractions of +features present in different Haskell implementations and wherever +possible it is best to take advantage of these to increase portability. +Where necessary however it is possible to use specific features of +specific implementations. For example one of the pieces of information a +package author can put in the package's ``.cabal`` file is what language +extensions the code uses. This is far preferable to specifying flags for +a specific compiler as it allows Cabal to pick the right flags for the +Haskell implementation that the user picks. It also allows Cabal to +figure out if the language extension is even supported by the Haskell +implementation that the user picks. Where compiler-specific options are +needed however, there is an "escape hatch" available. The developer can +specify implementation-specific options and more generally there is a +configuration mechanism to customise many aspects of how a package is +built depending on the Haskell implementation, the Operating system, +computer architecture and user-specified configuration flags. + +:: + + name: Foo + version: 1.0 + + library + build-depends: base >= 4 && < 5 + exposed-modules: Foo + extensions: ForeignFunctionInterface + ghc-options: -Wall + if os(windows) + build-depends: Win32 >= 2.1 && < 2.6 + +Example: A package containing a simple library +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The HUnit package contains a file ``HUnit.cabal`` containing: + +:: + + name: HUnit + version: 1.1.1 + synopsis: A unit testing framework for Haskell + homepage: http://hunit.sourceforge.net/ + category: Testing + author: Dean Herington + license: BSD3 + license-file: LICENSE + cabal-version: 1.12 + build-type: Simple + + library + build-depends: base >= 2 && < 4 + exposed-modules: Test.HUnit.Base, Test.HUnit.Lang, + Test.HUnit.Terminal, Test.HUnit.Text, Test.HUnit + default-extensions: CPP + +and the following ``Setup.hs``: + +.. code-block:: haskell + + import Distribution.Simple + main = defaultMain + +Example: A package containing executable programs +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +:: + + name: TestPackage + version: 0.0 + synopsis: Small package with two programs + author: Angela Author + license: BSD3 + build-type: Simple + cabal-version: >= 1.8 + + executable program1 + build-depends: HUnit >= 1.1.1 && < 1.2 + main-is: Main.hs + hs-source-dirs: prog1 + + executable program2 + main-is: Main.hs + build-depends: HUnit >= 1.1.1 && < 1.2 + hs-source-dirs: prog2 + other-modules: Utils + +with ``Setup.hs`` the same as above. + +Example: A package containing a library and executable programs +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +:: + + name: TestPackage + version: 0.0 + synopsis: Package with library and two programs + license: BSD3 + author: Angela Author + build-type: Simple + cabal-version: >= 1.8 + + library + build-depends: HUnit >= 1.1.1 && < 1.2 + exposed-modules: A, B, C + + executable program1 + main-is: Main.hs + hs-source-dirs: prog1 + other-modules: A, B + + executable program2 + main-is: Main.hs + hs-source-dirs: prog2 + other-modules: A, C, Utils + +with ``Setup.hs`` the same as above. Note that any library modules +required (directly or indirectly) by an executable must be listed again. + +The trivial setup script used in these examples uses the *simple build +infrastructure* provided by the Cabal library (see +`Distribution.Simple <../release/cabal-latest/doc/API/Cabal/Distribution-Simple.html>`__). +The simplicity lies in its interface rather that its implementation. It +automatically handles preprocessing with standard preprocessors, and +builds packages for all the Haskell implementations. + +The simple build infrastructure can also handle packages where building +is governed by system-dependent parameters, if you specify a little more +(see the section on `system-dependent parameters`_). +A few packages require `more elaborate solutions `_. + +.. _pkg-desc: + +Package descriptions +-------------------- + +The package description file must have a name ending in "``.cabal``". It +must be a Unicode text file encoded using valid UTF-8. There must be +exactly one such file in the directory. The first part of the name is +usually the package name, and some of the tools that operate on Cabal +packages require this; specifically, Hackage rejects packages which +don't follow this rule. + +In the package description file, lines whose first non-whitespace +characters are "``--``" are treated as comments and ignored. + +This file should contain of a number global property descriptions and +several sections. + +- The `package properties`_ describe the package + as a whole, such as name, license, author, etc. + +- Optionally, a number of *configuration flags* can be declared. These + can be used to enable or disable certain features of a package. (see + the section on `configurations`_). + +- The (optional) library section specifies the `library`_ properties and + relevant `build information`_. + +- Following is an arbitrary number of executable sections which describe + an executable program and relevant `build information`_. + +Each section consists of a number of property descriptions in the form +of field/value pairs, with a syntax roughly like mail message headers. + +- Case is not significant in field names, but is significant in field + values. + +- To continue a field value, indent the next line relative to the field + name. + +- Field names may be indented, but all field values in the same section + must use the same indentation. + +- Tabs are *not* allowed as indentation characters due to a missing + standard interpretation of tab width. + +- Before Cabal 3.0, to get a blank line in a field value, use an indented "``.``" + +The syntax of the value depends on the field. Field types include: + +*token*, *filename*, *directory* + Either a sequence of one or more non-space non-comma characters, or + a quoted string in Haskell 98 lexical syntax. The latter can be used + for escaping whitespace, for example: + ``ghc-options: -Wall "-with-rtsopts=-T -I1"``. Unless otherwise + stated, relative filenames and directories are interpreted from the + package root directory. +*freeform*, *URL*, *address* + An arbitrary, uninterpreted string. +*identifier* + A letter followed by zero or more alphanumerics or underscores. +*compiler* + A compiler flavor (one of: ``GHC``, ``UHC`` or ``LHC``) + followed by a version range. For example, ``GHC ==6.10.3``, or + ``LHC >=0.6 && <0.8``. + +Modules and preprocessors +^^^^^^^^^^^^^^^^^^^^^^^^^ + +Haskell module names listed in the :pkg-field:`library:exposed-modules` and +:pkg-field:`library:other-modules` fields may correspond to Haskell source +files, i.e. with names ending in "``.hs``" or "``.lhs``", or to inputs for +various Haskell preprocessors. The simple build infrastructure understands the +extensions: + +- ``.gc`` (:hackage-pkg:`greencard`) +- ``.chs`` (:hackage-pkg:`c2hs`) +- ``.hsc`` (:hackage-pkg:`hsc2hs`) +- ``.y`` and ``.ly`` (happy_) +- ``.x`` (alex_) +- ``.cpphs`` (cpphs_) + +When building, Cabal will automatically run the appropriate preprocessor +and compile the Haskell module it produces. For the ``c2hs`` and +``hsc2hs`` preprocessors, Cabal will also automatically add, compile and +link any C sources generated by the preprocessor (produced by +``hsc2hs``'s ``#def`` feature or ``c2hs``'s auto-generated wrapper +functions). Dependencies on pre-processors are specified via the +:pkg-field:`build-tools` or :pkg-field:`build-tool-depends` fields. + +Some fields take lists of values, which are optionally separated by +commas, except for the :pkg-field:`build-depends` field, where the commas are +mandatory. + +Some fields are marked as required. All others are optional, and unless +otherwise specified have empty default values. + +Package properties +^^^^^^^^^^^^^^^^^^ + +These fields may occur in the first top-level properties section and +describe the package as a whole: + +.. pkg-field:: name: package-name (required) + + The unique name of the package, without the version number. + + As pointed out in the section on `package descriptions`_, some + tools require the package-name specified for this field to match + the package description's file-name :file:`{package-name}.cabal`. + + Package names are case-sensitive and must match the regular expression + (i.e. alphanumeric "words" separated by dashes; each alphanumeric + word must contain at least one letter): + ``[[:digit:]]*[[:alpha:]][[:alnum:]]*(-[[:digit:]]*[[:alpha:]][[:alnum:]]*)*``. + + Or, expressed in ABNF_: + + .. code-block:: abnf + + package-name = package-name-part *("-" package-name-part) + package-name-part = *DIGIT UALPHA *UALNUM + + UALNUM = UALPHA / DIGIT + UALPHA = ... ; set of alphabetic Unicode code-points + + .. note:: + + Hackage restricts package names to the ASCII subset. + +.. pkg-field:: version: numbers (required) + + The package version number, usually consisting of a sequence of + natural numbers separated by dots, i.e. as the regular + expression ``[0-9]+([.][0-9]+)*`` or expressed in ABNF_: + + .. code-block:: abnf + + package-version = 1*DIGIT *("." 1*DIGIT) + +.. pkg-field:: cabal-version: x.y[.z] + + The version of the Cabal specification that this package + description uses. The Cabal specification does slowly evolve (see + also :ref:`spec-history`), introducing new features and + occasionally changing the meaning of existing features. By + specifying which version of the specification you are using it + enables programs which process the package description to know + what syntax to expect and what each part means. + + The version number you specify will affect both compatibility and + behaviour. Most tools (including the Cabal library and the ``cabal`` + program) understand a range of versions of the Cabal specification. + Older tools will of course only work with older versions of the + Cabal specification that was known at the time. Most of the time, + tools that are too old will recognise this fact and produce a + suitable error message. Likewise, ``cabal check`` will tell you + whether the version number is sufficiently high for the features + you use in the package description. + + As for behaviour, new versions of the Cabal specification can change the + meaning of existing syntax. This means if you want to take advantage + of the new meaning or behaviour then you must specify the newer + Cabal version. Tools are expected to use the meaning and behaviour + appropriate to the version given in the package description. + + In particular, the syntax of package descriptions changed + significantly with Cabal version 1.2 and the :pkg-field:`cabal-version` + field is now required. Files written in the old syntax are still + recognized, so if you require compatibility with very old Cabal + versions then you may write your package description file using the + old syntax. Please consult the user's guide of an older Cabal + version for a description of that syntax. + + Starting with ``cabal-version: 2.2`` this field is only valid if + fully contained in the very first line of a package description + and ought to adhere to the ABNF_ grammar + + .. code-block:: abnf + + newstyle-spec-version-decl = "cabal-version" *WS ":" *WS newstyle-spec-version *WS + + newstyle-spec-version = NUM "." NUM [ "." NUM ] + + NUM = DIGIT0 / DIGITP 1*DIGIT0 + DIGIT0 = %x30-39 + DIGITP = %x31-39 + WS = %20 + + + .. note:: + + For package descriptions using a format prior to + ``cabal-version: 1.12`` the legacy syntax resembling a version + range syntax + + .. code-block:: cabal + + cabal-version: >= 1.10 + + needs to be used. + + This legacy syntax is supported up until ``cabal-version: >= + 2.0`` it is however strongly recommended to avoid using the + legacy syntax. See also :issue:`4899`. + + + +.. pkg-field:: build-type: identifier + + :default: ``Custom`` or ``Simple`` + + The type of build used by this package. Build types are the + constructors of the + `BuildType <../release/cabal-latest/doc/API/Cabal/Distribution-PackageDescription.html#t:BuildType>`__ + type. This field is optional and when missing, its default value + is inferred according to the following rules: + + - When :pkg-field:`cabal-version` is set to ``2.2`` or higher, + the default is ``Simple`` unless a :pkg-section:`custom-setup` + exists, in which case the inferred default is ``Custom``. + + - For lower :pkg-field:`cabal-version` values, the default is + ``Custom`` unconditionally. + + If the build type is anything other than ``Custom``, then the + ``Setup.hs`` file *must* be exactly the standardized content + discussed below. This is because in these cases, ``cabal`` will + ignore the ``Setup.hs`` file completely, whereas other methods of + package management, such as ``runhaskell Setup.hs [CMD]``, still + rely on the ``Setup.hs`` file. + + For build type ``Simple``, the contents of ``Setup.hs`` must be: + + .. code-block:: haskell + + import Distribution.Simple + main = defaultMain + + For build type ``Configure`` (see the section on `system-dependent + parameters`_ below), the contents of + ``Setup.hs`` must be: + + .. code-block:: haskell + + import Distribution.Simple + main = defaultMainWithHooks autoconfUserHooks + + For build type ``Make`` (see the section on `more complex packages`_ below), + the contents of ``Setup.hs`` must be: + + .. code-block:: haskell + + import Distribution.Make + main = defaultMain + + For build type ``Custom``, the file ``Setup.hs`` can be customized, + and will be used both by ``cabal`` and other tools. + + For most packages, the build type ``Simple`` is sufficient. + +.. pkg-field:: license: SPDX expression + + :default: ``NONE`` + + The type of license under which this package is distributed. + + Starting with ``cabal-version: 2.2`` the ``license`` field takes a + (case-sensitive) SPDX expression such as + + .. code-block:: cabal + + license: Apache-2.0 AND (MIT OR GPL-2.0-or-later) + + See `SPDX IDs: How to use `__ for more + examples of SPDX expressions. + + The version of the + `list of SPDX license identifiers `__ + is a function of the :pkg-field:`cabal-version` value as defined + in the following table: + + +--------------------------+--------------------+ + | Cabal specification | SPDX license list | + | version | version | + | | | + +==========================+====================+ + | ``cabal-version: 2.2`` | ``3.0 2017-12-28`` | + +--------------------------+--------------------+ + | ``cabal-version: 2.4`` | ``3.2 2018-07-10`` | + +--------------------------+--------------------+ + + **Pre-SPDX Legacy Identifiers** + + The license identifier in the table below are defined for + ``cabal-version: 2.0`` and previous versions of the Cabal + specification. + + +--------------------------+-----------------+ + | :pkg-field:`license` | Note | + | identifier | | + | | | + +==========================+=================+ + | ``GPL`` | | + | ``GPL-2`` | | + | ``GPL-3`` | | + +--------------------------+-----------------+ + | ``LGPL`` | | + | ``LGPL-2.1`` | | + | ``LGPL-3`` | | + +--------------------------+-----------------+ + | ``AGPL`` | since 1.18 | + | ``AGPL-3`` | | + +--------------------------+-----------------+ + | ``BSD2`` | since 1.20 | + +--------------------------+-----------------+ + | ``BSD3`` | | + +--------------------------+-----------------+ + | ``MIT`` | | + +--------------------------+-----------------+ + | ``ISC`` | since 1.22 | + +--------------------------+-----------------+ + | ``MPL-2.0`` | since 1.20 | + +--------------------------+-----------------+ + | ``Apache`` | | + | ``Apache-2.0`` | | + +--------------------------+-----------------+ + | ``PublicDomain`` | | + +--------------------------+-----------------+ + | ``AllRightsReserved`` | | + +--------------------------+-----------------+ + | ``OtherLicense`` | | + +--------------------------+-----------------+ + + +.. pkg-field:: license-file: filename + + See :pkg-field:`license-files`. + +.. pkg-field:: license-files: filename list + :since: 1.20 + + The name of a file(s) containing the precise copyright license for + this package. The license file(s) will be installed with the + package. + + If you have multiple license files then use the :pkg-field:`license-files` + field instead of (or in addition to) the :pkg-field:`license-file` field. + +.. pkg-field:: copyright: freeform + + The content of a copyright notice, typically the name of the holder + of the copyright on the package and the year(s) from which copyright + is claimed. For example:: + + copyright: (c) 2006-2007 Joe Bloggs + +.. pkg-field:: author: freeform + + The original author of the package. + + Remember that ``.cabal`` files are Unicode, using the UTF-8 + encoding. + +.. pkg-field:: maintainer: address + + The current maintainer or maintainers of the package. This is an + e-mail address to which users should send bug reports, feature + requests and patches. + +.. pkg-field:: stability: freeform + + The stability level of the package, e.g. ``alpha``, + ``experimental``, ``provisional``, ``stable``. + +.. pkg-field:: homepage: URL + + The package homepage. + +.. pkg-field:: bug-reports: URL + + The URL where users should direct bug reports. This would normally + be either: + + - A ``mailto:`` URL, e.g. for a person or a mailing list. + + - An ``http:`` (or ``https:``) URL for an online bug tracking + system. + + For example Cabal itself uses a web-based bug tracking system + + :: + + bug-reports: https://github.com/haskell/cabal/issues + +.. pkg-field:: package-url: URL + + The location of a source bundle for the package. The distribution + should be a Cabal package. + +.. pkg-field:: synopsis: freeform + + A very short description of the package, for use in a table of + packages. This is your headline, so keep it short (one line) but as + informative as possible. Save space by not including the package + name or saying it's written in Haskell. + +.. pkg-field:: description: freeform + + Description of the package. This may be several paragraphs, and + should be aimed at a Haskell programmer who has never heard of your + package before. + + For library packages, this field is used as prologue text by + :ref:`setup-haddock` and thus may contain the same markup as Haddock_ + documentation comments. + +.. pkg-field:: category: freeform + + A classification category for future use by the package catalogue + Hackage_. These categories have not + yet been specified, but the upper levels of the module hierarchy + make a good start. + +.. pkg-field:: tested-with: compiler list + + A list of compilers and versions against which the package has been + tested (or at least built). The value of this field is not used by Cabal + and is rather intended as extra metadata for use by third party + tooling, such as e.g. CI tooling. + + Here's a typical usage example + + :: + + tested-with: GHC == 8.6.3, GHC == 8.4.4, GHC == 8.2.2, GHC == 8.0.2, + GHC == 7.10.3, GHC == 7.8.4, GHC == 7.6.3, GHC == 7.4.2 + + which can (starting with Cabal 3.0) also be written using the more + concise set notation syntax + + :: + + tested-with: GHC == { 8.6.3, 8.4.4, 8.2.2, 8.0.2, 7.10.3, 7.8.4, 7.6.3, 7.4.2 } + +.. pkg-field:: data-files: filename list + + A list of files to be installed for run-time use by the package. + This is useful for packages that use a large amount of static data, + such as tables of values or code templates. Cabal provides a way to + `find these files at run-time <#accessing-data-files-from-package-code>`_. + + A limited form of ``*`` wildcards in file names, for example + ``data-files: images/*.png`` matches all the ``.png`` files in the + ``images`` directory. ``data-files: audio/**/*.mp3`` matches all + the ``.mp3`` files in the ``audio`` directory, including + subdirectories. + + The specific limitations of this wildcard syntax are + + - ``*`` wildcards are only allowed in place of the file name, not + in the directory name or file extension. It must replace the + whole file name (e.g., ``*.html`` is allowed, but + ``chapter-*.html`` is not). If a wildcard is used, it must be + used with an extension, so ``data-files: data/*`` is not + allowed. + + - Prior to Cabal 2.4, when matching a wildcard plus extension, a + file's full extension must match exactly, so ``*.gz`` matches + ``foo.gz`` but not ``foo.tar.gz``. This restriction has been + lifted when ``cabal-version: 2.4`` or greater so that ``*.gz`` + does match ``foo.tar.gz`` + + - ``*`` wildcards will not match if the file name is empty (e.g., + ``*.html`` will not match ``foo/.html``). + + - ``**`` wildcards can only appear as the final path component + before the file name (e.g., ``data/**/images/*.jpg`` is not + allowed). If a ``**`` wildcard is used, then the file name must + include a ``*`` wildcard (e.g., ``data/**/README.rst`` is not + allowed). + + - A wildcard that does not match any files is an error. + + The reason for providing only a very limited form of wildcard is to + concisely express the common case of a large number of related files + of the same file type without making it too easy to accidentally + include unwanted files. + + On efficiency: if you use ``**`` patterns, the directory tree will + be walked starting with the parent directory of the ``**``. If + that's the root of the project, this might include ``.git/``, + ``dist-newstyle/``, or other large directories! To avoid this + behaviour, put the files that wildcards will match against in + their own folder. + + ``**`` wildcards are available starting in Cabal 2.4. + +.. pkg-field:: data-dir: directory + + The directory where Cabal looks for data files to install, relative + to the source directory. By default, Cabal will look in the source + directory itself. + +.. pkg-field:: extra-source-files: filename list + + A list of additional files to be included in source distributions + built with :ref:`setup-sdist`. As with :pkg-field:`data-files` it can use + a limited form of ``*`` wildcards in file names. + +.. pkg-field:: extra-doc-files: filename list + :since: 1.18 + + A list of additional files to be included in source distributions, + and also copied to the html directory when Haddock documentation is + generated. As with :pkg-field:`data-files` it can use a limited form of + ``*`` wildcards in file names. + +.. pkg-field:: extra-tmp-files: filename list + + A list of additional files or directories to be removed by + :ref:`setup-clean`. These would typically be additional files created by + additional hooks, such as the scheme described in the section on + `system-dependent parameters`_ + +Library +^^^^^^^ + +.. pkg-section:: library name + :synopsis: Library build information. + + Build information for libraries. + + Currently, there can only be one publicly exposed library in a + package, and its name is the same as package name set by global + :pkg-field:`name` field. In this case, the ``name`` argument to + the :pkg-section:`library` section must be omitted. + + Starting with Cabal 2.0, private internal sub-library components + can be defined by using setting the ``name`` field to a name + different from the current package's name; see section on + :ref:`Internal Libraries ` for more information. + +The library section should contain the following fields: + +.. pkg-field:: exposed-modules: identifier list + + :required: if this package contains a library + + A list of modules added by this package. + +.. pkg-field:: virtual-modules: identifier list + :since: 2.2 + + A list of virtual modules provided by this package. Virtual modules + are modules without a source file. See for example the ``GHC.Prim`` + module from the ``ghc-prim`` package. Modules listed here will not be + built, but still end up in the list of ``exposed-modules`` in the + installed package info when the package is registered in the package + database. + +.. pkg-field:: exposed: boolean + + :default: ``True`` + + Some Haskell compilers (notably GHC) support the notion of packages + being "exposed" or "hidden" which means the modules they provide can + be easily imported without always having to specify which package + they come from. However this only works effectively if the modules + provided by all exposed packages do not overlap (otherwise a module + import would be ambiguous). + + Almost all new libraries use hierarchical module names that do not + clash, so it is very uncommon to have to use this field. However it + may be necessary to set ``exposed: False`` for some old libraries + that use a flat module namespace or where it is known that the + exposed modules would clash with other common modules. + +.. pkg-field:: visibility: visibilty specifiers + + :since 3.0 + + :default: ``private`` for internal libraries. Cannot be set for public library. + + Cabal recognizes ``public`` and ``private`` here... + + Multiple public libraries... + +.. pkg-field:: reexported-modules: exportlist + :since: 1.22 + + Supported only in GHC 7.10 and later. A list of modules to + *reexport* from this package. The syntax of this field is + ``orig-pkg:Name as NewName`` to reexport module ``Name`` from + ``orig-pkg`` with the new name ``NewName``. We also support + abbreviated versions of the syntax: if you omit ``as NewName``, + we'll reexport without renaming; if you omit ``orig-pkg``, then we + will automatically figure out which package to reexport from, if + it's unambiguous. + + Reexported modules are useful for compatibility shims when a package + has been split into multiple packages, and they have the useful + property that if a package provides a module, and another package + reexports it under the same name, these are not considered a + conflict (as would be the case with a stub module.) They can also be + used to resolve name conflicts. + +.. pkg-field:: signatures: signature list + :since: 2.0 + + Supported only in GHC 8.2 and later. A list of `module signatures `__ required by this package. + + Module signatures are part of the Backpack_ extension to + the Haskell module system. + + Packages that do not export any modules and only export required signatures + are called "signature-only packages", and their signatures are subjected to + `signature thinning + `__. + + + +The library section may also contain build information fields (see the +section on `build information`_). + +.. _sublibs: + +**Internal Libraries** + +Cabal 2.0 and later support "internal libraries", which are extra named +libraries (as opposed to the usual unnamed library section). For +example, suppose that your test suite needs access to some internal +modules in your library, which you do not otherwise want to export. You +could put these modules in an internal library, which the main library +and the test suite :pkg-field:`build-depends` upon. Then your Cabal file might +look something like this: + +:: + + cabal-version: 2.0 + name: foo + version: 0.1.0.0 + license: BSD3 + build-type: Simple + + library foo-internal + exposed-modules: Foo.Internal + -- NOTE: no explicit constraints on base needed + -- as they're inherited from the 'library' stanza + build-depends: base + + library + exposed-modules: Foo.Public + build-depends: foo-internal, base >= 4.3 && < 5 + + test-suite test-foo + type: exitcode-stdio-1.0 + main-is: test-foo.hs + -- NOTE: no constraints on 'foo-internal' as same-package + -- dependencies implicitly refer to the same package instance + build-depends: foo-internal, base + +Internal libraries are also useful for packages that define multiple +executables, but do not define a publicly accessible library. Internal +libraries are only visible internally in the package (so they can only +be added to the :pkg-field:`build-depends` of same-package libraries, +executables, test suites, etc.) Internal libraries locally shadow any +packages which have the same name; consequently, don't name an internal +library with the same name as an external dependency if you need to be +able to refer to the external dependency in a +:pkg-field:`build-depends` declaration. + +Shadowing can be used to vendor an external dependency into a package +and thus emulate *private dependencies*. Below is an example based on +a real-world use case: + +:: + + cabal-version: 2.2 + name: haddock-library + version: 1.6.0 + + library + build-depends: + , base ^>= 4.11.1.0 + , bytestring ^>= 0.10.2.0 + , containers ^>= 0.4.2.1 || ^>= 0.5.0.0 + , transformers ^>= 0.5.0.0 + + hs-source-dirs: src + + -- internal sub-lib + build-depends: attoparsec + + exposed-modules: + Documentation.Haddock + + library attoparsec + build-depends: + , base ^>= 4.11.1.0 + , bytestring ^>= 0.10.2.0 + , deepseq ^>= 1.4.0.0 + + hs-source-dirs: vendor/attoparsec-0.13.1.0 + + -- NB: haddock-library needs only small part of lib:attoparsec + -- internally, so we only bundle that subset here + exposed-modules: + Data.Attoparsec.ByteString + Data.Attoparsec.Combinator + + other-modules: + Data.Attoparsec.Internal + + ghc-options: -funbox-strict-fields -Wall -fwarn-tabs -O2 + + +Opening an interpreter session +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +While developing a package, it is often useful to make its code +available inside an interpreter session. This can be done with the +``repl`` command: + +.. code-block:: console + + $ cabal repl + +The name comes from the acronym +`REPL `__, +which stands for "read-eval-print-loop". By default ``cabal repl`` loads +the first component in a package. If the package contains several named +components, the name can be given as an argument to ``repl``. The name +can be also optionally prefixed with the component's type for +disambiguation purposes. Example: + +.. code-block:: console + + $ cabal repl foo + $ cabal repl exe:foo + $ cabal repl test:bar + $ cabal repl bench:baz + +Freezing dependency versions +"""""""""""""""""""""""""""" + +If a package is built in several different environments, such as a +development environment, a staging environment and a production +environment, it may be necessary or desirable to ensure that the same +dependency versions are selected in each environment. This can be done +with the ``freeze`` command: + +.. code-block:: console + + $ cabal freeze + +The command writes the selected version for all dependencies to the +``cabal.config`` file. All environments which share this file will use +the dependency versions specified in it. + +Generating dependency version bounds +"""""""""""""""""""""""""""""""""""" + +Cabal also has the ability to suggest dependency version bounds that +conform to `Package Versioning Policy`_, which is +a recommended versioning system for publicly released Cabal packages. +This is done by running the ``gen-bounds`` command: + +.. code-block:: console + + $ cabal gen-bounds + +For example, given the following dependencies specified in +:pkg-field:`build-depends`: + +:: + + build-depends: + foo == 0.5.2 + bar == 1.1 + +``gen-bounds`` will suggest changing them to the following: + +:: + + build-depends: + foo >= 0.5.2 && < 0.6 + bar >= 1.1 && < 1.2 + +Listing outdated dependency version bounds +"""""""""""""""""""""""""""""""""""""""""" + +Manually updating dependency version bounds in a ``.cabal`` file or a +freeze file can be tedious, especially when there's a lot of +dependencies. The ``cabal outdated`` command is designed to help with +that. It will print a list of packages for which there is a new +version on Hackage that is outside the version bound specified in the +``build-depends`` field. The ``outdated`` command can also be +configured to act on the freeze file (both old- and v2-style) and +ignore major (or all) version bumps on Hackage for a subset of +dependencies. + +The following flags are supported by the ``outdated`` command: + +``--freeze-file`` + Read dependency version bounds from the freeze file (``cabal.config``) + instead of the package description file (``$PACKAGENAME.cabal``). + ``--v1-freeze-file`` is an alias for this flag starting in Cabal 2.4. +``--v2-freeze-file`` + :since: 2.4 + + Read dependency version bounds from the v2-style freeze file + (by default, ``cabal.project.freeze``) instead of the package + description file. ``--new-freeze-file`` is an alias for this flag + that can be used with pre-2.4 ``cabal``. +``--project-file`` *PROJECTFILE* + :since: 2.4 + + Read dependendency version bounds from the v2-style freeze file + related to the named project file (i.e., ``$PROJECTFILE.freeze``) + instead of the package desctription file. If multiple ``--project-file`` + flags are provided, only the final one is considered. This flag + must only be passed in when ``--new-freeze-file`` is present. +``--simple-output`` + Print only the names of outdated dependencies, one per line. +``--exit-code`` + Exit with a non-zero exit code when there are outdated dependencies. +``-q, --quiet`` + Don't print any output. Implies ``-v0`` and ``--exit-code``. +``--ignore`` *PACKAGENAMES* + Don't warn about outdated dependency version bounds for the packages in this + list. +``--minor`` *[PACKAGENAMES]* + Ignore major version bumps for these packages. E.g. if there's a version 2.0 + of a package ``pkg`` on Hackage and the freeze file specifies the constraint + ``pkg == 1.9``, ``cabal outdated --freeze --minor=pkg`` will only consider + the ``pkg`` outdated when there's a version of ``pkg`` on Hackage satisfying + ``pkg > 1.9 && < 2.0``. ``--minor`` can also be used without arguments, in + that case major version bumps are ignored for all packages. + +Examples: + +.. code-block:: console + + $ cd /some/package + $ cabal outdated + Outdated dependencies: + haskell-src-exts <1.17 (latest: 1.19.1) + language-javascript <0.6 (latest: 0.6.0.9) + unix ==2.7.2.0 (latest: 2.7.2.1) + + $ cabal outdated --simple-output + haskell-src-exts + language-javascript + unix + + $ cabal outdated --ignore=haskell-src-exts + Outdated dependencies: + language-javascript <0.6 (latest: 0.6.0.9) + unix ==2.7.2.0 (latest: 2.7.2.1) + + $ cabal outdated --ignore=haskell-src-exts,language-javascript,unix + All dependencies are up to date. + + $ cabal outdated --ignore=haskell-src-exts,language-javascript,unix -q + $ echo $? + 0 + + $ cd /some/other/package + $ cabal outdated --freeze-file + Outdated dependencies: + HTTP ==4000.3.3 (latest: 4000.3.4) + HUnit ==1.3.1.1 (latest: 1.5.0.0) + + $ cabal outdated --freeze-file --ignore=HTTP --minor=HUnit + Outdated dependencies: + HUnit ==1.3.1.1 (latest: 1.3.1.2) + + +Executables +^^^^^^^^^^^ + +.. pkg-section:: executable name + :synopsis: Executable build info section. + + Executable sections (if present) describe executable programs contained + in the package and must have an argument after the section label, which + defines the name of the executable. This is a freeform argument but may + not contain spaces. + +The executable may be described using the following fields, as well as +build information fields (see the section on `build information`_). + +.. pkg-field:: main-is: filename (required) + + The name of the ``.hs`` or ``.lhs`` file containing the ``Main`` + module. Note that it is the ``.hs`` filename that must be listed, + even if that file is generated using a preprocessor. The source file + must be relative to one of the directories listed in + :pkg-field:`hs-source-dirs`. Further, while the name of the file may + vary, the module itself must be named ``Main``. + + Starting with ``cabal-version: 1.18`` this field supports + specifying a C, C++, or objC source file as the main entry point. + +.. pkg-field:: scope: token + :since: 2.0 + + Whether the executable is ``public`` (default) or ``private``, i.e. meant to + be run by other programs rather than the user. Private executables are + installed into `$libexecdir/$libexecsubdir`. + +Running executables +""""""""""""""""""" + +You can have Cabal build and run your executables by using the ``run`` +command: + +.. code-block:: console + + $ cabal run EXECUTABLE [-- EXECUTABLE_FLAGS] + +This command will configure, build and run the executable +``EXECUTABLE``. The double dash separator is required to distinguish +executable flags from ``run``'s own flags. If there is only one +executable defined in the whole package, the executable's name can be +omitted. See the output of ``cabal help run`` for a list of options you +can pass to ``cabal run``. + +Test suites +^^^^^^^^^^^ + +.. pkg-section:: test-suite name + :synopsis: Test suite build information. + + Test suite sections (if present) describe package test suites and must + have an argument after the section label, which defines the name of the + test suite. This is a freeform argument, but may not contain spaces. It + should be unique among the names of the package's other test suites, the + package's executables, and the package itself. Using test suite sections + requires at least Cabal version 1.9.2. + +The test suite may be described using the following fields, as well as +build information fields (see the section on `build information`_). + +.. pkg-field:: type: interface (required) + + The interface type and version of the test suite. Cabal supports two + test suite interfaces, called ``exitcode-stdio-1.0`` and + ``detailed-0.9``. Each of these types may require or disallow other + fields as described below. + +Test suites using the ``exitcode-stdio-1.0`` interface are executables +that indicate test failure with a non-zero exit code when run; they may +provide human-readable log information through the standard output and +error channels. The ``exitcode-stdio-1.0`` type requires the ``main-is`` +field. + +.. pkg-field:: main-is: filename + :synopsis: Module containing tests main function. + + :required: ``exitcode-stdio-1.0`` + :disallowed: ``detailed-0.9`` + + The name of the ``.hs`` or ``.lhs`` file containing the ``Main`` + module. Note that it is the ``.hs`` filename that must be listed, + even if that file is generated using a preprocessor. The source file + must be relative to one of the directories listed in + :pkg-field:`hs-source-dirs`. This field is analogous to the ``main-is`` field + of an executable section. + +Test suites using the ``detailed-0.9`` interface are modules exporting +the symbol ``tests :: IO [Test]``. The ``Test`` type is exported by the +module ``Distribution.TestSuite`` provided by Cabal. For more details, +see the example below. + +The ``detailed-0.9`` interface allows Cabal and other test agents to +inspect a test suite's results case by case, producing detailed human- +and machine-readable log files. The ``detailed-0.9`` interface requires +the :pkg-field:`test-module` field. + +.. pkg-field:: test-module: identifier + + :required: ``detailed-0.9`` + :disallowed: ``exitcode-stdio-1.0`` + + The module exporting the ``tests`` symbol. + +Example: Package using ``exitcode-stdio-1.0`` interface +""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +The example package description and executable source file below +demonstrate the use of the ``exitcode-stdio-1.0`` interface. + +.. code-block:: cabal + :caption: foo.cabal + + Name: foo + Version: 1.0 + License: BSD3 + Cabal-Version: >= 1.9.2 + Build-Type: Simple + + Test-Suite test-foo + type: exitcode-stdio-1.0 + main-is: test-foo.hs + build-depends: base >= 4 && < 5 + +.. code-block:: haskell + :caption: test-foo.hs + + module Main where + + import System.Exit (exitFailure) + + main = do + putStrLn "This test always fails!" + exitFailure + +Example: Package using ``detailed-0.9`` interface +""""""""""""""""""""""""""""""""""""""""""""""""" + +The example package description and test module source file below +demonstrate the use of the ``detailed-0.9`` interface. The test module +also develops a simple implementation of the interface set by +``Distribution.TestSuite``, but in actual usage the implementation would +be provided by the library that provides the testing facility. + +.. code-block:: cabal + :caption: bar.cabal + + Name: bar + Version: 1.0 + License: BSD3 + Cabal-Version: >= 1.9.2 + Build-Type: Simple + + Test-Suite test-bar + type: detailed-0.9 + test-module: Bar + build-depends: base >= 4 && < 5, Cabal >= 1.9.2 && < 2 + + +.. code-block:: haskell + :caption: Bar.hs + + module Bar ( tests ) where + + import Distribution.TestSuite + + tests :: IO [Test] + tests = return [ Test succeeds, Test fails ] + where + succeeds = TestInstance + { run = return $ Finished Pass + , name = "succeeds" + , tags = [] + , options = [] + , setOption = \_ _ -> Right succeeds + } + fails = TestInstance + { run = return $ Finished $ Fail "Always fails!" + , name = "fails" + , tags = [] + , options = [] + , setOption = \_ _ -> Right fails + } + +Running test suites +""""""""""""""""""" + +You can have Cabal run your test suites using its built-in test runner: + +:: + + $ cabal configure --enable-tests + $ cabal build + $ cabal test + +See the output of ``cabal help test`` for a list of options you can pass +to ``cabal test``. + +Benchmarks +^^^^^^^^^^ + +.. pkg-section:: benchmark name + :since: 1.9.2 + :synopsis: Benchmark build information. + + Benchmark sections (if present) describe benchmarks contained in the + package and must have an argument after the section label, which defines + the name of the benchmark. This is a freeform argument, but may not + contain spaces. It should be unique among the names of the package's + other benchmarks, the package's test suites, the package's executables, + and the package itself. Using benchmark sections requires at least Cabal + version 1.9.2. + +The benchmark may be described using the following fields, as well as +build information fields (see the section on `build information`_). + +.. pkg-field:: type: interface (required) + + The interface type and version of the benchmark. At the moment Cabal + only support one benchmark interface, called ``exitcode-stdio-1.0``. + +Benchmarks using the ``exitcode-stdio-1.0`` interface are executables +that indicate failure to run the benchmark with a non-zero exit code +when run; they may provide human-readable information through the +standard output and error channels. + +.. pkg-field:: main-is: filename + + :required: ``exitcode-stdio-1.0`` + + The name of the ``.hs`` or ``.lhs`` file containing the ``Main`` + module. Note that it is the ``.hs`` filename that must be listed, + even if that file is generated using a preprocessor. The source file + must be relative to one of the directories listed in + :pkg-field:`hs-source-dirs`. This field is analogous to the ``main-is`` + field of an executable section. Further, while the name of the file may + vary, the module itself must be named ``Main``. + +Example: Package using ``exitcode-stdio-1.0`` interface +""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +The example package description and executable source file below +demonstrate the use of the ``exitcode-stdio-1.0`` interface. + +.. code-block:: cabal + :caption: foo.cabal + :name: foo-bench.cabal + + Name: foo + Version: 1.0 + License: BSD3 + Cabal-Version: >= 1.9.2 + Build-Type: Simple + + Benchmark bench-foo + type: exitcode-stdio-1.0 + main-is: bench-foo.hs + build-depends: base >= 4 && < 5, time >= 1.1 && < 1.7 + +.. code-block:: haskell + :caption: bench-foo.hs + + {-# LANGUAGE BangPatterns #-} + module Main where + + import Data.Time.Clock + + fib 0 = 1 + fib 1 = 1 + fib n = fib (n-1) + fib (n-2) + + main = do + start <- getCurrentTime + let !r = fib 20 + end <- getCurrentTime + putStrLn $ "fib 20 took " ++ show (diffUTCTime end start) + +Running benchmarks +"""""""""""""""""" + +You can have Cabal run your benchmark using its built-in benchmark +runner: + +:: + + $ cabal configure --enable-benchmarks + $ cabal build + $ cabal bench + +See the output of ``cabal help bench`` for a list of options you can +pass to ``cabal bench``. + +Foreign libraries +^^^^^^^^^^^^^^^^^ + +Foreign libraries are system libraries intended to be linked against +programs written in C or other "foreign" languages. They +come in two primary flavours: dynamic libraries (``.so`` files on Linux, +``.dylib`` files on OSX, ``.dll`` files on Windows, etc.) are linked against +executables when the executable is run (or even lazily during +execution), while static libraries (``.a`` files on Linux/OSX, ``.lib`` +files on Windows) get linked against the executable at compile time. + +Foreign libraries only work with GHC 7.8 and later. + +A typical stanza for a foreign library looks like + +:: + + foreign-library myforeignlib + type: native-shared + lib-version-info: 6:3:2 + + if os(Windows) + options: standalone + mod-def-file: MyForeignLib.def + + other-modules: MyForeignLib.SomeModule + MyForeignLib.SomeOtherModule + build-depends: base >=4.7 && <4.9 + hs-source-dirs: src + c-sources: csrc/MyForeignLibWrapper.c + default-language: Haskell2010 + + +.. pkg-section:: foreign-library name + :since: 2.0 + :synopsis: Foriegn library build information. + + Build information for `foreign libraries`_. + +.. pkg-field:: type: foreign library type + + Cabal recognizes ``native-static`` and ``native-shared`` here, although + we currently only support building `native-shared` libraries. + +.. pkg-field:: options: foreign library option list + + Options for building the foreign library, typically specific to the + specified type of foreign library. Currently we only support + ``standalone`` here. A standalone dynamic library is one that does not + have any dependencies on other (Haskell) shared libraries; without + the ``standalone`` option the generated library would have dependencies + on the Haskell runtime library (``libHSrts``), the base library + (``libHSbase``), etc. Currently, ``standalone`` *must* be used on Windows + and *must not* be used on any other platform. + +.. pkg-field:: mod-def-file: filename + + This option can only be used when creating dynamic Windows libraries + (that is, when using ``native-shared`` and the ``os`` is ``Windows``). If + used, it must be a path to a *module definition file*. The details of + module definition files are beyond the scope of this document; see the + `GHC `_ + manual for some details and some further pointers. + +.. pkg-field:: lib-version-info: current:revision:age + + This field is currently only used on Linux. + + This field specifies a Libtool-style version-info field that sets + an appropriate ABI version for the foreign library. Note that the + three numbers specified in this field do not directly specify the + actual ABI version: ``6:3:2`` results in library version ``4.2.3``. + + With this field set, the SONAME of the library is set, and symlinks + are installed. + + How you should bump this field on an ABI change depends on the + breakage you introduce: + + - Programs using the previous version may use the new version as + drop-in replacement, and programs using the new version can also + work with the previous one. In other words, no recompiling nor + relinking is needed. In this case, bump ``revision`` only, don't + touch current nor age. + - Programs using the previous version may use the new version as + drop-in replacement, but programs using the new version may use + APIs not present in the previous one. In other words, a program + linking against the new version may fail with "unresolved + symbols" if linking against the old version at runtime: set + revision to 0, bump current and age. + - Programs may need to be changed, recompiled, and relinked in + order to use the new version. Bump current, set revision and age + to 0. + + Also refer to the Libtool documentation on the version-info field. + +.. pkg-field:: lib-version-linux: version + + This field is only used on Linux. + + Specifies the library ABI version directly for foreign libraries + built on Linux: so specifying ``4.2.3`` causes a library + ``libfoo.so.4.2.3`` to be built with SONAME ``libfoo.so.4``, and + appropriate symlinks ``libfoo.so.4`` and ``libfoo.so`` to be + installed. + +Note that typically foreign libraries should export a way to initialize +and shutdown the Haskell runtime. In the example above, this is done by +the ``csrc/MyForeignLibWrapper.c`` file, which might look something like + +.. code-block:: c + + #include + #include "HsFFI.h" + + HsBool myForeignLibInit(void){ + int argc = 2; + char *argv[] = { "+RTS", "-A32m", NULL }; + char **pargv = argv; + + // Initialize Haskell runtime + hs_init(&argc, &pargv); + + // do any other initialization here and + // return false if there was a problem + return HS_BOOL_TRUE; + } + + void myForeignLibExit(void){ + hs_exit(); + } + +With modern ghc regular libraries are installed in directories that contain +package keys. This isn't usually a problem because the package gets registered +in ghc's package DB and so we can figure out what the location of the library +is. Foreign libraries however don't get registered, which means that we'd have +to have a way of finding out where a platform library got installed (other than by +searching the ``lib/`` directory). Instead, we install foreign libraries in +``~/.cabal/lib``, much like we install executables in ``~/.cabal/bin``. + +Build information +^^^^^^^^^^^^^^^^^ +.. pkg-section:: None + +The following fields may be optionally present in a library, executable, +test suite or benchmark section, and give information for the building +of the corresponding library or executable. See also the sections on +`system-dependent parameters`_ and `configurations`_ for a way to supply +system-dependent values for these fields. + +.. pkg-field:: build-depends: library list + + Declares the *library* dependencies required to build the current + package component; see :pkg-field:`build-tool-depends` for + declaring build-time *tool* dependencies. External library + dependencies should be annotated with a version constraint. + + **Library Names** + + External libraries are identified by the package's name they're + provided by (currently a package can only publicly expose its + main library compeonent; in future, packages with multiple exposed + public library components will be supported and a syntax for + referring to public sub-libraries will be provided). + + In order to specify an intra-package dependency on an internal + library component you can use the unqualified name of the + component library component. Note that locally defined sub-library + names shadow external package names of the same name. See section on + :ref:`Internal Libraries ` for examples and more information. + + **Version Constraints** + + Version constraints use the operators ``==, >=, >, <, <=`` and a + version number. Multiple constraints can be combined using ``&&`` or + ``||``. If no version constraint is specified, any version is + assumed to be acceptable. For example: + + :: + + library + build-depends: + base >= 2, + foo >= 1.2.3 && < 1.3, + bar + + Dependencies like ``foo >= 1.2.3 && < 1.3`` turn out to be very + common because it is recommended practise for package versions to + correspond to API versions (see PVP_). + + Since Cabal 1.6, there is a special wildcard syntax to help with + such ranges + + :: + + build-depends: foo ==1.2.* + + It is only syntactic sugar. It is exactly equivalent to + ``foo >= 1.2 && < 1.3``. + + .. Warning:: + + A potential pitfall of the wildcard syntax is that the + constraint ``nats == 1.0.*`` doesn't match the release + ``nats-1`` because the version ``1`` is lexicographically less + than ``1.0``. This is not an issue with the caret-operator + ``^>=`` described below. + + Starting with Cabal 2.0, there's a new version operator to express + PVP_-style major upper bounds conveniently, and is inspired by similar + syntactic sugar found in other language ecosystems where it's often + called the "Caret" operator: + + :: + + build-depends: + foo ^>= 1.2.3.4, + bar ^>= 1 + + This allows to assert the positive knowledge that this package is + *known* to be semantically compatible with the releases + ``foo-1.2.3.4`` and ``bar-1`` respectively. The information + encoded via such ``^>=``-assertions is used by the cabal solver to + infer version constraints describing semantically compatible + version ranges according to the PVP_ contract (see below). + + Another way to say this is that ``foo < 1.3`` expresses *negative* + information, i.e. "``foo-1.3`` or ``foo-1.4.2`` will *not* be + compatible"; whereas ``foo ^>= 1.2.3.4`` asserts the *positive* + information that "``foo-1.2.3.4`` is *known* to be compatible" and (in + the absence of additional information) according to the PVP_ + contract we can (positively) infer right away that all versions + satisfying ``foo >= 1.2.3.4 && < 1.3`` will be compatible as well. + + .. Note:: + + More generally, the PVP_ contract implies that we can safely + relax the lower bound to ``>= 1.2``, because if we know that + ``foo-1.2.3.4`` is semantically compatible, then so is + ``foo-1.2`` (if it typechecks). But we'd need to perform + additional static analysis (i.e. perform typechecking) in order + to know if our package in the role of an API consumer will + successfully typecheck against the dependency ``foo-1.2``. But + since we cannot do this analysis during constraint solving and + to keep things simple, we pragmatically use ``foo >= 1.2.3.4`` + as the initially inferred approximation for the lower bound + resulting from the assertion ``foo ^>= 1.2.3.4``. If further + evidence becomes available that e.g. ``foo-1.2`` typechecks, + one can simply revise the dependency specification to include + the assertion ``foo ^>= 1.2``. + + The subtle but important difference in signaling allows tooling to + treat explicitly expressed ``<``-style constraints and inferred + (``^>=``-style) upper bounds differently. For instance, + :option:`--allow-newer`'s ``^``-modifier allows to relax only + ``^>=``-style bounds while leaving explicitly stated + ``<``-constraints unaffected. + + Ignoring the signaling intent, the default syntactic desugaring rules are + + - ``^>= x`` == ``>= x && < x.1`` + - ``^>= x.y`` == ``>= x.y && < x.(y+1)`` + - ``^>= x.y.z`` == ``>= x.y.z && < x.(y+1)`` + - ``^>= x.y.z.u`` == ``>= x.y.z.u && < x.(y+1)`` + - etc. + + .. Note:: + + One might expected the desugaring to truncate all version + components below (and including) the patch-level, i.e. + ``^>= x.y.z.u`` == ``>= x.y.z && < x.(y+1)``, + as the major and minor version components alone are supposed to + uniquely identify the API according to the PVP_. However, by + designing ``^>=`` to be closer to the ``>=`` operator, we avoid + the potentially confusing effect of ``^>=`` being more liberal + than ``>=`` in the presence of patch-level versions. + + Consequently, the example declaration above is equivalent to + + :: + + build-depends: + foo >= 1.2.3.4 && < 1.3, + bar >= 1 && < 1.1 + + .. Note:: + + Prior to Cabal 1.8, ``build-depends`` specified in each + section were global to all sections. This was unintentional, but + some packages were written to depend on it, so if you need your + :pkg-field:`build-depends` to be local to each section, you must specify + at least ``Cabal-Version: >= 1.8`` in your ``.cabal`` file. + + .. Note:: + + Cabal 1.20 experimentally supported module thinning and + renaming in ``build-depends``; however, this support has since been + removed and should not be used. + + Starting with Cabal 3.0, a set notation for the ``==`` and ``^>=`` operator + is available. For instance, + + :: + + tested-with: GHC == 8.6.3, GHC == 8.4.4, GHC == 8.2.2, GHC == 8.0.2, + GHC == 7.10.3, GHC == 7.8.4, GHC == 7.6.3, GHC == 7.4.2 + + build-depends: network ^>= 2.6.3.6 || ^>= 2.7.0.2 || ^>= 2.8.0.0 || ^>= 3.0.1.0 + + can be then written in a more convenient and concise form + + :: + + tested-with: GHC == { 8.6.3, 8.4.4, 8.2.2, 8.0.2, 7.10.3, 7.8.4, 7.6.3, 7.4.2 } + + build-depends: network ^>= { 2.6.3.6, 2.7.0.2, 2.8.0.0, 3.0.1.0 } + + +.. pkg-field:: other-modules: identifier list + + A list of modules used by the component but not exposed to users. + For a library component, these would be hidden modules of the + library. For an executable, these would be auxiliary modules to be + linked with the file named in the ``main-is`` field. + + .. Note:: + + Every module in the package *must* be listed in one of + :pkg-field:`other-modules`, :pkg-field:`library:exposed-modules` or + :pkg-field:`executable:main-is` fields. + +.. pkg-field:: hs-source-dir: directory list + :deprecated: 2.0 + :removed: 3.0 + + :default: ``.`` + + Root directories for the module hierarchy. + + Deprecated in favor of :pkg-field:`hs-source-dirs`. + +.. pkg-field:: hs-source-dirs: directory list + + :default: ``.`` + + Root directories for the module hierarchy. + + .. note:: + + Components can share source directories but modules found there will be + recompiled even if other components already built them, i.e., if a + library and an executable share a source directory and the executable + depends on the library and imports its ``Foo`` module, ``Foo`` will be + compiled twice, once as part of the library and again for the executable. + +.. pkg-field:: default-extensions: identifier list + + A list of Haskell extensions used by every module. These determine + corresponding compiler options enabled for all files. Extension + names are the constructors of the + `Extension <../release/cabal-latest/doc/API/Cabal/Language-Haskell-Extension.html#t:Extension>`__ + type. For example, ``CPP`` specifies that Haskell source files are + to be preprocessed with a C preprocessor. + +.. pkg-field:: other-extensions: identifier list + + A list of Haskell extensions used by some (but not necessarily all) + modules. From GHC version 6.6 onward, these may be specified by + placing a ``LANGUAGE`` pragma in the source files affected e.g. + + .. code-block:: haskell + + {-# LANGUAGE CPP, MultiParamTypeClasses #-} + + In Cabal-1.24 the dependency solver will use this and + :pkg-field:`default-extensions` information. Cabal prior to 1.24 will abort + compilation if the current compiler doesn't provide the extensions. + + If you use some extensions conditionally, using CPP or conditional + module lists, it is good to replicate the condition in + :pkg-field:`other-extensions` declarations: + + :: + + other-extensions: CPP + if impl(ghc >= 7.5) + other-extensions: PolyKinds + + You could also omit the conditionally used extensions, as they are + for information only, but it is recommended to replicate them in + :pkg-field:`other-extensions` declarations. + +.. pkg-field:: extensions: identifier list + :deprecated: 1.12 + :removed: 3.0 + + Deprecated in favor of :pkg-field:`default-extensions`. + +.. pkg-field:: build-tool-depends: package:executable list + :since: 2.0 + + A list of Haskell executables needed to build this component. Executables are provided + during the whole duration of the component, so this field can be used for executables + needed during :pkg-section:`test-suite` as well. + + Each is specified by the package containing the executable and the name of the + executable itself, separated by a colon, and optionally followed by a version bound. + + All executables defined in the given Cabal file are termed as *internal* dependencies + as opposed to the rest which are *external* dependencies. + + Each of the two is handled differently: + + 1. External dependencies can (and should) contain a version bound like conventional + :pkg-field:`build-depends` dependencies. + 2. Internal depenedencies should not contain a version bound, as they will be always + resolved within the same configuration of the package in the build plan. + Specifically, version bounds that include the package's version will be warned for + being extraneous, and version bounds that exclude the package's version will raise + an error for being impossible to follow. + + For example (1) using a test-suite to make sure README.md Haskell snippets are tested using + `markdown-unlit `__: + + :: + + build-tool-depends: markdown-unlit:markdown-unlit >= 0.5.0 && < 0.6 + + For example (2) using a test-suite to test executable behaviour in the same package: + + :: + + build-tool-depends: mypackage:executable + + Cabal tries to make sure that all specified programs are atomically built and prepended + on the ``$PATH`` shell variable before building the component in question, but can only do + so for Nix-style builds. Specifically: + + a) For Nix-style local builds, both internal and external dependencies. + b) For old-style builds, only for internal dependencies [#old-style-build-tool-depends]_. + It's up to the user to provide needed executables in this case under `$PATH.` + + + .. note:: + + :pkg-field:`build-tool-depends` was added in Cabal 2.0, and it will + be ignored (with a warning) with old versions of Cabal. See + :pkg-field:`build-tools` for more information about backwards + compatibility. + +.. pkg-field:: build-tools: program list + :deprecated: 2.0 + :removed: 3.0 + + Deprecated in favor of :pkg-field:`build-tool-depends`, but :ref:`see below for backwards compatibility information `. + + A list of Haskell programs needed to build this component. + Each may be followed by an optional version bound. + Confusingly, each program in the list either refer to one of three things: + + 1. Another executables in the same package (supported since Cabal 1.12) + + 2. Tool name contained in Cabal's :ref:`hard-coded set of common tools ` + + 3. A pre-built executable that should already be on the ``PATH`` + (supported since Cabal 2.0) + + These cases are listed in order of priority: + an executable in the package will override any of the hard-coded packages with the same name, + and a hard-coded package will override any executable on the ``PATH``. + + In the first two cases, the list entry is desugared into a :pkg-field:`build-tool-depends` entry. + In the first case, the entry is desugared into a :pkg-field:`build-tool-depends` entry by prefixing with ``$pkg:``. + In the second case, it is desugared by looking up the package and executable name in a hard-coded table. + In either case, the optional version bound is passed through unchanged. + Refer to the documentation for :pkg-field:`build-tool-depends` to understand the desugared field's meaning, along with restrictions on version bounds. + + .. _buildtoolsbc: + + **Backward Compatibility** + + Although this field is deprecated in favor of :pkg-field:`build-tool-depends`, there are some situations where you may prefer to use :pkg-field:`build-tools` in cases (1) and (2), as it is supported by more versions of Cabal. + In case (3), :pkg-field:`build-tool-depends` is better for backwards-compatibility, as it will be ignored by old versions of Cabal; if you add the executable to :pkg-field:`build-tools`, a setup script built against old Cabal will choke. + If an old version of Cabal is used, an end-user will have to manually arrange for the requested executable to be in your ``PATH``. + + .. _buildtoolsmap: + + **Set of Known Tool Names** + + Identifiers specified in :pkg-field:`build-tools` are desugared into their respective equivalent :pkg-field:`build-tool-depends` form according to the table below. Consequently, a legacy specification such as:: + + build-tools: alex >= 3.2.1 && < 3.3, happy >= 1.19.5 && < 1.20 + + is simply desugared into the equivalent specification:: + + build-tool-depends: alex:alex >= 3.2.1 && < 3.3, happy:happy >= 1.19.5 && < 1.20 + + +--------------------------+-----------------------------------+-----------------+ + | :pkg-field:`build-tools` | desugared | Note | + | identifier | :pkg-field:`build-tool-depends` | | + | | identifier | | + +==========================+===================================+=================+ + | ``alex`` | ``alex:alex`` | | + +--------------------------+-----------------------------------+-----------------+ + | ``c2hs`` | ``c2hs:c2hs`` | | + +--------------------------+-----------------------------------+-----------------+ + | ``cpphs`` | ``cpphs:cpphs`` | | + +--------------------------+-----------------------------------+-----------------+ + | ``greencard`` | ``greencard:greencard`` | | + +--------------------------+-----------------------------------+-----------------+ + | ``haddock`` | ``haddock:haddock`` | | + +--------------------------+-----------------------------------+-----------------+ + | ``happy`` | ``happy:happy`` | | + +--------------------------+-----------------------------------+-----------------+ + | ``hsc2hs`` | ``hsc2hs:hsc2hs`` | | + +--------------------------+-----------------------------------+-----------------+ + | ``hscolour`` | ``hscolour:hscolour`` | | + +--------------------------+-----------------------------------+-----------------+ + | ``hspec-discover`` | ``hspec-discover:hspec-discover`` | since Cabal 2.0 | + +--------------------------+-----------------------------------+-----------------+ + + This built-in set can be programmatically extended via ``Custom`` setup scripts; this, however, is of limited use since the Cabal solver cannot access information injected by ``Custom`` setup scripts. + +.. pkg-field:: buildable: boolean + + :default: ``True`` + + Is the component buildable? Like some of the other fields below, + this field is more useful with the slightly more elaborate form of + the simple build infrastructure described in the section on + `system-dependent parameters`_. + +.. pkg-field:: ghc-options: token list + + Additional options for GHC. You can often achieve the same effect + using the :pkg-field:`default-extensions` field, which is preferred. + + Options required only by one module may be specified by placing an + ``OPTIONS_GHC`` pragma in the source file affected. + + As with many other fields, whitespace can be escaped by using + Haskell string syntax. Example: + ``ghc-options: -Wcompat "-with-rtsopts=-T -I1" -Wall``. + +.. pkg-field:: ghc-prof-options: token list + + Additional options for GHC when the package is built with profiling + enabled. + + Note that as of Cabal-1.24, the default profiling detail level + defaults to ``exported-functions`` for libraries and + ``toplevel-functions`` for executables. For GHC these correspond to + the flags ``-fprof-auto-exported`` and ``-fprof-auto-top``. Prior to + Cabal-1.24 the level defaulted to ``none``. These levels can be + adjusted by the person building the package with the + ``--profiling-detail`` and ``--library-profiling-detail`` flags. + + It is typically better for the person building the package to pick + the profiling detail level rather than for the package author. So + unless you have special needs it is probably better not to specify + any of the GHC ``-fprof-auto*`` flags here. However if you wish to + override the profiling detail level, you can do so using the + :pkg-field:`ghc-prof-options` field: use ``-fno-prof-auto`` or one of the + other ``-fprof-auto*`` flags. + +.. pkg-field:: ghc-shared-options: token list + + Additional options for GHC when the package is built as shared + library. The options specified via this field are combined with the + ones specified via :pkg-field:`ghc-options`, and are passed to GHC during + both the compile and link phases. + +.. pkg-field:: includes: filename list + + A list of header files to be included in any compilations via C. + This field applies to both header files that are already installed + on the system and to those coming with the package to be installed. + The former files should be found in absolute paths, while the latter + files should be found in paths relative to the top of the source + tree or relative to one of the directories listed in + :pkg-field:`include-dirs`. + + These files typically contain function prototypes for foreign + imports used by the package. This is in contrast to + :pkg-field:`install-includes`, which lists header files that are intended + to be exposed to other packages that transitively depend on this + library. + +.. pkg-field:: install-includes: filename list + + A list of header files from this package to be installed into + ``$libdir/includes`` when the package is installed. Files listed in + :pkg-field:`install-includes` should be found in relative to the top of the + source tree or relative to one of the directories listed in + :pkg-field:`include-dirs`. + + :pkg-field:`install-includes` is typically used to name header files that + contain prototypes for foreign imports used in Haskell code in this + package, for which the C implementations are also provided with the + package. For example, here is a ``.cabal`` file for a hypothetical + ``bindings-clib`` package that bundles the C source code for ``clib``:: + + include-dirs: cbits + c-sources: clib.c + install-includes: clib.h + + Now any package that depends (directly or transitively) on the + ``bindings-clib`` library can use ``clib.h``. + + Note that in order for files listed in :pkg-field:`install-includes` to be + usable when compiling the package itself, they need to be listed in + the :pkg-field:`includes` field as well. + +.. pkg-field:: include-dirs: directory list + + A list of directories to search for header files, when preprocessing + with ``c2hs``, ``hsc2hs``, ``cpphs`` or the C preprocessor, and also + when compiling via C. Directories can be absolute paths (e.g., for + system directories) or paths that are relative to the top of the + source tree. Cabal looks in these directories when attempting to + locate files listed in :pkg-field:`includes` and + :pkg-field:`install-includes`. + +.. pkg-field:: c-sources: filename list + + A list of C source files to be compiled and linked with the Haskell + files. + +.. pkg-field:: cxx-sources: filename list + :since: 2.2 + + A list of C++ source files to be compiled and linked with the Haskell + files. Useful for segregating C and C++ sources when supplying different + command-line arguments to the compiler via the :pkg-field:`cc-options` + and the :pkg-field:`cxx-options` fields. The files listed in the + :pkg-field:`cxx-sources` can reference files listed in the + :pkg-field:`c-sources` field and vice-versa. The object files will be linked + appropriately. + +.. pkg-field:: asm-sources: filename list + :since: 3.0 + + A list of assembly source files to be compiled and linked with the + Haskell files. + +.. pkg-field:: cmm-sources: filename list + :since: 3.0 + + A list of C-- source files to be compiled and linked with the Haskell + files. + +.. pkg-field:: js-sources: filename list + + A list of JavaScript source files to be linked with the Haskell + files (only for JavaScript targets). + +.. pkg-field:: extra-libraries: token list + + A list of extra libraries to link with. + +.. pkg-field:: extra-ghci-libraries: token list + + A list of extra libraries to be used instead of 'extra-libraries' + when the package is loaded with GHCi. + +.. pkg-field:: extra-bundled-libraries: token list + :since: 2.2 + + A list of libraries that are supposed to be copied from the build + directory alongside the produced Haskell libraries. Note that you + are under the obligation to produce those libraries in the build + directory (e.g. via a custom setup). Libraries listed here will + be included when ``copy``-ing packages and be listed in the + ``hs-libraries`` of the package configuration in the package database. + Library names must either be prefixed with "HS" or "C" and corresponding + library file names must match: + + - Libraries with name "HS": + - `libHS.a` + - `libHS-ghc.*` + - Libraries with name "C": + - `libC.a` + - `lib.*` + +.. pkg-field:: extra-lib-dirs: directory list + + A list of directories to search for libraries. + +.. pkg-field:: cc-options: token list + + Command-line arguments to be passed to the C compiler. Since the + arguments are compiler-dependent, this field is more useful with the + setup described in the section on `system-dependent parameters`_. + +.. pkg-field:: cpp-options: token list + + Command-line arguments for pre-processing Haskell code. Applies to + Haskell source and other pre-processed Haskell source like .hsc + .chs. Does not apply to C code, that's what cc-options is for. + +.. pkg-field:: cxx-options: token list + :since: 2.2 + + Command-line arguments to be passed to the compiler when compiling + C++ code. The C++ sources to which these command-line arguments + should be applied can be specified with the :pkg-field:`cxx-sources` + field. Command-line options for C and C++ can be passed separately to + the compiler when compiling both C and C++ sources by segregating the C + and C++ sources with the :pkg-field:`c-sources` and + :pkg-field:`cxx-sources` fields respectively, and providing different + command-line arguments with the :pkg-field:`cc-options` and the + :pkg-field:`cxx-options` fields. + +.. pkg-field:: cmm-options: token list + :since: 3.0 + + Command-line arguments to be passed to the compiler when compiling + C-- code. See also :pkg-field:`cmm-sources`. + +.. pkg-field:: asm-options: token list + :since: 3.0 + + Command-line arguments to be passed to the assembler when compiling + assembler code. See also :pkg-field:`asm-sources`. + +.. pkg-field:: ld-options: token list + + Command-line arguments to be passed to the linker. Since the + arguments are compiler-dependent, this field is more useful with the + setup described in the section on `system-dependent parameters`_. + +.. pkg-field:: pkgconfig-depends: package list + + A list of + `pkg-config `__ + packages, needed to build this package. They can be annotated with + versions, e.g. ``gtk+-2.0 >= 2.10, cairo >= 1.0``. If no version + constraint is specified, any version is assumed to be acceptable. + Cabal uses ``pkg-config`` to find if the packages are available on + the system and to find the extra compilation and linker options + needed to use the packages. + + If you need to bind to a C library that supports ``pkg-config`` then + it is much preferable to use this field rather than hard code options + into the other fields. ``pkg-config --list-all`` will show you all + supported libraries. Depending on your system you may need to adjust + ``PKG_CONFIG_PATH``. + +.. pkg-field:: frameworks: token list + + On Darwin/MacOS X, a list of frameworks to link to. See Apple's + developer documentation for more details on frameworks. This entry + is ignored on all other platforms. + +.. pkg-field:: extra-frameworks-dirs: directory list + :since: 1.24 + + On Darwin/MacOS X, a list of directories to search for frameworks. + This entry is ignored on all other platforms. + +.. pkg-field:: mixins: mixin list + :since: 2.0 + + Supported only in GHC 8.2 and later. A list of packages mentioned in the + :pkg-field:`build-depends` field, each optionally accompanied by a list of + module and module signature renamings. + + The simplest mixin syntax is simply the name of a package mentioned in the + :pkg-field:`build-depends` field. For example: + + :: + + library + build-depends: + foo ^>= 1.2.3 + mixins: + foo + + But this doesn't have any effect. More interesting is to use the mixin + entry to rename one or more modules from the package, like this: + + :: + + library + mixins: + foo (Foo.Bar as AnotherFoo.Bar, Foo.Baz as AnotherFoo.Baz) + + Note that renaming a module like this will hide all the modules + that are not explicitly named. + + Modules can also be hidden: + + :: + + library: + mixins: + foo hiding (Foo.Bar) + + Hiding modules exposes everything that is not explicitly hidden. + + .. Note:: + + The current version of Cabal suffers from an infelicity in how the + entries of :pkg-field:`mixins` are parsed: an entry will fail to parse + if the provided renaming clause has whitespace after the opening + parenthesis. This will be fixed in future versions of Cabal. + + See issues :issue:`5150`, :issue:`4864`, and :issue:`5293`. + + There can be multiple mixin entries for a given package, in effect creating + multiple copies of the dependency: + + :: + + library + mixins: + foo (Foo.Bar as AnotherFoo.Bar, Foo.Baz as AnotherFoo.Baz), + foo (Foo.Bar as YetAnotherFoo.Bar) + + The ``requires`` clause is used to rename the module signatures required by + a package: + + :: + + library + mixins: + foo (Foo.Bar as AnotherFoo.Bar) requires (Foo.SomeSig as AnotherFoo.SomeSig) + + Signature-only packages don't have any modules, so only the signatures can + be renamed, with the following syntax: + + :: + + library + mixins: + sigonly requires (SigOnly.SomeSig as AnotherSigOnly.SomeSig) + + See the :pkg-field:`library:signatures` field for more details. + + Mixin packages are part of the Backpack_ extension to the + Haskell module system. + + The matching of the module signatures required by a + :pkg-field:`build-depends` dependency with the implementation modules + present in another dependency is triggered by a coincidence of names. When + the names of the signature and of the implementation are already the same, + the matching is automatic. But when the names don't coincide, or we want to + instantiate a signature in two different ways, adding mixin entries that + perform renamings becomes necessary. + + .. Warning:: + + Backpack_ has the limitation that implementation modules that instantiate + signatures required by a :pkg-field:`build-depends` dependency can't + reside in the same component that has the dependency. They must reside + in a different package dependency, or at least in a separate internal + library. + +Configurations +^^^^^^^^^^^^^^ + +Library and executable sections may include conditional blocks, which +test for various system parameters and configuration flags. The flags +mechanism is rather generic, but most of the time a flag represents +certain feature, that can be switched on or off by the package user. +Here is an example package description file using configurations: + +Example: A package containing a library and executable programs +""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +:: + + Name: Test1 + Version: 0.0.1 + Cabal-Version: >= 1.8 + License: BSD3 + Author: Jane Doe + Synopsis: Test package to test configurations + Category: Example + Build-Type: Simple + + Flag Debug + Description: Enable debug support + Default: False + Manual: True + + Flag WebFrontend + Description: Include API for web frontend. + Default: False + Manual: True + + Flag NewDirectory + description: Whether to build against @directory >= 1.2@ + -- This is an automatic flag which the solver will be + -- assign automatically while searching for a solution + + Library + Build-Depends: base >= 4.2 && < 4.9 + Exposed-Modules: Testing.Test1 + Extensions: CPP + + GHC-Options: -Wall + if flag(Debug) + CPP-Options: -DDEBUG + if !os(windows) + CC-Options: "-DDEBUG" + else + CC-Options: "-DNDEBUG" + + if flag(WebFrontend) + Build-Depends: cgi >= 0.42 && < 0.44 + Other-Modules: Testing.WebStuff + CPP-Options: -DWEBFRONTEND + + if flag(NewDirectory) + build-depends: directory >= 1.2 && < 1.4 + Build-Depends: time >= 1.0 && < 1.9 + else + build-depends: directory == 1.1.* + Build-Depends: old-time >= 1.0 && < 1.2 + + Executable test1 + Main-is: T1.hs + Other-Modules: Testing.Test1 + Build-Depends: base >= 4.2 && < 4.9 + + if flag(debug) + CC-Options: "-DDEBUG" + CPP-Options: -DDEBUG + +Layout +"""""" + +Flags, conditionals, library and executable sections use layout to +indicate structure. This is very similar to the Haskell layout rule. +Entries in a section have to all be indented to the same level which +must be more than the section header. Tabs are not allowed to be used +for indentation. + +As an alternative to using layout you can also use explicit braces +``{}``. In this case the indentation of entries in a section does not +matter, though different fields within a block must be on different +lines. Here is a bit of the above example again, using braces: + +Example: Using explicit braces rather than indentation for layout +""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +:: + + Name: Test1 + Version: 0.0.1 + Cabal-Version: >= 1.8 + License: BSD3 + Author: Jane Doe + Synopsis: Test package to test configurations + Category: Example + Build-Type: Simple + + Flag Debug { + Description: Enable debug support + Default: False + Manual: True + } + + Library { + Build-Depends: base >= 4.2 && < 4.9 + Exposed-Modules: Testing.Test1 + Extensions: CPP + if flag(debug) { + CPP-Options: -DDEBUG + if !os(windows) { + CC-Options: "-DDEBUG" + } else { + CC-Options: "-DNDEBUG" + } + } + } + +Configuration Flags +""""""""""""""""""" + +.. pkg-section:: flag name + :synopsis: Flag declaration. + + Flag section declares a flag which can be used in `conditional blocks`_. + + Flag names are case-insensitive and must match ``[[:alnum:]_][[:alnum:]_-]*`` + regular expression, or expressed as ABNF_: + + .. code-block:: abnf + + flag-name = (UALNUM / "_") *(UALNUM / "_" / "-") + + UALNUM = UALPHA / DIGIT + UALPHA = ... ; set of alphabetic Unicode code-points + + .. note:: + + Hackage accepts ASCII-only flags, ``[a-zA-Z0-9_][a-zA-Z0-9_-]*`` regexp. + +.. pkg-field:: description: freeform + + The description of this flag. + +.. pkg-field:: default: boolean + + :default: ``True`` + + The default value of this flag. + + .. note:: + + This value may be `overridden in several + ways `__. The + rationale for having flags default to True is that users usually + want new features as soon as they are available. Flags representing + features that are not (yet) recommended for most users (such as + experimental features or debugging support) should therefore + explicitly override the default to False. + +.. pkg-field:: manual: boolean + + :default: ``False`` + :since: 1.6 + + By default, Cabal will first try to satisfy dependencies with the + default flag value and then, if that is not possible, with the + negated value. However, if the flag is manual, then the default + value (which can be overridden by commandline flags) will be used. + +Conditional Blocks +^^^^^^^^^^^^^^^^^^ + +Conditional blocks may appear anywhere inside a library or executable +section. They have to follow rather strict formatting rules. Conditional +blocks must always be of the shape + +:: + + if condition + property-descriptions-or-conditionals + +or + +:: + + if condition + property-descriptions-or-conditionals + else + property-descriptions-or-conditionals + +Note that the ``if`` and the condition have to be all on the same line. + +Since Cabal 2.2 conditional blocks support ``elif`` construct. + +:: + + if condition1 + property-descriptions-or-conditionals + elif condition2 + property-descriptions-or-conditionals + else + property-descriptions-or-conditionals + +Conditions +"""""""""" + +Conditions can be formed using boolean tests and the boolean operators +``||`` (disjunction / logical "or"), ``&&`` (conjunction / logical +"and"), or ``!`` (negation / logical "not"). The unary ``!`` takes +highest precedence, ``||`` takes lowest. Precedence levels may be +overridden through the use of parentheses. For example, +``os(darwin) && !arch(i386) || os(freebsd)`` is equivalent to +``(os(darwin) && !(arch(i386))) || os(freebsd)``. + +The following tests are currently supported. + +:samp:`os({name})` + Tests if the current operating system is *name*. The argument is + tested against ``System.Info.os`` on the target system. There is + unfortunately some disagreement between Haskell implementations + about the standard values of ``System.Info.os``. Cabal canonicalises + it so that in particular ``os(windows)`` works on all + implementations. If the canonicalised os names match, this test + evaluates to true, otherwise false. The match is case-insensitive. +:samp:`arch({name})` + Tests if the current architecture is *name*. The argument is matched + against ``System.Info.arch`` on the target system. If the arch names + match, this test evaluates to true, otherwise false. The match is + case-insensitive. +:samp:`impl({compiler})` + Tests for the configured Haskell implementation. An optional version + constraint may be specified (for example ``impl(ghc >= 6.6.1)``). If + the configured implementation is of the right type and matches the + version constraint, then this evaluates to true, otherwise false. + The match is case-insensitive. + + Note that including a version constraint in an ``impl`` test causes + it to check for two properties: + + - The current compiler has the specified name, and + + - The compiler's version satisfied the specified version constraint + + As a result, ``!impl(ghc >= x.y.z)`` is not entirely equivalent to + ``impl(ghc < x.y.z)``. The test ``!impl(ghc >= x.y.z)`` checks that: + + - The current compiler is not GHC, or + + - The version of GHC is earlier than version x.y.z. + +:samp:`flag({name})` + Evaluates to the current assignment of the flag of the given name. + Flag names are case insensitive. Testing for flags that have not + been introduced with a flag section is an error. +``true`` + Constant value true. +``false`` + Constant value false. + +Resolution of Conditions and Flags +"""""""""""""""""""""""""""""""""" + +If a package descriptions specifies configuration flags the package user +can `control these in several +ways `__. If the +user does not fix the value of a flag, Cabal will try to find a flag +assignment in the following way. + +- For each flag specified, it will assign its default value, evaluate + all conditions with this flag assignment, and check if all + dependencies can be satisfied. If this check succeeded, the package + will be configured with those flag assignments. + +- If dependencies were missing, the last flag (as by the order in which + the flags were introduced in the package description) is tried with + its alternative value and so on. This continues until either an + assignment is found where all dependencies can be satisfied, or all + possible flag assignments have been tried. + +To put it another way, Cabal does a complete backtracking search to find +a satisfiable package configuration. It is only the dependencies +specified in the :pkg-field:`build-depends` field in conditional blocks that +determine if a particular flag assignment is satisfiable +(:pkg-field:`build-tools` are not considered). The order of the declaration and +the default value of the flags determines the search order. Flags +overridden on the command line fix the assignment of that flag, so no +backtracking will be tried for that flag. + +If no suitable flag assignment could be found, the configuration phase +will fail and a list of missing dependencies will be printed. Note that +this resolution process is exponential in the worst case (i.e., in the +case where dependencies cannot be satisfied). There are some +optimizations applied internally, but the overall complexity remains +unchanged. + +Meaning of field values when using conditionals +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +During the configuration phase, a flag assignment is chosen, all +conditionals are evaluated, and the package description is combined into +a flat package descriptions. If the same field both inside a conditional +and outside then they are combined using the following rules. + +- Boolean fields are combined using conjunction (logical "and"). + +- List fields are combined by appending the inner items to the outer + items, for example + + :: + + other-extensions: CPP + if impl(ghc) + other-extensions: MultiParamTypeClasses + + when compiled using GHC will be combined to + + :: + + other-extensions: CPP, MultiParamTypeClasses + + Similarly, if two conditional sections appear at the same nesting + level, properties specified in the latter will come after properties + specified in the former. + +- All other fields must not be specified in ambiguous ways. For example + + :: + + Main-is: Main.hs + if flag(useothermain) + Main-is: OtherMain.hs + + will lead to an error. Instead use + + :: + + if flag(useothermain) + Main-is: OtherMain.hs + else + Main-is: Main.hs + +Common stanzas +^^^^^^^^^^^^^^ + +.. pkg-section:: common name + :since: 2.2 + :synopsis: Common build info section + +Starting with Cabal-2.2 it's possible to use common build info stanzas. + +:: + + common deps + build-depends: base ^>= 4.11 + ghc-options: -Wall + + common test-deps + build-depends: tasty ^>= 0.12.0.1 + + library + import: deps + exposed-modules: Foo + + test-suite tests + import: deps, test-deps + type: exitcode-stdio-1.0 + main-is: Tests.hs + build-depends: foo + +- You can use `build information`_ fields in common stanzas. + +- Common stanzas must be defined before use. + +- Common stanzas can import other common stanzas. + +- You can import multiple stanzas at once. Stanza names must be separated by commas. + +- ``import`` must be the first field in a section. Since Cabal 3.0 imports + are also allowed inside conditionals. + +.. Note:: + + The name `import` was chosen, because there is ``includes`` field. + +Source Repositories +^^^^^^^^^^^^^^^^^^^ + +.. pkg-section:: source-repository + :since: 1.6 + +It is often useful to be able to specify a source revision control +repository for a package. Cabal lets you specifying this information in +a relatively structured form which enables other tools to interpret and +make effective use of the information. For example the information +should be sufficient for an automatic tool to checkout the sources. + +Cabal supports specifying different information for various common +source control systems. Obviously not all automated tools will support +all source control systems. + +Cabal supports specifying repositories for different use cases. By +declaring which case we mean automated tools can be more useful. There +are currently two kinds defined: + +- The ``head`` kind refers to the latest development branch of the + package. This may be used for example to track activity of a project + or as an indication to outside developers what sources to get for + making new contributions. + +- The ``this`` kind refers to the branch and tag of a repository that + contains the sources for this version or release of a package. For + most source control systems this involves specifying a tag, id or + hash of some form and perhaps a branch. The purpose is to be able to + reconstruct the sources corresponding to a particular package + version. This might be used to indicate what sources to get if + someone needs to fix a bug in an older branch that is no longer an + active head branch. + +You can specify one kind or the other or both. As an example here are +the repositories for the Cabal library. Note that the ``this`` kind of +repository specifies a tag. + +:: + + source-repository head + type: darcs + location: http://darcs.haskell.org/cabal/ + + source-repository this + type: darcs + location: http://darcs.haskell.org/cabal-branches/cabal-1.6/ + tag: 1.6.1 + +The exact fields are as follows: + +.. pkg-field:: type: token + + The name of the source control system used for this repository. The + currently recognised types are: + + - ``darcs`` + - ``git`` + - ``svn`` + - ``cvs`` + - ``mercurial`` (or alias ``hg``) + - ``bazaar`` (or alias ``bzr``) + - ``arch`` + - ``monotone`` + + This field is required. + +.. pkg-field:: location: URL + + The location of the repository. The exact form of this field depends + on the repository type. For example: + + - for darcs: ``http://code.haskell.org/foo/`` + - for git: ``git://github.com/foo/bar.git`` + - for CVS: ``anoncvs@cvs.foo.org:/cvs`` + + This field is required. + +.. pkg-field:: module: token + + CVS requires a named module, as each CVS server can host multiple + named repositories. + + This field is required for the CVS repository type and should not be + used otherwise. + +.. pkg-field:: branch: token + + Many source control systems support the notion of a branch, as a + distinct concept from having repositories in separate locations. For + example CVS, SVN and git use branches while for darcs uses different + locations for different branches. If you need to specify a branch to + identify a your repository then specify it in this field. + + This field is optional. + +.. pkg-field:: tag: token + + A tag identifies a particular state of a source repository. The tag + can be used with a ``this`` repository kind to identify the state of + a repository corresponding to a particular package version or + release. The exact form of the tag depends on the repository type. + + This field is required for the ``this`` repository kind. + +.. pkg-field:: subdir: directory + + Some projects put the sources for multiple packages under a single + source repository. This field lets you specify the relative path + from the root of the repository to the top directory for the + package, i.e. the directory containing the package's ``.cabal`` + file. + + This field is optional. It default to empty which corresponds to the + root directory of the repository. + +Downloading a package's source +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The ``cabal get`` command allows to access a package's source code - +either by unpacking a tarball downloaded from Hackage (the default) or +by checking out a working copy from the package's source repository. + +:: + + $ cabal get [FLAGS] PACKAGES + +The ``get`` command supports the following options: + +``-d --destdir`` *PATH* + Where to place the package source, defaults to (a subdirectory of) + the current directory. +``-s --source-repository`` *[head\|this\|...]* + Fork the package's source repository using the appropriate version + control system. The optional argument allows to choose a specific + repository kind. +``--index-state`` *[HEAD\|@\|]* + Use source package index state as it existed at a previous time. Accepts + unix-timestamps (e.g. ``@1474732068``), ISO8601 UTC timestamps (e.g. + ``2016-09-24T17:47:48Z``), or ``HEAD`` (default). + This determines which package versions are available as well as which + ``.cabal`` file revision is selected (unless ``--pristine`` is used). +``--pristine`` + Unpack the original pristine tarball, rather than updating the + ``.cabal`` file with the latest revision from the package archive. + +Custom setup scripts +-------------------- + +Since Cabal 1.24, custom ``Setup.hs`` are required to accurately track +their dependencies by declaring them in the ``.cabal`` file rather than +rely on dependencies being implicitly in scope. Please refer +`this article `__ +for more details. + +As of Cabal library version 3.0, ``defaultMain*`` variants implement support +for response files. Custom ``Setup.hs`` files that do not use one of these +main functions are required to implement their own support, such as by using +``GHC.ResponseFile.getArgsWithResponseFiles``. + +Declaring a ``custom-setup`` stanza also enables the generation of +``MIN_VERSION_package_(A,B,C)`` CPP macros for the Setup component. + +.. pkg-section:: custom-setup + :synopsis: Custom Setup.hs build information. + :since: 1.24 + + The optional :pkg-section:`custom-setup` stanza contains information needed + for the compilation of custom ``Setup.hs`` scripts, + +:: + + custom-setup + setup-depends: + base >= 4.5 && < 4.11, + Cabal >= 1.14 && < 1.25 + +.. pkg-field:: setup-depends: package list + :since: 1.24 + + The dependencies needed to compile ``Setup.hs``. See the + :pkg-field:`build-depends` field for a description of the syntax expected by + this field. + + If the field is not specified the implicit package set will be used. + The package set contains packages bundled with GHC (i.e. ``base``, + ``bytestring``) and specifically ``Cabal``. + The specific bounds are put on ``Cabal`` dependency: + lower-bound is inferred from :pkg-field:`cabal-version`, + and the upper-bound is ``< 1.25``. + + ``Cabal`` version is additionally restricted by GHC, + with absolute minimum being ``1.20``, and for example ``Custom`` + builds with GHC-8.10 require at least ``Cabal-3.2``. + + +Backward compatibility and ``custom-setup`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Versions prior to Cabal 1.24 don't recognise ``custom-setup`` stanzas, +and will behave agnostic to them (except for warning about an unknown +section). Consequently, versions prior to Cabal 1.24 can't ensure the +declared dependencies ``setup-depends`` are in scope, and instead +whatever is registered in the current package database environment +will become eligible (and resolved by the compiler) for the +``Setup.hs`` module. + +The availability of the +``MIN_VERSION_package_(A,B,C)`` CPP macros +inside ``Setup.hs`` scripts depends on the condition that either + +- a ``custom-setup`` section has been declared (or ``cabal v2-build`` is being + used which injects an implicit hard-coded ``custom-setup`` stanza if it's missing), or +- GHC 8.0 or later is used (which natively injects package version CPP macros) + +Consequently, if you need to write backward compatible ``Setup.hs`` +scripts using CPP, you should declare a ``custom-setup`` stanza and +use the pattern below: + +.. code-block:: haskell + + {-# LANGUAGE CPP #-} + import Distribution.Simple + + #if defined(MIN_VERSION_Cabal) + -- version macros are available and can be used as usual + # if MIN_VERSION_Cabal(a,b,c) + -- code specific to lib:Cabal >= a.b.c + # else + -- code specific to lib:Cabal < a.b.c + # endif + #else + # warning Enabling heuristic fall-back. Please upgrade cabal-install to 1.24 or later if Setup.hs fails to compile. + + -- package version macros not available; except for exotic environments, + -- you can heuristically assume that lib:Cabal's version is correlated + -- with __GLASGOW_HASKELL__, and specifically since we can assume that + -- GHC < 8.0, we can assume that lib:Cabal is version 1.22 or older. + #endif + + main = ... + +The simplified (heuristic) CPP pattern shown below is useful if all you need +is to distinguish ``Cabal < 2.0`` from ``Cabal >= 2.0``. + +.. code-block:: haskell + + {-# LANGUAGE CPP #-} + import Distribution.Simple + + #if !defined(MIN_VERSION_Cabal) + # define MIN_VERSION_Cabal(a,b,c) 0 + #endif + + #if MIN_VERSION_Cabal(2,0,0) + -- code for lib:Cabal >= 2.0 + #else + -- code for lib:Cabal < 2.0 + #endif + + main = ... + + + +Autogenerated modules and includes +---------------------------------- + +Modules that are built automatically at setup, created with a custom +setup script, must appear on :pkg-field:`other-modules` for the library, +executable, test-suite or benchmark stanzas or also on +:pkg-field:`library:exposed-modules` for libraries to be used, but are not +really on the package when distributed. This makes commands like sdist fail +because the file is not found. + +These special modules must appear again on the :pkg-field:`autogen-modules` +field of the stanza that is using it, besides :pkg-field:`other-modules` or +:pkg-field:`library:exposed-modules`. With this there is no need to create +complex build hooks for this poweruser case. + +.. pkg-field:: autogen-modules: module list + :since: 2.0 + + .. todo:: document autogen-modules field + +Right now :pkg-field:`executable:main-is` modules are not supported on +:pkg-field:`autogen-modules`. + +:: + + Library + default-language: Haskell2010 + build-depends: base + exposed-modules: + MyLibrary + MyLibHelperModule + other-modules: + MyLibModule + autogen-modules: + MyLibHelperModule + + Executable Exe + default-language: Haskell2010 + main-is: Dummy.hs + build-depends: base + other-modules: + MyExeModule + MyExeHelperModule + autogen-modules: + MyExeHelperModule + +.. pkg-field:: autogen-includes: filename list + :since: 3.0 + + A list of header files from this package which are autogenerated + (e.g. by a ``configure`` script). Autogenerated header files are not + packaged by ``sdist`` command. + +Accessing data files from package code +-------------------------------------- + +The placement on the target system of files listed in +the :pkg-field:`data-files` field varies between systems, and in some cases +one can even move packages around after installation (see `prefix +independence `__). To +enable packages to find these files in a portable way, Cabal generates a +module called :file:`Paths_{pkgname}` (with any hyphens in *pkgname* +replaced by underscores) during building, so that it may be imported by +modules of the package. This module defines a function + +.. code-block:: haskell + + getDataFileName :: FilePath -> IO FilePath + +If the argument is a filename listed in the :pkg-field:`data-files` field, the +result is the name of the corresponding file on the system on which the +program is running. + +.. Note:: + + If you decide to import the :file:`Paths_{pkgname}` module then it + *must* be listed in the :pkg-field:`other-modules` field just like any other + module in your package and on :pkg-field:`autogen-modules` as the file is + autogenerated. + +The :file:`Paths_{pkgname}` module is not platform independent, as any +other autogenerated module, so it does not get included in the source +tarballs generated by ``sdist``. + +The :file:`Paths_{pkgname}` module also includes some other useful +functions and values, which record the version of the package and some +other directories which the package has been configured to be installed +into (e.g. data files live in ``getDataDir``): + +.. code-block:: haskell + + version :: Version + + getBinDir :: IO FilePath + getLibDir :: IO FilePath + getDynLibDir :: IO FilePath + getDataDir :: IO FilePath + getLibexecDir :: IO FilePath + getSysconfDir :: IO FilePath + +The actual location of all these directories can be individually +overridden at runtime using environment variables of the form +``pkg_name_var``, where ``pkg_name`` is the name of the package with all +hyphens converted into underscores, and ``var`` is either ``bindir``, +``libdir``, ``dynlibdir``, ``datadir``, ``libexedir`` or ``sysconfdir``. For example, +the configured data directory for ``pretty-show`` is controlled with the +``pretty_show_datadir`` environment variable. + +Accessing the package version +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The aforementioned auto generated :file:`Paths_{pkgname}` module also +exports the constant ``version ::`` +`Version `__ +which is defined as the version of your package as specified in the +``version`` field. + +System-dependent parameters +--------------------------- + +For some packages, especially those interfacing with C libraries, +implementation details and the build procedure depend on the build +environment. The ``build-type`` ``Configure`` can be used to handle many +such situations. In this case, ``Setup.hs`` should be: + +.. code-block:: haskell + + import Distribution.Simple + main = defaultMainWithHooks autoconfUserHooks + +Most packages, however, would probably do better using the ``Simple`` +build type and `configurations`_. + +The :pkg-field:`build-type` ``Configure`` differs from ``Simple`` in two ways: + +- The package root directory must contain a shell script called + ``configure``. The configure step will run the script. This + ``configure`` script may be produced by + `autoconf `__ or may be + hand-written. The ``configure`` script typically discovers + information about the system and records it for later steps, e.g. by + generating system-dependent header files for inclusion in C source + files and preprocessed Haskell source files. (Clearly this won't work + for Windows without MSYS or Cygwin: other ideas are needed.) + +- If the package root directory contains a file called + *package*\ ``.buildinfo`` after the configuration step, subsequent + steps will read it to obtain additional settings for `build + information`_ fields,to be merged with the ones + given in the ``.cabal`` file. In particular, this file may be + generated by the ``configure`` script mentioned above, allowing these + settings to vary depending on the build environment. + +The build information file should have the following structure: + + *buildinfo* + + ``executable:`` *name* *buildinfo* + + ``executable:`` *name* *buildinfo* ... + +where each *buildinfo* consists of settings of fields listed in the +section on `build information`_. The first one (if +present) relates to the library, while each of the others relate to the +named executable. (The names must match the package description, but you +don't have to have entries for all of them.) + +Neither of these files is required. If they are absent, this setup +script is equivalent to ``defaultMain``. + +Example: Using autoconf +^^^^^^^^^^^^^^^^^^^^^^^ + +This example is for people familiar with the +`autoconf `__ tools. + +In the X11 package, the file ``configure.ac`` contains: + +.. code-block:: shell + + AC_INIT([Haskell X11 package], [1.1], [libraries@haskell.org], [X11]) + + # Safety check: Ensure that we are in the correct source directory. + AC_CONFIG_SRCDIR([X11.cabal]) + + # Header file to place defines in + AC_CONFIG_HEADERS([include/HsX11Config.h]) + + # Check for X11 include paths and libraries + AC_PATH_XTRA + AC_TRY_CPP([#include ],,[no_x=yes]) + + # Build the package if we found X11 stuff + if test "$no_x" = yes + then BUILD_PACKAGE_BOOL=False + else BUILD_PACKAGE_BOOL=True + fi + AC_SUBST([BUILD_PACKAGE_BOOL]) + + AC_CONFIG_FILES([X11.buildinfo]) + AC_OUTPUT + +Then the setup script will run the ``configure`` script, which checks +for the presence of the X11 libraries and substitutes for variables in +the file ``X11.buildinfo.in``: + +:: + + buildable: @BUILD_PACKAGE_BOOL@ + cc-options: @X_CFLAGS@ + ld-options: @X_LIBS@ + +This generates a file ``X11.buildinfo`` supplying the parameters needed +by later stages: + +:: + + buildable: True + cc-options: -I/usr/X11R6/include + ld-options: -L/usr/X11R6/lib + +The ``configure`` script also generates a header file +``include/HsX11Config.h`` containing C preprocessor defines recording +the results of various tests. This file may be included by C source +files and preprocessed Haskell source files in the package. + +.. Note:: + + Packages using these features will also need to list additional + files such as ``configure``, templates for ``.buildinfo`` files, files + named only in ``.buildinfo`` files, header files and so on in the + :pkg-field:`extra-source-files` field to ensure that they are included in + source distributions. They should also list files and directories generated + by ``configure`` in the :pkg-field:`extra-tmp-files` field to ensure that + they are removed by ``setup clean``. + +Quite often the files generated by ``configure`` need to be listed +somewhere in the package description (for example, in the +:pkg-field:`install-includes` field). However, we usually don't want generated +files to be included in the source tarball. The solution is again +provided by the ``.buildinfo`` file. In the above example, the following +line should be added to ``X11.buildinfo``: + +:: + + install-includes: HsX11Config.h + +In this way, the generated ``HsX11Config.h`` file won't be included in +the source tarball in addition to ``HsX11Config.h.in``, but it will be +copied to the right location during the install process. Packages that +use custom ``Setup.hs`` scripts can update the necessary fields +programmatically instead of using the ``.buildinfo`` file. + +Conditional compilation +----------------------- + +Sometimes you want to write code that works with more than one version +of a dependency. You can specify a range of versions for the dependency +in the :pkg-field:`build-depends`, but how do you then write the code that can +use different versions of the API? + +Haskell lets you preprocess your code using the C preprocessor (either +the real C preprocessor, or ``cpphs``). To enable this, add +``extensions: CPP`` to your package description. When using CPP, Cabal +provides some pre-defined macros to let you test the version of +dependent packages; for example, suppose your package works with either +version 3 or version 4 of the ``base`` package, you could select the +available version in your Haskell modules like this: + +.. code-block:: cpp + + #if MIN_VERSION_base(4,0,0) + ... code that works with base-4 ... + #else + ... code that works with base-3 ... + #endif + +In general, Cabal supplies a macro +``MIN_VERSION_``\ *``package``*\ ``_(A,B,C)`` for each package depended +on via :pkg-field:`build-depends`. This macro is true if the actual version of +the package in use is greater than or equal to ``A.B.C`` (using the +conventional ordering on version numbers, which is lexicographic on the +sequence, but numeric on each component, so for example 1.2.0 is greater +than 1.0.3). + +Since version 1.20, the ``MIN_TOOL_VERSION_``\ *``tool``* +family of macros lets you condition on the version of build tools used to +build the program (e.g. ``hsc2hs``). + +Since version 1.24, the macro ``CURRENT_COMPONENT_ID``, which +expands to the string of the component identifier that uniquely +identifies this component. Furthermore, if the package is a library, +the macro ``CURRENT_PACKAGE_KEY`` records the identifier that was passed +to GHC for use in symbols and for type equality. + +Since version 2.0, the macro ``CURRENT_PACKAGE_VERSION`` expands +to the string version number of the current package. + +Cabal places the definitions of these macros into an +automatically-generated header file, which is included when +preprocessing Haskell source code by passing options to the C +preprocessor. + +Cabal also allows to detect when the source code is being used for +generating documentation. The ``__HADDOCK_VERSION__`` macro is defined +only when compiling via Haddock_ +instead of a normal Haskell compiler. The value of the +``__HADDOCK_VERSION__`` macro is defined as ``A*1000 + B*10 + C``, where +``A.B.C`` is the Haddock version. This can be useful for working around +bugs in Haddock or generating prettier documentation in some special +cases. + +More complex packages +--------------------- + +For packages that don't fit the simple schemes described above, you have +a few options: + +- By using the :pkg-field:`build-type` ``Custom``, you can supply your own + ``Setup.hs`` file, and customize the simple build infrastructure + using *hooks*. These allow you to perform additional actions before + and after each command is run, and also to specify additional + preprocessors. A typical ``Setup.hs`` may look like this: + + .. code-block:: haskell + + import Distribution.Simple + main = defaultMainWithHooks simpleUserHooks { postHaddock = posthaddock } + + posthaddock args flags desc info = .... + + See ``UserHooks`` in + `Distribution.Simple <../release/cabal-latest/doc/API/Cabal/Distribution-Simple.html>`__ + for the details, but note that this interface is experimental, and + likely to change in future releases. + + If you use a custom ``Setup.hs`` file you should strongly consider + adding a :pkg-section:`custom-setup` stanza with a + :pkg-field:`custom-setup:setup-depends` field to ensure that your setup + script does not break with future dependency versions. + +- You could delegate all the work to ``make``, though this is unlikely + to be very portable. Cabal supports this with the :pkg-field:`build-type` + ``Make`` and a trivial setup library + `Distribution.Make <../release/cabal-latest/doc/API/Cabal/Distribution-Make.html>`__, + which simply parses the command line arguments and invokes ``make``. + Here ``Setup.hs`` should look like this: + + .. code-block:: haskell + + import Distribution.Make + main = defaultMain + + The root directory of the package should contain a ``configure`` + script, and, after that has run, a ``Makefile`` with a default target + that builds the package, plus targets ``install``, ``register``, + ``unregister``, ``clean``, ``dist`` and ``docs``. Some options to + commands are passed through as follows: + + - The ``--with-hc-pkg``, ``--prefix``, ``--bindir``, ``--libdir``, + ``--dynlibdir``, ``--datadir``, ``--libexecdir`` and ``--sysconfdir`` options to + the ``configure`` command are passed on to the ``configure`` + script. In addition the value of the ``--with-compiler`` option is + passed in a ``--with-hc`` option and all options specified with + ``--configure-option=`` are passed on. + + - The ``--destdir`` option to the ``copy`` command becomes a setting + of a ``destdir`` variable on the invocation of ``make copy``. The + supplied ``Makefile`` should provide a ``copy`` target, which will + probably look like this: + + .. code-block:: make + + copy : + $(MAKE) install prefix=$(destdir)/$(prefix) \ + bindir=$(destdir)/$(bindir) \ + libdir=$(destdir)/$(libdir) \ + dynlibdir=$(destdir)/$(dynlibdir) \ + datadir=$(destdir)/$(datadir) \ + libexecdir=$(destdir)/$(libexecdir) \ + sysconfdir=$(destdir)/$(sysconfdir) \ + +- Finally, with the :pkg-field:`build-type` ``Custom``, you can also write your + own setup script from scratch. It must conform to the interface + described in the section on `building and installing + packages `__, and you may use the Cabal + library for all or part of the work. One option is to copy the source + of ``Distribution.Simple``, and alter it for your needs. Good luck. + + +.. include:: references.inc + +.. rubric:: Footnotes + +.. [#old-style-build-tool-depends] + + Some packages (ab)use :pkg-field:`build-depends` on old-style builds, but this has a few major drawbacks: + + - using Nix-style builds it's considered an error if you depend on a exe-only package via build-depends: the solver will refuse it. + - it may or may not place the executable on ``$PATH``. + - it does not ensure the correct version of the package is installed, so you might end up overwriting versions with each other. diff --git a/Cabal/doc/cabal-project.rst b/Cabal/doc/cabal-project.rst new file mode 100644 index 00000000000..12f655db20c --- /dev/null +++ b/Cabal/doc/cabal-project.rst @@ -0,0 +1,1526 @@ +cabal.project Reference +======================= + +``cabal.project`` files support a variety of options which configure the +details of your build. The general syntax of a ``cabal.project`` file is +similar to that of a Cabal file: there are a number of fields, some of +which live inside stanzas: + +:: + + packages: */*.cabal + with-compiler: /opt/ghc/8.0.1/bin/ghc + + package cryptohash + optimization: False + +In general, the accepted field names coincide with the accepted command +line flags that ``cabal install`` and other commands take. For example, +``cabal v2-configure --enable-profiling`` will write out a project +file with ``profiling: True``. + +The full configuration of a project is determined by combining the +following sources (later entries override earlier ones): + +1. ``~/.cabal/config`` (the user-wide global configuration) + +2. ``cabal.project`` (the project configuration) + +3. ``cabal.project.freeze`` (the output of ``cabal v2-freeze``) + +4. ``cabal.project.local`` (the output of ``cabal v2-configure``) + + +Specifying the local packages +----------------------------- + +The following top-level options specify what the local packages of a +project are: + +.. cfg-field:: packages: package location list (space or comma separated) + :synopsis: Project packages. + + :default: ``./*.cabal`` + + Specifies the list of package locations which contain the local + packages to be built by this project. Package locations can take the + following forms: + + 1. They can specify a Cabal file, or a directory containing a Cabal + file, e.g., ``packages: Cabal cabal-install/cabal-install.cabal``. + + 2. They can specify a glob-style wildcards, which must match one or + more (a) directories containing a (single) Cabal file, (b) Cabal + files (extension ``.cabal``), or (c) tarballs which contain Cabal + packages (extension ``.tar.gz``). + For example, to match all Cabal files in all + subdirectories, as well as the Cabal projects in the parent + directories ``foo`` and ``bar``, use + ``packages: */*.cabal ../{foo,bar}/`` + + 3. They can specify an ``http``, ``https`` or ``file`` + URL, representing the path to a remote tarball to be downloaded + and built. + + There is no command line variant of this field; see :issue:`3585`. + +.. cfg-field:: optional-packages: package location list (space or comma-separated) + :synopsis: Optional project packages. + + :default: ``./*/*.cabal`` + + Like :cfg-field:`packages`, specifies a list of package locations + containing local packages to be built. Unlike :cfg-field:`packages`, + if we glob for a package, it is permissible for the glob to match against + zero packages. The intended use-case for :cfg-field:`optional-packages` + is to make it so that vendored packages can be automatically picked up if + they are placed in a subdirectory, but not error if there aren't any. + + There is no command line variant of this field. + +.. cfg-field:: extra-packages: package list with version bounds (comma separated) + :synopsis: Adds external pacakges as local + + [STRIKEOUT:Specifies a list of external packages from Hackage which + should be considered local packages.] (Not implemented) + + There is no command line variant of this field. + + + +All local packages are *vendored*, in the sense that if other packages +(including external ones from Hackage) depend on a package with the name +of a local package, the local package is preferentially used. This +motivates the default settings:: + + packages: ./*.cabal + optional-packages: ./*/*.cabal + +...any package can be vendored simply by making a checkout in the +top-level project directory, as might be seen in this hypothetical +directory layout:: + + foo.cabal + foo-helper/ # local package + unix/ # vendored external package + +All of these options support globs. ``cabal v2-build`` has its own glob +format: + +- Anywhere in a path, as many times as you like, you can specify an + asterisk ``*`` wildcard. E.g., ``*/*.cabal`` matches all ``.cabal`` + files in all immediate subdirectories. Like in glob(7), asterisks do + not match hidden files unless there is an explicit period, e.g., + ``.*/foo.cabal`` will match ``.private/foo.cabal`` (but + ``*/foo.cabal`` will not). + +- You can use braces to specify specific directories; e.g., + ``{vendor,pkgs}/*.cabal`` matches all Cabal files in the ``vendor`` + and ``pkgs`` subdirectories. + +Formally, the format described by the following BNF: + +.. todo:: + convert globbing grammar to proper ABNF_ syntax + +.. code-block:: abnf + + FilePathGlob ::= FilePathRoot FilePathGlobRel + FilePathRoot ::= {- empty -} # relative to cabal.project + | "/" # Unix root + | [a-zA-Z] ":" [/\\] # Windows root + | "~" # home directory + FilePathGlobRel ::= Glob "/" FilePathGlobRel # Unix directory + | Glob "\\" FilePathGlobRel # Windows directory + | Glob # file + | {- empty -} # trailing slash + Glob ::= GlobPiece * + GlobPiece ::= "*" # wildcard + | [^*{},/\\] * # literal string + | "\\" [*{},] # escaped reserved character + | "{" Glob "," ... "," Glob "}" # union (match any of these) + + +Specifying Packages from Remote Version Control Locations +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Starting with Cabal 2.4, there is now a stanza +``source-repository-package`` for specifying packages from an external +version control which supports the following fields: + +- :pkg-field:`source-repository:type` +- :pkg-field:`source-repository:location` +- :pkg-field:`source-repository:tag` +- :pkg-field:`source-repository:subdir` + +A simple example is shown below: + +.. code-block:: cabal + + packages: . + + source-repository-package + type: git + location: https://github.com/hvr/HsYAML.git + tag: e70cf0c171c9a586b62b3f75d72f1591e4e6aaa1 + + source-repository-package + type: git + location: https://github.com/well-typed/cborg + tag: 3d274c14ca3077c3a081ba7ad57c5182da65c8c1 + subdir: cborg + +Global configuration options +---------------------------- + +The following top-level configuration options are not specific to any +package, and thus apply globally: + + +.. cfg-field:: verbose: nat + --verbose=n, -vn + :synopsis: Build verbosity level. + + :default: 1 + + Control the verbosity of ``cabal`` commands, valid values are from 0 + to 3. + + The command line variant of this field is ``--verbose=2``; a short + form ``-v2`` is also supported. + +.. cfg-field:: jobs: nat or $ncpus + --jobs=n, -jn, --jobs=$ncpus + :synopsis: Number of builds running in parallel. + + :default: 1 + + Run *nat* jobs simultaneously when building. If ``$ncpus`` is + specified, run the number of jobs equal to the number of CPUs. + Package building is often quite parallel, so turning on parallelism + can speed up build times quite a bit! + + The command line variant of this field is ``--jobs=2``; a short form + ``-j2`` is also supported; a bare ``--jobs`` or ``-j`` is equivalent + to ``--jobs=$ncpus``. + +.. cfg-field:: keep-going: boolean + --keep-going + :synopsis: Try to continue building on failure. + + :default: False + + If true, after a build failure, continue to build other unaffected + packages. + + The command line variant of this field is ``--keep-going``. + +.. option:: --builddir=DIR + + Specifies the name of the directory where build products for + build will be stored; defaults to ``dist-newstyle``. If a + relative name is specified, this directory is resolved relative + to the root of the project (i.e., where the ``cabal.project`` + file lives.) + + This option cannot be specified via a ``cabal.project`` file. + +.. _cmdoption-project-file: +.. option:: --project-file=FILE + + Specifies the name of the project file used to specify the + rest of the top-level configuration; defaults to ``cabal.project``. + This name not only specifies the name of the main project file, + but also the auxiliary project files ``cabal.project.freeze`` + and ``cabal.project.local``; for example, if you specify + ``--project-file=my.project``, then the other files that will + be probed are ``my.project.freeze`` and ``my.project.local``. + + If the specified project file is a relative path, we will + look for the file relative to the current working directory, + and then for the parent directory, until the project file is + found or we have hit the top of the user's home directory. + + This option cannot be specified via a ``cabal.project`` file. + +.. option:: --store-dir=DIR + + Specifies the name of the directory of the global package store. + +Solver configuration options +---------------------------- + +The following settings control the behavior of the dependency solver: + +.. cfg-field:: constraints: constraints list (comma separated) + --constraint="pkg >= 2.0" + :synopsis: Extra dependencies constraints. + + Add extra constraints to the version bounds, flag settings, + and other properties a solver can pick for a + package. For example: + + :: + + constraints: bar == 2.1 + + A package can be specified multiple times in ``constraints``, in + which case the specified constraints are intersected. This is + useful, since the syntax does not allow you to specify multiple + constraints at once. For example, to specify both version bounds and + flag assignments, you would write: + + :: + + constraints: bar == 2.1, + bar +foo -baz + + Valid constraints take the same form as for the `constraint + command line option + `__. + +.. cfg-field:: preferences: preference (comma separated) + --preference="pkg >= 2.0" + :synopsis: Prefered dependency versions. + + Like :cfg-field:`constraints`, but the solver will attempt to satisfy + these preferences on a best-effort basis. The resulting install is locally + optimal with respect to preferences; specifically, no single package + could be replaced with a more preferred version that still satisfies + the hard constraints. + + Operationally, preferences can cause the solver to attempt certain + version choices of a package before others, which can improve + dependency solver runtime. + + One way to use :cfg-field:`preferences` is to take a known working set of + constraints (e.g., via ``cabal v2-freeze``) and record them as + preferences. In this case, the solver will first attempt to use this + configuration, and if this violates hard constraints, it will try to + find the minimal number of upgrades to satisfy the hard constraints + again. + + The command line variant of this field is + ``--preference="pkg >= 2.0"``; to specify multiple preferences, pass + the flag multiple times. + +.. cfg-field:: allow-newer: none, all or list of scoped package names (space or comma separated) + --allow-newer, --allow-newer=[none,all,[scope:][^]pkg] + :synopsis: Lift dependencies upper bound constraints. + + :default: ``none`` + + Allow the solver to pick an newer version of some packages than + would normally be permitted by than the :pkg-field:`build-depends` bounds + of packages in the install plan. This option may be useful if the + dependency solver cannot otherwise find a valid install plan. + + For example, to relax ``pkg``\ s :pkg-field:`build-depends` upper bound on + ``dep-pkg``, write a scoped package name of the form: + + :: + + allow-newer: pkg:dep-pkg + + If the scope shall be limited to specific releases of ``pkg``, the + extended form as in + + :: + + allow-newer: pkg-1.2.3:dep-pkg, pkg-1.1.2:dep-pkg + + can be used to limit the relaxation of dependencies on + ``dep-pkg`` by the ``pkg-1.2.3`` and ``pkg-1.1.2`` releases only. + + The scoped syntax is recommended, as it is often only a single package + whose upper bound is misbehaving. In this case, the upper bounds of + other packages should still be respected; indeed, relaxing the bound + can break some packages which test the selected version of packages. + + The syntax also allows to prefix the dependee package with a + modifier symbol to modify the scope/semantic of the relaxation + transformation in a additional ways. Currently only one modifier + symbol is defined, i.e. ``^`` (i.e. caret) which causes the + relaxation to be applied only to ``^>=`` operators and leave all other + version operators untouched. + + However, in some situations (e.g., when attempting to build packages + on a new version of GHC), it is useful to disregard *all* + upper-bounds, with respect to a package or all packages. This can be + done by specifying just a package name, or using the keyword ``all`` + to specify all packages: + + :: + + -- Disregard upper bounds involving the dependencies on + -- packages bar, baz. For quux only, relax + -- 'quux ^>= ...'-style constraints only. + allow-newer: bar, baz, ^quux + + -- Disregard all upper bounds when dependency solving + allow-newer: all + + -- Disregard all `^>=`-style upper bounds when dependency solving + allow-newer: ^all + + + For consistency, there is also the explicit wildcard scope syntax + ``*`` (or its alphabetic synonym ``all``). Consequently, the + examples above are equivalent to the explicitly scoped variants: + + :: + + allow-newer: all:bar, *:baz, *:^quux + + allow-newer: *:* + allow-newer: all:all + + allow-newer: *:^* + allow-newer: all:^all + + In order to ignore all bounds specified by a package ``pkg-1.2.3`` + you can combine scoping with a right-hand-side wildcard like so + + :: + + -- Disregard any upper bounds specified by pkg-1.2.3 + allow-newer: pkg-1.2.3:* + + -- Disregard only `^>=`-style upper bounds in pkg-1.2.3 + allow-newer: pkg-1.2.3:^* + + + :cfg-field:`allow-newer` is often used in conjunction with a constraint + (in the cfg-field:`constraints` field) forcing the usage of a specific, + newer version of a package. + + The command line variant of this field is e.g. ``--allow-newer=bar``. A + bare ``--allow-newer`` is equivalent to ``--allow-newer=all``. + +.. cfg-field:: allow-older: none, all, list of scoped package names (space or comma separated) + --allow-older, --allow-older=[none,all,[scope:][^]pkg] + :synopsis: Lift dependency lower bound constraints. + :since: 2.0 + + :default: ``none`` + + Like :cfg-field:`allow-newer`, but applied to lower bounds rather than + upper bounds. + + The command line variant of this field is ``--allow-older=all``. A + bare ``--allow-older`` is equivalent to ``--allow-older=all``. + + +.. cfg-field:: index-state: HEAD, unix-timestamp, ISO8601 UTC timestamp. + :synopsis: Use source package index state as it existed at a previous time. + :since: 2.0 + + :default: ``HEAD`` + + This allows to change the source package index state the solver uses + to compute install-plans. This is particularly useful in + combination with freeze-files in order to also freeze the state the + package index was in at the time the install-plan was frozen. + + :: + + -- UNIX timestamp format example + index-state: @1474739268 + + -- ISO8601 UTC timestamp format example + -- This format is used by 'cabal v2-configure' + -- for storing `--index-state` values. + index-state: 2016-09-24T17:47:48Z + + +.. cfg-field:: reject-unconstrained-dependencies: all, none + --reject-unconstrained-dependencies=[all|none] + :synopsis: Restrict the solver to packages that have constraints on them. + + :default: none + :since: 2.6 + + By default, the dependency solver can include any package that it's + aware of in a build plan. If you wish to restrict the build plan to + a closed set of packages (e.g., from a freeze file), use this flag. + + When set to `all`, all non-local packages that aren't goals must be + explicitly constrained. When set to `none`, the solver will + consider all packages. + + +Package configuration options +----------------------------- + +Package options affect the building of specific packages. There are three +ways a package option can be specified: + +- They can be specified at the top-level, in which case they apply only + to **local package**, or + +- They can be specified inside a ``package`` stanza, in which case they + apply to the build of the package, whether or not it is local or + external. + +- They can be specified inside an ``package *`` stanza, in which case they + apply to all packages, local ones from the project and also external + dependencies. + + +For example, the following options specify that :cfg-field:`optimization` +should be turned off for all local packages, and that ``bytestring`` (possibly +an external dependency) should be built with ``-fno-state-hack``:: + + optimization: False + + package bytestring + ghc-options: -fno-state-hack + +``ghc-options`` is not specifically described in this documentation, +but is one of many fields for configuring programs. They take the form +``progname-options`` and ``progname-location``, and +can only be set inside package stanzas. (TODO: They are not supported +at top-level, see :issue:`3579`.) + +At the moment, there is no way to specify an option to apply to all +external packages or all inplace packages. Additionally, it is only +possible to specify these options on the command line for all local +packages (there is no per-package command line interface.) + +Some flags were added by more recent versions of the Cabal library. This +means that they are NOT supported by packages which use Custom setup +scripts that require a version of the Cabal library older than when the +feature was added. + +.. cfg-field:: flags: list of +flagname or -flagname (space separated) + --flags="+foo -bar", -ffoo, -f-bar + :synopsis: Enable or disable package flags. + + Force all flags specified as ``+flagname`` to be true, and all flags + specified as ``-flagname`` to be false. For example, to enable the + flag ``foo`` and disable ``bar``, set: + + :: + + flags: +foo -bar + + If there is no leading punctuation, it is assumed that the flag + should be enabled; e.g., this is equivalent: + + :: + + flags: foo -bar + + Flags are *per-package*, so it doesn't make much sense to specify + flags at the top-level, unless you happen to know that *all* of your + local packages support the same named flags. If a flag is not + supported by a package, it is ignored. + + See also the solver configuration field :cfg-field:`constraints`. + + The command line variant of this flag is ``--flags``. There is also + a shortened form ``-ffoo -f-bar``. + + A common mistake is to say ``cabal v2-build -fhans``, where + ``hans`` is a flag for a transitive dependency that is not in the + local package; in this case, the flag will be silently ignored. If + ``haskell-tor`` is the package you want this flag to apply to, try + ``--constraint="haskell-tor +hans"`` instead. + +.. cfg-field:: with-compiler: executable + --with-compiler=executable + :synopsis: Path to compiler executable. + + Specify the path to a particular compiler to be used. If not an + absolute path, it will be resolved according to the :envvar:`PATH` + environment. The type of the compiler (GHC, GHCJS, etc) must be + consistent with the setting of the :cfg-field:`compiler` field. + + The most common use of this option is to specify a different version + of your compiler to be used; e.g., if you have ``ghc-7.8`` in your + path, you can specify ``with-compiler: ghc-7.8`` to use it. + + This flag also sets the default value of :cfg-field:`with-hc-pkg`, using + the heuristic that it is named ``ghc-pkg-7.8`` (if your executable name + is suffixed with a version number), or is the executable named + ``ghc-pkg`` in the same directory as the ``ghc`` directory. If this + heuristic does not work, set :cfg-field:`with-hc-pkg` explicitly. + + For inplace packages, ``cabal v2-build`` maintains a separate build + directory for each version of GHC, so you can maintain multiple + build trees for different versions of GHC without clobbering each + other. + + At the moment, it's not possible to set :cfg-field:`with-compiler` on a + per-package basis, but eventually we plan on relaxing this + restriction. If this is something you need, give us a shout. + + The command line variant of this flag is + ``--with-compiler=ghc-7.8``; there is also a short version + ``-w ghc-7.8``. + +.. cfg-field:: with-hc-pkg: executable + --with-hc-pkg=executable + :synopsis: Specifies package tool. + + Specify the path to the package tool, e.g., ``ghc-pkg``. This + package tool must be compatible with the compiler specified by + :cfg-field:`with-compiler` (generally speaking, it should be precisely + the tool that was distributed with the compiler). If this option is + omitted, the default value is determined from :cfg-field:`with-compiler`. + + The command line variant of this flag is + ``--with-hc-pkg=ghc-pkg-7.8``. + +.. cfg-field:: optimization: nat + --enable-optimization + --disable-optimization + :synopsis: Build with optimization. + + :default: ``1`` + + Build with optimization. This is appropriate for production use, + taking more time to build faster libraries and programs. + + The optional *nat* value is the optimisation level. Some compilers + support multiple optimisation levels. The range is 0 to 2. Level 0 + disables optimization, level 1 is the default. Level 2 is higher + optimisation if the compiler supports it. Level 2 is likely to lead + to longer compile times and bigger generated code. If you are not + planning to run code, turning off optimization will lead to better + build times and less code to be rebuilt when a module changes. + + When optimizations are enabled, Cabal passes ``-O2`` to the C compiler. + + We also accept ``True`` (equivalent to 1) and ``False`` (equivalent + to 0). + + Note that as of GHC 8.0, GHC does not recompile when optimization + levels change (see :ghc-ticket:`10923`), so if + you change the optimization level for a local package you may need + to blow away your old build products in order to rebuild with the + new optimization level. + + The command line variant of this flag is ``-O2`` (with ``-O1`` + equivalent to ``-O``). There are also long-form variants + ``--enable-optimization`` and ``--disable-optimization``. + +.. cfg-field:: configure-options: args (space separated) + --configure-option=arg + :synopsis: Options to pass to configure script. + + A list of extra arguments to pass to the external ``./configure`` + script, if one is used. This is only useful for packages which have + the ``Configure`` build type. See also the section on + `system-dependent + parameters `__. + + The command line variant of this flag is ``--configure-option=arg``, + which can be specified multiple times to pass multiple options. + +.. cfg-field:: compiler: ghc, ghcjs, jhc, lhc, uhc or haskell-suite + --compiler=compiler + :synopsis: Compiler to build with. + + :default: ``ghc`` + + Specify which compiler toolchain to be used. This is independent of + ``with-compiler``, because the choice of toolchain affects Cabal's + build logic. + + The command line variant of this flag is ``--compiler=ghc``. + +.. cfg-field:: tests: boolean + --enable-tests + --disable-tests + :synopsis: Build tests. + + :default: ``False`` + + Force test suites to be enabled. For most users this should not be + needed, as we always attempt to solve for test suite dependencies, + even when this value is ``False``; furthermore, test suites are + automatically enabled if they are requested as a built target. + + The command line variant of this flag is ``--enable-tests`` and + ``--disable-tests``. + +.. cfg-field:: benchmarks: boolean + --enable-benchmarks + --disable-benchmarks + :synopsis: Build benchmarks. + + :default: ``False`` + + Force benchmarks to be enabled. For most users this should not be + needed, as we always attempt to solve for benchmark dependencies, + even when this value is ``False``; furthermore, benchmarks are + automatically enabled if they are requested as a built target. + + The command line variant of this flag is ``--enable-benchmarks`` and + ``--disable-benchmarks``. + +.. cfg-field:: extra-prog-path: paths (newline or comma separated) + --extra-prog-path=PATH + :synopsis: Add directories to program search path. + :since: 1.18 + + A list of directories to search for extra required programs. Most + users should not need this, as programs like ``happy`` and ``alex`` + will automatically be installed and added to the path. This can be + useful if a ``Custom`` setup script relies on an exotic extra + program. + + The command line variant of this flag is ``--extra-prog-path=PATH``, + which can be specified multiple times. + +.. cfg-field:: run-tests: boolean + --run-tests + :synopsis: Run package test suite upon installation. + + :default: ``False`` + + Run the package test suite upon installation. This is useful for + saying "When this package is installed, check that the test suite + passes, terminating the rest of the build if it is broken." + + .. warning:: + + One deficiency: the :cfg-field:`run-tests` setting of a package is NOT + recorded as part of the hash, so if you install something without + :cfg-field:`run-tests` and then turn on ``run-tests``, we won't + subsequently test the package. If this is causing you problems, give + us a shout. + + The command line variant of this flag is ``--run-tests``. + +Object code options +^^^^^^^^^^^^^^^^^^^ + +.. cfg-field:: debug-info: integer + --enable-debug-info= + --disable-debug-info + :synopsis: Build with debug info enabled. + :since: 1.22 + + :default: False + + If the compiler (e.g., GHC 7.10 and later) supports outputing OS + native debug info (e.g., DWARF), setting ``debug-info: True`` will + instruct it to do so. See the GHC wiki page on :ghc-wiki:`DWARF` + for more information about this feature. + + (This field also accepts numeric syntax, but until GHC 8.2 this didn't + do anything.) + + The command line variant of this flag is ``--enable-debug-info`` and + ``--disable-debug-info``. + +.. cfg-field:: split-sections: boolean + --enable-split-sections + --disable-split-sections + :synopsis: Use GHC's split sections feature. + :since: 2.2 + + :default: False + + Use the GHC ``-split-sections`` feature when building the library. This + reduces the final size of the executables that use the library by + allowing them to link with only the bits that they use rather than + the entire library. The downside is that building the library takes + longer and uses a bit more memory. + + This feature is supported by GHC 8.0 and later. + + The command line variant of this flag is ``--enable-split-sections`` and + ``--disable-split-sections``. + +.. cfg-field:: split-objs: boolean + --enable-split-objs + --disable-split-objs + :synopsis: Use GHC's split objects feature. + + :default: False + + Use the GHC ``-split-objs`` feature when building the library. This + reduces the final size of the executables that use the library by + allowing them to link with only the bits that they use rather than + the entire library. The downside is that building the library takes + longer and uses considerably more memory. + + It is generally recommend that you use ``split-sections`` instead + of ``split-objs`` where possible. + + The command line variant of this flag is ``--enable-split-objs`` and + ``--disable-split-objs``. + +.. cfg-field:: executable-stripping: boolean + --enable-executable-stripping + --disable-executable-stripping + :synopsis: Strip installed programs. + + :default: True + + When installing binary executable programs, run the ``strip`` + program on the binary. This can considerably reduce the size of the + executable binary file. It does this by removing debugging + information and symbols. + + Not all Haskell implementations generate native binaries. For such + implementations this option has no effect. + + If ``debug-info`` is set explicitly then ``executable-stripping`` is set + to ``False`` as otherwise all the debug symbols will be stripped. + + The command line variant of this flag is + ``--enable-executable-stripping`` and + ``--disable-executable-stripping``. + +.. cfg-field:: library-stripping: boolean + --enable-library-stripping + --disable-library-stripping + :synopsis: Strip installed libraries. + :since: 1.20 + + When installing binary libraries, run the ``strip`` program on the + binary, saving space on the file system. See also + ``executable-stripping``. + + If ``debug-info`` is set explicitly then ``library-stripping`` is set + to ``False`` as otherwise all the debug symbols will be stripped. + + The command line variant of this flag is + ``--enable-library-stripping`` and ``--disable-library-stripping``. + +Executable options +^^^^^^^^^^^^^^^^^^ + +.. cfg-field:: program-prefix: prefix + --program-prefix=prefix + :synopsis: Prepend prefix to program names. + + [STRIKEOUT:Prepend *prefix* to installed program names.] (Currently + implemented in a silly and not useful way. If you need this to work + give us a shout.) + + *prefix* may contain the following path variables: ``$pkgid``, + ``$pkg``, ``$version``, ``$compiler``, ``$os``, ``$arch``, ``$abi``, + ``$abitag`` + + The command line variant of this flag is ``--program-prefix=foo-``. + +.. cfg-field:: program-suffix: suffix + --program-suffix=suffix + :synopsis: Append refix to program names. + + [STRIKEOUT:Append *suffix* to installed program names.] (Currently + implemented in a silly and not useful way. If you need this to work + give us a shout.) + + The most obvious use for this is to append the program's version + number to make it possible to install several versions of a program + at once: ``program-suffix: $version``. + + *suffix* may contain the following path variables: ``$pkgid``, + ``$pkg``, ``$version``, ``$compiler``, ``$os``, ``$arch``, ``$abi``, + ``$abitag`` + + The command line variant of this flag is + ``--program-suffix='$version'``. + +Dynamic linking options +^^^^^^^^^^^^^^^^^^^^^^^ + +.. cfg-field:: shared: boolean + --enable-shared + --disable-shared + :synopsis: Build shared library. + + :default: False + + Build shared library. This implies a separate compiler run to + generate position independent code as required on most platforms. + + The command line variant of this flag is ``--enable-shared`` and + ``--disable-shared``. + +.. cfg-field:: executable-dynamic: boolean + --enable-executable-dynamic + --disable-executable-dynamic + :synopsis: Link executables dynamically. + + :default: False + + Link executables dynamically. The executable's library dependencies + should be built as shared objects. This implies ``shared: True`` + unless ``shared: False`` is explicitly specified. + + The command line variant of this flag is + ``--enable-executable-dynamic`` and + ``--disable-executable-dynamic``. + +.. cfg-field:: library-for-ghci: boolean + --enable-library-for-ghci + --disable-library-for-ghci + :synopsis: Build libraries suitable for use with GHCi. + + :default: True + + Build libraries suitable for use with GHCi. This involves an extra + linking step after the build. + + Not all platforms support GHCi and indeed on some platforms, trying + to build GHCi libs fails. In such cases, consider setting + ``library-for-ghci: False``. + + The command line variant of this flag is + ``--enable-library-for-ghci`` and ``--disable-library-for-ghci``. + +.. cfg-field:: relocatable: + --relocatable + :synopsis: Build relocatable package. + :since: 1.22 + + :default: False + + [STRIKEOUT:Build a package which is relocatable.] (TODO: It is not + clear what this actually does, or if it works at all.) + + The command line variant of this flag is ``--relocatable``. + +Static linking options +^^^^^^^^^^^^^^^^^^^^^^ + +.. cfg-field:: static: boolean + --enable-static + --disable-static + :synopsis: Build static library. + + + :default: False + + Roll this and all dependent libraries into a combined ``.a`` archive. + This uses GHCs ``-staticlib`` flag, which is available for iOS and with + GHC 8.4 and later for other platforms as well. + +.. cfg-field:: executable-static: boolean + --enable-executable-static + --disable-executable-static + :synopsis: Build fully static executables. + + + :default: False + + Build fully static executables. + This link all dependent libraries into executables statically, + including libc. + This passes ``-static`` and ``-optl=-static`` to GHC. + +Foreign function interface options +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. cfg-field:: extra-include-dirs: directories (comma or newline separated list) + --extra-include-dirs=DIR + :synopsis: Adds C header search path. + + An extra directory to search for C header files. You can use this + flag multiple times to get a list of directories. + + You might need to use this flag if you have standard system header + files in a non-standard location that is not mentioned in the + package's ``.cabal`` file. Using this option has the same affect as + appending the directory *dir* to the :pkg-field:`include-dirs` field in each + library and executable in the package's ``.cabal`` file. The + advantage of course is that you do not have to modify the package at + all. These extra directories will be used while building the package + and for libraries it is also saved in the package registration + information and used when compiling modules that use the library. + + The command line variant of this flag is + ``--extra-include-dirs=DIR``, which can be specified multiple times. + +.. cfg-field:: extra-lib-dirs: directories (comma or newline separated list) + --extra-lib-dirs=DIR + :synopsis: Adds library search directory. + + An extra directory to search for system libraries files. + + The command line variant of this flag is ``--extra-lib-dirs=DIR``, + which can be specified multiple times. + +.. cfg-field:: extra-framework-dirs: directories (comma or newline separated list) + --extra-framework-dirs=DIR + :synopsis: Adds framework search directory (OS X only). + + An extra directory to search for frameworks (OS X only). + + You might need to use this flag if you have standard system + libraries in a non-standard location that is not mentioned in the + package's ``.cabal`` file. Using this option has the same affect as + appending the directory *dir* to the :cfg-field:`extra-lib-dirs` field in + each library and executable in the package's ``.cabal`` file. The + advantage of course is that you do not have to modify the package at + all. These extra directories will be used while building the package + and for libraries it is also saved in the package registration + information and used when compiling modules that use the library. + + The command line variant of this flag is + ``--extra-framework-dirs=DIR``, which can be specified multiple + times. + +Profiling options +^^^^^^^^^^^^^^^^^ + +.. cfg-field:: profiling: boolean + --enable-profiling + --disable-profiling + :synopsis: Enable profiling builds. + :since: 1.22 + + :default: False + + Build libraries and executables with profiling enabled (for + compilers that support profiling as a separate mode). It is only + necessary to specify :cfg-field:`profiling` for the specific package you + want to profile; ``cabal v2-build`` will ensure that all of its + transitive dependencies are built with profiling enabled. + + To enable profiling for only libraries or executables, see + :cfg-field:`library-profiling` and :cfg-field:`executable-profiling`. + + For useful profiling, it can be important to control precisely what + cost centers are allocated; see :cfg-field:`profiling-detail`. + + The command line variant of this flag is ``--enable-profiling`` and + ``--disable-profiling``. + +.. cfg-field:: profiling-detail: level + --profiling-detail=level + :synopsis: Profiling detail level. + :since: 1.24 + + Some compilers that support profiling, notably GHC, can allocate + costs to different parts of the program and there are different + levels of granularity or detail with which this can be done. In + particular for GHC this concept is called "cost centers", and GHC + can automatically add cost centers, and can do so in different ways. + + This flag covers both libraries and executables, but can be + overridden by the ``library-profiling-detail`` field. + + Currently this setting is ignored for compilers other than GHC. The + levels that cabal currently supports are: + + default + For GHC this uses ``exported-functions`` for libraries and + ``toplevel-functions`` for executables. + none + No costs will be assigned to any code within this component. + exported-functions + Costs will be assigned at the granularity of all top level + functions exported from each module. In GHC, this + is for non-inline functions. Corresponds to ``-fprof-auto-exported``. + toplevel-functions + Costs will be assigned at the granularity of all top level + functions in each module, whether they are exported from the + module or not. In GHC specifically, this is for non-inline + functions. Corresponds to ``-fprof-auto-top``. + all-functions + Costs will be assigned at the granularity of all functions in + each module, whether top level or local. In GHC specifically, + this is for non-inline toplevel or where-bound functions or + values. Corresponds to ``-fprof-auto``. + + The command line variant of this flag is + ``--profiling-detail=none``. + +.. cfg-field:: library-profiling-detail: level + --library-profiling-detail=level + :synopsis: Libraries profiling detail level. + :since: 1.24 + + Like :cfg-field:`profiling-detail`, but applied only to libraries + + The command line variant of this flag is + ``--library-profiling-detail=none``. + +.. cfg-field:: library-vanilla: boolean + --enable-library-vanilla + --disable-library-vanilla + :synopsis: Build libraries without profiling. + + :default: True + + Build ordinary libraries (as opposed to profiling libraries). + Mostly, you can set this to False to avoid building ordinary + libraries when you are profiling. + + The command line variant of this flag is + ``--enable-library-vanilla`` and ``--disable-library-vanilla``. + +.. cfg-field:: library-profiling: boolean + --enable-library-profiling + --disable-library-profiling + :synopsis: Build libraries with profiling enabled. + :since: 1.22 + + :default: False + + Build libraries with profiling enabled. You probably want + to use :cfg-field:`profiling` instead. + + The command line variant of this flag is + ``--enable-library-profiling`` and ``--disable-library-profiling``. + +.. cfg-field:: executable-profiling: boolean + --enable-executable-profiling + --disable-executable-profiling + :synopsis: Build executables with profiling enabled. + :since: 1.22 + + :default: False + + Build executables with profiling enabled. You probably want + to use :cfg-field:`profiling` instead. + + The command line variant of this flag is + ``--enable-executable-profiling`` and + ``--disable-executable-profiling``. + +Coverage options +^^^^^^^^^^^^^^^^ + +.. cfg-field:: coverage: boolean + --enable-coverage + --disable-coverage + :synopsis: Build with coverage enabled. + :since: 1.22 + + :default: False + + Build libraries and executables (including test suites) with Haskell + Program Coverage enabled. Running the test suites will automatically + generate coverage reports with HPC. + + The command line variant of this flag is ``--enable-coverage`` and + ``--disable-coverage``. + +.. cfg-field:: library-coverage: boolean + --enable-library-coverage + --disable-library-coverage + :since: 1.22 + :deprecated: + + :default: False + + Deprecated, use :cfg-field:`coverage`. + + The command line variant of this flag is + ``--enable-library-coverage`` and ``--disable-library-coverage``. + +Haddock options +^^^^^^^^^^^^^^^ + +.. cfg-field:: documentation: boolean + --enable-documentation + --disable-documentation + :synopsis: Enable building of documentation. + + :default: False + + Enables building of Haddock documentation + + The command line variant of this flag is ``--enable-documentation`` + and ``--disable-documentation``. + + `documentation: true` does not imply :cfg-field:`haddock-benchmarks`, + :cfg-field:`haddock-executables`, :cfg-field:`haddock-internal` or + :cfg-field:`haddock-tests`. These need to be enabled separately if + desired. + +.. cfg-field:: doc-index-file: templated path + --doc-index-file=TEMPLATE + :synopsis: Path to haddock templates. + + A central index of Haddock API documentation (template cannot use + ``$pkgid``), which should be updated as documentation is built. + + The command line variant of this flag is + ``--doc-index-file=TEMPLATE`` + +The following commands are equivalent to ones that would be passed when +running ``setup haddock``. (TODO: Where does the documentation get put.) + +.. cfg-field:: haddock-hoogle: boolean + :synopsis: Generate Hoogle file. + + :default: False + + Generate a text file which can be converted by Hoogle_ + into a database for searching. This is equivalent to running ``haddock`` + with the ``--hoogle`` flag. + + The command line variant of this flag is ``--hoogle`` (for the + ``haddock`` command). + +.. cfg-field:: haddock-html: boolean + :synopsis: Build HTML documentation. + + :default: True + + Build HTML documentation. + + The command line variant of this flag is ``--html`` (for the + ``haddock`` command). + +.. cfg-field:: haddock-html-location: templated path + --html-location=TEMPLATE + :synopsis: Haddock HTML templates location. + + Specify a template for the location of HTML documentation for + prerequisite packages. The substitutions are applied to the template + to obtain a location for each package, which will be used by + hyperlinks in the generated documentation. For example, the + following command generates links pointing at [Hackage] pages: + + :: + + html-location: http://hackage.haskell.org/packages/archive/$pkg/latest/doc/html + + The command line variant of this flag is ``--html-location`` (for + the ``haddock`` subcommand). + + :: + + --html-location='http://hackage.haskell.org/packages/archive/$pkg/latest/doc/html' + + Here the argument is quoted to prevent substitution by the shell. If + this option is omitted, the location for each package is obtained + using the package tool (e.g. ``ghc-pkg``). + +.. cfg-field:: haddock-executables: boolean + :synopsis: Generate documentation for executables. + + :default: False + + Run haddock on all executable programs. + + The command line variant of this flag is ``--executables`` (for the + ``haddock`` subcommand). + +.. cfg-field:: haddock-tests: boolean + :synopsis: Generate documentation for tests. + + :default: False + + Run haddock on all test suites. + + The command line variant of this flag is ``--tests`` (for the + ``haddock`` subcommand). + +.. cfg-field:: haddock-benchmarks: boolean + :synopsis: Generate documentation for benchmarks. + + :default: False + + Run haddock on all benchmarks. + + The command line variant of this flag is ``--benchmarks`` (for the + ``haddock`` subcommand). + +.. cfg-field:: haddock-all: boolean + :synopsis: Generate documentation for everything + + :default: False + + Run haddock on all components. + + The command line variant of this flag is ``--all`` (for the + ``haddock`` subcommand). + +.. cfg-field:: haddock-internal: boolean + :synopsis: Generate documentation for internal modules + + :default: False + + Build haddock documentation which includes unexposed modules and + symbols. + + The command line variant of this flag is ``--internal`` (for the + ``haddock`` subcommand). + +.. cfg-field:: haddock-css: path + :synopsis: Location of Haddoc CSS file. + + The CSS file that should be used to style the generated + documentation (overriding haddock's default.) + + The command line variant of this flag is ``--css`` (for the + ``haddock`` subcommand). + +.. cfg-field:: haddock-hyperlink-source: boolean + :synopsis: Generate hyperlinked source code for documentation + + :default: False + + Generated hyperlinked source code using `HsColour`_, and have + Haddock documentation link to it. + + The command line variant of this flag is ``--hyperlink-source`` (for + the ``haddock`` subcommand). + +.. cfg-field:: haddock-hscolour-css: path + :synopsis: Location of CSS file for HsColour + + The CSS file that should be used to style the generated hyperlinked + source code (from `HsColour`_). + + The command line variant of this flag is ``--hscolour-css`` (for the + ``haddock`` subcommand). + +.. cfg-field:: haddock-contents-location: URL + :synopsis: URL for contents page. + + A baked-in URL to be used as the location for the contents page. + + The command line variant of this flag is ``--contents-location`` + (for the ``haddock`` subcommand). + +.. cfg-field:: haddock-keep-temp-files: boolean + :synopsis: Keep temporary Haddock files. + + Keep temporary files. + + The command line variant of this flag is ``--keep-temp-files`` (for + the ``haddock`` subcommand). + +Advanced global configuration options +------------------------------------- + +.. cfg-field:: write-ghc-environment-files: always, never, or ghc8.4.4+ + --write-ghc-environment-files=policy + :synopsis: Whether a ``.ghc.environment`` should be created after a successful build. + + :default: ``never`` + + Whether a `GHC package environment file `_ + should be created after a successful build. + + Since Cabal 3.0, defaults to ``never``. Before that, defaulted to + creating them only when compiling with GHC 8.4.4 and older (GHC + 8.4.4 `is the first version + `_ that supports + the ``-package-env -`` option that allows ignoring the package + environment files). + + +.. cfg-field:: http-transport: curl, wget, powershell, or plain-http + --http-transport=transport + :synopsis: Transport to use with http(s) requests. + + :default: ``curl`` + + Set a transport to be used when making http(s) requests. + + The command line variant of this field is ``--http-transport=curl``. + +.. cfg-field:: ignore-expiry: boolean + --ignore-expiry + :synopsis: Ignore Hackage expiration dates. + + :default: False + + If ``True``, we will ignore expiry dates on metadata from Hackage. + + In general, you should not set this to ``True`` as it will leave you + vulnerable to stale cache attacks. However, it may be temporarily + useful if the main Hackage server is down, and we need to rely on + mirrors which have not been updated for longer than the expiry + period on the timestamp. + + The command line variant of this field is ``--ignore-expiry``. + +.. cfg-field:: remote-repo-cache: directory + --remote-repo-cache=DIR + :synopsis: Location of packages cache. + + :default: ``~/.cabal/packages`` + + [STRIKEOUT:The location where packages downloaded from remote + repositories will be cached.] Not implemented yet. + + The command line variant of this flag is + ``--remote-repo-cache=DIR``. + +.. cfg-field:: logs-dir: directory + --logs-dir=DIR + :synopsis: Directory to store build logs. + + :default: ``~/.cabal/logs`` + + [STRIKEOUT:The location where build logs for packages are stored.] + Not implemented yet. + + The command line variant of this flag is ``--logs-dir=DIR``. + +.. cfg-field:: build-summary: template filepath + --build-summary=TEMPLATE + :synopsis: Build summaries location. + + :default: ``~/.cabal/logs/build.log`` + + [STRIKEOUT:The file to save build summaries. Valid variables which + can be used in the path are ``$pkgid``, ``$compiler``, ``$os`` and + ``$arch``.] Not implemented yet. + + The command line variant of this flag is + ``--build-summary=TEMPLATE``. + +.. cfg-field:: local-repo: directory + --local-repo=DIR + :deprecated: + + [STRIKEOUT:The location of a local repository.] Deprecated. See + "Legacy repositories." + + The command line variant of this flag is ``--local-repo=DIR``. + +.. cfg-field:: world-file: path + --world-file=FILE + :deprecated: + + [STRIKEOUT:The location of the world file.] Deprecated. + + The command line variant of this flag is ``--world-file=FILE``. + +Undocumented fields: ``root-cmd``, ``symlink-bindir``, ``build-log``, +``remote-build-reporting``, ``report-planned-failure``, ``one-shot``, +``offline``. + +Advanced solver options +^^^^^^^^^^^^^^^^^^^^^^^ + +Most users generally won't need these. + +.. cfg-field:: solver: modular + --solver=modular + :synopsis: Which solver to use. + + This field is reserved to allow the specification of alternative + dependency solvers. At the moment, the only accepted option is + ``modular``. + + The command line variant of this field is ``--solver=modular``. + +.. cfg-field:: max-backjumps: nat + --max-backjumps=N + :synopsis: Maximum number of solver backjumps. + + :default: 4000 + + Maximum number of backjumps (backtracking multiple steps) allowed + while solving. Set -1 to allow unlimited backtracking, and 0 to + disable backtracking completely. + + The command line variant of this field is ``--max-backjumps=4000``. + +.. cfg-field:: reorder-goals: boolean + --reorder-goals + --no-reorder-goals + :synopsis: Allow solver to reorder goals. + + :default: False + + When enabled, the solver will reorder goals according to certain + heuristics. Slows things down on average, but may make backtracking + faster for some packages. It's unlikely to help for small projects, + but for big install plans it may help you find a plan when otherwise + this is not possible. See :issue:`1780` for more commentary. + + The command line variant of this field is ``--(no-)reorder-goals``. + +.. cfg-field:: count-conflicts: boolean + --count-conflicts + --no-count-conflicts + :synopsis: Solver prefers versions with less conflicts. + + :default: True + + Try to speed up solving by preferring goals that are involved in a + lot of conflicts. + + The command line variant of this field is + ``--(no-)count-conflicts``. + +.. cfg-field:: fine-grained-conflicts: boolean + --fine-grained-conflicts + --no-fine-grained-conflicts + :synopsis: Skip a version of a package if it does not resolve any conflicts + encountered in the last version (solver optimization). + + :default: True + + When enabled, the solver will skip a version of a package if it does not + resolve any of the conflicts encountered in the last version of that + package. For example, if ``foo-1.2`` depended on ``bar``, and the solver + couldn't find consistent versions for ``bar``'s dependencies, then the + solver would skip ``foo-1.1`` if it also depended on ``bar``. + + The command line variant of this field is + ``--(no-)fine-grained-conflicts``. + +.. cfg-field:: minimize-conflict-set: boolean + --minimize-conflict-set + --no-minimize-conflict-set + :synopsis: Try to improve the solver error message when there is no + solution. + + :default: False + + When there is no solution, try to improve the solver error message + by finding a minimal conflict set. This option may increase run + time significantly, so it is off by default. + + The command line variant of this field is + ``--(no-)minimize-conflict-set``. + +.. cfg-field:: strong-flags: boolean + --strong-flags + --no-strong-flags + :synopsis: Do not defer flag choices when solving. + + :default: False + + Do not defer flag choices. (TODO: Better documentation.) + + The command line variant of this field is ``--(no-)strong-flags``. + +.. cfg-field:: allow-boot-library-installs: boolean + --allow-boot-library-installs + --no-allow-boot-library-installs + :synopsis: Allow cabal to install or upgrade any package. + + :default: False + + By default, the dependency solver doesn't allow ``base``, + ``ghc-prim``, ``integer-simple``, ``integer-gmp``, and + ``template-haskell`` to be installed or upgraded. This flag + removes the restriction. + + The command line variant of this field is + ``--(no-)allow-boot-library-installs``. + +.. cfg-field:: cabal-lib-version: version + --cabal-lib-version=version + :synopsis: Version of Cabal library used to build package. + + This field selects the version of the Cabal library which should be + used to build packages. This option is intended primarily for + internal development use (e.g., forcing a package to build with a + newer version of Cabal, to test a new version of Cabal.) (TODO: + Specify its semantics more clearly.) + + The command line variant of this field is + ``--cabal-lib-version=1.24.0.1``. + +.. include:: references.inc diff --git a/Cabal/doc/developing-packages.rst b/Cabal/doc/developing-packages.rst index 2cae0c318c7..de4c180c571 100644 --- a/Cabal/doc/developing-packages.rst +++ b/Cabal/doc/developing-packages.rst @@ -481,3285 +481,3 @@ options and more generally there is a configuration mechanism to customise many aspects of how a package is built depending on the Haskell implementation, the operating system, computer architecture and user-specified configuration flags. - -Developing packages -=================== - -The Cabal package is the unit of distribution. When installed, its -purpose is to make available: - -- One or more Haskell programs. - -- At most one library, exposing a number of Haskell modules. - -However having both a library and executables in a package does not work -very well; if the executables depend on the library, they must -explicitly list all the modules they directly or indirectly import from -that library. Fortunately, starting with Cabal 1.8.0.4, executables can -also declare the package that they are in as a dependency, and Cabal -will treat them as if they were in another package that depended on the -library. - -Internally, the package may consist of much more than a bunch of Haskell -modules: it may also have C source code and header files, source code -meant for preprocessing, documentation, test cases, auxiliary tools etc. - -A package is identified by a globally-unique *package name*, which -consists of one or more alphanumeric words separated by hyphens. To -avoid ambiguity, each of these words should contain at least one letter. -Chaos will result if two distinct packages with the same name are -installed on the same system. A particular version of the package is -distinguished by a *version number*, consisting of a sequence of one or -more integers separated by dots. These can be combined to form a single -text string called the *package ID*, using a hyphen to separate the name -from the version, e.g. "``HUnit-1.1``". - -.. Note:: - - Packages are not part of the Haskell language; they simply - populate the hierarchical space of module names. In GHC 6.6 and later a - program may contain multiple modules with the same name if they come - from separate packages; in all other current Haskell systems packages - may not overlap in the modules they provide, including hidden modules. - -Creating a package ------------------- - -Suppose you have a directory hierarchy containing the source files that -make up your package. You will need to add two more files to the root -directory of the package: - -:file:`{package-name}.cabal` - a Unicode UTF-8 text file containing a package description. For - details of the syntax of this file, see the section on - `package descriptions`_. - -:file:`Setup.hs` - a single-module Haskell program to perform various setup tasks (with - the interface described in the section on :ref:`installing-packages`). - This module should import only modules that will be present in all Haskell - implementations, including modules of the Cabal library. The content of - this file is determined by the :pkg-field:`build-type` setting in the - ``.cabal`` file. In most cases it will be trivial, calling on the Cabal - library to do most of the work. - -Once you have these, you can create a source bundle of this directory -for distribution. Building of the package is discussed in the section on -:ref:`installing-packages`. - -One of the purposes of Cabal is to make it easier to build a package -with different Haskell implementations. So it provides abstractions of -features present in different Haskell implementations and wherever -possible it is best to take advantage of these to increase portability. -Where necessary however it is possible to use specific features of -specific implementations. For example one of the pieces of information a -package author can put in the package's ``.cabal`` file is what language -extensions the code uses. This is far preferable to specifying flags for -a specific compiler as it allows Cabal to pick the right flags for the -Haskell implementation that the user picks. It also allows Cabal to -figure out if the language extension is even supported by the Haskell -implementation that the user picks. Where compiler-specific options are -needed however, there is an "escape hatch" available. The developer can -specify implementation-specific options and more generally there is a -configuration mechanism to customise many aspects of how a package is -built depending on the Haskell implementation, the Operating system, -computer architecture and user-specified configuration flags. - -:: - - name: Foo - version: 1.0 - - library - build-depends: base >= 4 && < 5 - exposed-modules: Foo - extensions: ForeignFunctionInterface - ghc-options: -Wall - if os(windows) - build-depends: Win32 >= 2.1 && < 2.6 - -Example: A package containing a simple library -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The HUnit package contains a file ``HUnit.cabal`` containing: - -:: - - name: HUnit - version: 1.1.1 - synopsis: A unit testing framework for Haskell - homepage: http://hunit.sourceforge.net/ - category: Testing - author: Dean Herington - license: BSD3 - license-file: LICENSE - cabal-version: 1.12 - build-type: Simple - - library - build-depends: base >= 2 && < 4 - exposed-modules: Test.HUnit.Base, Test.HUnit.Lang, - Test.HUnit.Terminal, Test.HUnit.Text, Test.HUnit - default-extensions: CPP - -and the following ``Setup.hs``: - -.. code-block:: haskell - - import Distribution.Simple - main = defaultMain - -Example: A package containing executable programs -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -:: - - name: TestPackage - version: 0.0 - synopsis: Small package with two programs - author: Angela Author - license: BSD3 - build-type: Simple - cabal-version: >= 1.8 - - executable program1 - build-depends: HUnit >= 1.1.1 && < 1.2 - main-is: Main.hs - hs-source-dirs: prog1 - - executable program2 - main-is: Main.hs - build-depends: HUnit >= 1.1.1 && < 1.2 - hs-source-dirs: prog2 - other-modules: Utils - -with ``Setup.hs`` the same as above. - -Example: A package containing a library and executable programs -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -:: - - name: TestPackage - version: 0.0 - synopsis: Package with library and two programs - license: BSD3 - author: Angela Author - build-type: Simple - cabal-version: >= 1.8 - - library - build-depends: HUnit >= 1.1.1 && < 1.2 - exposed-modules: A, B, C - - executable program1 - main-is: Main.hs - hs-source-dirs: prog1 - other-modules: A, B - - executable program2 - main-is: Main.hs - hs-source-dirs: prog2 - other-modules: A, C, Utils - -with ``Setup.hs`` the same as above. Note that any library modules -required (directly or indirectly) by an executable must be listed again. - -The trivial setup script used in these examples uses the *simple build -infrastructure* provided by the Cabal library (see -`Distribution.Simple <../release/cabal-latest/doc/API/Cabal/Distribution-Simple.html>`__). -The simplicity lies in its interface rather that its implementation. It -automatically handles preprocessing with standard preprocessors, and -builds packages for all the Haskell implementations. - -The simple build infrastructure can also handle packages where building -is governed by system-dependent parameters, if you specify a little more -(see the section on `system-dependent parameters`_). -A few packages require `more elaborate solutions `_. - -.. _pkg-desc: - -Package descriptions --------------------- - -The package description file must have a name ending in "``.cabal``". It -must be a Unicode text file encoded using valid UTF-8. There must be -exactly one such file in the directory. The first part of the name is -usually the package name, and some of the tools that operate on Cabal -packages require this; specifically, Hackage rejects packages which -don't follow this rule. - -In the package description file, lines whose first non-whitespace -characters are "``--``" are treated as comments and ignored. - -This file should contain of a number global property descriptions and -several sections. - -- The `package properties`_ describe the package - as a whole, such as name, license, author, etc. - -- Optionally, a number of *configuration flags* can be declared. These - can be used to enable or disable certain features of a package. (see - the section on `configurations`_). - -- The (optional) library section specifies the `library`_ properties and - relevant `build information`_. - -- Following is an arbitrary number of executable sections which describe - an executable program and relevant `build information`_. - -Each section consists of a number of property descriptions in the form -of field/value pairs, with a syntax roughly like mail message headers. - -- Case is not significant in field names, but is significant in field - values. - -- To continue a field value, indent the next line relative to the field - name. - -- Field names may be indented, but all field values in the same section - must use the same indentation. - -- Tabs are *not* allowed as indentation characters due to a missing - standard interpretation of tab width. - -- Before Cabal 3.0, to get a blank line in a field value, use an indented "``.``" - -The syntax of the value depends on the field. Field types include: - -*token*, *filename*, *directory* - Either a sequence of one or more non-space non-comma characters, or - a quoted string in Haskell 98 lexical syntax. The latter can be used - for escaping whitespace, for example: - ``ghc-options: -Wall "-with-rtsopts=-T -I1"``. Unless otherwise - stated, relative filenames and directories are interpreted from the - package root directory. -*freeform*, *URL*, *address* - An arbitrary, uninterpreted string. -*identifier* - A letter followed by zero or more alphanumerics or underscores. -*compiler* - A compiler flavor (one of: ``GHC``, ``UHC`` or ``LHC``) - followed by a version range. For example, ``GHC ==6.10.3``, or - ``LHC >=0.6 && <0.8``. - -Modules and preprocessors -^^^^^^^^^^^^^^^^^^^^^^^^^ - -Haskell module names listed in the :pkg-field:`library:exposed-modules` and -:pkg-field:`library:other-modules` fields may correspond to Haskell source -files, i.e. with names ending in "``.hs``" or "``.lhs``", or to inputs for -various Haskell preprocessors. The simple build infrastructure understands the -extensions: - -- ``.gc`` (:hackage-pkg:`greencard`) -- ``.chs`` (:hackage-pkg:`c2hs`) -- ``.hsc`` (:hackage-pkg:`hsc2hs`) -- ``.y`` and ``.ly`` (happy_) -- ``.x`` (alex_) -- ``.cpphs`` (cpphs_) - -When building, Cabal will automatically run the appropriate preprocessor -and compile the Haskell module it produces. For the ``c2hs`` and -``hsc2hs`` preprocessors, Cabal will also automatically add, compile and -link any C sources generated by the preprocessor (produced by -``hsc2hs``'s ``#def`` feature or ``c2hs``'s auto-generated wrapper -functions). Dependencies on pre-processors are specified via the -:pkg-field:`build-tools` or :pkg-field:`build-tool-depends` fields. - -Some fields take lists of values, which are optionally separated by -commas, except for the :pkg-field:`build-depends` field, where the commas are -mandatory. - -Some fields are marked as required. All others are optional, and unless -otherwise specified have empty default values. - -Package properties -^^^^^^^^^^^^^^^^^^ - -These fields may occur in the first top-level properties section and -describe the package as a whole: - -.. pkg-field:: name: package-name (required) - - The unique name of the package, without the version number. - - As pointed out in the section on `package descriptions`_, some - tools require the package-name specified for this field to match - the package description's file-name :file:`{package-name}.cabal`. - - Package names are case-sensitive and must match the regular expression - (i.e. alphanumeric "words" separated by dashes; each alphanumeric - word must contain at least one letter): - ``[[:digit:]]*[[:alpha:]][[:alnum:]]*(-[[:digit:]]*[[:alpha:]][[:alnum:]]*)*``. - - Or, expressed in ABNF_: - - .. code-block:: abnf - - package-name = package-name-part *("-" package-name-part) - package-name-part = *DIGIT UALPHA *UALNUM - - UALNUM = UALPHA / DIGIT - UALPHA = ... ; set of alphabetic Unicode code-points - - .. note:: - - Hackage restricts package names to the ASCII subset. - -.. pkg-field:: version: numbers (required) - - The package version number, usually consisting of a sequence of - natural numbers separated by dots, i.e. as the regular - expression ``[0-9]+([.][0-9]+)*`` or expressed in ABNF_: - - .. code-block:: abnf - - package-version = 1*DIGIT *("." 1*DIGIT) - -.. pkg-field:: cabal-version: x.y[.z] - - The version of the Cabal specification that this package - description uses. The Cabal specification does slowly evolve (see - also :ref:`spec-history`), introducing new features and - occasionally changing the meaning of existing features. By - specifying which version of the specification you are using it - enables programs which process the package description to know - what syntax to expect and what each part means. - - The version number you specify will affect both compatibility and - behaviour. Most tools (including the Cabal library and the ``cabal`` - program) understand a range of versions of the Cabal specification. - Older tools will of course only work with older versions of the - Cabal specification that was known at the time. Most of the time, - tools that are too old will recognise this fact and produce a - suitable error message. Likewise, ``cabal check`` will tell you - whether the version number is sufficiently high for the features - you use in the package description. - - As for behaviour, new versions of the Cabal specification can change the - meaning of existing syntax. This means if you want to take advantage - of the new meaning or behaviour then you must specify the newer - Cabal version. Tools are expected to use the meaning and behaviour - appropriate to the version given in the package description. - - In particular, the syntax of package descriptions changed - significantly with Cabal version 1.2 and the :pkg-field:`cabal-version` - field is now required. Files written in the old syntax are still - recognized, so if you require compatibility with very old Cabal - versions then you may write your package description file using the - old syntax. Please consult the user's guide of an older Cabal - version for a description of that syntax. - - Starting with ``cabal-version: 2.2`` this field is only valid if - fully contained in the very first line of a package description - and ought to adhere to the ABNF_ grammar - - .. code-block:: abnf - - newstyle-spec-version-decl = "cabal-version" *WS ":" *WS newstyle-spec-version *WS - - newstyle-spec-version = NUM "." NUM [ "." NUM ] - - NUM = DIGIT0 / DIGITP 1*DIGIT0 - DIGIT0 = %x30-39 - DIGITP = %x31-39 - WS = %20 - - - .. note:: - - For package descriptions using a format prior to - ``cabal-version: 1.12`` the legacy syntax resembling a version - range syntax - - .. code-block:: cabal - - cabal-version: >= 1.10 - - needs to be used. - - This legacy syntax is supported up until ``cabal-version: >= - 2.0`` it is however strongly recommended to avoid using the - legacy syntax. See also :issue:`4899`. - - - -.. pkg-field:: build-type: identifier - - :default: ``Custom`` or ``Simple`` - - The type of build used by this package. Build types are the - constructors of the - `BuildType <../release/cabal-latest/doc/API/Cabal/Distribution-PackageDescription.html#t:BuildType>`__ - type. This field is optional and when missing, its default value - is inferred according to the following rules: - - - When :pkg-field:`cabal-version` is set to ``2.2`` or higher, - the default is ``Simple`` unless a :pkg-section:`custom-setup` - exists, in which case the inferred default is ``Custom``. - - - For lower :pkg-field:`cabal-version` values, the default is - ``Custom`` unconditionally. - - If the build type is anything other than ``Custom``, then the - ``Setup.hs`` file *must* be exactly the standardized content - discussed below. This is because in these cases, ``cabal`` will - ignore the ``Setup.hs`` file completely, whereas other methods of - package management, such as ``runhaskell Setup.hs [CMD]``, still - rely on the ``Setup.hs`` file. - - For build type ``Simple``, the contents of ``Setup.hs`` must be: - - .. code-block:: haskell - - import Distribution.Simple - main = defaultMain - - For build type ``Configure`` (see the section on `system-dependent - parameters`_ below), the contents of - ``Setup.hs`` must be: - - .. code-block:: haskell - - import Distribution.Simple - main = defaultMainWithHooks autoconfUserHooks - - For build type ``Make`` (see the section on `more complex packages`_ below), - the contents of ``Setup.hs`` must be: - - .. code-block:: haskell - - import Distribution.Make - main = defaultMain - - For build type ``Custom``, the file ``Setup.hs`` can be customized, - and will be used both by ``cabal`` and other tools. - - For most packages, the build type ``Simple`` is sufficient. - -.. pkg-field:: license: SPDX expression - - :default: ``NONE`` - - The type of license under which this package is distributed. - - Starting with ``cabal-version: 2.2`` the ``license`` field takes a - (case-sensitive) SPDX expression such as - - .. code-block:: cabal - - license: Apache-2.0 AND (MIT OR GPL-2.0-or-later) - - See `SPDX IDs: How to use `__ for more - examples of SPDX expressions. - - The version of the - `list of SPDX license identifiers `__ - is a function of the :pkg-field:`cabal-version` value as defined - in the following table: - - +--------------------------+--------------------+ - | Cabal specification | SPDX license list | - | version | version | - | | | - +==========================+====================+ - | ``cabal-version: 2.2`` | ``3.0 2017-12-28`` | - +--------------------------+--------------------+ - | ``cabal-version: 2.4`` | ``3.2 2018-07-10`` | - +--------------------------+--------------------+ - - **Pre-SPDX Legacy Identifiers** - - The license identifier in the table below are defined for - ``cabal-version: 2.0`` and previous versions of the Cabal - specification. - - +--------------------------+-----------------+ - | :pkg-field:`license` | Note | - | identifier | | - | | | - +==========================+=================+ - | ``GPL`` | | - | ``GPL-2`` | | - | ``GPL-3`` | | - +--------------------------+-----------------+ - | ``LGPL`` | | - | ``LGPL-2.1`` | | - | ``LGPL-3`` | | - +--------------------------+-----------------+ - | ``AGPL`` | since 1.18 | - | ``AGPL-3`` | | - +--------------------------+-----------------+ - | ``BSD2`` | since 1.20 | - +--------------------------+-----------------+ - | ``BSD3`` | | - +--------------------------+-----------------+ - | ``MIT`` | | - +--------------------------+-----------------+ - | ``ISC`` | since 1.22 | - +--------------------------+-----------------+ - | ``MPL-2.0`` | since 1.20 | - +--------------------------+-----------------+ - | ``Apache`` | | - | ``Apache-2.0`` | | - +--------------------------+-----------------+ - | ``PublicDomain`` | | - +--------------------------+-----------------+ - | ``AllRightsReserved`` | | - +--------------------------+-----------------+ - | ``OtherLicense`` | | - +--------------------------+-----------------+ - - -.. pkg-field:: license-file: filename - - See :pkg-field:`license-files`. - -.. pkg-field:: license-files: filename list - :since: 1.20 - - The name of a file(s) containing the precise copyright license for - this package. The license file(s) will be installed with the - package. - - If you have multiple license files then use the :pkg-field:`license-files` - field instead of (or in addition to) the :pkg-field:`license-file` field. - -.. pkg-field:: copyright: freeform - - The content of a copyright notice, typically the name of the holder - of the copyright on the package and the year(s) from which copyright - is claimed. For example:: - - copyright: (c) 2006-2007 Joe Bloggs - -.. pkg-field:: author: freeform - - The original author of the package. - - Remember that ``.cabal`` files are Unicode, using the UTF-8 - encoding. - -.. pkg-field:: maintainer: address - - The current maintainer or maintainers of the package. This is an - e-mail address to which users should send bug reports, feature - requests and patches. - -.. pkg-field:: stability: freeform - - The stability level of the package, e.g. ``alpha``, - ``experimental``, ``provisional``, ``stable``. - -.. pkg-field:: homepage: URL - - The package homepage. - -.. pkg-field:: bug-reports: URL - - The URL where users should direct bug reports. This would normally - be either: - - - A ``mailto:`` URL, e.g. for a person or a mailing list. - - - An ``http:`` (or ``https:``) URL for an online bug tracking - system. - - For example Cabal itself uses a web-based bug tracking system - - :: - - bug-reports: https://github.com/haskell/cabal/issues - -.. pkg-field:: package-url: URL - - The location of a source bundle for the package. The distribution - should be a Cabal package. - -.. pkg-field:: synopsis: freeform - - A very short description of the package, for use in a table of - packages. This is your headline, so keep it short (one line) but as - informative as possible. Save space by not including the package - name or saying it's written in Haskell. - -.. pkg-field:: description: freeform - - Description of the package. This may be several paragraphs, and - should be aimed at a Haskell programmer who has never heard of your - package before. - - For library packages, this field is used as prologue text by - :ref:`setup-haddock` and thus may contain the same markup as Haddock_ - documentation comments. - -.. pkg-field:: category: freeform - - A classification category for future use by the package catalogue - Hackage_. These categories have not - yet been specified, but the upper levels of the module hierarchy - make a good start. - -.. pkg-field:: tested-with: compiler list - - A list of compilers and versions against which the package has been - tested (or at least built). The value of this field is not used by Cabal - and is rather intended as extra metadata for use by third party - tooling, such as e.g. CI tooling. - - Here's a typical usage example - - :: - - tested-with: GHC == 8.6.3, GHC == 8.4.4, GHC == 8.2.2, GHC == 8.0.2, - GHC == 7.10.3, GHC == 7.8.4, GHC == 7.6.3, GHC == 7.4.2 - - which can (starting with Cabal 3.0) also be written using the more - concise set notation syntax - - :: - - tested-with: GHC == { 8.6.3, 8.4.4, 8.2.2, 8.0.2, 7.10.3, 7.8.4, 7.6.3, 7.4.2 } - -.. pkg-field:: data-files: filename list - - A list of files to be installed for run-time use by the package. - This is useful for packages that use a large amount of static data, - such as tables of values or code templates. Cabal provides a way to - `find these files at run-time <#accessing-data-files-from-package-code>`_. - - A limited form of ``*`` wildcards in file names, for example - ``data-files: images/*.png`` matches all the ``.png`` files in the - ``images`` directory. ``data-files: audio/**/*.mp3`` matches all - the ``.mp3`` files in the ``audio`` directory, including - subdirectories. - - The specific limitations of this wildcard syntax are - - - ``*`` wildcards are only allowed in place of the file name, not - in the directory name or file extension. It must replace the - whole file name (e.g., ``*.html`` is allowed, but - ``chapter-*.html`` is not). If a wildcard is used, it must be - used with an extension, so ``data-files: data/*`` is not - allowed. - - - Prior to Cabal 2.4, when matching a wildcard plus extension, a - file's full extension must match exactly, so ``*.gz`` matches - ``foo.gz`` but not ``foo.tar.gz``. This restriction has been - lifted when ``cabal-version: 2.4`` or greater so that ``*.gz`` - does match ``foo.tar.gz`` - - - ``*`` wildcards will not match if the file name is empty (e.g., - ``*.html`` will not match ``foo/.html``). - - - ``**`` wildcards can only appear as the final path component - before the file name (e.g., ``data/**/images/*.jpg`` is not - allowed). If a ``**`` wildcard is used, then the file name must - include a ``*`` wildcard (e.g., ``data/**/README.rst`` is not - allowed). - - - A wildcard that does not match any files is an error. - - The reason for providing only a very limited form of wildcard is to - concisely express the common case of a large number of related files - of the same file type without making it too easy to accidentally - include unwanted files. - - On efficiency: if you use ``**`` patterns, the directory tree will - be walked starting with the parent directory of the ``**``. If - that's the root of the project, this might include ``.git/``, - ``dist-newstyle/``, or other large directories! To avoid this - behaviour, put the files that wildcards will match against in - their own folder. - - ``**`` wildcards are available starting in Cabal 2.4. - -.. pkg-field:: data-dir: directory - - The directory where Cabal looks for data files to install, relative - to the source directory. By default, Cabal will look in the source - directory itself. - -.. pkg-field:: extra-source-files: filename list - - A list of additional files to be included in source distributions - built with :ref:`setup-sdist`. As with :pkg-field:`data-files` it can use - a limited form of ``*`` wildcards in file names. - -.. pkg-field:: extra-doc-files: filename list - :since: 1.18 - - A list of additional files to be included in source distributions, - and also copied to the html directory when Haddock documentation is - generated. As with :pkg-field:`data-files` it can use a limited form of - ``*`` wildcards in file names. - -.. pkg-field:: extra-tmp-files: filename list - - A list of additional files or directories to be removed by - :ref:`setup-clean`. These would typically be additional files created by - additional hooks, such as the scheme described in the section on - `system-dependent parameters`_ - -Library -^^^^^^^ - -.. pkg-section:: library name - :synopsis: Library build information. - - Build information for libraries. - - Currently, there can only be one publicly exposed library in a - package, and its name is the same as package name set by global - :pkg-field:`name` field. In this case, the ``name`` argument to - the :pkg-section:`library` section must be omitted. - - Starting with Cabal 2.0, private internal sub-library components - can be defined by using setting the ``name`` field to a name - different from the current package's name; see section on - :ref:`Internal Libraries ` for more information. - -The library section should contain the following fields: - -.. pkg-field:: exposed-modules: identifier list - - :required: if this package contains a library - - A list of modules added by this package. - -.. pkg-field:: virtual-modules: identifier list - :since: 2.2 - - A list of virtual modules provided by this package. Virtual modules - are modules without a source file. See for example the ``GHC.Prim`` - module from the ``ghc-prim`` package. Modules listed here will not be - built, but still end up in the list of ``exposed-modules`` in the - installed package info when the package is registered in the package - database. - -.. pkg-field:: exposed: boolean - - :default: ``True`` - - Some Haskell compilers (notably GHC) support the notion of packages - being "exposed" or "hidden" which means the modules they provide can - be easily imported without always having to specify which package - they come from. However this only works effectively if the modules - provided by all exposed packages do not overlap (otherwise a module - import would be ambiguous). - - Almost all new libraries use hierarchical module names that do not - clash, so it is very uncommon to have to use this field. However it - may be necessary to set ``exposed: False`` for some old libraries - that use a flat module namespace or where it is known that the - exposed modules would clash with other common modules. - -.. pkg-field:: visibility: visibilty specifiers - - :since 3.0 - - :default: ``private`` for internal libraries. Cannot be set for public library. - - Cabal recognizes ``public`` and ``private`` here... - - Multiple public libraries... - -.. pkg-field:: reexported-modules: exportlist - :since: 1.22 - - Supported only in GHC 7.10 and later. A list of modules to - *reexport* from this package. The syntax of this field is - ``orig-pkg:Name as NewName`` to reexport module ``Name`` from - ``orig-pkg`` with the new name ``NewName``. We also support - abbreviated versions of the syntax: if you omit ``as NewName``, - we'll reexport without renaming; if you omit ``orig-pkg``, then we - will automatically figure out which package to reexport from, if - it's unambiguous. - - Reexported modules are useful for compatibility shims when a package - has been split into multiple packages, and they have the useful - property that if a package provides a module, and another package - reexports it under the same name, these are not considered a - conflict (as would be the case with a stub module.) They can also be - used to resolve name conflicts. - -.. pkg-field:: signatures: signature list - :since: 2.0 - - Supported only in GHC 8.2 and later. A list of `module signatures `__ required by this package. - - Module signatures are part of the Backpack_ extension to - the Haskell module system. - - Packages that do not export any modules and only export required signatures - are called "signature-only packages", and their signatures are subjected to - `signature thinning - `__. - - - -The library section may also contain build information fields (see the -section on `build information`_). - -.. _sublibs: - -**Internal Libraries** - -Cabal 2.0 and later support "internal libraries", which are extra named -libraries (as opposed to the usual unnamed library section). For -example, suppose that your test suite needs access to some internal -modules in your library, which you do not otherwise want to export. You -could put these modules in an internal library, which the main library -and the test suite :pkg-field:`build-depends` upon. Then your Cabal file might -look something like this: - -:: - - cabal-version: 2.0 - name: foo - version: 0.1.0.0 - license: BSD3 - build-type: Simple - - library foo-internal - exposed-modules: Foo.Internal - -- NOTE: no explicit constraints on base needed - -- as they're inherited from the 'library' stanza - build-depends: base - - library - exposed-modules: Foo.Public - build-depends: foo-internal, base >= 4.3 && < 5 - - test-suite test-foo - type: exitcode-stdio-1.0 - main-is: test-foo.hs - -- NOTE: no constraints on 'foo-internal' as same-package - -- dependencies implicitly refer to the same package instance - build-depends: foo-internal, base - -Internal libraries are also useful for packages that define multiple -executables, but do not define a publicly accessible library. Internal -libraries are only visible internally in the package (so they can only -be added to the :pkg-field:`build-depends` of same-package libraries, -executables, test suites, etc.) Internal libraries locally shadow any -packages which have the same name; consequently, don't name an internal -library with the same name as an external dependency if you need to be -able to refer to the external dependency in a -:pkg-field:`build-depends` declaration. - -Shadowing can be used to vendor an external dependency into a package -and thus emulate *private dependencies*. Below is an example based on -a real-world use case: - -:: - - cabal-version: 2.2 - name: haddock-library - version: 1.6.0 - - library - build-depends: - , base ^>= 4.11.1.0 - , bytestring ^>= 0.10.2.0 - , containers ^>= 0.4.2.1 || ^>= 0.5.0.0 - , transformers ^>= 0.5.0.0 - - hs-source-dirs: src - - -- internal sub-lib - build-depends: attoparsec - - exposed-modules: - Documentation.Haddock - - library attoparsec - build-depends: - , base ^>= 4.11.1.0 - , bytestring ^>= 0.10.2.0 - , deepseq ^>= 1.4.0.0 - - hs-source-dirs: vendor/attoparsec-0.13.1.0 - - -- NB: haddock-library needs only small part of lib:attoparsec - -- internally, so we only bundle that subset here - exposed-modules: - Data.Attoparsec.ByteString - Data.Attoparsec.Combinator - - other-modules: - Data.Attoparsec.Internal - - ghc-options: -funbox-strict-fields -Wall -fwarn-tabs -O2 - - -Opening an interpreter session -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -While developing a package, it is often useful to make its code -available inside an interpreter session. This can be done with the -``repl`` command: - -.. code-block:: console - - $ cabal repl - -The name comes from the acronym -`REPL `__, -which stands for "read-eval-print-loop". By default ``cabal repl`` loads -the first component in a package. If the package contains several named -components, the name can be given as an argument to ``repl``. The name -can be also optionally prefixed with the component's type for -disambiguation purposes. Example: - -.. code-block:: console - - $ cabal repl foo - $ cabal repl exe:foo - $ cabal repl test:bar - $ cabal repl bench:baz - -Freezing dependency versions -"""""""""""""""""""""""""""" - -If a package is built in several different environments, such as a -development environment, a staging environment and a production -environment, it may be necessary or desirable to ensure that the same -dependency versions are selected in each environment. This can be done -with the ``freeze`` command: - -.. code-block:: console - - $ cabal freeze - -The command writes the selected version for all dependencies to the -``cabal.config`` file. All environments which share this file will use -the dependency versions specified in it. - -Generating dependency version bounds -"""""""""""""""""""""""""""""""""""" - -Cabal also has the ability to suggest dependency version bounds that -conform to `Package Versioning Policy`_, which is -a recommended versioning system for publicly released Cabal packages. -This is done by running the ``gen-bounds`` command: - -.. code-block:: console - - $ cabal gen-bounds - -For example, given the following dependencies specified in -:pkg-field:`build-depends`: - -:: - - build-depends: - foo == 0.5.2 - bar == 1.1 - -``gen-bounds`` will suggest changing them to the following: - -:: - - build-depends: - foo >= 0.5.2 && < 0.6 - bar >= 1.1 && < 1.2 - -Listing outdated dependency version bounds -"""""""""""""""""""""""""""""""""""""""""" - -Manually updating dependency version bounds in a ``.cabal`` file or a -freeze file can be tedious, especially when there's a lot of -dependencies. The ``cabal outdated`` command is designed to help with -that. It will print a list of packages for which there is a new -version on Hackage that is outside the version bound specified in the -``build-depends`` field. The ``outdated`` command can also be -configured to act on the freeze file (both old- and v2-style) and -ignore major (or all) version bumps on Hackage for a subset of -dependencies. - -The following flags are supported by the ``outdated`` command: - -``--freeze-file`` - Read dependency version bounds from the freeze file (``cabal.config``) - instead of the package description file (``$PACKAGENAME.cabal``). - ``--v1-freeze-file`` is an alias for this flag starting in Cabal 2.4. -``--v2-freeze-file`` - :since: 2.4 - - Read dependency version bounds from the v2-style freeze file - (by default, ``cabal.project.freeze``) instead of the package - description file. ``--new-freeze-file`` is an alias for this flag - that can be used with pre-2.4 ``cabal``. -``--project-file`` *PROJECTFILE* - :since: 2.4 - - Read dependendency version bounds from the v2-style freeze file - related to the named project file (i.e., ``$PROJECTFILE.freeze``) - instead of the package desctription file. If multiple ``--project-file`` - flags are provided, only the final one is considered. This flag - must only be passed in when ``--new-freeze-file`` is present. -``--simple-output`` - Print only the names of outdated dependencies, one per line. -``--exit-code`` - Exit with a non-zero exit code when there are outdated dependencies. -``-q, --quiet`` - Don't print any output. Implies ``-v0`` and ``--exit-code``. -``--ignore`` *PACKAGENAMES* - Don't warn about outdated dependency version bounds for the packages in this - list. -``--minor`` *[PACKAGENAMES]* - Ignore major version bumps for these packages. E.g. if there's a version 2.0 - of a package ``pkg`` on Hackage and the freeze file specifies the constraint - ``pkg == 1.9``, ``cabal outdated --freeze --minor=pkg`` will only consider - the ``pkg`` outdated when there's a version of ``pkg`` on Hackage satisfying - ``pkg > 1.9 && < 2.0``. ``--minor`` can also be used without arguments, in - that case major version bumps are ignored for all packages. - -Examples: - -.. code-block:: console - - $ cd /some/package - $ cabal outdated - Outdated dependencies: - haskell-src-exts <1.17 (latest: 1.19.1) - language-javascript <0.6 (latest: 0.6.0.9) - unix ==2.7.2.0 (latest: 2.7.2.1) - - $ cabal outdated --simple-output - haskell-src-exts - language-javascript - unix - - $ cabal outdated --ignore=haskell-src-exts - Outdated dependencies: - language-javascript <0.6 (latest: 0.6.0.9) - unix ==2.7.2.0 (latest: 2.7.2.1) - - $ cabal outdated --ignore=haskell-src-exts,language-javascript,unix - All dependencies are up to date. - - $ cabal outdated --ignore=haskell-src-exts,language-javascript,unix -q - $ echo $? - 0 - - $ cd /some/other/package - $ cabal outdated --freeze-file - Outdated dependencies: - HTTP ==4000.3.3 (latest: 4000.3.4) - HUnit ==1.3.1.1 (latest: 1.5.0.0) - - $ cabal outdated --freeze-file --ignore=HTTP --minor=HUnit - Outdated dependencies: - HUnit ==1.3.1.1 (latest: 1.3.1.2) - - -Executables -^^^^^^^^^^^ - -.. pkg-section:: executable name - :synopsis: Executable build info section. - - Executable sections (if present) describe executable programs contained - in the package and must have an argument after the section label, which - defines the name of the executable. This is a freeform argument but may - not contain spaces. - -The executable may be described using the following fields, as well as -build information fields (see the section on `build information`_). - -.. pkg-field:: main-is: filename (required) - - The name of the ``.hs`` or ``.lhs`` file containing the ``Main`` - module. Note that it is the ``.hs`` filename that must be listed, - even if that file is generated using a preprocessor. The source file - must be relative to one of the directories listed in - :pkg-field:`hs-source-dirs`. Further, while the name of the file may - vary, the module itself must be named ``Main``. - - Starting with ``cabal-version: 1.18`` this field supports - specifying a C, C++, or objC source file as the main entry point. - -.. pkg-field:: scope: token - :since: 2.0 - - Whether the executable is ``public`` (default) or ``private``, i.e. meant to - be run by other programs rather than the user. Private executables are - installed into `$libexecdir/$libexecsubdir`. - -Running executables -""""""""""""""""""" - -You can have Cabal build and run your executables by using the ``run`` -command: - -.. code-block:: console - - $ cabal run EXECUTABLE [-- EXECUTABLE_FLAGS] - -This command will configure, build and run the executable -``EXECUTABLE``. The double dash separator is required to distinguish -executable flags from ``run``'s own flags. If there is only one -executable defined in the whole package, the executable's name can be -omitted. See the output of ``cabal help run`` for a list of options you -can pass to ``cabal run``. - -Test suites -^^^^^^^^^^^ - -.. pkg-section:: test-suite name - :synopsis: Test suite build information. - - Test suite sections (if present) describe package test suites and must - have an argument after the section label, which defines the name of the - test suite. This is a freeform argument, but may not contain spaces. It - should be unique among the names of the package's other test suites, the - package's executables, and the package itself. Using test suite sections - requires at least Cabal version 1.9.2. - -The test suite may be described using the following fields, as well as -build information fields (see the section on `build information`_). - -.. pkg-field:: type: interface (required) - - The interface type and version of the test suite. Cabal supports two - test suite interfaces, called ``exitcode-stdio-1.0`` and - ``detailed-0.9``. Each of these types may require or disallow other - fields as described below. - -Test suites using the ``exitcode-stdio-1.0`` interface are executables -that indicate test failure with a non-zero exit code when run; they may -provide human-readable log information through the standard output and -error channels. The ``exitcode-stdio-1.0`` type requires the ``main-is`` -field. - -.. pkg-field:: main-is: filename - :synopsis: Module containing tests main function. - - :required: ``exitcode-stdio-1.0`` - :disallowed: ``detailed-0.9`` - - The name of the ``.hs`` or ``.lhs`` file containing the ``Main`` - module. Note that it is the ``.hs`` filename that must be listed, - even if that file is generated using a preprocessor. The source file - must be relative to one of the directories listed in - :pkg-field:`hs-source-dirs`. This field is analogous to the ``main-is`` field - of an executable section. - -Test suites using the ``detailed-0.9`` interface are modules exporting -the symbol ``tests :: IO [Test]``. The ``Test`` type is exported by the -module ``Distribution.TestSuite`` provided by Cabal. For more details, -see the example below. - -The ``detailed-0.9`` interface allows Cabal and other test agents to -inspect a test suite's results case by case, producing detailed human- -and machine-readable log files. The ``detailed-0.9`` interface requires -the :pkg-field:`test-module` field. - -.. pkg-field:: test-module: identifier - - :required: ``detailed-0.9`` - :disallowed: ``exitcode-stdio-1.0`` - - The module exporting the ``tests`` symbol. - -Example: Package using ``exitcode-stdio-1.0`` interface -""""""""""""""""""""""""""""""""""""""""""""""""""""""" - -The example package description and executable source file below -demonstrate the use of the ``exitcode-stdio-1.0`` interface. - -.. code-block:: cabal - :caption: foo.cabal - - Name: foo - Version: 1.0 - License: BSD3 - Cabal-Version: >= 1.9.2 - Build-Type: Simple - - Test-Suite test-foo - type: exitcode-stdio-1.0 - main-is: test-foo.hs - build-depends: base >= 4 && < 5 - -.. code-block:: haskell - :caption: test-foo.hs - - module Main where - - import System.Exit (exitFailure) - - main = do - putStrLn "This test always fails!" - exitFailure - -Example: Package using ``detailed-0.9`` interface -""""""""""""""""""""""""""""""""""""""""""""""""" - -The example package description and test module source file below -demonstrate the use of the ``detailed-0.9`` interface. The test module -also develops a simple implementation of the interface set by -``Distribution.TestSuite``, but in actual usage the implementation would -be provided by the library that provides the testing facility. - -.. code-block:: cabal - :caption: bar.cabal - - Name: bar - Version: 1.0 - License: BSD3 - Cabal-Version: >= 1.9.2 - Build-Type: Simple - - Test-Suite test-bar - type: detailed-0.9 - test-module: Bar - build-depends: base >= 4 && < 5, Cabal >= 1.9.2 && < 2 - - -.. code-block:: haskell - :caption: Bar.hs - - module Bar ( tests ) where - - import Distribution.TestSuite - - tests :: IO [Test] - tests = return [ Test succeeds, Test fails ] - where - succeeds = TestInstance - { run = return $ Finished Pass - , name = "succeeds" - , tags = [] - , options = [] - , setOption = \_ _ -> Right succeeds - } - fails = TestInstance - { run = return $ Finished $ Fail "Always fails!" - , name = "fails" - , tags = [] - , options = [] - , setOption = \_ _ -> Right fails - } - -Running test suites -""""""""""""""""""" - -You can have Cabal run your test suites using its built-in test runner: - -:: - - $ cabal configure --enable-tests - $ cabal build - $ cabal test - -See the output of ``cabal help test`` for a list of options you can pass -to ``cabal test``. - -Benchmarks -^^^^^^^^^^ - -.. pkg-section:: benchmark name - :since: 1.9.2 - :synopsis: Benchmark build information. - - Benchmark sections (if present) describe benchmarks contained in the - package and must have an argument after the section label, which defines - the name of the benchmark. This is a freeform argument, but may not - contain spaces. It should be unique among the names of the package's - other benchmarks, the package's test suites, the package's executables, - and the package itself. Using benchmark sections requires at least Cabal - version 1.9.2. - -The benchmark may be described using the following fields, as well as -build information fields (see the section on `build information`_). - -.. pkg-field:: type: interface (required) - - The interface type and version of the benchmark. At the moment Cabal - only support one benchmark interface, called ``exitcode-stdio-1.0``. - -Benchmarks using the ``exitcode-stdio-1.0`` interface are executables -that indicate failure to run the benchmark with a non-zero exit code -when run; they may provide human-readable information through the -standard output and error channels. - -.. pkg-field:: main-is: filename - - :required: ``exitcode-stdio-1.0`` - - The name of the ``.hs`` or ``.lhs`` file containing the ``Main`` - module. Note that it is the ``.hs`` filename that must be listed, - even if that file is generated using a preprocessor. The source file - must be relative to one of the directories listed in - :pkg-field:`hs-source-dirs`. This field is analogous to the ``main-is`` - field of an executable section. Further, while the name of the file may - vary, the module itself must be named ``Main``. - -Example: Package using ``exitcode-stdio-1.0`` interface -""""""""""""""""""""""""""""""""""""""""""""""""""""""" - -The example package description and executable source file below -demonstrate the use of the ``exitcode-stdio-1.0`` interface. - -.. code-block:: cabal - :caption: foo.cabal - :name: foo-bench.cabal - - Name: foo - Version: 1.0 - License: BSD3 - Cabal-Version: >= 1.9.2 - Build-Type: Simple - - Benchmark bench-foo - type: exitcode-stdio-1.0 - main-is: bench-foo.hs - build-depends: base >= 4 && < 5, time >= 1.1 && < 1.7 - -.. code-block:: haskell - :caption: bench-foo.hs - - {-# LANGUAGE BangPatterns #-} - module Main where - - import Data.Time.Clock - - fib 0 = 1 - fib 1 = 1 - fib n = fib (n-1) + fib (n-2) - - main = do - start <- getCurrentTime - let !r = fib 20 - end <- getCurrentTime - putStrLn $ "fib 20 took " ++ show (diffUTCTime end start) - -Running benchmarks -"""""""""""""""""" - -You can have Cabal run your benchmark using its built-in benchmark -runner: - -:: - - $ cabal configure --enable-benchmarks - $ cabal build - $ cabal bench - -See the output of ``cabal help bench`` for a list of options you can -pass to ``cabal bench``. - -Foreign libraries -^^^^^^^^^^^^^^^^^ - -Foreign libraries are system libraries intended to be linked against -programs written in C or other "foreign" languages. They -come in two primary flavours: dynamic libraries (``.so`` files on Linux, -``.dylib`` files on OSX, ``.dll`` files on Windows, etc.) are linked against -executables when the executable is run (or even lazily during -execution), while static libraries (``.a`` files on Linux/OSX, ``.lib`` -files on Windows) get linked against the executable at compile time. - -Foreign libraries only work with GHC 7.8 and later. - -A typical stanza for a foreign library looks like - -:: - - foreign-library myforeignlib - type: native-shared - lib-version-info: 6:3:2 - - if os(Windows) - options: standalone - mod-def-file: MyForeignLib.def - - other-modules: MyForeignLib.SomeModule - MyForeignLib.SomeOtherModule - build-depends: base >=4.7 && <4.9 - hs-source-dirs: src - c-sources: csrc/MyForeignLibWrapper.c - default-language: Haskell2010 - - -.. pkg-section:: foreign-library name - :since: 2.0 - :synopsis: Foriegn library build information. - - Build information for `foreign libraries`_. - -.. pkg-field:: type: foreign library type - - Cabal recognizes ``native-static`` and ``native-shared`` here, although - we currently only support building `native-shared` libraries. - -.. pkg-field:: options: foreign library option list - - Options for building the foreign library, typically specific to the - specified type of foreign library. Currently we only support - ``standalone`` here. A standalone dynamic library is one that does not - have any dependencies on other (Haskell) shared libraries; without - the ``standalone`` option the generated library would have dependencies - on the Haskell runtime library (``libHSrts``), the base library - (``libHSbase``), etc. Currently, ``standalone`` *must* be used on Windows - and *must not* be used on any other platform. - -.. pkg-field:: mod-def-file: filename - - This option can only be used when creating dynamic Windows libraries - (that is, when using ``native-shared`` and the ``os`` is ``Windows``). If - used, it must be a path to a *module definition file*. The details of - module definition files are beyond the scope of this document; see the - `GHC `_ - manual for some details and some further pointers. - -.. pkg-field:: lib-version-info: current:revision:age - - This field is currently only used on Linux. - - This field specifies a Libtool-style version-info field that sets - an appropriate ABI version for the foreign library. Note that the - three numbers specified in this field do not directly specify the - actual ABI version: ``6:3:2`` results in library version ``4.2.3``. - - With this field set, the SONAME of the library is set, and symlinks - are installed. - - How you should bump this field on an ABI change depends on the - breakage you introduce: - - - Programs using the previous version may use the new version as - drop-in replacement, and programs using the new version can also - work with the previous one. In other words, no recompiling nor - relinking is needed. In this case, bump ``revision`` only, don't - touch current nor age. - - Programs using the previous version may use the new version as - drop-in replacement, but programs using the new version may use - APIs not present in the previous one. In other words, a program - linking against the new version may fail with "unresolved - symbols" if linking against the old version at runtime: set - revision to 0, bump current and age. - - Programs may need to be changed, recompiled, and relinked in - order to use the new version. Bump current, set revision and age - to 0. - - Also refer to the Libtool documentation on the version-info field. - -.. pkg-field:: lib-version-linux: version - - This field is only used on Linux. - - Specifies the library ABI version directly for foreign libraries - built on Linux: so specifying ``4.2.3`` causes a library - ``libfoo.so.4.2.3`` to be built with SONAME ``libfoo.so.4``, and - appropriate symlinks ``libfoo.so.4`` and ``libfoo.so`` to be - installed. - -Note that typically foreign libraries should export a way to initialize -and shutdown the Haskell runtime. In the example above, this is done by -the ``csrc/MyForeignLibWrapper.c`` file, which might look something like - -.. code-block:: c - - #include - #include "HsFFI.h" - - HsBool myForeignLibInit(void){ - int argc = 2; - char *argv[] = { "+RTS", "-A32m", NULL }; - char **pargv = argv; - - // Initialize Haskell runtime - hs_init(&argc, &pargv); - - // do any other initialization here and - // return false if there was a problem - return HS_BOOL_TRUE; - } - - void myForeignLibExit(void){ - hs_exit(); - } - -With modern ghc regular libraries are installed in directories that contain -package keys. This isn't usually a problem because the package gets registered -in ghc's package DB and so we can figure out what the location of the library -is. Foreign libraries however don't get registered, which means that we'd have -to have a way of finding out where a platform library got installed (other than by -searching the ``lib/`` directory). Instead, we install foreign libraries in -``~/.cabal/lib``, much like we install executables in ``~/.cabal/bin``. - -Build information -^^^^^^^^^^^^^^^^^ -.. pkg-section:: None - -The following fields may be optionally present in a library, executable, -test suite or benchmark section, and give information for the building -of the corresponding library or executable. See also the sections on -`system-dependent parameters`_ and `configurations`_ for a way to supply -system-dependent values for these fields. - -.. pkg-field:: build-depends: library list - - Declares the *library* dependencies required to build the current - package component; see :pkg-field:`build-tool-depends` for - declaring build-time *tool* dependencies. External library - dependencies should be annotated with a version constraint. - - **Library Names** - - External libraries are identified by the package's name they're - provided by (currently a package can only publicly expose its - main library compeonent; in future, packages with multiple exposed - public library components will be supported and a syntax for - referring to public sub-libraries will be provided). - - In order to specify an intra-package dependency on an internal - library component you can use the unqualified name of the - component library component. Note that locally defined sub-library - names shadow external package names of the same name. See section on - :ref:`Internal Libraries ` for examples and more information. - - **Version Constraints** - - Version constraints use the operators ``==, >=, >, <, <=`` and a - version number. Multiple constraints can be combined using ``&&`` or - ``||``. If no version constraint is specified, any version is - assumed to be acceptable. For example: - - :: - - library - build-depends: - base >= 2, - foo >= 1.2.3 && < 1.3, - bar - - Dependencies like ``foo >= 1.2.3 && < 1.3`` turn out to be very - common because it is recommended practise for package versions to - correspond to API versions (see PVP_). - - Since Cabal 1.6, there is a special wildcard syntax to help with - such ranges - - :: - - build-depends: foo ==1.2.* - - It is only syntactic sugar. It is exactly equivalent to - ``foo >= 1.2 && < 1.3``. - - .. Warning:: - - A potential pitfall of the wildcard syntax is that the - constraint ``nats == 1.0.*`` doesn't match the release - ``nats-1`` because the version ``1`` is lexicographically less - than ``1.0``. This is not an issue with the caret-operator - ``^>=`` described below. - - Starting with Cabal 2.0, there's a new version operator to express - PVP_-style major upper bounds conveniently, and is inspired by similar - syntactic sugar found in other language ecosystems where it's often - called the "Caret" operator: - - :: - - build-depends: - foo ^>= 1.2.3.4, - bar ^>= 1 - - This allows to assert the positive knowledge that this package is - *known* to be semantically compatible with the releases - ``foo-1.2.3.4`` and ``bar-1`` respectively. The information - encoded via such ``^>=``-assertions is used by the cabal solver to - infer version constraints describing semantically compatible - version ranges according to the PVP_ contract (see below). - - Another way to say this is that ``foo < 1.3`` expresses *negative* - information, i.e. "``foo-1.3`` or ``foo-1.4.2`` will *not* be - compatible"; whereas ``foo ^>= 1.2.3.4`` asserts the *positive* - information that "``foo-1.2.3.4`` is *known* to be compatible" and (in - the absence of additional information) according to the PVP_ - contract we can (positively) infer right away that all versions - satisfying ``foo >= 1.2.3.4 && < 1.3`` will be compatible as well. - - .. Note:: - - More generally, the PVP_ contract implies that we can safely - relax the lower bound to ``>= 1.2``, because if we know that - ``foo-1.2.3.4`` is semantically compatible, then so is - ``foo-1.2`` (if it typechecks). But we'd need to perform - additional static analysis (i.e. perform typechecking) in order - to know if our package in the role of an API consumer will - successfully typecheck against the dependency ``foo-1.2``. But - since we cannot do this analysis during constraint solving and - to keep things simple, we pragmatically use ``foo >= 1.2.3.4`` - as the initially inferred approximation for the lower bound - resulting from the assertion ``foo ^>= 1.2.3.4``. If further - evidence becomes available that e.g. ``foo-1.2`` typechecks, - one can simply revise the dependency specification to include - the assertion ``foo ^>= 1.2``. - - The subtle but important difference in signaling allows tooling to - treat explicitly expressed ``<``-style constraints and inferred - (``^>=``-style) upper bounds differently. For instance, - :option:`--allow-newer`'s ``^``-modifier allows to relax only - ``^>=``-style bounds while leaving explicitly stated - ``<``-constraints unaffected. - - Ignoring the signaling intent, the default syntactic desugaring rules are - - - ``^>= x`` == ``>= x && < x.1`` - - ``^>= x.y`` == ``>= x.y && < x.(y+1)`` - - ``^>= x.y.z`` == ``>= x.y.z && < x.(y+1)`` - - ``^>= x.y.z.u`` == ``>= x.y.z.u && < x.(y+1)`` - - etc. - - .. Note:: - - One might expected the desugaring to truncate all version - components below (and including) the patch-level, i.e. - ``^>= x.y.z.u`` == ``>= x.y.z && < x.(y+1)``, - as the major and minor version components alone are supposed to - uniquely identify the API according to the PVP_. However, by - designing ``^>=`` to be closer to the ``>=`` operator, we avoid - the potentially confusing effect of ``^>=`` being more liberal - than ``>=`` in the presence of patch-level versions. - - Consequently, the example declaration above is equivalent to - - :: - - build-depends: - foo >= 1.2.3.4 && < 1.3, - bar >= 1 && < 1.1 - - .. Note:: - - Prior to Cabal 1.8, ``build-depends`` specified in each - section were global to all sections. This was unintentional, but - some packages were written to depend on it, so if you need your - :pkg-field:`build-depends` to be local to each section, you must specify - at least ``Cabal-Version: >= 1.8`` in your ``.cabal`` file. - - .. Note:: - - Cabal 1.20 experimentally supported module thinning and - renaming in ``build-depends``; however, this support has since been - removed and should not be used. - - Starting with Cabal 3.0, a set notation for the ``==`` and ``^>=`` operator - is available. For instance, - - :: - - tested-with: GHC == 8.6.3, GHC == 8.4.4, GHC == 8.2.2, GHC == 8.0.2, - GHC == 7.10.3, GHC == 7.8.4, GHC == 7.6.3, GHC == 7.4.2 - - build-depends: network ^>= 2.6.3.6 || ^>= 2.7.0.2 || ^>= 2.8.0.0 || ^>= 3.0.1.0 - - can be then written in a more convenient and concise form - - :: - - tested-with: GHC == { 8.6.3, 8.4.4, 8.2.2, 8.0.2, 7.10.3, 7.8.4, 7.6.3, 7.4.2 } - - build-depends: network ^>= { 2.6.3.6, 2.7.0.2, 2.8.0.0, 3.0.1.0 } - - -.. pkg-field:: other-modules: identifier list - - A list of modules used by the component but not exposed to users. - For a library component, these would be hidden modules of the - library. For an executable, these would be auxiliary modules to be - linked with the file named in the ``main-is`` field. - - .. Note:: - - Every module in the package *must* be listed in one of - :pkg-field:`other-modules`, :pkg-field:`library:exposed-modules` or - :pkg-field:`executable:main-is` fields. - -.. pkg-field:: hs-source-dir: directory list - :deprecated: 2.0 - :removed: 3.0 - - :default: ``.`` - - Root directories for the module hierarchy. - - Deprecated in favor of :pkg-field:`hs-source-dirs`. - -.. pkg-field:: hs-source-dirs: directory list - - :default: ``.`` - - Root directories for the module hierarchy. - - .. note:: - - Components can share source directories but modules found there will be - recompiled even if other components already built them, i.e., if a - library and an executable share a source directory and the executable - depends on the library and imports its ``Foo`` module, ``Foo`` will be - compiled twice, once as part of the library and again for the executable. - -.. pkg-field:: default-extensions: identifier list - - A list of Haskell extensions used by every module. These determine - corresponding compiler options enabled for all files. Extension - names are the constructors of the - `Extension <../release/cabal-latest/doc/API/Cabal/Language-Haskell-Extension.html#t:Extension>`__ - type. For example, ``CPP`` specifies that Haskell source files are - to be preprocessed with a C preprocessor. - -.. pkg-field:: other-extensions: identifier list - - A list of Haskell extensions used by some (but not necessarily all) - modules. From GHC version 6.6 onward, these may be specified by - placing a ``LANGUAGE`` pragma in the source files affected e.g. - - .. code-block:: haskell - - {-# LANGUAGE CPP, MultiParamTypeClasses #-} - - In Cabal-1.24 the dependency solver will use this and - :pkg-field:`default-extensions` information. Cabal prior to 1.24 will abort - compilation if the current compiler doesn't provide the extensions. - - If you use some extensions conditionally, using CPP or conditional - module lists, it is good to replicate the condition in - :pkg-field:`other-extensions` declarations: - - :: - - other-extensions: CPP - if impl(ghc >= 7.5) - other-extensions: PolyKinds - - You could also omit the conditionally used extensions, as they are - for information only, but it is recommended to replicate them in - :pkg-field:`other-extensions` declarations. - -.. pkg-field:: extensions: identifier list - :deprecated: 1.12 - :removed: 3.0 - - Deprecated in favor of :pkg-field:`default-extensions`. - -.. pkg-field:: build-tool-depends: package:executable list - :since: 2.0 - - A list of Haskell executables needed to build this component. Executables are provided - during the whole duration of the component, so this field can be used for executables - needed during :pkg-section:`test-suite` as well. - - Each is specified by the package containing the executable and the name of the - executable itself, separated by a colon, and optionally followed by a version bound. - - All executables defined in the given Cabal file are termed as *internal* dependencies - as opposed to the rest which are *external* dependencies. - - Each of the two is handled differently: - - 1. External dependencies can (and should) contain a version bound like conventional - :pkg-field:`build-depends` dependencies. - 2. Internal depenedencies should not contain a version bound, as they will be always - resolved within the same configuration of the package in the build plan. - Specifically, version bounds that include the package's version will be warned for - being extraneous, and version bounds that exclude the package's version will raise - an error for being impossible to follow. - - For example (1) using a test-suite to make sure README.md Haskell snippets are tested using - `markdown-unlit `__: - - :: - - build-tool-depends: markdown-unlit:markdown-unlit >= 0.5.0 && < 0.6 - - For example (2) using a test-suite to test executable behaviour in the same package: - - :: - - build-tool-depends: mypackage:executable - - Cabal tries to make sure that all specified programs are atomically built and prepended - on the ``$PATH`` shell variable before building the component in question, but can only do - so for Nix-style builds. Specifically: - - a) For Nix-style local builds, both internal and external dependencies. - b) For old-style builds, only for internal dependencies [#old-style-build-tool-depends]_. - It's up to the user to provide needed executables in this case under `$PATH.` - - - .. note:: - - :pkg-field:`build-tool-depends` was added in Cabal 2.0, and it will - be ignored (with a warning) with old versions of Cabal. See - :pkg-field:`build-tools` for more information about backwards - compatibility. - -.. pkg-field:: build-tools: program list - :deprecated: 2.0 - :removed: 3.0 - - Deprecated in favor of :pkg-field:`build-tool-depends`, but :ref:`see below for backwards compatibility information `. - - A list of Haskell programs needed to build this component. - Each may be followed by an optional version bound. - Confusingly, each program in the list either refer to one of three things: - - 1. Another executables in the same package (supported since Cabal 1.12) - - 2. Tool name contained in Cabal's :ref:`hard-coded set of common tools ` - - 3. A pre-built executable that should already be on the ``PATH`` - (supported since Cabal 2.0) - - These cases are listed in order of priority: - an executable in the package will override any of the hard-coded packages with the same name, - and a hard-coded package will override any executable on the ``PATH``. - - In the first two cases, the list entry is desugared into a :pkg-field:`build-tool-depends` entry. - In the first case, the entry is desugared into a :pkg-field:`build-tool-depends` entry by prefixing with ``$pkg:``. - In the second case, it is desugared by looking up the package and executable name in a hard-coded table. - In either case, the optional version bound is passed through unchanged. - Refer to the documentation for :pkg-field:`build-tool-depends` to understand the desugared field's meaning, along with restrictions on version bounds. - - .. _buildtoolsbc: - - **Backward Compatibility** - - Although this field is deprecated in favor of :pkg-field:`build-tool-depends`, there are some situations where you may prefer to use :pkg-field:`build-tools` in cases (1) and (2), as it is supported by more versions of Cabal. - In case (3), :pkg-field:`build-tool-depends` is better for backwards-compatibility, as it will be ignored by old versions of Cabal; if you add the executable to :pkg-field:`build-tools`, a setup script built against old Cabal will choke. - If an old version of Cabal is used, an end-user will have to manually arrange for the requested executable to be in your ``PATH``. - - .. _buildtoolsmap: - - **Set of Known Tool Names** - - Identifiers specified in :pkg-field:`build-tools` are desugared into their respective equivalent :pkg-field:`build-tool-depends` form according to the table below. Consequently, a legacy specification such as:: - - build-tools: alex >= 3.2.1 && < 3.3, happy >= 1.19.5 && < 1.20 - - is simply desugared into the equivalent specification:: - - build-tool-depends: alex:alex >= 3.2.1 && < 3.3, happy:happy >= 1.19.5 && < 1.20 - - +--------------------------+-----------------------------------+-----------------+ - | :pkg-field:`build-tools` | desugared | Note | - | identifier | :pkg-field:`build-tool-depends` | | - | | identifier | | - +==========================+===================================+=================+ - | ``alex`` | ``alex:alex`` | | - +--------------------------+-----------------------------------+-----------------+ - | ``c2hs`` | ``c2hs:c2hs`` | | - +--------------------------+-----------------------------------+-----------------+ - | ``cpphs`` | ``cpphs:cpphs`` | | - +--------------------------+-----------------------------------+-----------------+ - | ``greencard`` | ``greencard:greencard`` | | - +--------------------------+-----------------------------------+-----------------+ - | ``haddock`` | ``haddock:haddock`` | | - +--------------------------+-----------------------------------+-----------------+ - | ``happy`` | ``happy:happy`` | | - +--------------------------+-----------------------------------+-----------------+ - | ``hsc2hs`` | ``hsc2hs:hsc2hs`` | | - +--------------------------+-----------------------------------+-----------------+ - | ``hscolour`` | ``hscolour:hscolour`` | | - +--------------------------+-----------------------------------+-----------------+ - | ``hspec-discover`` | ``hspec-discover:hspec-discover`` | since Cabal 2.0 | - +--------------------------+-----------------------------------+-----------------+ - - This built-in set can be programmatically extended via ``Custom`` setup scripts; this, however, is of limited use since the Cabal solver cannot access information injected by ``Custom`` setup scripts. - -.. pkg-field:: buildable: boolean - - :default: ``True`` - - Is the component buildable? Like some of the other fields below, - this field is more useful with the slightly more elaborate form of - the simple build infrastructure described in the section on - `system-dependent parameters`_. - -.. pkg-field:: ghc-options: token list - - Additional options for GHC. You can often achieve the same effect - using the :pkg-field:`default-extensions` field, which is preferred. - - Options required only by one module may be specified by placing an - ``OPTIONS_GHC`` pragma in the source file affected. - - As with many other fields, whitespace can be escaped by using - Haskell string syntax. Example: - ``ghc-options: -Wcompat "-with-rtsopts=-T -I1" -Wall``. - -.. pkg-field:: ghc-prof-options: token list - - Additional options for GHC when the package is built with profiling - enabled. - - Note that as of Cabal-1.24, the default profiling detail level - defaults to ``exported-functions`` for libraries and - ``toplevel-functions`` for executables. For GHC these correspond to - the flags ``-fprof-auto-exported`` and ``-fprof-auto-top``. Prior to - Cabal-1.24 the level defaulted to ``none``. These levels can be - adjusted by the person building the package with the - ``--profiling-detail`` and ``--library-profiling-detail`` flags. - - It is typically better for the person building the package to pick - the profiling detail level rather than for the package author. So - unless you have special needs it is probably better not to specify - any of the GHC ``-fprof-auto*`` flags here. However if you wish to - override the profiling detail level, you can do so using the - :pkg-field:`ghc-prof-options` field: use ``-fno-prof-auto`` or one of the - other ``-fprof-auto*`` flags. - -.. pkg-field:: ghc-shared-options: token list - - Additional options for GHC when the package is built as shared - library. The options specified via this field are combined with the - ones specified via :pkg-field:`ghc-options`, and are passed to GHC during - both the compile and link phases. - -.. pkg-field:: includes: filename list - - A list of header files to be included in any compilations via C. - This field applies to both header files that are already installed - on the system and to those coming with the package to be installed. - The former files should be found in absolute paths, while the latter - files should be found in paths relative to the top of the source - tree or relative to one of the directories listed in - :pkg-field:`include-dirs`. - - These files typically contain function prototypes for foreign - imports used by the package. This is in contrast to - :pkg-field:`install-includes`, which lists header files that are intended - to be exposed to other packages that transitively depend on this - library. - -.. pkg-field:: install-includes: filename list - - A list of header files from this package to be installed into - ``$libdir/includes`` when the package is installed. Files listed in - :pkg-field:`install-includes` should be found in relative to the top of the - source tree or relative to one of the directories listed in - :pkg-field:`include-dirs`. - - :pkg-field:`install-includes` is typically used to name header files that - contain prototypes for foreign imports used in Haskell code in this - package, for which the C implementations are also provided with the - package. For example, here is a ``.cabal`` file for a hypothetical - ``bindings-clib`` package that bundles the C source code for ``clib``:: - - include-dirs: cbits - c-sources: clib.c - install-includes: clib.h - - Now any package that depends (directly or transitively) on the - ``bindings-clib`` library can use ``clib.h``. - - Note that in order for files listed in :pkg-field:`install-includes` to be - usable when compiling the package itself, they need to be listed in - the :pkg-field:`includes` field as well. - -.. pkg-field:: include-dirs: directory list - - A list of directories to search for header files, when preprocessing - with ``c2hs``, ``hsc2hs``, ``cpphs`` or the C preprocessor, and also - when compiling via C. Directories can be absolute paths (e.g., for - system directories) or paths that are relative to the top of the - source tree. Cabal looks in these directories when attempting to - locate files listed in :pkg-field:`includes` and - :pkg-field:`install-includes`. - -.. pkg-field:: c-sources: filename list - - A list of C source files to be compiled and linked with the Haskell - files. - -.. pkg-field:: cxx-sources: filename list - :since: 2.2 - - A list of C++ source files to be compiled and linked with the Haskell - files. Useful for segregating C and C++ sources when supplying different - command-line arguments to the compiler via the :pkg-field:`cc-options` - and the :pkg-field:`cxx-options` fields. The files listed in the - :pkg-field:`cxx-sources` can reference files listed in the - :pkg-field:`c-sources` field and vice-versa. The object files will be linked - appropriately. - -.. pkg-field:: asm-sources: filename list - :since: 3.0 - - A list of assembly source files to be compiled and linked with the - Haskell files. - -.. pkg-field:: cmm-sources: filename list - :since: 3.0 - - A list of C-- source files to be compiled and linked with the Haskell - files. - -.. pkg-field:: js-sources: filename list - - A list of JavaScript source files to be linked with the Haskell - files (only for JavaScript targets). - -.. pkg-field:: extra-libraries: token list - - A list of extra libraries to link with. - -.. pkg-field:: extra-ghci-libraries: token list - - A list of extra libraries to be used instead of 'extra-libraries' - when the package is loaded with GHCi. - -.. pkg-field:: extra-bundled-libraries: token list - :since: 2.2 - - A list of libraries that are supposed to be copied from the build - directory alongside the produced Haskell libraries. Note that you - are under the obligation to produce those libraries in the build - directory (e.g. via a custom setup). Libraries listed here will - be included when ``copy``-ing packages and be listed in the - ``hs-libraries`` of the package configuration in the package database. - Library names must either be prefixed with "HS" or "C" and corresponding - library file names must match: - - - Libraries with name "HS": - - `libHS.a` - - `libHS-ghc.*` - - Libraries with name "C": - - `libC.a` - - `lib.*` - -.. pkg-field:: extra-lib-dirs: directory list - - A list of directories to search for libraries. - -.. pkg-field:: cc-options: token list - - Command-line arguments to be passed to the C compiler. Since the - arguments are compiler-dependent, this field is more useful with the - setup described in the section on `system-dependent parameters`_. - -.. pkg-field:: cpp-options: token list - - Command-line arguments for pre-processing Haskell code. Applies to - Haskell source and other pre-processed Haskell source like .hsc - .chs. Does not apply to C code, that's what cc-options is for. - -.. pkg-field:: cxx-options: token list - :since: 2.2 - - Command-line arguments to be passed to the compiler when compiling - C++ code. The C++ sources to which these command-line arguments - should be applied can be specified with the :pkg-field:`cxx-sources` - field. Command-line options for C and C++ can be passed separately to - the compiler when compiling both C and C++ sources by segregating the C - and C++ sources with the :pkg-field:`c-sources` and - :pkg-field:`cxx-sources` fields respectively, and providing different - command-line arguments with the :pkg-field:`cc-options` and the - :pkg-field:`cxx-options` fields. - -.. pkg-field:: cmm-options: token list - :since: 3.0 - - Command-line arguments to be passed to the compiler when compiling - C-- code. See also :pkg-field:`cmm-sources`. - -.. pkg-field:: asm-options: token list - :since: 3.0 - - Command-line arguments to be passed to the assembler when compiling - assembler code. See also :pkg-field:`asm-sources`. - -.. pkg-field:: ld-options: token list - - Command-line arguments to be passed to the linker. Since the - arguments are compiler-dependent, this field is more useful with the - setup described in the section on `system-dependent parameters`_. - -.. pkg-field:: pkgconfig-depends: package list - - A list of - `pkg-config `__ - packages, needed to build this package. They can be annotated with - versions, e.g. ``gtk+-2.0 >= 2.10, cairo >= 1.0``. If no version - constraint is specified, any version is assumed to be acceptable. - Cabal uses ``pkg-config`` to find if the packages are available on - the system and to find the extra compilation and linker options - needed to use the packages. - - If you need to bind to a C library that supports ``pkg-config`` then - it is much preferable to use this field rather than hard code options - into the other fields. ``pkg-config --list-all`` will show you all - supported libraries. Depending on your system you may need to adjust - ``PKG_CONFIG_PATH``. - -.. pkg-field:: frameworks: token list - - On Darwin/MacOS X, a list of frameworks to link to. See Apple's - developer documentation for more details on frameworks. This entry - is ignored on all other platforms. - -.. pkg-field:: extra-frameworks-dirs: directory list - :since: 1.24 - - On Darwin/MacOS X, a list of directories to search for frameworks. - This entry is ignored on all other platforms. - -.. pkg-field:: mixins: mixin list - :since: 2.0 - - Supported only in GHC 8.2 and later. A list of packages mentioned in the - :pkg-field:`build-depends` field, each optionally accompanied by a list of - module and module signature renamings. - - The simplest mixin syntax is simply the name of a package mentioned in the - :pkg-field:`build-depends` field. For example: - - :: - - library - build-depends: - foo ^>= 1.2.3 - mixins: - foo - - But this doesn't have any effect. More interesting is to use the mixin - entry to rename one or more modules from the package, like this: - - :: - - library - mixins: - foo (Foo.Bar as AnotherFoo.Bar, Foo.Baz as AnotherFoo.Baz) - - Note that renaming a module like this will hide all the modules - that are not explicitly named. - - Modules can also be hidden: - - :: - - library: - mixins: - foo hiding (Foo.Bar) - - Hiding modules exposes everything that is not explicitly hidden. - - .. Note:: - - The current version of Cabal suffers from an infelicity in how the - entries of :pkg-field:`mixins` are parsed: an entry will fail to parse - if the provided renaming clause has whitespace after the opening - parenthesis. This will be fixed in future versions of Cabal. - - See issues :issue:`5150`, :issue:`4864`, and :issue:`5293`. - - There can be multiple mixin entries for a given package, in effect creating - multiple copies of the dependency: - - :: - - library - mixins: - foo (Foo.Bar as AnotherFoo.Bar, Foo.Baz as AnotherFoo.Baz), - foo (Foo.Bar as YetAnotherFoo.Bar) - - The ``requires`` clause is used to rename the module signatures required by - a package: - - :: - - library - mixins: - foo (Foo.Bar as AnotherFoo.Bar) requires (Foo.SomeSig as AnotherFoo.SomeSig) - - Signature-only packages don't have any modules, so only the signatures can - be renamed, with the following syntax: - - :: - - library - mixins: - sigonly requires (SigOnly.SomeSig as AnotherSigOnly.SomeSig) - - See the :pkg-field:`library:signatures` field for more details. - - Mixin packages are part of the Backpack_ extension to the - Haskell module system. - - The matching of the module signatures required by a - :pkg-field:`build-depends` dependency with the implementation modules - present in another dependency is triggered by a coincidence of names. When - the names of the signature and of the implementation are already the same, - the matching is automatic. But when the names don't coincide, or we want to - instantiate a signature in two different ways, adding mixin entries that - perform renamings becomes necessary. - - .. Warning:: - - Backpack_ has the limitation that implementation modules that instantiate - signatures required by a :pkg-field:`build-depends` dependency can't - reside in the same component that has the dependency. They must reside - in a different package dependency, or at least in a separate internal - library. - -Configurations -^^^^^^^^^^^^^^ - -Library and executable sections may include conditional blocks, which -test for various system parameters and configuration flags. The flags -mechanism is rather generic, but most of the time a flag represents -certain feature, that can be switched on or off by the package user. -Here is an example package description file using configurations: - -Example: A package containing a library and executable programs -""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" - -:: - - Name: Test1 - Version: 0.0.1 - Cabal-Version: >= 1.8 - License: BSD3 - Author: Jane Doe - Synopsis: Test package to test configurations - Category: Example - Build-Type: Simple - - Flag Debug - Description: Enable debug support - Default: False - Manual: True - - Flag WebFrontend - Description: Include API for web frontend. - Default: False - Manual: True - - Flag NewDirectory - description: Whether to build against @directory >= 1.2@ - -- This is an automatic flag which the solver will be - -- assign automatically while searching for a solution - - Library - Build-Depends: base >= 4.2 && < 4.9 - Exposed-Modules: Testing.Test1 - Extensions: CPP - - GHC-Options: -Wall - if flag(Debug) - CPP-Options: -DDEBUG - if !os(windows) - CC-Options: "-DDEBUG" - else - CC-Options: "-DNDEBUG" - - if flag(WebFrontend) - Build-Depends: cgi >= 0.42 && < 0.44 - Other-Modules: Testing.WebStuff - CPP-Options: -DWEBFRONTEND - - if flag(NewDirectory) - build-depends: directory >= 1.2 && < 1.4 - Build-Depends: time >= 1.0 && < 1.9 - else - build-depends: directory == 1.1.* - Build-Depends: old-time >= 1.0 && < 1.2 - - Executable test1 - Main-is: T1.hs - Other-Modules: Testing.Test1 - Build-Depends: base >= 4.2 && < 4.9 - - if flag(debug) - CC-Options: "-DDEBUG" - CPP-Options: -DDEBUG - -Layout -"""""" - -Flags, conditionals, library and executable sections use layout to -indicate structure. This is very similar to the Haskell layout rule. -Entries in a section have to all be indented to the same level which -must be more than the section header. Tabs are not allowed to be used -for indentation. - -As an alternative to using layout you can also use explicit braces -``{}``. In this case the indentation of entries in a section does not -matter, though different fields within a block must be on different -lines. Here is a bit of the above example again, using braces: - -Example: Using explicit braces rather than indentation for layout -""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" - -:: - - Name: Test1 - Version: 0.0.1 - Cabal-Version: >= 1.8 - License: BSD3 - Author: Jane Doe - Synopsis: Test package to test configurations - Category: Example - Build-Type: Simple - - Flag Debug { - Description: Enable debug support - Default: False - Manual: True - } - - Library { - Build-Depends: base >= 4.2 && < 4.9 - Exposed-Modules: Testing.Test1 - Extensions: CPP - if flag(debug) { - CPP-Options: -DDEBUG - if !os(windows) { - CC-Options: "-DDEBUG" - } else { - CC-Options: "-DNDEBUG" - } - } - } - -Configuration Flags -""""""""""""""""""" - -.. pkg-section:: flag name - :synopsis: Flag declaration. - - Flag section declares a flag which can be used in `conditional blocks`_. - - Flag names are case-insensitive and must match ``[[:alnum:]_][[:alnum:]_-]*`` - regular expression, or expressed as ABNF_: - - .. code-block:: abnf - - flag-name = (UALNUM / "_") *(UALNUM / "_" / "-") - - UALNUM = UALPHA / DIGIT - UALPHA = ... ; set of alphabetic Unicode code-points - - .. note:: - - Hackage accepts ASCII-only flags, ``[a-zA-Z0-9_][a-zA-Z0-9_-]*`` regexp. - -.. pkg-field:: description: freeform - - The description of this flag. - -.. pkg-field:: default: boolean - - :default: ``True`` - - The default value of this flag. - - .. note:: - - This value may be `overridden in several - ways `__. The - rationale for having flags default to True is that users usually - want new features as soon as they are available. Flags representing - features that are not (yet) recommended for most users (such as - experimental features or debugging support) should therefore - explicitly override the default to False. - -.. pkg-field:: manual: boolean - - :default: ``False`` - :since: 1.6 - - By default, Cabal will first try to satisfy dependencies with the - default flag value and then, if that is not possible, with the - negated value. However, if the flag is manual, then the default - value (which can be overridden by commandline flags) will be used. - -Conditional Blocks -^^^^^^^^^^^^^^^^^^ - -Conditional blocks may appear anywhere inside a library or executable -section. They have to follow rather strict formatting rules. Conditional -blocks must always be of the shape - -:: - - if condition - property-descriptions-or-conditionals - -or - -:: - - if condition - property-descriptions-or-conditionals - else - property-descriptions-or-conditionals - -Note that the ``if`` and the condition have to be all on the same line. - -Since Cabal 2.2 conditional blocks support ``elif`` construct. - -:: - - if condition1 - property-descriptions-or-conditionals - elif condition2 - property-descriptions-or-conditionals - else - property-descriptions-or-conditionals - -Conditions -"""""""""" - -Conditions can be formed using boolean tests and the boolean operators -``||`` (disjunction / logical "or"), ``&&`` (conjunction / logical -"and"), or ``!`` (negation / logical "not"). The unary ``!`` takes -highest precedence, ``||`` takes lowest. Precedence levels may be -overridden through the use of parentheses. For example, -``os(darwin) && !arch(i386) || os(freebsd)`` is equivalent to -``(os(darwin) && !(arch(i386))) || os(freebsd)``. - -The following tests are currently supported. - -:samp:`os({name})` - Tests if the current operating system is *name*. The argument is - tested against ``System.Info.os`` on the target system. There is - unfortunately some disagreement between Haskell implementations - about the standard values of ``System.Info.os``. Cabal canonicalises - it so that in particular ``os(windows)`` works on all - implementations. If the canonicalised os names match, this test - evaluates to true, otherwise false. The match is case-insensitive. -:samp:`arch({name})` - Tests if the current architecture is *name*. The argument is matched - against ``System.Info.arch`` on the target system. If the arch names - match, this test evaluates to true, otherwise false. The match is - case-insensitive. -:samp:`impl({compiler})` - Tests for the configured Haskell implementation. An optional version - constraint may be specified (for example ``impl(ghc >= 6.6.1)``). If - the configured implementation is of the right type and matches the - version constraint, then this evaluates to true, otherwise false. - The match is case-insensitive. - - Note that including a version constraint in an ``impl`` test causes - it to check for two properties: - - - The current compiler has the specified name, and - - - The compiler's version satisfied the specified version constraint - - As a result, ``!impl(ghc >= x.y.z)`` is not entirely equivalent to - ``impl(ghc < x.y.z)``. The test ``!impl(ghc >= x.y.z)`` checks that: - - - The current compiler is not GHC, or - - - The version of GHC is earlier than version x.y.z. - -:samp:`flag({name})` - Evaluates to the current assignment of the flag of the given name. - Flag names are case insensitive. Testing for flags that have not - been introduced with a flag section is an error. -``true`` - Constant value true. -``false`` - Constant value false. - -Resolution of Conditions and Flags -"""""""""""""""""""""""""""""""""" - -If a package descriptions specifies configuration flags the package user -can `control these in several -ways `__. If the -user does not fix the value of a flag, Cabal will try to find a flag -assignment in the following way. - -- For each flag specified, it will assign its default value, evaluate - all conditions with this flag assignment, and check if all - dependencies can be satisfied. If this check succeeded, the package - will be configured with those flag assignments. - -- If dependencies were missing, the last flag (as by the order in which - the flags were introduced in the package description) is tried with - its alternative value and so on. This continues until either an - assignment is found where all dependencies can be satisfied, or all - possible flag assignments have been tried. - -To put it another way, Cabal does a complete backtracking search to find -a satisfiable package configuration. It is only the dependencies -specified in the :pkg-field:`build-depends` field in conditional blocks that -determine if a particular flag assignment is satisfiable -(:pkg-field:`build-tools` are not considered). The order of the declaration and -the default value of the flags determines the search order. Flags -overridden on the command line fix the assignment of that flag, so no -backtracking will be tried for that flag. - -If no suitable flag assignment could be found, the configuration phase -will fail and a list of missing dependencies will be printed. Note that -this resolution process is exponential in the worst case (i.e., in the -case where dependencies cannot be satisfied). There are some -optimizations applied internally, but the overall complexity remains -unchanged. - -Meaning of field values when using conditionals -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -During the configuration phase, a flag assignment is chosen, all -conditionals are evaluated, and the package description is combined into -a flat package descriptions. If the same field both inside a conditional -and outside then they are combined using the following rules. - -- Boolean fields are combined using conjunction (logical "and"). - -- List fields are combined by appending the inner items to the outer - items, for example - - :: - - other-extensions: CPP - if impl(ghc) - other-extensions: MultiParamTypeClasses - - when compiled using GHC will be combined to - - :: - - other-extensions: CPP, MultiParamTypeClasses - - Similarly, if two conditional sections appear at the same nesting - level, properties specified in the latter will come after properties - specified in the former. - -- All other fields must not be specified in ambiguous ways. For example - - :: - - Main-is: Main.hs - if flag(useothermain) - Main-is: OtherMain.hs - - will lead to an error. Instead use - - :: - - if flag(useothermain) - Main-is: OtherMain.hs - else - Main-is: Main.hs - -Common stanzas -^^^^^^^^^^^^^^ - -.. pkg-section:: common name - :since: 2.2 - :synopsis: Common build info section - -Starting with Cabal-2.2 it's possible to use common build info stanzas. - -:: - - common deps - build-depends: base ^>= 4.11 - ghc-options: -Wall - - common test-deps - build-depends: tasty ^>= 0.12.0.1 - - library - import: deps - exposed-modules: Foo - - test-suite tests - import: deps, test-deps - type: exitcode-stdio-1.0 - main-is: Tests.hs - build-depends: foo - -- You can use `build information`_ fields in common stanzas. - -- Common stanzas must be defined before use. - -- Common stanzas can import other common stanzas. - -- You can import multiple stanzas at once. Stanza names must be separated by commas. - -- ``import`` must be the first field in a section. Since Cabal 3.0 imports - are also allowed inside conditionals. - -.. Note:: - - The name `import` was chosen, because there is ``includes`` field. - -Source Repositories -^^^^^^^^^^^^^^^^^^^ - -.. pkg-section:: source-repository - :since: 1.6 - -It is often useful to be able to specify a source revision control -repository for a package. Cabal lets you specifying this information in -a relatively structured form which enables other tools to interpret and -make effective use of the information. For example the information -should be sufficient for an automatic tool to checkout the sources. - -Cabal supports specifying different information for various common -source control systems. Obviously not all automated tools will support -all source control systems. - -Cabal supports specifying repositories for different use cases. By -declaring which case we mean automated tools can be more useful. There -are currently two kinds defined: - -- The ``head`` kind refers to the latest development branch of the - package. This may be used for example to track activity of a project - or as an indication to outside developers what sources to get for - making new contributions. - -- The ``this`` kind refers to the branch and tag of a repository that - contains the sources for this version or release of a package. For - most source control systems this involves specifying a tag, id or - hash of some form and perhaps a branch. The purpose is to be able to - reconstruct the sources corresponding to a particular package - version. This might be used to indicate what sources to get if - someone needs to fix a bug in an older branch that is no longer an - active head branch. - -You can specify one kind or the other or both. As an example here are -the repositories for the Cabal library. Note that the ``this`` kind of -repository specifies a tag. - -:: - - source-repository head - type: darcs - location: http://darcs.haskell.org/cabal/ - - source-repository this - type: darcs - location: http://darcs.haskell.org/cabal-branches/cabal-1.6/ - tag: 1.6.1 - -The exact fields are as follows: - -.. pkg-field:: type: token - - The name of the source control system used for this repository. The - currently recognised types are: - - - ``darcs`` - - ``git`` - - ``svn`` - - ``cvs`` - - ``mercurial`` (or alias ``hg``) - - ``bazaar`` (or alias ``bzr``) - - ``arch`` - - ``monotone`` - - This field is required. - -.. pkg-field:: location: URL - - The location of the repository. The exact form of this field depends - on the repository type. For example: - - - for darcs: ``http://code.haskell.org/foo/`` - - for git: ``git://github.com/foo/bar.git`` - - for CVS: ``anoncvs@cvs.foo.org:/cvs`` - - This field is required. - -.. pkg-field:: module: token - - CVS requires a named module, as each CVS server can host multiple - named repositories. - - This field is required for the CVS repository type and should not be - used otherwise. - -.. pkg-field:: branch: token - - Many source control systems support the notion of a branch, as a - distinct concept from having repositories in separate locations. For - example CVS, SVN and git use branches while for darcs uses different - locations for different branches. If you need to specify a branch to - identify a your repository then specify it in this field. - - This field is optional. - -.. pkg-field:: tag: token - - A tag identifies a particular state of a source repository. The tag - can be used with a ``this`` repository kind to identify the state of - a repository corresponding to a particular package version or - release. The exact form of the tag depends on the repository type. - - This field is required for the ``this`` repository kind. - -.. pkg-field:: subdir: directory - - Some projects put the sources for multiple packages under a single - source repository. This field lets you specify the relative path - from the root of the repository to the top directory for the - package, i.e. the directory containing the package's ``.cabal`` - file. - - This field is optional. It default to empty which corresponds to the - root directory of the repository. - -Downloading a package's source -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The ``cabal get`` command allows to access a package's source code - -either by unpacking a tarball downloaded from Hackage (the default) or -by checking out a working copy from the package's source repository. - -:: - - $ cabal get [FLAGS] PACKAGES - -The ``get`` command supports the following options: - -``-d --destdir`` *PATH* - Where to place the package source, defaults to (a subdirectory of) - the current directory. -``-s --source-repository`` *[head\|this\|...]* - Fork the package's source repository using the appropriate version - control system. The optional argument allows to choose a specific - repository kind. -``--index-state`` *[HEAD\|@\|]* - Use source package index state as it existed at a previous time. Accepts - unix-timestamps (e.g. ``@1474732068``), ISO8601 UTC timestamps (e.g. - ``2016-09-24T17:47:48Z``), or ``HEAD`` (default). - This determines which package versions are available as well as which - ``.cabal`` file revision is selected (unless ``--pristine`` is used). -``--pristine`` - Unpack the original pristine tarball, rather than updating the - ``.cabal`` file with the latest revision from the package archive. - -Custom setup scripts --------------------- - -Since Cabal 1.24, custom ``Setup.hs`` are required to accurately track -their dependencies by declaring them in the ``.cabal`` file rather than -rely on dependencies being implicitly in scope. Please refer -`this article `__ -for more details. - -As of Cabal library version 3.0, ``defaultMain*`` variants implement support -for response files. Custom ``Setup.hs`` files that do not use one of these -main functions are required to implement their own support, such as by using -``GHC.ResponseFile.getArgsWithResponseFiles``. - -Declaring a ``custom-setup`` stanza also enables the generation of -``MIN_VERSION_package_(A,B,C)`` CPP macros for the Setup component. - -.. pkg-section:: custom-setup - :synopsis: Custom Setup.hs build information. - :since: 1.24 - - The optional :pkg-section:`custom-setup` stanza contains information needed - for the compilation of custom ``Setup.hs`` scripts, - -:: - - custom-setup - setup-depends: - base >= 4.5 && < 4.11, - Cabal >= 1.14 && < 1.25 - -.. pkg-field:: setup-depends: package list - :since: 1.24 - - The dependencies needed to compile ``Setup.hs``. See the - :pkg-field:`build-depends` field for a description of the syntax expected by - this field. - - If the field is not specified the implicit package set will be used. - The package set contains packages bundled with GHC (i.e. ``base``, - ``bytestring``) and specifically ``Cabal``. - The specific bounds are put on ``Cabal`` dependency: - lower-bound is inferred from :pkg-field:`cabal-version`, - and the upper-bound is ``< 1.25``. - - ``Cabal`` version is additionally restricted by GHC, - with absolute minimum being ``1.20``, and for example ``Custom`` - builds with GHC-8.10 require at least ``Cabal-3.2``. - - -Backward compatibility and ``custom-setup`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Versions prior to Cabal 1.24 don't recognise ``custom-setup`` stanzas, -and will behave agnostic to them (except for warning about an unknown -section). Consequently, versions prior to Cabal 1.24 can't ensure the -declared dependencies ``setup-depends`` are in scope, and instead -whatever is registered in the current package database environment -will become eligible (and resolved by the compiler) for the -``Setup.hs`` module. - -The availability of the -``MIN_VERSION_package_(A,B,C)`` CPP macros -inside ``Setup.hs`` scripts depends on the condition that either - -- a ``custom-setup`` section has been declared (or ``cabal v2-build`` is being - used which injects an implicit hard-coded ``custom-setup`` stanza if it's missing), or -- GHC 8.0 or later is used (which natively injects package version CPP macros) - -Consequently, if you need to write backward compatible ``Setup.hs`` -scripts using CPP, you should declare a ``custom-setup`` stanza and -use the pattern below: - -.. code-block:: haskell - - {-# LANGUAGE CPP #-} - import Distribution.Simple - - #if defined(MIN_VERSION_Cabal) - -- version macros are available and can be used as usual - # if MIN_VERSION_Cabal(a,b,c) - -- code specific to lib:Cabal >= a.b.c - # else - -- code specific to lib:Cabal < a.b.c - # endif - #else - # warning Enabling heuristic fall-back. Please upgrade cabal-install to 1.24 or later if Setup.hs fails to compile. - - -- package version macros not available; except for exotic environments, - -- you can heuristically assume that lib:Cabal's version is correlated - -- with __GLASGOW_HASKELL__, and specifically since we can assume that - -- GHC < 8.0, we can assume that lib:Cabal is version 1.22 or older. - #endif - - main = ... - -The simplified (heuristic) CPP pattern shown below is useful if all you need -is to distinguish ``Cabal < 2.0`` from ``Cabal >= 2.0``. - -.. code-block:: haskell - - {-# LANGUAGE CPP #-} - import Distribution.Simple - - #if !defined(MIN_VERSION_Cabal) - # define MIN_VERSION_Cabal(a,b,c) 0 - #endif - - #if MIN_VERSION_Cabal(2,0,0) - -- code for lib:Cabal >= 2.0 - #else - -- code for lib:Cabal < 2.0 - #endif - - main = ... - - - -Autogenerated modules and includes ----------------------------------- - -Modules that are built automatically at setup, created with a custom -setup script, must appear on :pkg-field:`other-modules` for the library, -executable, test-suite or benchmark stanzas or also on -:pkg-field:`library:exposed-modules` for libraries to be used, but are not -really on the package when distributed. This makes commands like sdist fail -because the file is not found. - -These special modules must appear again on the :pkg-field:`autogen-modules` -field of the stanza that is using it, besides :pkg-field:`other-modules` or -:pkg-field:`library:exposed-modules`. With this there is no need to create -complex build hooks for this poweruser case. - -.. pkg-field:: autogen-modules: module list - :since: 2.0 - - .. todo:: document autogen-modules field - -Right now :pkg-field:`executable:main-is` modules are not supported on -:pkg-field:`autogen-modules`. - -:: - - Library - default-language: Haskell2010 - build-depends: base - exposed-modules: - MyLibrary - MyLibHelperModule - other-modules: - MyLibModule - autogen-modules: - MyLibHelperModule - - Executable Exe - default-language: Haskell2010 - main-is: Dummy.hs - build-depends: base - other-modules: - MyExeModule - MyExeHelperModule - autogen-modules: - MyExeHelperModule - -.. pkg-field:: autogen-includes: filename list - :since: 3.0 - - A list of header files from this package which are autogenerated - (e.g. by a ``configure`` script). Autogenerated header files are not - packaged by ``sdist`` command. - -Accessing data files from package code --------------------------------------- - -The placement on the target system of files listed in -the :pkg-field:`data-files` field varies between systems, and in some cases -one can even move packages around after installation (see `prefix -independence `__). To -enable packages to find these files in a portable way, Cabal generates a -module called :file:`Paths_{pkgname}` (with any hyphens in *pkgname* -replaced by underscores) during building, so that it may be imported by -modules of the package. This module defines a function - -.. code-block:: haskell - - getDataFileName :: FilePath -> IO FilePath - -If the argument is a filename listed in the :pkg-field:`data-files` field, the -result is the name of the corresponding file on the system on which the -program is running. - -.. Note:: - - If you decide to import the :file:`Paths_{pkgname}` module then it - *must* be listed in the :pkg-field:`other-modules` field just like any other - module in your package and on :pkg-field:`autogen-modules` as the file is - autogenerated. - -The :file:`Paths_{pkgname}` module is not platform independent, as any -other autogenerated module, so it does not get included in the source -tarballs generated by ``sdist``. - -The :file:`Paths_{pkgname}` module also includes some other useful -functions and values, which record the version of the package and some -other directories which the package has been configured to be installed -into (e.g. data files live in ``getDataDir``): - -.. code-block:: haskell - - version :: Version - - getBinDir :: IO FilePath - getLibDir :: IO FilePath - getDynLibDir :: IO FilePath - getDataDir :: IO FilePath - getLibexecDir :: IO FilePath - getSysconfDir :: IO FilePath - -The actual location of all these directories can be individually -overridden at runtime using environment variables of the form -``pkg_name_var``, where ``pkg_name`` is the name of the package with all -hyphens converted into underscores, and ``var`` is either ``bindir``, -``libdir``, ``dynlibdir``, ``datadir``, ``libexedir`` or ``sysconfdir``. For example, -the configured data directory for ``pretty-show`` is controlled with the -``pretty_show_datadir`` environment variable. - -Accessing the package version -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The aforementioned auto generated :file:`Paths_{pkgname}` module also -exports the constant ``version ::`` -`Version `__ -which is defined as the version of your package as specified in the -``version`` field. - -System-dependent parameters ---------------------------- - -For some packages, especially those interfacing with C libraries, -implementation details and the build procedure depend on the build -environment. The ``build-type`` ``Configure`` can be used to handle many -such situations. In this case, ``Setup.hs`` should be: - -.. code-block:: haskell - - import Distribution.Simple - main = defaultMainWithHooks autoconfUserHooks - -Most packages, however, would probably do better using the ``Simple`` -build type and `configurations`_. - -The :pkg-field:`build-type` ``Configure`` differs from ``Simple`` in two ways: - -- The package root directory must contain a shell script called - ``configure``. The configure step will run the script. This - ``configure`` script may be produced by - `autoconf `__ or may be - hand-written. The ``configure`` script typically discovers - information about the system and records it for later steps, e.g. by - generating system-dependent header files for inclusion in C source - files and preprocessed Haskell source files. (Clearly this won't work - for Windows without MSYS or Cygwin: other ideas are needed.) - -- If the package root directory contains a file called - *package*\ ``.buildinfo`` after the configuration step, subsequent - steps will read it to obtain additional settings for `build - information`_ fields,to be merged with the ones - given in the ``.cabal`` file. In particular, this file may be - generated by the ``configure`` script mentioned above, allowing these - settings to vary depending on the build environment. - -The build information file should have the following structure: - - *buildinfo* - - ``executable:`` *name* *buildinfo* - - ``executable:`` *name* *buildinfo* ... - -where each *buildinfo* consists of settings of fields listed in the -section on `build information`_. The first one (if -present) relates to the library, while each of the others relate to the -named executable. (The names must match the package description, but you -don't have to have entries for all of them.) - -Neither of these files is required. If they are absent, this setup -script is equivalent to ``defaultMain``. - -Example: Using autoconf -^^^^^^^^^^^^^^^^^^^^^^^ - -This example is for people familiar with the -`autoconf `__ tools. - -In the X11 package, the file ``configure.ac`` contains: - -.. code-block:: shell - - AC_INIT([Haskell X11 package], [1.1], [libraries@haskell.org], [X11]) - - # Safety check: Ensure that we are in the correct source directory. - AC_CONFIG_SRCDIR([X11.cabal]) - - # Header file to place defines in - AC_CONFIG_HEADERS([include/HsX11Config.h]) - - # Check for X11 include paths and libraries - AC_PATH_XTRA - AC_TRY_CPP([#include ],,[no_x=yes]) - - # Build the package if we found X11 stuff - if test "$no_x" = yes - then BUILD_PACKAGE_BOOL=False - else BUILD_PACKAGE_BOOL=True - fi - AC_SUBST([BUILD_PACKAGE_BOOL]) - - AC_CONFIG_FILES([X11.buildinfo]) - AC_OUTPUT - -Then the setup script will run the ``configure`` script, which checks -for the presence of the X11 libraries and substitutes for variables in -the file ``X11.buildinfo.in``: - -:: - - buildable: @BUILD_PACKAGE_BOOL@ - cc-options: @X_CFLAGS@ - ld-options: @X_LIBS@ - -This generates a file ``X11.buildinfo`` supplying the parameters needed -by later stages: - -:: - - buildable: True - cc-options: -I/usr/X11R6/include - ld-options: -L/usr/X11R6/lib - -The ``configure`` script also generates a header file -``include/HsX11Config.h`` containing C preprocessor defines recording -the results of various tests. This file may be included by C source -files and preprocessed Haskell source files in the package. - -.. Note:: - - Packages using these features will also need to list additional - files such as ``configure``, templates for ``.buildinfo`` files, files - named only in ``.buildinfo`` files, header files and so on in the - :pkg-field:`extra-source-files` field to ensure that they are included in - source distributions. They should also list files and directories generated - by ``configure`` in the :pkg-field:`extra-tmp-files` field to ensure that - they are removed by ``setup clean``. - -Quite often the files generated by ``configure`` need to be listed -somewhere in the package description (for example, in the -:pkg-field:`install-includes` field). However, we usually don't want generated -files to be included in the source tarball. The solution is again -provided by the ``.buildinfo`` file. In the above example, the following -line should be added to ``X11.buildinfo``: - -:: - - install-includes: HsX11Config.h - -In this way, the generated ``HsX11Config.h`` file won't be included in -the source tarball in addition to ``HsX11Config.h.in``, but it will be -copied to the right location during the install process. Packages that -use custom ``Setup.hs`` scripts can update the necessary fields -programmatically instead of using the ``.buildinfo`` file. - -Conditional compilation ------------------------ - -Sometimes you want to write code that works with more than one version -of a dependency. You can specify a range of versions for the dependency -in the :pkg-field:`build-depends`, but how do you then write the code that can -use different versions of the API? - -Haskell lets you preprocess your code using the C preprocessor (either -the real C preprocessor, or ``cpphs``). To enable this, add -``extensions: CPP`` to your package description. When using CPP, Cabal -provides some pre-defined macros to let you test the version of -dependent packages; for example, suppose your package works with either -version 3 or version 4 of the ``base`` package, you could select the -available version in your Haskell modules like this: - -.. code-block:: cpp - - #if MIN_VERSION_base(4,0,0) - ... code that works with base-4 ... - #else - ... code that works with base-3 ... - #endif - -In general, Cabal supplies a macro -``MIN_VERSION_``\ *``package``*\ ``_(A,B,C)`` for each package depended -on via :pkg-field:`build-depends`. This macro is true if the actual version of -the package in use is greater than or equal to ``A.B.C`` (using the -conventional ordering on version numbers, which is lexicographic on the -sequence, but numeric on each component, so for example 1.2.0 is greater -than 1.0.3). - -Since version 1.20, the ``MIN_TOOL_VERSION_``\ *``tool``* -family of macros lets you condition on the version of build tools used to -build the program (e.g. ``hsc2hs``). - -Since version 1.24, the macro ``CURRENT_COMPONENT_ID``, which -expands to the string of the component identifier that uniquely -identifies this component. Furthermore, if the package is a library, -the macro ``CURRENT_PACKAGE_KEY`` records the identifier that was passed -to GHC for use in symbols and for type equality. - -Since version 2.0, the macro ``CURRENT_PACKAGE_VERSION`` expands -to the string version number of the current package. - -Cabal places the definitions of these macros into an -automatically-generated header file, which is included when -preprocessing Haskell source code by passing options to the C -preprocessor. - -Cabal also allows to detect when the source code is being used for -generating documentation. The ``__HADDOCK_VERSION__`` macro is defined -only when compiling via Haddock_ -instead of a normal Haskell compiler. The value of the -``__HADDOCK_VERSION__`` macro is defined as ``A*1000 + B*10 + C``, where -``A.B.C`` is the Haddock version. This can be useful for working around -bugs in Haddock or generating prettier documentation in some special -cases. - -More complex packages ---------------------- - -For packages that don't fit the simple schemes described above, you have -a few options: - -- By using the :pkg-field:`build-type` ``Custom``, you can supply your own - ``Setup.hs`` file, and customize the simple build infrastructure - using *hooks*. These allow you to perform additional actions before - and after each command is run, and also to specify additional - preprocessors. A typical ``Setup.hs`` may look like this: - - .. code-block:: haskell - - import Distribution.Simple - main = defaultMainWithHooks simpleUserHooks { postHaddock = posthaddock } - - posthaddock args flags desc info = .... - - See ``UserHooks`` in - `Distribution.Simple <../release/cabal-latest/doc/API/Cabal/Distribution-Simple.html>`__ - for the details, but note that this interface is experimental, and - likely to change in future releases. - - If you use a custom ``Setup.hs`` file you should strongly consider - adding a :pkg-section:`custom-setup` stanza with a - :pkg-field:`custom-setup:setup-depends` field to ensure that your setup - script does not break with future dependency versions. - -- You could delegate all the work to ``make``, though this is unlikely - to be very portable. Cabal supports this with the :pkg-field:`build-type` - ``Make`` and a trivial setup library - `Distribution.Make <../release/cabal-latest/doc/API/Cabal/Distribution-Make.html>`__, - which simply parses the command line arguments and invokes ``make``. - Here ``Setup.hs`` should look like this: - - .. code-block:: haskell - - import Distribution.Make - main = defaultMain - - The root directory of the package should contain a ``configure`` - script, and, after that has run, a ``Makefile`` with a default target - that builds the package, plus targets ``install``, ``register``, - ``unregister``, ``clean``, ``dist`` and ``docs``. Some options to - commands are passed through as follows: - - - The ``--with-hc-pkg``, ``--prefix``, ``--bindir``, ``--libdir``, - ``--dynlibdir``, ``--datadir``, ``--libexecdir`` and ``--sysconfdir`` options to - the ``configure`` command are passed on to the ``configure`` - script. In addition the value of the ``--with-compiler`` option is - passed in a ``--with-hc`` option and all options specified with - ``--configure-option=`` are passed on. - - - The ``--destdir`` option to the ``copy`` command becomes a setting - of a ``destdir`` variable on the invocation of ``make copy``. The - supplied ``Makefile`` should provide a ``copy`` target, which will - probably look like this: - - .. code-block:: make - - copy : - $(MAKE) install prefix=$(destdir)/$(prefix) \ - bindir=$(destdir)/$(bindir) \ - libdir=$(destdir)/$(libdir) \ - dynlibdir=$(destdir)/$(dynlibdir) \ - datadir=$(destdir)/$(datadir) \ - libexecdir=$(destdir)/$(libexecdir) \ - sysconfdir=$(destdir)/$(sysconfdir) \ - -- Finally, with the :pkg-field:`build-type` ``Custom``, you can also write your - own setup script from scratch. It must conform to the interface - described in the section on `building and installing - packages `__, and you may use the Cabal - library for all or part of the work. One option is to copy the source - of ``Distribution.Simple``, and alter it for your needs. Good luck. - - -.. include:: references.inc - -.. rubric:: Footnotes - -.. [#old-style-build-tool-depends] - - Some packages (ab)use :pkg-field:`build-depends` on old-style builds, but this has a few major drawbacks: - - - using Nix-style builds it's considered an error if you depend on a exe-only package via build-depends: the solver will refuse it. - - it may or may not place the executable on ``$PATH``. - - it does not ensure the correct version of the package is installed, so you might end up overwriting versions with each other. diff --git a/Cabal/doc/index.rst b/Cabal/doc/index.rst index a625a19cc69..a53d63bef31 100644 --- a/Cabal/doc/index.rst +++ b/Cabal/doc/index.rst @@ -9,8 +9,12 @@ Welcome to the Cabal User Guide intro config-and-install concepts-and-development - bugs-and-stability nix-local-build-overview - nix-integration + cabal-commands + cabal-package + cabal-project + setup-commands file-format-changelog buildinfo-fields-reference + bugs-and-stability + nix-integration diff --git a/Cabal/doc/installing-packages.rst b/Cabal/doc/installing-packages.rst index 7e79753176d..31262255243 100644 --- a/Cabal/doc/installing-packages.rst +++ b/Cabal/doc/installing-packages.rst @@ -226,68 +226,7 @@ can be used to create and manage such repositories. Building and installing packages ================================ -.. highlight:: console - -After you've unpacked a Cabal package, you can build it by moving into -the root directory of the package and running the ``cabal`` tool there: - -:: - - $ cabal [command] [option...] - -The *command* argument selects a particular step in the build/install -process. - -You can also get a summary of the command syntax with - -:: - - $ cabal help - -Alternatively, you can also use the ``Setup.hs`` or ``Setup.lhs`` -script: - -:: - - $ runhaskell Setup.hs [command] [option...] - -For the summary of the command syntax, run: - -:: - - $ cabal help - -or - -:: - - $ runhaskell Setup.hs --help - -Building and installing a system package ----------------------------------------- - -:: - - $ runhaskell Setup.hs configure --ghc - $ runhaskell Setup.hs build - $ runhaskell Setup.hs install - -The first line readies the system to build the tool using GHC; for -example, it checks that GHC exists on the system. The second line -performs the actual building, while the last both copies the build -results to some permanent place and registers the package with GHC. - -Building and installing a user package --------------------------------------- - -:: - - $ runhaskell Setup.hs configure --user - $ runhaskell Setup.hs build - $ runhaskell Setup.hs install - -The package is installed under the user's home directory and is -registered in the user's package database (:option:`setup configure --user`). +To be written Installing packages from Hackage -------------------------------- @@ -302,1388 +241,3 @@ dependencies in a single step. To do this, run: To browse the list of available packages, visit the Hackage_ web site. - - -Creating a binary package -------------------------- - -When creating binary packages (e.g. for Red Hat or Debian) one needs to -create a tarball that can be sent to another system for unpacking in the -root directory: - -:: - - $ runhaskell Setup.hs configure --prefix=/usr - $ runhaskell Setup.hs build - $ runhaskell Setup.hs copy --destdir=/tmp/mypkg - $ tar -czf mypkg.tar.gz /tmp/mypkg/ - -If the package contains a library, you need two additional steps: - -:: - - $ runhaskell Setup.hs register --gen-script - $ runhaskell Setup.hs unregister --gen-script - -This creates shell scripts ``register.sh`` and ``unregister.sh``, which -must also be sent to the target system. After unpacking there, the -package must be registered by running the ``register.sh`` script. The -``unregister.sh`` script would be used in the uninstall procedure of the -package. Similar steps may be used for creating binary packages for -Windows. - -The following options are understood by all commands: - -.. program:: setup - -.. option:: --help, -h or -? - - List the available options for the command. - -.. option:: --verbose=n or -v n - - Set the verbosity level (0-3). The normal level is 1; a missing *n* - defaults to 2. - - There is also an extended version of this command which can be - used to fine-tune the verbosity of output. It takes the - form ``[silent|normal|verbose|debug]``\ *flags*, where *flags* - is a list of ``+`` flags which toggle various aspects of - output. At the moment, only ``+callsite`` and ``+callstack`` - are supported, which respectively toggle call site and call - stack printing (these are only supported if Cabal - is built with a sufficiently recent GHC.) - -The various commands and the additional options they support are -described below. In the simple build infrastructure, any other options -will be reported as errors. - -.. _setup-configure: - -setup configure ---------------- - -.. program:: setup configure - -Prepare to build the package. Typically, this step checks that the -target platform is capable of building the package, and discovers -platform-specific features that are needed during the build. - -The user may also adjust the behaviour of later stages using the options -listed in the following subsections. In the simple build infrastructure, -the values supplied via these options are recorded in a private file -read by later stages. - -If a user-supplied ``configure`` script is run (see the section on -`system-dependent -parameters `__ or -on `complex -packages `__), it is -passed the :option:`--with-hc-pkg`, :option:`--prefix`, :option:`--bindir`, -:option:`--libdir`, :option:`--dynlibdir`, :option:`--datadir`, :option:`--libexecdir` and -:option:`--sysconfdir` options. In addition the value of the -:option:`--with-compiler` option is passed in a :option:`--with-hc-pkg` option -and all options specified with :option:`--configure-option` are passed on. - -.. note:: - `GNU autoconf places restrictions on paths, including the directory - that the package is built from. - `_ - The errors produced when this happens can be obscure; Cabal attempts to - detect and warn in this situation, but it is not perfect. - -In Cabal 2.0, support for a single positional argument was added to -``setup configure`` This makes Cabal configure the specific component to -be configured. Specified names can be qualified with ``lib:`` or -``exe:`` in case just a name is ambiguous (as would be the case for a -package named ``p`` which has a library and an executable named ``p``.) -This has the following effects: - -- Subsequent invocations of ``cabal build``, ``register``, etc. operate only - on the configured component. - -- Cabal requires all "internal" dependencies (e.g., an executable - depending on a library defined in the same package) must be found in - the set of databases via :option:`--package-db` (and related flags): these - dependencies are assumed to be up-to-date. A dependency can be - explicitly specified using :option:`--dependency` simply by giving the name - of the internal library; e.g., the dependency for an internal library - named ``foo`` is given as - ``--dependency=pkg-internal=pkg-1.0-internal-abcd``. - -- Only the dependencies needed for the requested component are - required. Similarly, when :option:`--exact-configuration` is specified, - it's only necessary to specify :option:`--dependency` for the component. - (As mentioned previously, you *must* specify internal dependencies as - well.) - -- Internal ``build-tool-depends`` and ``build-tools`` dependencies are expected - to be in the ``PATH`` upon subsequent invocations of ``setup``. - -Full details can be found in the `Componentized Cabal -proposal `__. - -Programs used for building -^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The following options govern the programs used to process the source -files of a package: - -.. option:: --ghc or -g, --jhc, --lhc, --uhc - - Specify which Haskell implementation to use to build the package. At - most one of these flags may be given. If none is given, the - implementation under which the setup script was compiled or - interpreted is used. - -.. option:: --with-compiler=path or -w *path* - - Specify the path to a particular compiler. If given, this must match - the implementation selected above. The default is to search for the - usual name of the selected implementation. - - This flag also sets the default value of the :option:`--with-hc-pkg` - option to the package tool for this compiler. Check the output of - ``setup configure -v`` to ensure that it finds the right package - tool (or use :option:`--with-hc-pkg` explicitly). - -.. option:: --with-hc-pkg=path - - Specify the path to the package tool, e.g. ``ghc-pkg``. The package - tool must be compatible with the compiler specified by - :option:`--with-compiler`. If this option is omitted, the default value is - determined from the compiler selected. - -.. option:: --with-prog=path - - Specify the path to the program *prog*. Any program known to Cabal - can be used in place of *prog*. It can either be a fully path or the - name of a program that can be found on the program search path. For - example: ``--with-ghc=ghc-6.6.1`` or - ``--with-cpphs=/usr/local/bin/cpphs``. The full list of accepted - programs is not enumerated in this user guide. Rather, run - ``cabal install --help`` to view the list. - -.. option:: --prog-options=options - - Specify additional options to the program *prog*. Any program known - to Cabal can be used in place of *prog*. For example: - ``--alex-options="--template=mytemplatedir/"``. The *options* is - split into program options based on spaces. Any options containing - embedded spaced need to be quoted, for example - ``--foo-options='--bar="C:\Program File\Bar"'``. As an alternative - that takes only one option at a time but avoids the need to quote, - use :option:`--prog-option` instead. - -.. option:: --prog-option=option - - Specify a single additional option to the program *prog*. For - passing an option that contain embedded spaces, such as a file name - with embedded spaces, using this rather than :option:`--prog-options` - means you do not need an additional level of quoting. Of course if you - are using a command shell you may still need to quote, for example - ``--foo-options="--bar=C:\Program File\Bar"``. - -All of the options passed with either :option:`--prog-options` -or :option:`--prog-option` are passed in the order they were -specified on the configure command line. - -Installation paths -^^^^^^^^^^^^^^^^^^ - -The following options govern the location of installed files from a -package: - -.. option:: --prefix=dir - - The root of the installation. For example for a global install you - might use ``/usr/local`` on a Unix system, or ``C:\Program Files`` - on a Windows system. The other installation paths are usually - subdirectories of *prefix*, but they don't have to be. - - In the simple build system, *dir* may contain the following path - variables: ``$pkgid``, ``$pkg``, ``$version``, ``$compiler``, - ``$os``, ``$arch``, ``$abi``, ``$abitag`` - -.. option:: --bindir=dir - - Executables that the user might invoke are installed here. - - In the simple build system, *dir* may contain the following path - variables: ``$prefix``, ``$pkgid``, ``$pkg``, ``$version``, - ``$compiler``, ``$os``, ``$arch``, ``$abi``, ``$abitag`` - -.. option:: --libdir=dir - - Object-code libraries are installed here. - - In the simple build system, *dir* may contain the following path - variables: ``$prefix``, ``$bindir``, ``$pkgid``, ``$pkg``, - ``$version``, ``$compiler``, ``$os``, ``$arch``, ``$abi``, - ``$abitag`` - -.. option:: --dynlibdir=dir - - Dynamic libraries are installed here. - - By default, this is set to `$libdir/$abi`, which is usually not equal to - `$libdir/$libsubdir`. - - In the simple build system, *dir* may contain the following path - variables: ``$prefix``, ``$bindir``, ``$libdir``, ``$pkgid``, ``$pkg``, - ``$version``, ``$compiler``, ``$os``, ``$arch``, ``$abi``, - ``$abitag`` - -.. option:: --libexecdir=dir - - Executables that are not expected to be invoked directly by the user - are installed here. - - In the simple build system, *dir* may contain the following path - variables: ``$prefix``, ``$bindir``, ``$libdir``, ``$libsubdir``, - ``$pkgid``, ``$pkg``, ``$version``, ``$compiler``, ``$os``, - ``$arch``, ``$abi``, ``$abitag`` - -.. option:: --datadir=dir - - Architecture-independent data files are installed here. - - In the simple build system, *dir* may contain the following path - variables: ``$prefix``, ``$bindir``, ``$libdir``, ``$libsubdir``, - ``$pkgid``, ``$pkg``, ``$version``, ``$compiler``, ``$os``, - ``$arch``, ``$abi``, ``$abitag`` - -.. option:: --sysconfdir=dir - - Installation directory for the configuration files. - - In the simple build system, *dir* may contain the following path - variables: ``$prefix``, ``$bindir``, ``$libdir``, ``$libsubdir``, - ``$pkgid``, ``$pkg``, ``$version``, ``$compiler``, ``$os``, - ``$arch``, ``$abi``, ``$abitag`` - -In addition the simple build system supports the following installation -path options: - -.. option:: --libsubdir=dir - - A subdirectory of *libdir* in which libraries are actually installed. For - example, in the simple build system on Unix, the default *libdir* is - ``/usr/local/lib``, and *libsubdir* contains the compiler ABI and package - identifier, - e.g. ``x86_64-linux-ghc-8.0.2/mypkg-0.1.0-IxQNmCA7qrSEQNkoHSF7A``, so - libraries would be installed in - ``/usr/local/lib/x86_64-linux-ghc-8.0.2/mypkg-0.1.0-IxQNmCA7qrSEQNkoHSF7A/``. - - *dir* may contain the following path variables: ``$pkgid``, - ``$pkg``, ``$version``, ``$compiler``, ``$os``, ``$arch``, ``$abi``, - ``$abitag`` - -.. option:: --libexecsubdir=dir - - A subdirectory of *libexecdir* in which private executables are - installed. For example, in the simple build system on Unix, the default - *libexecdir* is ``/usr/local/libexec``, and *libsubdir* is - ``x86_64-linux-ghc-8.0.2/mypkg-0.1.0``, so private executables would be - installed in ``/usr/local/libexec/x86_64-linux-ghc-8.0.2/mypkg-0.1.0/`` - - *dir* may contain the following path variables: ``$pkgid``, - ``$pkg``, ``$version``, ``$compiler``, ``$os``, ``$arch``, ``$abi``, - ``$abitag`` - -.. option:: --datasubdir=dir - - A subdirectory of *datadir* in which data files are actually - installed. - - *dir* may contain the following path variables: ``$pkgid``, - ``$pkg``, ``$version``, ``$compiler``, ``$os``, ``$arch``, ``$abi``, - ``$abitag`` - -.. option:: --docdir=dir - - Documentation files are installed relative to this directory. - - *dir* may contain the following path variables: ``$prefix``, - ``$bindir``, ``$libdir``, ``$libsubdir``, ``$datadir``, - ``$datasubdir``, ``$pkgid``, ``$pkg``, ``$version``, ``$compiler``, - ``$os``, ``$arch``, ``$abi``, ``$abitag`` - -.. option:: --htmldir=dir - - HTML documentation files are installed relative to this directory. - - *dir* may contain the following path variables: ``$prefix``, - ``$bindir``, ``$libdir``, ``$libsubdir``, ``$datadir``, - ``$datasubdir``, ``$docdir``, ``$pkgid``, ``$pkg``, ``$version``, - ``$compiler``, ``$os``, ``$arch``, ``$abi``, ``$abitag`` - -.. option:: --program-prefix=prefix - - Prepend *prefix* to installed program names. - - *prefix* may contain the following path variables: ``$pkgid``, - ``$pkg``, ``$version``, ``$compiler``, ``$os``, ``$arch``, ``$abi``, - ``$abitag`` - -.. option:: --program-suffix=suffix - - Append *suffix* to installed program names. The most obvious use for - this is to append the program's version number to make it possible - to install several versions of a program at once: - ``--program-suffix='$version'``. - - *suffix* may contain the following path variables: ``$pkgid``, - ``$pkg``, ``$version``, ``$compiler``, ``$os``, ``$arch``, ``$abi``, - ``$abitag`` - -Path variables in the simple build system -""""""""""""""""""""""""""""""""""""""""" - -For the simple build system, there are a number of variables that can be -used when specifying installation paths. The defaults are also specified -in terms of these variables. A number of the variables are actually for -other paths, like ``$prefix``. This allows paths to be specified -relative to each other rather than as absolute paths, which is important -for building relocatable packages (see `prefix -independence <#prefix-independence>`__). - -$prefix - The path variable that stands for the root of the installation. For - an installation to be relocatable, all other installation paths must - be relative to the ``$prefix`` variable. -$bindir - The path variable that expands to the path given by the :option:`--bindir` - configure option (or the default). -$libdir - As above but for :option:`--libdir` -$libsubdir - As above but for :option:`--libsubdir` -$dynlibdir - As above but for :option:`--dynlibdir` -$datadir - As above but for :option:`--datadir` -$datasubdir - As above but for :option:`--datasubdir` -$docdir - As above but for :option:`--docdir` -$pkgid - The name and version of the package, e.g. ``mypkg-0.2`` -$pkg - The name of the package, e.g. ``mypkg`` -$version - The version of the package, e.g. ``0.2`` -$compiler - The compiler being used to build the package, e.g. ``ghc-6.6.1`` -$os - The operating system of the computer being used to build the - package, e.g. ``linux``, ``windows``, ``osx``, ``freebsd`` or - ``solaris`` -$arch - The architecture of the computer being used to build the package, - e.g. ``i386``, ``x86_64``, ``ppc`` or ``sparc`` -$abitag - An optional tag that a compiler can use for telling incompatible - ABI's on the same architecture apart. GHCJS encodes the underlying - GHC version in the ABI tag. -$abi - A shortcut for getting a path that completely identifies the - platform in terms of binary compatibility. Expands to the same value - as ``$arch-$os-compiler-$abitag`` if the compiler uses an abi tag, - ``$arch-$os-$compiler`` if it doesn't. - -Paths in the simple build system -"""""""""""""""""""""""""""""""" - -For the simple build system, the following defaults apply: - -.. list-table:: Default installation paths - - * - Option - - Unix Default - - Windows Default - * - :option:`--prefix` (global) - - ``/usr/local`` - - ``%PROGRAMFILES%\Haskell`` - * - :option:`--prefix` (per-user) - - ``$HOME/.cabal`` - - ``%APPDATA%\cabal`` - * - :option:`--bindir` - - ``$prefix/bin`` - - ``$prefix\bin`` - * - :option:`--libdir` - - ``$prefix/lib`` - - ``$prefix`` - * - :option:`--libsubdir` (others) - - ``$pkgid/$compiler`` - - ``$pkgid\$compiler`` - * - :option:`--dynlibdir` - - ``$libdir/$abi`` - - ``$libdir\$abi`` - * - :option:`--libexecdir` - - ``$prefix/libexec`` - - ``$prefix\$pkgid`` - * - :option:`--datadir` (executable) - - ``$prefix/share`` - - ``$prefix`` - * - :option:`--datadir` (library) - - ``$prefix/share`` - - ``%PROGRAMFILES%\Haskell`` - * - :option:`--datasubdir` - - ``$pkgid`` - - ``$pkgid`` - * - :option:`--docdir` - - ``$datadir/doc/$pkgid`` - - ``$prefix\doc\$pkgid`` - * - :option:`--sysconfdir` - - ``$prefix/etc`` - - ``$prefix\etc`` - * - :option:`--htmldir` - - ``$docdir/html`` - - ``$docdir\html`` - * - :option:`--program-prefix` - - (empty) - - (empty) - * - :option:`--program-suffix` - - (empty) - - (empty) - -Prefix-independence -""""""""""""""""""" - -On Windows it is possible to obtain the pathname of the running program. -This means that we can construct an installable executable package that -is independent of its absolute install location. The executable can find -its auxiliary files by finding its own path and knowing the location of -the other files relative to ``$bindir``. Prefix-independence is -particularly useful: it means the user can choose the install location -(i.e. the value of ``$prefix``) at install-time, rather than having to -bake the path into the binary when it is built. - -In order to achieve this, we require that for an executable on Windows, -all of ``$bindir``, ``$libdir``, ``$dynlibdir``, ``$datadir`` and ``$libexecdir`` begin -with ``$prefix``. If this is not the case then the compiled executable -will have baked-in all absolute paths. - -The application need do nothing special to achieve prefix-independence. -If it finds any files using ``getDataFileName`` and the `other functions -provided for the -purpose `__, -the files will be accessed relative to the location of the current -executable. - -A library cannot (currently) be prefix-independent, because it will be -linked into an executable whose file system location bears no relation -to the library package. - -Controlling Flag Assignments -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Flag assignments (see the `resolution of conditions and -flags `__) -can be controlled with the following command line options. - -.. option:: -f flagname or -f -flagname - - Force the specified flag to ``true`` or ``false`` (if preceded with - a ``-``). Later specifications for the same flags will override - earlier, i.e., specifying ``-fdebug -f-debug`` is equivalent to - ``-f-debug`` - -.. option:: --flags=flagspecs - - Same as ``-f``, but allows specifying multiple flag assignments at - once. The parameter is a space-separated list of flag names (to - force a flag to ``true``), optionally preceded by a ``-`` (to force - a flag to ``false``). For example, - ``--flags="debug -feature1 feature2"`` is equivalent to - ``-fdebug -f-feature1 -ffeature2``. - -Building Test Suites -^^^^^^^^^^^^^^^^^^^^ - -.. option:: --enable-tests - - Build the test suites defined in the package description file during - the ``build`` stage. Check for dependencies required by the test - suites. If the package is configured with this option, it will be - possible to run the test suites with the ``test`` command after the - package is built. - -.. option:: --disable-tests - - (default) Do not build any test suites during the ``build`` stage. - Do not check for dependencies required only by the test suites. It - will not be possible to invoke the ``test`` command without - reconfiguring the package. - -.. option:: --enable-coverage - - Build libraries and executables (including test suites) with Haskell - Program Coverage enabled. Running the test suites will automatically - generate coverage reports with HPC. - -.. option:: --disable-coverage - - (default) Do not enable Haskell Program Coverage. - -Miscellaneous options -^^^^^^^^^^^^^^^^^^^^^ - -.. option:: --user - - Does a per-user installation. This changes the `default installation - prefix <#paths-in-the-simple-build-system>`__. It also allow - dependencies to be satisfied by the user's package database, in - addition to the global database. This also implies a default of - ``--user`` for any subsequent ``install`` command, as packages - registered in the global database should not depend on packages - registered in a user's database. - -.. option:: --global - - (default) Does a global installation. In this case package - dependencies must be satisfied by the global package database. All - packages in the user's package database will be ignored. Typically - the final installation step will require administrative privileges. - -.. option:: --package-db=db - - Allows package dependencies to be satisfied from this additional - package database *db* in addition to the global package database. - All packages in the user's package database will be ignored. The - interpretation of *db* is implementation-specific. Typically it will - be a file or directory. Not all implementations support arbitrary - package databases. - - This pushes an extra db onto the db stack. The :option:`--global` and - :option:`--user` mode switches add the respective [Global] and [Global, - User] dbs to the initial stack. There is a compiler-implementation - constraint that the global db must appear first in the stack, and if - the user one appears at all, it must appear immediately after the - global db. - - To reset the stack, use ``--package-db=clear``. - -.. option:: --ipid=ipid - - Specifies the *installed package identifier* of the package to be - built; this identifier is passed on to GHC and serves as the basis - for linker symbols and the ``id`` field in a ``ghc-pkg`` - registration. When a package has multiple components, the actual - component identifiers are derived off of this identifier (e.g., an - internal library ``foo`` from package ``p-0.1-abcd`` will get the - identifier ``p-0.1-abcd-foo``. - -.. option:: --cid=cid - - Specifies the *component identifier* of the component being built; - this is only valid if you are configuring a single component. - -.. option:: --default-user-config=file - - Allows a "default" ``cabal.config`` freeze file to be passed in - manually. This file will only be used if one does not exist in the - project directory already. Typically, this can be set from the - global cabal ``config`` file so as to provide a default set of - partial constraints to be used by projects, providing a way for - users to peg themselves to stable package collections. - -.. option:: --enable-optimization[=n] or -O [n] - - (default) Build with optimization flags (if available). This is - appropriate for production use, taking more time to build faster - libraries and programs. - - The optional *n* value is the optimisation level. Some compilers - support multiple optimisation levels. The range is 0 to 2. Level 0 - is equivalent to :option:`--disable-optimization`, level 1 is the - default if no *n* parameter is given. Level 2 is higher optimisation - if the compiler supports it. Level 2 is likely to lead to longer - compile times and bigger generated code. - - When optimizations are enabled, Cabal passes ``-O2`` to the C compiler. - -.. option:: --disable-optimization - - Build without optimization. This is suited for development: building - will be quicker, but the resulting library or programs will be - slower. - -.. option:: --enable-profiling - - Build libraries and executables with profiling enabled (for - compilers that support profiling as a separate mode). For this to - work, all libraries used by this package must also have been built - with profiling support. For libraries this involves building an - additional instance of the library in addition to the normal - non-profiling instance. For executables it changes the single - executable to be built in profiling mode. - - This flag covers both libraries and executables, but can be - overridden by the :option:`--enable-library-profiling` flag. - - See also the :option:`--profiling-detail` flag below. - -.. option:: --disable-profiling - - (default) Do not enable profiling in generated libraries and - executables. - -.. option:: --enable-library-profiling or -p - - As with :option:`--enable-profiling` above, but it applies only for - libraries. So this generates an additional profiling instance of the - library in addition to the normal non-profiling instance. - - The :option:`--enable-profiling` flag controls the profiling mode for both - libraries and executables, but if different modes are desired for - libraries versus executables then use :option:`--enable-library-profiling` - as well. - -.. option:: --disable-library-profiling - - (default) Do not generate an additional profiling version of the library. - -.. option:: --profiling-detail[=level] - - Some compilers that support profiling, notably GHC, can allocate - costs to different parts of the program and there are different - levels of granularity or detail with which this can be done. In - particular for GHC this concept is called "cost centers", and GHC - can automatically add cost centers, and can do so in different ways. - - This flag covers both libraries and executables, but can be - overridden by the :option:`--library-profiling-detail` flag. - - Currently this setting is ignored for compilers other than GHC. The - levels that cabal currently supports are: - - default - For GHC this uses ``exported-functions`` for libraries and - ``toplevel-functions`` for executables. - none - No costs will be assigned to any code within this component. - exported-functions - Costs will be assigned at the granularity of all top level - functions exported from each module. In GHC specifically, this - is for non-inline functions. - toplevel-functions - Costs will be assigned at the granularity of all top level - functions in each module, whether they are exported from the - module or not. In GHC specifically, this is for non-inline - functions. - all-functions - Costs will be assigned at the granularity of all functions in - each module, whether top level or local. In GHC specifically, - this is for non-inline toplevel or where-bound functions or - values. - - This flag is new in Cabal-1.24. Prior versions used the equivalent - of ``none`` above. - -.. option:: --library-profiling-detail[=level] - - As with :option:`--profiling-detail` above, but it applies only for - libraries. - - The level for both libraries and executables is set by the - :option:`--profiling-detail` flag, but if different levels are desired - for libraries versus executables then use - :option:`--library-profiling-detail` as well. - -.. option:: --enable-library-vanilla - - (default) Build ordinary libraries (as opposed to profiling - libraries). This is independent of the - :option:`--enable-library-profiling` option. If you enable both, you get - both. - -.. option:: --disable-library-vanilla - - Do not build ordinary libraries. This is useful in conjunction with - :option:`--enable-library-profiling` to build only profiling libraries, - rather than profiling and ordinary libraries. - -.. option:: --enable-library-for-ghci - - (default) Build libraries suitable for use with GHCi. - -.. option:: --disable-library-for-ghci - - Not all platforms support GHCi and indeed on some platforms, trying - to build GHCi libs fails. In such cases this flag can be used as a - workaround. - -.. option:: --enable-split-objs - - Use the GHC ``-split-objs`` feature when building the library. This - reduces the final size of the executables that use the library by - allowing them to link with only the bits that they use rather than - the entire library. The downside is that building the library takes - longer and uses considerably more memory. - -.. option:: --disable-split-objs - - (default) Do not use the GHC ``-split-objs`` feature. This makes - building the library quicker but the final executables that use the - library will be larger. - -.. option:: --enable-executable-stripping - - (default) When installing binary executable programs, run the - ``strip`` program on the binary. This can considerably reduce the - size of the executable binary file. It does this by removing - debugging information and symbols. While such extra information is - useful for debugging C programs with traditional debuggers it is - rarely helpful for debugging binaries produced by Haskell compilers. - - Not all Haskell implementations generate native binaries. For such - implementations this option has no effect. - -.. option:: --disable-executable-stripping - - Do not strip binary executables during installation. You might want - to use this option if you need to debug a program using gdb, for - example if you want to debug the C parts of a program containing - both Haskell and C code. Another reason is if your are building a - package for a system which has a policy of managing the stripping - itself (such as some Linux distributions). - -.. option:: --enable-shared - - Build shared library. This implies a separate compiler run to - generate position independent code as required on most platforms. - -.. option:: --disable-shared - - (default) Do not build shared library. - -.. option:: --enable-static - - Build a static library. This passes ``-staticlib`` to GHC (available - for iOS, and with 8.4 more platforms). The result is an archive ``.a`` - containing all dependent haskell libararies combined. - -.. option:: --disable-static - - (default) Do not build a static library. - -.. option:: --enable-executable-dynamic - - Link dependent Haskell libraries into executables dynamically. - The executable's library dependencies must have been - built as shared objects. This implies :option:`--enable-shared` - unless :option:`--disable-shared` is explicitly specified. - -.. option:: --disable-executable-dynamic - - (default) Link dependent Haskell libraries into executables statically. - Non-Haskell (C) libraries are still linked dynamically, including libc, - so the result is still not a fully static executable - unless :option:`--enable-executable-static` is given. - -.. option:: --enable-executable-static - - Build fully static executables. - This link all dependent libraries into executables statically, - including libc. - -.. option:: --disable-executable-static - - (default) Do not build fully static executables. - -.. option:: --configure-option=str - - An extra option to an external ``configure`` script, if one is used - (see the section on `system-dependent - parameters `__). - There can be several of these options. - -.. option:: --extra-include-dirs[=dir] - - An extra directory to search for C header files. You can use this - flag multiple times to get a list of directories. - - You might need to use this flag if you have standard system header - files in a non-standard location that is not mentioned in the - package's ``.cabal`` file. Using this option has the same affect as - appending the directory *dir* to the ``include-dirs`` field in each - library and executable in the package's ``.cabal`` file. The - advantage of course is that you do not have to modify the package at - all. These extra directories will be used while building the package - and for libraries it is also saved in the package registration - information and used when compiling modules that use the library. - -.. option:: --extra-lib-dirs[=dir] - - An extra directory to search for system libraries files. You can use - this flag multiple times to get a list of directories. - -.. option:: --extra-framework-dirs[=dir] - - An extra directory to search for frameworks (OS X only). You can use - this flag multiple times to get a list of directories. - - You might need to use this flag if you have standard system - libraries in a non-standard location that is not mentioned in the - package's ``.cabal`` file. Using this option has the same affect as - appending the directory *dir* to the ``extra-lib-dirs`` field in - each library and executable in the package's ``.cabal`` file. The - advantage of course is that you do not have to modify the package at - all. These extra directories will be used while building the package - and for libraries it is also saved in the package registration - information and used when compiling modules that use the library. - -.. option:: --dependency[=pkgname=ipid] - - Specify that a particular dependency should used for a particular - package name. In particular, it declares that any reference to - *pkgname* in a :pkg-field:`build-depends` should be resolved to - *ipid*. - -.. option:: --exact-configuration - - This changes Cabal to require every dependency be explicitly - specified using :option:`--dependency`, rather than use Cabal's (very - simple) dependency solver. This is useful for programmatic use of - Cabal's API, where you want to error if you didn't specify enough - :option:`--dependency` flags. - -.. option:: --allow-newer[=pkgs], --allow-older[=pkgs] - - Selectively relax upper or lower bounds in dependencies without - editing the package description respectively. - - The following description focuses on upper bounds and the - :option:`--allow-newer` flag, but applies analogously to - :option:`--allow-older` and lower bounds. :option:`--allow-newer` - and :option:`--allow-older` can be used at the same time. - - If you want to install a package A that depends on B >= 1.0 && < - 2.0, but you have the version 2.0 of B installed, you can compile A - against B 2.0 by using ``cabal install --allow-newer=B A``. This - works for the whole package index: if A also depends on C that in - turn depends on B < 2.0, C's dependency on B will be also relaxed. - - Example: - - :: - - $ cd foo - $ cabal configure - Resolving dependencies... - cabal: Could not resolve dependencies: - [...] - $ cabal configure --allow-newer - Resolving dependencies... - Configuring foo... - - Additional examples: - - :: - - # Relax upper bounds in all dependencies. - $ cabal install --allow-newer foo - - # Relax upper bounds only in dependencies on bar, baz and quux. - $ cabal install --allow-newer=bar,baz,quux foo - - # Relax the upper bound on bar and force bar==2.1. - $ cabal install --allow-newer=bar --constraint="bar==2.1" foo - - It's also possible to limit the scope of :option:`--allow-newer` to single - packages with the ``--allow-newer=scope:dep`` syntax. This means - that the dependency on ``dep`` will be relaxed only for the package - ``scope``. - - Example: - - :: - - # Relax upper bound in foo's dependency on base; also relax upper bound in - # every package's dependency on lens. - $ cabal install --allow-newer=foo:base,lens - - # Relax upper bounds in foo's dependency on base and bar's dependency - # on time; also relax the upper bound in the dependency on lens specified by - # any package. - $ cabal install --allow-newer=foo:base,lens --allow-newer=bar:time - - Finally, one can enable :option:`--allow-newer` permanently by setting - ``allow-newer: True`` in the ``~/.cabal/config`` file. Enabling - 'allow-newer' selectively is also supported in the config file - (``allow-newer: foo, bar, baz:base``). - -.. option:: --constraint=constraint - - Restrict solutions involving a package to given version - bounds, flag settings, and other properties. For example, to - consider only install plans that use version 2.1 of ``bar`` - or do not use ``bar`` at all, write: - - :: - - $ cabal install --constraint="bar == 2.1" - - Version bounds have the same syntax as :pkg-field:`build-depends`. - As a special case, the following prevents ``bar`` from being - used at all: - - :: - - # Note: this is just syntax sugar for '> 1 && < 1', and is - # supported by build-depends. - $ cabal install --constraint="bar -none" - - You can also specify flag assignments: - - :: - - # Require bar to be installed with the foo flag turned on and - # the baz flag turned off. - $ cabal install --constraint="bar +foo -baz" - - To specify multiple constraints, you may pass the - ``constraint`` option multiple times. - - There are also some more specialized constraints, which most people - don't generally need: - - :: - - # Require that a version of bar be used that is already installed in - # the global package database. - $ cabal install --constraint="bar installed" - - # Require the local source copy of bar to be used. - # (Note: By default, if we have a local package we will - # automatically use it, so it will generally not be necessary to - # specify this.) - $ cabal install --constraint="bar source" - - # Require that bar have test suites and benchmarks enabled. - $ cabal install --constraint="bar test" --constraint="bar bench" - - By default, constraints only apply to build dependencies - (:pkg-field:`build-depends`), build dependencies of build - dependencies, and so on. Constraints normally do not apply to - dependencies of the ``Setup.hs`` script of any package - (:pkg-field:`setup-depends`) nor do they apply to build tools - (:pkg-field:`build-tool-depends`) or the dependencies of build - tools. To explicitly apply a constraint to a setup or build - tool dependency, you can add a qualifier to the constraint as - follows: - - :: - - # Example use of the 'any' qualifier. This constraint - # applies to package bar anywhere in the dependency graph. - $ cabal install --constraint="any.bar == 1.0" - - :: - - # Example uses of 'setup' qualifiers. - - # This constraint applies to package bar when it is a - # dependency of any Setup.hs script. - $ cabal install --constraint="setup.bar == 1.0" - - # This constraint applies to package bar when it is a - # dependency of the Setup.hs script of package foo. - $ cabal install --constraint="foo:setup.bar == 1.0" - - .. TODO: Uncomment this example once we decide on a syntax for 'exe'. - .. # Example use of the 'exe' (executable build tool) - # qualifier. This constraint applies to package baz when it - # is a dependency of the build tool bar being used to - # build package foo. - $ cabal install --constraint="foo:bar:exe.baz == 1.0" - -.. option:: --preference=preference - - Specify a soft constraint on versions of a package. The solver will - attempt to satisfy these preferences on a "best-effort" basis. - -.. option:: --disable-response-files - - Enable workaround for older versions of programs such as ``ar`` or - ``ld`` that do not support response file arguments (i.e. ``@file`` - arguments). You may want this flag only if you specify custom ar - executable. For system ``ar`` or the one bundled with ``ghc`` on - Windows the ``cabal`` should do the right thing and hence should - normally not require this flag. - -.. _setup-build: - -setup build ------------ - -Perform any preprocessing or compilation needed to make this package -ready for installation. - -This command takes the following options: - -.. program:: setup build - -.. option:: --prog-options=options, --prog-option=option - - These are mostly the same as the `options configure - step <#setup-configure>`__. Unlike the options specified at the - configure step, any program options specified at the build step are - not persistent but are used for that invocation only. They options - specified at the build step are in addition not in replacement of - any options specified at the configure step. - -.. _setup-haddock: - -setup haddock -------------- - -.. program:: setup haddock - -Build the documentation for the package using Haddock_. -By default, only the documentation for the exposed modules is generated -(but see the :option:`--executables` and :option:`--internal` flags below). - -This command takes the following options: - -.. option:: --hoogle - - Generate a file ``dist/doc/html/``\ *pkgid*\ ``.txt``, which can be - converted by Hoogle_ into a - database for searching. This is equivalent to running Haddock_ - with the ``--hoogle`` flag. - -.. option:: --html-location=url - - Specify a template for the location of HTML documentation for - prerequisite packages. The substitutions (`see - listing <#paths-in-the-simple-build-system>`__) are applied to the - template to obtain a location for each package, which will be used - by hyperlinks in the generated documentation. For example, the - following command generates links pointing at Hackage_ pages: - - setup haddock - --html-location='http://hackage.haskell.org/packages/archive/$pkg/latest/doc/html' - - Here the argument is quoted to prevent substitution by the shell. If - this option is omitted, the location for each package is obtained - using the package tool (e.g. ``ghc-pkg``). - -.. option:: --executables - - Also run Haddock_ for the modules of all the executable programs. By default - Haddock_ is run only on the exported modules. - -.. option:: --internal - - Run Haddock_ for the all - modules, including unexposed ones, and make - Haddock_ generate documentation - for unexported symbols as well. - -.. option:: --css=path - - The argument *path* denotes a CSS file, which is passed to - Haddock_ and used to set the - style of the generated documentation. This is only needed to - override the default style that - Haddock_ uses. - -.. option:: --hyperlink-source - - Generate Haddock_ documentation integrated with HsColour_ . First, - HsColour_ is run to generate colourised code. Then Haddock_ is run to - generate HTML documentation. Each entity shown in the documentation is - linked to its definition in the colourised code. - -.. option:: --hscolour-css=path - - The argument *path* denotes a CSS file, which is passed to HsColour_ as in - - runhaskell Setup.hs hscolour --css=*path* - -.. _setup-hscolour: - -setup hscolour --------------- - -Produce colourised code in HTML format using HsColour_. Colourised code for -exported modules is put in ``dist/doc/html/``\ *pkgid*\ ``/src``. - -This command takes the following options: - -.. program:: setup hscolour - -.. option:: --executables - - Also run HsColour_ on the sources of all executable programs. Colourised - code is put in ``dist/doc/html/``\ *pkgid*/*executable*\ ``/src``. - -.. option:: --css=path - - Use the given CSS file for the generated HTML files. The CSS file - defines the colours used to colourise code. Note that this copies - the given CSS file to the directory with the generated HTML files - (renamed to ``hscolour.css``) rather than linking to it. - -.. _setup-install: - -setup install -------------- - -.. program:: setup install - -Copy the files into the install locations and (for library packages) -register the package with the compiler, i.e. make the modules it -contains available to programs. - -The `install locations <#installation-paths>`__ are determined by -options to `setup configure`_. - -This command takes the following options: - -.. option:: --global - - Register this package in the system-wide database. (This is the - default, unless the :option:`setup configure --user` option was supplied - to the ``configure`` command.) - -.. option:: --user - - Register this package in the user's local package database. (This is - the default if the :option:`setup configure --user` option was supplied - to the ``configure`` command.) - -.. _setup-copy: - -setup copy ----------- - -Copy the files without registering them. This command is mainly of use -to those creating binary packages. - -This command takes the following option: - -.. program:: setup copy - -.. option:: --destdir=path - - Specify the directory under which to place installed files. If this is - not given, then the root directory is assumed. - -.. _setup-register: - -setup register --------------- - -Register this package with the compiler, i.e. make the modules it -contains available to programs. This only makes sense for library -packages. Note that the ``install`` command incorporates this action. -The main use of this separate command is in the post-installation step -for a binary package. - -This command takes the following options: - -.. program:: setup register - -.. option:: --global - - Register this package in the system-wide database. (This is the - default.) - -.. option:: --user - - Register this package in the user's local package database. - -.. option:: --gen-script - - Instead of registering the package, generate a script containing - commands to perform the registration. On Unix, this file is called - ``register.sh``, on Windows, ``register.bat``. This script might be - included in a binary bundle, to be run after the bundle is unpacked - on the target system. - -.. option:: --gen-pkg-config[=path] - - Instead of registering the package, generate a package registration - file (or directory, in some circumstances). This only applies to - compilers that support package registration files which at the - moment is only GHC. The file should be used with the compiler's - mechanism for registering packages. This option is mainly intended - for packaging systems. If possible use the :option:`--gen-script` option - instead since it is more portable across Haskell implementations. - The *path* is optional and can be used to specify a particular - output file to generate. Otherwise, by default the file is the - package name and version with a ``.conf`` extension. - - This option outputs a directory if the package requires multiple - registrations: this can occur if internal/convenience libraries are - used. These configuration file names are sorted so that they can be - registered in order. - -.. option:: --inplace - - Registers the package for use directly from the build tree, without - needing to install it. This can be useful for testing: there's no - need to install the package after modifying it, just recompile and - test. - - This flag does not create a build-tree-local package database. It - still registers the package in one of the user or global databases. - - However, there are some caveats. It only works with GHC (currently). - It only works if your package doesn't depend on having any - supplemental files installed --- plain Haskell libraries should be - fine. - -.. _setup-unregister: - -setup unregister ----------------- - -.. program:: setup unregister - -Deregister this package with the compiler. - -This command takes the following options: - -.. option:: --global - - Deregister this package in the system-wide database. (This is the - default.) - -.. option:: --user - - Deregister this package in the user's local package database. - -.. option:: --gen-script - - Instead of deregistering the package, generate a script containing - commands to perform the deregistration. On Unix, this file is called - ``unregister.sh``, on Windows, ``unregister.bat``. This script might - be included in a binary bundle, to be run on the target system. - -.. _setup-clean: - -setup clean ------------ - -Remove any local files created during the ``configure``, ``build``, -``haddock``, ``register`` or ``unregister`` steps, and also any files -and directories listed in the :pkg-field:`extra-tmp-files` field. - -This command takes the following options: - -.. program:: setup clean - -.. option:: --save-configure, -s - - Keeps the configuration information so it is not necessary to run - the configure step again before building. - -.. _setup-test: - -setup test ----------- - -Run the test suites specified in the package description file. Aside -from the following flags, Cabal accepts the name of one or more test -suites on the command line after ``test``. When supplied, Cabal will run -only the named test suites, otherwise, Cabal will run all test suites in -the package. - -.. program:: setup test - -.. option:: --builddir=dir - - The directory where Cabal puts generated build files (default: - ``dist``). Test logs will be located in the ``test`` subdirectory. - -.. option:: --human-log=path - - The template used to name human-readable test logs; the path is - relative to ``dist/test``. By default, logs are named according to - the template ``$pkgid-$test-suite.log``, so that each test suite - will be logged to its own human-readable log file. Template - variables allowed are: ``$pkgid``, ``$compiler``, ``$os``, - ``$arch``, ``$abi``, ``$abitag``, ``$test-suite``, and ``$result``. - -.. option:: --machine-log=path - - The path to the machine-readable log, relative to ``dist/test``. The - default template is ``$pkgid.log``. Template variables allowed are: - ``$pkgid``, ``$compiler``, ``$os``, ``$arch``, ``$abi``, ``$abitag`` - and ``$result``. - -.. option:: --show-details=filter - - Determines if the results of individual test cases are shown on the - terminal. May be ``always`` (always show), ``never`` (never show), - ``failures`` (show only failed results), or ``streaming`` (show all - results in real time). - -.. option:: --test-options=options - Give extra options to the test executables. - -.. option:: --test-option=option - - Give an extra option to the test executables. There is no need to - quote options containing spaces because a single option is assumed, - so options will not be split on spaces. - -.. option:: --test-wrapper=path - - The wrapper script/application used to setup and tear down the test - execution context. The text executable path and test arguments are - passed as arguments to the wrapper and it is expected that the wrapper - will return the test's return code, as well as a copy of stdout/stderr. - -.. _setup-bench: - -setup bench ------------ - -Run the benchmarks specified in the package description file. Aside -from the following flags, Cabal accepts the name of one or more benchmarks -on the command line after ``bench``. When supplied, Cabal will run -only the named benchmarks, otherwise, Cabal will run all benchmarks in -the package. - -.. option:: --benchmark-options=options - Give extra options to the benchmark executables. - -.. option:: --benchmark-option=option - - Give an extra option to the benchmark executables. There is no need to - quote options containing spaces because a single option is assumed, - so options will not be split on spaces. - -.. _setup-sdist: - -setup sdist ------------ - -Create a system- and compiler-independent source distribution in a file -*package*-*version*\ ``.tar.gz`` in the ``dist`` subdirectory, for -distribution to package builders. When unpacked, the commands listed in -this section will be available. - -The files placed in this distribution are the package description file, -the setup script, the sources of the modules named in the package -description file, and files named in the ``license-file``, ``main-is``, -``c-sources``, ``asm-sources``, ``cmm-sources``, ``js-sources``, -``data-files``, ``extra-source-files`` and ``extra-doc-files`` fields. - -This command takes the following option: - -.. program:: setup sdist - -.. option:: --snapshot - - Append today's date (in "YYYYMMDD" format) to the version number for - the generated source package. The original package is unaffected. - - -.. include:: references.inc diff --git a/Cabal/doc/nix-integration.rst b/Cabal/doc/nix-integration.rst index f3c376390cb..01efed6898b 100644 --- a/Cabal/doc/nix-integration.rst +++ b/Cabal/doc/nix-integration.rst @@ -1,6 +1,11 @@ Nix Integration =============== +.. note:: + + This functionality doesn't work with nix-style builds. + Nix-style builds are not related to Nix integration. + `Nix `_ is a package manager popular with some Haskell developers due to its focus on reliability and reproducibility. ``cabal`` now has the ability to integrate with Nix for dependency management during local package development. Enabling Nix Integration diff --git a/Cabal/doc/nix-local-build-overview.rst b/Cabal/doc/nix-local-build-overview.rst index 12da6a36436..0edd1b3a83e 100644 --- a/Cabal/doc/nix-local-build-overview.rst +++ b/Cabal/doc/nix-local-build-overview.rst @@ -1,6 +1,8 @@ Nix-style Local Builds ====================== +.. _nix-style-builds + Nix-style local builds are a new build system implementation inspired by Nix. The Nix-style local build system is commonly called "v2-build" for short after the ``cabal v2-*`` family of commands that control it. However, those @@ -16,7 +18,7 @@ until such a point as it is completely removed from Cabal. Nix-style local builds combine the best of non-sandboxed and sandboxed Cabal: -1. Like sandboxed Cabal today, we build sets of independent local +1. Like sandboxed Cabal previously, we build sets of independent local packages deterministically and independent of any global state. v2-build will never tell you that it can't build your package because it would result in a "dangerous reinstall." Given a diff --git a/Cabal/doc/nix-local-build.rst b/Cabal/doc/nix-local-build.rst index af854a94e12..a2f6e7fb304 100644 --- a/Cabal/doc/nix-local-build.rst +++ b/Cabal/doc/nix-local-build.rst @@ -266,1925 +266,3 @@ build system, e.g., in ``$distdir/cache``. There is another useful file in ``dist-newstyle/cache``, ``plan.json``, which is a JSON serialization of the computed install plan and is intended for integrating with external tooling. - - - - -Commands -======== - -We now give an in-depth description of all the commands, describing the -arguments and flags they accept. - -cabal v2-configure -------------------- - -``cabal v2-configure`` takes a set of arguments and writes a -``cabal.project.local`` file based on the flags passed to this command. -``cabal v2-configure FLAGS; cabal new-build`` is roughly equivalent to -``cabal v2-build FLAGS``, except that with ``new-configure`` the flags -are persisted to all subsequent calls to ``v2-build``. - -``cabal v2-configure`` is intended to be a convenient way to write out -a ``cabal.project.local`` for simple configurations; e.g., -``cabal v2-configure -w ghc-7.8`` would ensure that all subsequent -builds with ``cabal v2-build`` are performed with the compiler -``ghc-7.8``. For more complex configuration, we recommend writing the -``cabal.project.local`` file directly (or placing it in -``cabal.project``!) - -``cabal v2-configure`` inherits options from ``Cabal``. semantics: - -- Any flag accepted by ``./Setup configure``. - -- Any flag accepted by ``cabal configure`` beyond - ``./Setup configure``, namely ``--cabal-lib-version``, - ``--constraint``, ``--preference`` and ``--solver.`` - -- Any flag accepted by ``cabal install`` beyond ``./Setup configure``. - -- Any flag accepted by ``./Setup haddock``. - -The options of all of these flags apply only to *local* packages in a -project; this behavior is different than that of ``cabal install``, -which applies flags to every package that would be built. The motivation -for this is to avoid an innocuous addition to the flags of a package -resulting in a rebuild of every package in the store (which might need -to happen if a flag actually applied to every transitive dependency). To -apply options to an external package, use a ``package`` stanza in a -``cabal.project`` file. - -cabal v2-update ----------------- - -``cabal v2-update`` updates the state of the package index. If the -project contains multiple remote package repositories it will update -the index of all of them (e.g. when using overlays). - -Some examples: - -:: - - $ cabal v2-update # update all remote repos - $ cabal v2-update head.hackage # update only head.hackage - -cabal v2-build ---------------- - -``cabal v2-build`` takes a set of targets and builds them. It -automatically handles building and installing any dependencies of these -targets. - -A target can take any of the following forms: - -- A package target: ``package``, which specifies that all enabled - components of a package to be built. By default, test suites and - benchmarks are *not* enabled, unless they are explicitly requested - (e.g., via ``--enable-tests``.) - -- A component target: ``[package:][ctype:]component``, which specifies - a specific component (e.g., a library, executable, test suite or - benchmark) to be built. - -- All packages: ``all``, which specifies all packages within the project. - -- Components of a particular type: ``package:ctypes``, ``all:ctypes``: - which specifies all components of the given type. Where valid - ``ctypes`` are: - - ``libs``, ``libraries``, - - ``flibs``, ``foreign-libraries``, - - ``exes``, ``executables``, - - ``tests``, - - ``benches``, ``benchmarks``. - -In component targets, ``package:`` and ``ctype:`` (valid component types -are ``lib``, ``flib``, ``exe``, ``test`` and ``bench``) can be used to -disambiguate when multiple packages define the same component, or the -same component name is used in a package (e.g., a package ``foo`` -defines both an executable and library named ``foo``). We always prefer -interpreting a target as a package name rather than as a component name. - -Some example targets: - -:: - - $ cabal v2-build lib:foo-pkg # build the library named foo-pkg - $ cabal v2-build foo-pkg:foo-tests # build foo-tests in foo-pkg - -(There is also syntax for specifying module and file targets, but it -doesn't currently do anything.) - -Beyond a list of targets, ``cabal v2-build`` accepts all the flags that -``cabal v2-configure`` takes. Most of these flags are only taken into -consideration when building local packages; however, some flags may -cause extra store packages to be built (for example, -``--enable-profiling`` will automatically make sure profiling libraries -for all transitive dependencies are built and installed.) - -In addition ``cabal v2-build`` accepts these flags: - -- ``--only-configure``: When given we will forgoe performing a full build and - abort after running the configure phase of each target package. - - -cabal v2-repl --------------- - -``cabal v2-repl TARGET`` loads all of the modules of the target into -GHCi as interpreted bytecode. In addition to ``cabal v2-build``'s flags, -it takes an additional ``--repl-options`` flag. - -To avoid ``ghci`` specific flags from triggering unneeded global rebuilds these -flags are now stripped from the internal configuration. As a result -``--ghc-options`` will no longer (reliably) work to pass flags to ``ghci`` (or -other repls). Instead, you should use the new ``--repl-options`` flag to -specify these options to the invoked repl. (This flag also works on ``cabal -repl`` and ``Setup repl`` on sufficiently new versions of Cabal.) - -Currently, it is not supported to pass multiple targets to ``v2-repl`` -(``v2-repl`` will just successively open a separate GHCi session for -each target.) - -It also provides a way to experiment with libraries without needing to download -them manually or to install them globally. - -This command opens a REPL with the current default target loaded, and a version -of the ``vector`` package matching that specification exposed. - -:: - - $ cabal v2-repl --build-depends "vector >= 0.12 && < 0.13" - -Both of these commands do the same thing as the above, but only exposes ``base``, -``vector``, and the ``vector`` package's transitive dependencies even if the user -is in a project context. - -:: - - $ cabal v2-repl --ignore-project --build-depends "vector >= 0.12 && < 0.13" - $ cabal v2-repl --project='' --build-depends "vector >= 0.12 && < 0.13" - -This command would add ``vector``, but not (for example) ``primitive``, because -it only includes the packages specified on the command line (and ``base``, which -cannot be excluded for technical reasons). - -:: - - $ cabal v2-repl --build-depends vector --no-transitive-deps - -cabal v2-run -------------- - -``cabal v2-run [TARGET [ARGS]]`` runs the executable specified by the -target, which can be a component, a package or can be left blank, as -long as it can uniquely identify an executable within the project. -Tests and benchmarks are also treated as executables. - -See `the v2-build section <#cabal-new-build>`__ for the target syntax. - -Except in the case of the empty target, the strings after it will be -passed to the executable as arguments. - -If one of the arguments starts with ``-`` it will be interpreted as -a cabal flag, so if you need to pass flags to the executable you -have to separate them with ``--``. - -:: - - $ cabal v2-run target -- -a -bcd --argument - -'v2-run' also supports running script files that use a certain format. With -a script that looks like: - -:: - - #!/usr/bin/env cabal - {- cabal: - build-depends: base ^>= 4.11 - , shelly ^>= 1.8.1 - -} - - main :: IO () - main = do - ... - -It can either be executed like any other script, using ``cabal`` as an -interpreter, or through this command: - -:: - - $ cabal v2-run script.hs - $ cabal v2-run script.hs -- --arg1 # args are passed like this - -cabal v2-freeze ----------------- - -``cabal v2-freeze`` writes out a **freeze file** which records all of -the versions and flags which that are picked by the solver under the -current index and flags. Default name of this file is -``cabal.project.freeze`` but in combination with a -``--project-file=my.project`` flag (see :ref:`project-file -`) -the name will be ``my.project.freeze``. -A freeze file has the same syntax as ``cabal.project`` and looks -something like this: - -.. highlight:: cabal - -:: - - constraints: HTTP ==4000.3.3, - HTTP +warp-tests -warn-as-error -network23 +network-uri -mtl1 -conduit10, - QuickCheck ==2.9.1, - QuickCheck +templatehaskell, - -- etc... - - -For end-user executables, it is recommended that you distribute the -``cabal.project.freeze`` file in your source repository so that all -users see a consistent set of dependencies. For libraries, this is not -recommended: users often need to build against different versions of -libraries than what you developed against. - -cabal v2-bench ---------------- - -``cabal v2-bench [TARGETS] [OPTIONS]`` runs the specified benchmarks -(all the benchmarks in the current package by default), first ensuring -they are up to date. - -cabal v2-test --------------- - -``cabal v2-test [TARGETS] [OPTIONS]`` runs the specified test suites -(all the test suites in the current package by default), first ensuring -they are up to date. - -cabal v2-haddock ------------------ - -``cabal v2-haddock [FLAGS] [TARGET]`` builds Haddock documentation for -the specified packages within the project. - -If a target is not a library :cfg-field:`haddock-benchmarks`, -:cfg-field:`haddock-executables`, :cfg-field:`haddock-internal`, -:cfg-field:`haddock-tests` will be implied as necessary. - -cabal v2-exec ---------------- - -``cabal v2-exec [FLAGS] [--] COMMAND [--] [ARGS]`` runs the specified command -using the project's environment. That is, passing the right flags to compiler -invocations and bringing the project's executables into scope. - -cabal v2-install ------------------ - -``cabal v2-install [FLAGS] PACKAGES`` builds the specified packages and -symlinks/copies their executables in ``installdir`` (usually ``~/.cabal/bin``). - -For example this command will build the latest ``cabal-install`` and symlink -its ``cabal`` executable: - -:: - - $ cabal v2-install cabal-install - -In addition, it's possible to use ``cabal v2-install`` to install components -of a local project. For example, with an up-to-date Git clone of the Cabal -repository, this command will build cabal-install HEAD and symlink the -``cabal`` executable: - -:: - - $ cabal v2-install exe:cabal - -Where symlinking is not possible (eg. on some Windows versions) the ``copy`` -method is used by default. You can specify the install method -by using ``--install-method`` flag: - -:: - - $ cabal v2-install exe:cabal --install-method=copy --installdir=$HOME/bin - -Note that copied executables are not self-contained, since they might use -data-files from the store. - -It is also possible to "install" libraries using the ``--lib`` flag. For -example, this command will build the latest Cabal library and install it: - -:: - - $ cabal v2-install --lib Cabal - -This works by managing GHC environments. By default, it is writing to the -global environment in ``~/.ghc/$ARCH-$OS-$GHCVER/environments/default``. -``v2-install`` provides the ``--package-env`` flag to control which of -these environments is modified. - -This command will modify the environment file in the current directory: - -:: - - $ cabal v2-install --lib Cabal --package-env . - -This command will modify the environment file in the ``~/foo`` directory: - -:: - - $ cabal v2-install --lib Cabal --package-env foo/ - -Do note that the results of the previous two commands will be overwritten by -the use of other v2-style commands, so it is not recommended to use them inside -a project directory. - -This command will modify the environment in the "local.env" file in the -current directory: - -:: - - $ cabal v2-install --lib Cabal --package-env local.env - -This command will modify the ``myenv`` named global environment: - -:: - - $ cabal v2-install --lib Cabal --package-env myenv - -If you wish to create a named environment file in the current directory where -the name does not contain an extension, you must reference it as ``./myenv``. - -You can learn more about how to use these environments in `this section of the -GHC manual `_. - -cabal v2-clean ---------------- - -``cabal v2-clean [FLAGS]`` cleans up the temporary files and build artifacts -stored in the ``dist-newstyle`` folder. - -By default, it removes the entire folder, but it can also spare the configuration -and caches if the ``--save-config`` option is given, in which case it only removes -the build artefacts (``.hi``, ``.o`` along with any other temporary files generated -by the compiler, along with the build output). - -cabal v2-sdist ---------------- - -``cabal v2-sdist [FLAGS] [TARGETS]`` takes the crucial files needed to build ``TARGETS`` -and puts them into an archive format ready for upload to Hackage. These archives are stable -and two archives of the same format built from the same source will hash to the same value. - -``cabal v2-sdist`` takes the following flags: - -- ``-l``, ``--list-only``: Rather than creating an archive, lists files that would be included. - Output is to ``stdout`` by default. The file paths are relative to the project's root - directory. - -- ``-o``, ``--output-dir``: Sets the output dir, if a non-default one is desired. The default is - ``dist-newstyle/sdist/``. ``--output-dir -`` will send output to ``stdout`` - unless multiple archives are being created. - -- ``-z``, ``--null``: Only used with ``--list-only``. Separates filenames with a NUL - byte instead of newlines. - -``v2-sdist`` is inherently incompatible with sdist hooks, not due to implementation but due -to fundamental core invariants (same source code should result in the same tarball, byte for -byte) that must be satisfied for it to function correctly in the larger v2-build ecosystem. -``autogen-modules`` is able to replace uses of the hooks to add generated modules, along with -the custom publishing of Haddock documentation to Hackage. - -.. warning:: - - Packages that use Backpack will stop working if uploaded to - Hackage, due to `issue #6005 `_. - While this is happening, we recommend not uploading these packages - to Hackage (and instead referencing the package directly - as a ``source-repository-package``). - -Configuring builds with cabal.project -===================================== - -``cabal.project`` files support a variety of options which configure the -details of your build. The general syntax of a ``cabal.project`` file is -similar to that of a Cabal file: there are a number of fields, some of -which live inside stanzas: - -:: - - packages: */*.cabal - with-compiler: /opt/ghc/8.0.1/bin/ghc - - package cryptohash - optimization: False - -In general, the accepted field names coincide with the accepted command -line flags that ``cabal install`` and other commands take. For example, -``cabal v2-configure --enable-profiling`` will write out a project -file with ``profiling: True``. - -The full configuration of a project is determined by combining the -following sources (later entries override earlier ones): - -1. ``~/.cabal/config`` (the user-wide global configuration) - -2. ``cabal.project`` (the project configuration) - -3. ``cabal.project.freeze`` (the output of ``cabal v2-freeze``) - -4. ``cabal.project.local`` (the output of ``cabal v2-configure``) - - -Specifying the local packages ------------------------------ - -The following top-level options specify what the local packages of a -project are: - -.. cfg-field:: packages: package location list (space or comma separated) - :synopsis: Project packages. - - :default: ``./*.cabal`` - - Specifies the list of package locations which contain the local - packages to be built by this project. Package locations can take the - following forms: - - 1. They can specify a Cabal file, or a directory containing a Cabal - file, e.g., ``packages: Cabal cabal-install/cabal-install.cabal``. - - 2. They can specify a glob-style wildcards, which must match one or - more (a) directories containing a (single) Cabal file, (b) Cabal - files (extension ``.cabal``), or (c) tarballs which contain Cabal - packages (extension ``.tar.gz``). - For example, to match all Cabal files in all - subdirectories, as well as the Cabal projects in the parent - directories ``foo`` and ``bar``, use - ``packages: */*.cabal ../{foo,bar}/`` - - 3. They can specify an ``http``, ``https`` or ``file`` - URL, representing the path to a remote tarball to be downloaded - and built. - - There is no command line variant of this field; see :issue:`3585`. - -.. cfg-field:: optional-packages: package location list (space or comma-separated) - :synopsis: Optional project packages. - - :default: ``./*/*.cabal`` - - Like :cfg-field:`packages`, specifies a list of package locations - containing local packages to be built. Unlike :cfg-field:`packages`, - if we glob for a package, it is permissible for the glob to match against - zero packages. The intended use-case for :cfg-field:`optional-packages` - is to make it so that vendored packages can be automatically picked up if - they are placed in a subdirectory, but not error if there aren't any. - - There is no command line variant of this field. - -.. cfg-field:: extra-packages: package list with version bounds (comma separated) - :synopsis: Adds external pacakges as local - - [STRIKEOUT:Specifies a list of external packages from Hackage which - should be considered local packages.] (Not implemented) - - There is no command line variant of this field. - - - -All local packages are *vendored*, in the sense that if other packages -(including external ones from Hackage) depend on a package with the name -of a local package, the local package is preferentially used. This -motivates the default settings:: - - packages: ./*.cabal - optional-packages: ./*/*.cabal - -...any package can be vendored simply by making a checkout in the -top-level project directory, as might be seen in this hypothetical -directory layout:: - - foo.cabal - foo-helper/ # local package - unix/ # vendored external package - -All of these options support globs. ``cabal v2-build`` has its own glob -format: - -- Anywhere in a path, as many times as you like, you can specify an - asterisk ``*`` wildcard. E.g., ``*/*.cabal`` matches all ``.cabal`` - files in all immediate subdirectories. Like in glob(7), asterisks do - not match hidden files unless there is an explicit period, e.g., - ``.*/foo.cabal`` will match ``.private/foo.cabal`` (but - ``*/foo.cabal`` will not). - -- You can use braces to specify specific directories; e.g., - ``{vendor,pkgs}/*.cabal`` matches all Cabal files in the ``vendor`` - and ``pkgs`` subdirectories. - -Formally, the format described by the following BNF: - -.. todo:: - convert globbing grammar to proper ABNF_ syntax - -.. code-block:: abnf - - FilePathGlob ::= FilePathRoot FilePathGlobRel - FilePathRoot ::= {- empty -} # relative to cabal.project - | "/" # Unix root - | [a-zA-Z] ":" [/\\] # Windows root - | "~" # home directory - FilePathGlobRel ::= Glob "/" FilePathGlobRel # Unix directory - | Glob "\\" FilePathGlobRel # Windows directory - | Glob # file - | {- empty -} # trailing slash - Glob ::= GlobPiece * - GlobPiece ::= "*" # wildcard - | [^*{},/\\] * # literal string - | "\\" [*{},] # escaped reserved character - | "{" Glob "," ... "," Glob "}" # union (match any of these) - - -Specifying Packages from Remote Version Control Locations -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Starting with Cabal 2.4, there is now a stanza -``source-repository-package`` for specifying packages from an external -version control which supports the following fields: - -- :pkg-field:`source-repository:type` -- :pkg-field:`source-repository:location` -- :pkg-field:`source-repository:tag` -- :pkg-field:`source-repository:subdir` - -A simple example is shown below: - -.. code-block:: cabal - - packages: . - - source-repository-package - type: git - location: https://github.com/hvr/HsYAML.git - tag: e70cf0c171c9a586b62b3f75d72f1591e4e6aaa1 - - source-repository-package - type: git - location: https://github.com/well-typed/cborg - tag: 3d274c14ca3077c3a081ba7ad57c5182da65c8c1 - subdir: cborg - -Global configuration options ----------------------------- - -The following top-level configuration options are not specific to any -package, and thus apply globally: - - -.. cfg-field:: verbose: nat - --verbose=n, -vn - :synopsis: Build verbosity level. - - :default: 1 - - Control the verbosity of ``cabal`` commands, valid values are from 0 - to 3. - - The command line variant of this field is ``--verbose=2``; a short - form ``-v2`` is also supported. - -.. cfg-field:: jobs: nat or $ncpus - --jobs=n, -jn, --jobs=$ncpus - :synopsis: Number of builds running in parallel. - - :default: 1 - - Run *nat* jobs simultaneously when building. If ``$ncpus`` is - specified, run the number of jobs equal to the number of CPUs. - Package building is often quite parallel, so turning on parallelism - can speed up build times quite a bit! - - The command line variant of this field is ``--jobs=2``; a short form - ``-j2`` is also supported; a bare ``--jobs`` or ``-j`` is equivalent - to ``--jobs=$ncpus``. - -.. cfg-field:: keep-going: boolean - --keep-going - :synopsis: Try to continue building on failure. - - :default: False - - If true, after a build failure, continue to build other unaffected - packages. - - The command line variant of this field is ``--keep-going``. - -.. option:: --builddir=DIR - - Specifies the name of the directory where build products for - build will be stored; defaults to ``dist-newstyle``. If a - relative name is specified, this directory is resolved relative - to the root of the project (i.e., where the ``cabal.project`` - file lives.) - - This option cannot be specified via a ``cabal.project`` file. - -.. _cmdoption-project-file: -.. option:: --project-file=FILE - - Specifies the name of the project file used to specify the - rest of the top-level configuration; defaults to ``cabal.project``. - This name not only specifies the name of the main project file, - but also the auxiliary project files ``cabal.project.freeze`` - and ``cabal.project.local``; for example, if you specify - ``--project-file=my.project``, then the other files that will - be probed are ``my.project.freeze`` and ``my.project.local``. - - If the specified project file is a relative path, we will - look for the file relative to the current working directory, - and then for the parent directory, until the project file is - found or we have hit the top of the user's home directory. - - This option cannot be specified via a ``cabal.project`` file. - -.. option:: --store-dir=DIR - - Specifies the name of the directory of the global package store. - -Solver configuration options ----------------------------- - -The following settings control the behavior of the dependency solver: - -.. cfg-field:: constraints: constraints list (comma separated) - --constraint="pkg >= 2.0" - :synopsis: Extra dependencies constraints. - - Add extra constraints to the version bounds, flag settings, - and other properties a solver can pick for a - package. For example: - - :: - - constraints: bar == 2.1 - - A package can be specified multiple times in ``constraints``, in - which case the specified constraints are intersected. This is - useful, since the syntax does not allow you to specify multiple - constraints at once. For example, to specify both version bounds and - flag assignments, you would write: - - :: - - constraints: bar == 2.1, - bar +foo -baz - - Valid constraints take the same form as for the `constraint - command line option - `__. - -.. cfg-field:: preferences: preference (comma separated) - --preference="pkg >= 2.0" - :synopsis: Prefered dependency versions. - - Like :cfg-field:`constraints`, but the solver will attempt to satisfy - these preferences on a best-effort basis. The resulting install is locally - optimal with respect to preferences; specifically, no single package - could be replaced with a more preferred version that still satisfies - the hard constraints. - - Operationally, preferences can cause the solver to attempt certain - version choices of a package before others, which can improve - dependency solver runtime. - - One way to use :cfg-field:`preferences` is to take a known working set of - constraints (e.g., via ``cabal v2-freeze``) and record them as - preferences. In this case, the solver will first attempt to use this - configuration, and if this violates hard constraints, it will try to - find the minimal number of upgrades to satisfy the hard constraints - again. - - The command line variant of this field is - ``--preference="pkg >= 2.0"``; to specify multiple preferences, pass - the flag multiple times. - -.. cfg-field:: allow-newer: none, all or list of scoped package names (space or comma separated) - --allow-newer, --allow-newer=[none,all,[scope:][^]pkg] - :synopsis: Lift dependencies upper bound constraints. - - :default: ``none`` - - Allow the solver to pick an newer version of some packages than - would normally be permitted by than the :pkg-field:`build-depends` bounds - of packages in the install plan. This option may be useful if the - dependency solver cannot otherwise find a valid install plan. - - For example, to relax ``pkg``\ s :pkg-field:`build-depends` upper bound on - ``dep-pkg``, write a scoped package name of the form: - - :: - - allow-newer: pkg:dep-pkg - - If the scope shall be limited to specific releases of ``pkg``, the - extended form as in - - :: - - allow-newer: pkg-1.2.3:dep-pkg, pkg-1.1.2:dep-pkg - - can be used to limit the relaxation of dependencies on - ``dep-pkg`` by the ``pkg-1.2.3`` and ``pkg-1.1.2`` releases only. - - The scoped syntax is recommended, as it is often only a single package - whose upper bound is misbehaving. In this case, the upper bounds of - other packages should still be respected; indeed, relaxing the bound - can break some packages which test the selected version of packages. - - The syntax also allows to prefix the dependee package with a - modifier symbol to modify the scope/semantic of the relaxation - transformation in a additional ways. Currently only one modifier - symbol is defined, i.e. ``^`` (i.e. caret) which causes the - relaxation to be applied only to ``^>=`` operators and leave all other - version operators untouched. - - However, in some situations (e.g., when attempting to build packages - on a new version of GHC), it is useful to disregard *all* - upper-bounds, with respect to a package or all packages. This can be - done by specifying just a package name, or using the keyword ``all`` - to specify all packages: - - :: - - -- Disregard upper bounds involving the dependencies on - -- packages bar, baz. For quux only, relax - -- 'quux ^>= ...'-style constraints only. - allow-newer: bar, baz, ^quux - - -- Disregard all upper bounds when dependency solving - allow-newer: all - - -- Disregard all `^>=`-style upper bounds when dependency solving - allow-newer: ^all - - - For consistency, there is also the explicit wildcard scope syntax - ``*`` (or its alphabetic synonym ``all``). Consequently, the - examples above are equivalent to the explicitly scoped variants: - - :: - - allow-newer: all:bar, *:baz, *:^quux - - allow-newer: *:* - allow-newer: all:all - - allow-newer: *:^* - allow-newer: all:^all - - In order to ignore all bounds specified by a package ``pkg-1.2.3`` - you can combine scoping with a right-hand-side wildcard like so - - :: - - -- Disregard any upper bounds specified by pkg-1.2.3 - allow-newer: pkg-1.2.3:* - - -- Disregard only `^>=`-style upper bounds in pkg-1.2.3 - allow-newer: pkg-1.2.3:^* - - - :cfg-field:`allow-newer` is often used in conjunction with a constraint - (in the cfg-field:`constraints` field) forcing the usage of a specific, - newer version of a package. - - The command line variant of this field is e.g. ``--allow-newer=bar``. A - bare ``--allow-newer`` is equivalent to ``--allow-newer=all``. - -.. cfg-field:: allow-older: none, all, list of scoped package names (space or comma separated) - --allow-older, --allow-older=[none,all,[scope:][^]pkg] - :synopsis: Lift dependency lower bound constraints. - :since: 2.0 - - :default: ``none`` - - Like :cfg-field:`allow-newer`, but applied to lower bounds rather than - upper bounds. - - The command line variant of this field is ``--allow-older=all``. A - bare ``--allow-older`` is equivalent to ``--allow-older=all``. - - -.. cfg-field:: index-state: HEAD, unix-timestamp, ISO8601 UTC timestamp. - :synopsis: Use source package index state as it existed at a previous time. - :since: 2.0 - - :default: ``HEAD`` - - This allows to change the source package index state the solver uses - to compute install-plans. This is particularly useful in - combination with freeze-files in order to also freeze the state the - package index was in at the time the install-plan was frozen. - - :: - - -- UNIX timestamp format example - index-state: @1474739268 - - -- ISO8601 UTC timestamp format example - -- This format is used by 'cabal v2-configure' - -- for storing `--index-state` values. - index-state: 2016-09-24T17:47:48Z - - -.. cfg-field:: reject-unconstrained-dependencies: all, none - --reject-unconstrained-dependencies=[all|none] - :synopsis: Restrict the solver to packages that have constraints on them. - - :default: none - :since: 2.6 - - By default, the dependency solver can include any package that it's - aware of in a build plan. If you wish to restrict the build plan to - a closed set of packages (e.g., from a freeze file), use this flag. - - When set to `all`, all non-local packages that aren't goals must be - explicitly constrained. When set to `none`, the solver will - consider all packages. - - -Package configuration options ------------------------------ - -Package options affect the building of specific packages. There are three -ways a package option can be specified: - -- They can be specified at the top-level, in which case they apply only - to **local package**, or - -- They can be specified inside a ``package`` stanza, in which case they - apply to the build of the package, whether or not it is local or - external. - -- They can be specified inside an ``package *`` stanza, in which case they - apply to all packages, local ones from the project and also external - dependencies. - - -For example, the following options specify that :cfg-field:`optimization` -should be turned off for all local packages, and that ``bytestring`` (possibly -an external dependency) should be built with ``-fno-state-hack``:: - - optimization: False - - package bytestring - ghc-options: -fno-state-hack - -``ghc-options`` is not specifically described in this documentation, -but is one of many fields for configuring programs. They take the form -``progname-options`` and ``progname-location``, and -can only be set inside package stanzas. (TODO: They are not supported -at top-level, see :issue:`3579`.) - -At the moment, there is no way to specify an option to apply to all -external packages or all inplace packages. Additionally, it is only -possible to specify these options on the command line for all local -packages (there is no per-package command line interface.) - -Some flags were added by more recent versions of the Cabal library. This -means that they are NOT supported by packages which use Custom setup -scripts that require a version of the Cabal library older than when the -feature was added. - -.. cfg-field:: flags: list of +flagname or -flagname (space separated) - --flags="+foo -bar", -ffoo, -f-bar - :synopsis: Enable or disable package flags. - - Force all flags specified as ``+flagname`` to be true, and all flags - specified as ``-flagname`` to be false. For example, to enable the - flag ``foo`` and disable ``bar``, set: - - :: - - flags: +foo -bar - - If there is no leading punctuation, it is assumed that the flag - should be enabled; e.g., this is equivalent: - - :: - - flags: foo -bar - - Flags are *per-package*, so it doesn't make much sense to specify - flags at the top-level, unless you happen to know that *all* of your - local packages support the same named flags. If a flag is not - supported by a package, it is ignored. - - See also the solver configuration field :cfg-field:`constraints`. - - The command line variant of this flag is ``--flags``. There is also - a shortened form ``-ffoo -f-bar``. - - A common mistake is to say ``cabal v2-build -fhans``, where - ``hans`` is a flag for a transitive dependency that is not in the - local package; in this case, the flag will be silently ignored. If - ``haskell-tor`` is the package you want this flag to apply to, try - ``--constraint="haskell-tor +hans"`` instead. - -.. cfg-field:: with-compiler: executable - --with-compiler=executable - :synopsis: Path to compiler executable. - - Specify the path to a particular compiler to be used. If not an - absolute path, it will be resolved according to the :envvar:`PATH` - environment. The type of the compiler (GHC, GHCJS, etc) must be - consistent with the setting of the :cfg-field:`compiler` field. - - The most common use of this option is to specify a different version - of your compiler to be used; e.g., if you have ``ghc-7.8`` in your - path, you can specify ``with-compiler: ghc-7.8`` to use it. - - This flag also sets the default value of :cfg-field:`with-hc-pkg`, using - the heuristic that it is named ``ghc-pkg-7.8`` (if your executable name - is suffixed with a version number), or is the executable named - ``ghc-pkg`` in the same directory as the ``ghc`` directory. If this - heuristic does not work, set :cfg-field:`with-hc-pkg` explicitly. - - For inplace packages, ``cabal v2-build`` maintains a separate build - directory for each version of GHC, so you can maintain multiple - build trees for different versions of GHC without clobbering each - other. - - At the moment, it's not possible to set :cfg-field:`with-compiler` on a - per-package basis, but eventually we plan on relaxing this - restriction. If this is something you need, give us a shout. - - The command line variant of this flag is - ``--with-compiler=ghc-7.8``; there is also a short version - ``-w ghc-7.8``. - -.. cfg-field:: with-hc-pkg: executable - --with-hc-pkg=executable - :synopsis: Specifies package tool. - - Specify the path to the package tool, e.g., ``ghc-pkg``. This - package tool must be compatible with the compiler specified by - :cfg-field:`with-compiler` (generally speaking, it should be precisely - the tool that was distributed with the compiler). If this option is - omitted, the default value is determined from :cfg-field:`with-compiler`. - - The command line variant of this flag is - ``--with-hc-pkg=ghc-pkg-7.8``. - -.. cfg-field:: optimization: nat - --enable-optimization - --disable-optimization - :synopsis: Build with optimization. - - :default: ``1`` - - Build with optimization. This is appropriate for production use, - taking more time to build faster libraries and programs. - - The optional *nat* value is the optimisation level. Some compilers - support multiple optimisation levels. The range is 0 to 2. Level 0 - disables optimization, level 1 is the default. Level 2 is higher - optimisation if the compiler supports it. Level 2 is likely to lead - to longer compile times and bigger generated code. If you are not - planning to run code, turning off optimization will lead to better - build times and less code to be rebuilt when a module changes. - - When optimizations are enabled, Cabal passes ``-O2`` to the C compiler. - - We also accept ``True`` (equivalent to 1) and ``False`` (equivalent - to 0). - - Note that as of GHC 8.0, GHC does not recompile when optimization - levels change (see :ghc-ticket:`10923`), so if - you change the optimization level for a local package you may need - to blow away your old build products in order to rebuild with the - new optimization level. - - The command line variant of this flag is ``-O2`` (with ``-O1`` - equivalent to ``-O``). There are also long-form variants - ``--enable-optimization`` and ``--disable-optimization``. - -.. cfg-field:: configure-options: args (space separated) - --configure-option=arg - :synopsis: Options to pass to configure script. - - A list of extra arguments to pass to the external ``./configure`` - script, if one is used. This is only useful for packages which have - the ``Configure`` build type. See also the section on - `system-dependent - parameters `__. - - The command line variant of this flag is ``--configure-option=arg``, - which can be specified multiple times to pass multiple options. - -.. cfg-field:: compiler: ghc, ghcjs, jhc, lhc, uhc or haskell-suite - --compiler=compiler - :synopsis: Compiler to build with. - - :default: ``ghc`` - - Specify which compiler toolchain to be used. This is independent of - ``with-compiler``, because the choice of toolchain affects Cabal's - build logic. - - The command line variant of this flag is ``--compiler=ghc``. - -.. cfg-field:: tests: boolean - --enable-tests - --disable-tests - :synopsis: Build tests. - - :default: ``False`` - - Force test suites to be enabled. For most users this should not be - needed, as we always attempt to solve for test suite dependencies, - even when this value is ``False``; furthermore, test suites are - automatically enabled if they are requested as a built target. - - The command line variant of this flag is ``--enable-tests`` and - ``--disable-tests``. - -.. cfg-field:: benchmarks: boolean - --enable-benchmarks - --disable-benchmarks - :synopsis: Build benchmarks. - - :default: ``False`` - - Force benchmarks to be enabled. For most users this should not be - needed, as we always attempt to solve for benchmark dependencies, - even when this value is ``False``; furthermore, benchmarks are - automatically enabled if they are requested as a built target. - - The command line variant of this flag is ``--enable-benchmarks`` and - ``--disable-benchmarks``. - -.. cfg-field:: extra-prog-path: paths (newline or comma separated) - --extra-prog-path=PATH - :synopsis: Add directories to program search path. - :since: 1.18 - - A list of directories to search for extra required programs. Most - users should not need this, as programs like ``happy`` and ``alex`` - will automatically be installed and added to the path. This can be - useful if a ``Custom`` setup script relies on an exotic extra - program. - - The command line variant of this flag is ``--extra-prog-path=PATH``, - which can be specified multiple times. - -.. cfg-field:: run-tests: boolean - --run-tests - :synopsis: Run package test suite upon installation. - - :default: ``False`` - - Run the package test suite upon installation. This is useful for - saying "When this package is installed, check that the test suite - passes, terminating the rest of the build if it is broken." - - .. warning:: - - One deficiency: the :cfg-field:`run-tests` setting of a package is NOT - recorded as part of the hash, so if you install something without - :cfg-field:`run-tests` and then turn on ``run-tests``, we won't - subsequently test the package. If this is causing you problems, give - us a shout. - - The command line variant of this flag is ``--run-tests``. - -Object code options -^^^^^^^^^^^^^^^^^^^ - -.. cfg-field:: debug-info: integer - --enable-debug-info= - --disable-debug-info - :synopsis: Build with debug info enabled. - :since: 1.22 - - :default: False - - If the compiler (e.g., GHC 7.10 and later) supports outputing OS - native debug info (e.g., DWARF), setting ``debug-info: True`` will - instruct it to do so. See the GHC wiki page on :ghc-wiki:`DWARF` - for more information about this feature. - - (This field also accepts numeric syntax, but until GHC 8.2 this didn't - do anything.) - - The command line variant of this flag is ``--enable-debug-info`` and - ``--disable-debug-info``. - -.. cfg-field:: split-sections: boolean - --enable-split-sections - --disable-split-sections - :synopsis: Use GHC's split sections feature. - :since: 2.2 - - :default: False - - Use the GHC ``-split-sections`` feature when building the library. This - reduces the final size of the executables that use the library by - allowing them to link with only the bits that they use rather than - the entire library. The downside is that building the library takes - longer and uses a bit more memory. - - This feature is supported by GHC 8.0 and later. - - The command line variant of this flag is ``--enable-split-sections`` and - ``--disable-split-sections``. - -.. cfg-field:: split-objs: boolean - --enable-split-objs - --disable-split-objs - :synopsis: Use GHC's split objects feature. - - :default: False - - Use the GHC ``-split-objs`` feature when building the library. This - reduces the final size of the executables that use the library by - allowing them to link with only the bits that they use rather than - the entire library. The downside is that building the library takes - longer and uses considerably more memory. - - It is generally recommend that you use ``split-sections`` instead - of ``split-objs`` where possible. - - The command line variant of this flag is ``--enable-split-objs`` and - ``--disable-split-objs``. - -.. cfg-field:: executable-stripping: boolean - --enable-executable-stripping - --disable-executable-stripping - :synopsis: Strip installed programs. - - :default: True - - When installing binary executable programs, run the ``strip`` - program on the binary. This can considerably reduce the size of the - executable binary file. It does this by removing debugging - information and symbols. - - Not all Haskell implementations generate native binaries. For such - implementations this option has no effect. - - If ``debug-info`` is set explicitly then ``executable-stripping`` is set - to ``False`` as otherwise all the debug symbols will be stripped. - - The command line variant of this flag is - ``--enable-executable-stripping`` and - ``--disable-executable-stripping``. - -.. cfg-field:: library-stripping: boolean - --enable-library-stripping - --disable-library-stripping - :synopsis: Strip installed libraries. - :since: 1.20 - - When installing binary libraries, run the ``strip`` program on the - binary, saving space on the file system. See also - ``executable-stripping``. - - If ``debug-info`` is set explicitly then ``library-stripping`` is set - to ``False`` as otherwise all the debug symbols will be stripped. - - The command line variant of this flag is - ``--enable-library-stripping`` and ``--disable-library-stripping``. - -Executable options -^^^^^^^^^^^^^^^^^^ - -.. cfg-field:: program-prefix: prefix - --program-prefix=prefix - :synopsis: Prepend prefix to program names. - - [STRIKEOUT:Prepend *prefix* to installed program names.] (Currently - implemented in a silly and not useful way. If you need this to work - give us a shout.) - - *prefix* may contain the following path variables: ``$pkgid``, - ``$pkg``, ``$version``, ``$compiler``, ``$os``, ``$arch``, ``$abi``, - ``$abitag`` - - The command line variant of this flag is ``--program-prefix=foo-``. - -.. cfg-field:: program-suffix: suffix - --program-suffix=suffix - :synopsis: Append refix to program names. - - [STRIKEOUT:Append *suffix* to installed program names.] (Currently - implemented in a silly and not useful way. If you need this to work - give us a shout.) - - The most obvious use for this is to append the program's version - number to make it possible to install several versions of a program - at once: ``program-suffix: $version``. - - *suffix* may contain the following path variables: ``$pkgid``, - ``$pkg``, ``$version``, ``$compiler``, ``$os``, ``$arch``, ``$abi``, - ``$abitag`` - - The command line variant of this flag is - ``--program-suffix='$version'``. - -Dynamic linking options -^^^^^^^^^^^^^^^^^^^^^^^ - -.. cfg-field:: shared: boolean - --enable-shared - --disable-shared - :synopsis: Build shared library. - - :default: False - - Build shared library. This implies a separate compiler run to - generate position independent code as required on most platforms. - - The command line variant of this flag is ``--enable-shared`` and - ``--disable-shared``. - -.. cfg-field:: executable-dynamic: boolean - --enable-executable-dynamic - --disable-executable-dynamic - :synopsis: Link executables dynamically. - - :default: False - - Link executables dynamically. The executable's library dependencies - should be built as shared objects. This implies ``shared: True`` - unless ``shared: False`` is explicitly specified. - - The command line variant of this flag is - ``--enable-executable-dynamic`` and - ``--disable-executable-dynamic``. - -.. cfg-field:: library-for-ghci: boolean - --enable-library-for-ghci - --disable-library-for-ghci - :synopsis: Build libraries suitable for use with GHCi. - - :default: True - - Build libraries suitable for use with GHCi. This involves an extra - linking step after the build. - - Not all platforms support GHCi and indeed on some platforms, trying - to build GHCi libs fails. In such cases, consider setting - ``library-for-ghci: False``. - - The command line variant of this flag is - ``--enable-library-for-ghci`` and ``--disable-library-for-ghci``. - -.. cfg-field:: relocatable: - --relocatable - :synopsis: Build relocatable package. - :since: 1.22 - - :default: False - - [STRIKEOUT:Build a package which is relocatable.] (TODO: It is not - clear what this actually does, or if it works at all.) - - The command line variant of this flag is ``--relocatable``. - -Static linking options -^^^^^^^^^^^^^^^^^^^^^^ - -.. cfg-field:: static: boolean - --enable-static - --disable-static - :synopsis: Build static library. - - - :default: False - - Roll this and all dependent libraries into a combined ``.a`` archive. - This uses GHCs ``-staticlib`` flag, which is available for iOS and with - GHC 8.4 and later for other platforms as well. - -.. cfg-field:: executable-static: boolean - --enable-executable-static - --disable-executable-static - :synopsis: Build fully static executables. - - - :default: False - - Build fully static executables. - This link all dependent libraries into executables statically, - including libc. - This passes ``-static`` and ``-optl=-static`` to GHC. - -Foreign function interface options -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. cfg-field:: extra-include-dirs: directories (comma or newline separated list) - --extra-include-dirs=DIR - :synopsis: Adds C header search path. - - An extra directory to search for C header files. You can use this - flag multiple times to get a list of directories. - - You might need to use this flag if you have standard system header - files in a non-standard location that is not mentioned in the - package's ``.cabal`` file. Using this option has the same affect as - appending the directory *dir* to the :pkg-field:`include-dirs` field in each - library and executable in the package's ``.cabal`` file. The - advantage of course is that you do not have to modify the package at - all. These extra directories will be used while building the package - and for libraries it is also saved in the package registration - information and used when compiling modules that use the library. - - The command line variant of this flag is - ``--extra-include-dirs=DIR``, which can be specified multiple times. - -.. cfg-field:: extra-lib-dirs: directories (comma or newline separated list) - --extra-lib-dirs=DIR - :synopsis: Adds library search directory. - - An extra directory to search for system libraries files. - - The command line variant of this flag is ``--extra-lib-dirs=DIR``, - which can be specified multiple times. - -.. cfg-field:: extra-framework-dirs: directories (comma or newline separated list) - --extra-framework-dirs=DIR - :synopsis: Adds framework search directory (OS X only). - - An extra directory to search for frameworks (OS X only). - - You might need to use this flag if you have standard system - libraries in a non-standard location that is not mentioned in the - package's ``.cabal`` file. Using this option has the same affect as - appending the directory *dir* to the :cfg-field:`extra-lib-dirs` field in - each library and executable in the package's ``.cabal`` file. The - advantage of course is that you do not have to modify the package at - all. These extra directories will be used while building the package - and for libraries it is also saved in the package registration - information and used when compiling modules that use the library. - - The command line variant of this flag is - ``--extra-framework-dirs=DIR``, which can be specified multiple - times. - -Profiling options -^^^^^^^^^^^^^^^^^ - -.. cfg-field:: profiling: boolean - --enable-profiling - --disable-profiling - :synopsis: Enable profiling builds. - :since: 1.22 - - :default: False - - Build libraries and executables with profiling enabled (for - compilers that support profiling as a separate mode). It is only - necessary to specify :cfg-field:`profiling` for the specific package you - want to profile; ``cabal v2-build`` will ensure that all of its - transitive dependencies are built with profiling enabled. - - To enable profiling for only libraries or executables, see - :cfg-field:`library-profiling` and :cfg-field:`executable-profiling`. - - For useful profiling, it can be important to control precisely what - cost centers are allocated; see :cfg-field:`profiling-detail`. - - The command line variant of this flag is ``--enable-profiling`` and - ``--disable-profiling``. - -.. cfg-field:: profiling-detail: level - --profiling-detail=level - :synopsis: Profiling detail level. - :since: 1.24 - - Some compilers that support profiling, notably GHC, can allocate - costs to different parts of the program and there are different - levels of granularity or detail with which this can be done. In - particular for GHC this concept is called "cost centers", and GHC - can automatically add cost centers, and can do so in different ways. - - This flag covers both libraries and executables, but can be - overridden by the ``library-profiling-detail`` field. - - Currently this setting is ignored for compilers other than GHC. The - levels that cabal currently supports are: - - default - For GHC this uses ``exported-functions`` for libraries and - ``toplevel-functions`` for executables. - none - No costs will be assigned to any code within this component. - exported-functions - Costs will be assigned at the granularity of all top level - functions exported from each module. In GHC, this - is for non-inline functions. Corresponds to ``-fprof-auto-exported``. - toplevel-functions - Costs will be assigned at the granularity of all top level - functions in each module, whether they are exported from the - module or not. In GHC specifically, this is for non-inline - functions. Corresponds to ``-fprof-auto-top``. - all-functions - Costs will be assigned at the granularity of all functions in - each module, whether top level or local. In GHC specifically, - this is for non-inline toplevel or where-bound functions or - values. Corresponds to ``-fprof-auto``. - - The command line variant of this flag is - ``--profiling-detail=none``. - -.. cfg-field:: library-profiling-detail: level - --library-profiling-detail=level - :synopsis: Libraries profiling detail level. - :since: 1.24 - - Like :cfg-field:`profiling-detail`, but applied only to libraries - - The command line variant of this flag is - ``--library-profiling-detail=none``. - -.. cfg-field:: library-vanilla: boolean - --enable-library-vanilla - --disable-library-vanilla - :synopsis: Build libraries without profiling. - - :default: True - - Build ordinary libraries (as opposed to profiling libraries). - Mostly, you can set this to False to avoid building ordinary - libraries when you are profiling. - - The command line variant of this flag is - ``--enable-library-vanilla`` and ``--disable-library-vanilla``. - -.. cfg-field:: library-profiling: boolean - --enable-library-profiling - --disable-library-profiling - :synopsis: Build libraries with profiling enabled. - :since: 1.22 - - :default: False - - Build libraries with profiling enabled. You probably want - to use :cfg-field:`profiling` instead. - - The command line variant of this flag is - ``--enable-library-profiling`` and ``--disable-library-profiling``. - -.. cfg-field:: executable-profiling: boolean - --enable-executable-profiling - --disable-executable-profiling - :synopsis: Build executables with profiling enabled. - :since: 1.22 - - :default: False - - Build executables with profiling enabled. You probably want - to use :cfg-field:`profiling` instead. - - The command line variant of this flag is - ``--enable-executable-profiling`` and - ``--disable-executable-profiling``. - -Coverage options -^^^^^^^^^^^^^^^^ - -.. cfg-field:: coverage: boolean - --enable-coverage - --disable-coverage - :synopsis: Build with coverage enabled. - :since: 1.22 - - :default: False - - Build libraries and executables (including test suites) with Haskell - Program Coverage enabled. Running the test suites will automatically - generate coverage reports with HPC. - - The command line variant of this flag is ``--enable-coverage`` and - ``--disable-coverage``. - -.. cfg-field:: library-coverage: boolean - --enable-library-coverage - --disable-library-coverage - :since: 1.22 - :deprecated: - - :default: False - - Deprecated, use :cfg-field:`coverage`. - - The command line variant of this flag is - ``--enable-library-coverage`` and ``--disable-library-coverage``. - -Haddock options -^^^^^^^^^^^^^^^ - -.. cfg-field:: documentation: boolean - --enable-documentation - --disable-documentation - :synopsis: Enable building of documentation. - - :default: False - - Enables building of Haddock documentation - - The command line variant of this flag is ``--enable-documentation`` - and ``--disable-documentation``. - - `documentation: true` does not imply :cfg-field:`haddock-benchmarks`, - :cfg-field:`haddock-executables`, :cfg-field:`haddock-internal` or - :cfg-field:`haddock-tests`. These need to be enabled separately if - desired. - -.. cfg-field:: doc-index-file: templated path - --doc-index-file=TEMPLATE - :synopsis: Path to haddock templates. - - A central index of Haddock API documentation (template cannot use - ``$pkgid``), which should be updated as documentation is built. - - The command line variant of this flag is - ``--doc-index-file=TEMPLATE`` - -The following commands are equivalent to ones that would be passed when -running ``setup haddock``. (TODO: Where does the documentation get put.) - -.. cfg-field:: haddock-hoogle: boolean - :synopsis: Generate Hoogle file. - - :default: False - - Generate a text file which can be converted by Hoogle_ - into a database for searching. This is equivalent to running ``haddock`` - with the ``--hoogle`` flag. - - The command line variant of this flag is ``--hoogle`` (for the - ``haddock`` command). - -.. cfg-field:: haddock-html: boolean - :synopsis: Build HTML documentation. - - :default: True - - Build HTML documentation. - - The command line variant of this flag is ``--html`` (for the - ``haddock`` command). - -.. cfg-field:: haddock-html-location: templated path - --html-location=TEMPLATE - :synopsis: Haddock HTML templates location. - - Specify a template for the location of HTML documentation for - prerequisite packages. The substitutions are applied to the template - to obtain a location for each package, which will be used by - hyperlinks in the generated documentation. For example, the - following command generates links pointing at [Hackage] pages: - - :: - - html-location: http://hackage.haskell.org/packages/archive/$pkg/latest/doc/html - - The command line variant of this flag is ``--html-location`` (for - the ``haddock`` subcommand). - - :: - - --html-location='http://hackage.haskell.org/packages/archive/$pkg/latest/doc/html' - - Here the argument is quoted to prevent substitution by the shell. If - this option is omitted, the location for each package is obtained - using the package tool (e.g. ``ghc-pkg``). - -.. cfg-field:: haddock-executables: boolean - :synopsis: Generate documentation for executables. - - :default: False - - Run haddock on all executable programs. - - The command line variant of this flag is ``--executables`` (for the - ``haddock`` subcommand). - -.. cfg-field:: haddock-tests: boolean - :synopsis: Generate documentation for tests. - - :default: False - - Run haddock on all test suites. - - The command line variant of this flag is ``--tests`` (for the - ``haddock`` subcommand). - -.. cfg-field:: haddock-benchmarks: boolean - :synopsis: Generate documentation for benchmarks. - - :default: False - - Run haddock on all benchmarks. - - The command line variant of this flag is ``--benchmarks`` (for the - ``haddock`` subcommand). - -.. cfg-field:: haddock-all: boolean - :synopsis: Generate documentation for everything - - :default: False - - Run haddock on all components. - - The command line variant of this flag is ``--all`` (for the - ``haddock`` subcommand). - -.. cfg-field:: haddock-internal: boolean - :synopsis: Generate documentation for internal modules - - :default: False - - Build haddock documentation which includes unexposed modules and - symbols. - - The command line variant of this flag is ``--internal`` (for the - ``haddock`` subcommand). - -.. cfg-field:: haddock-css: path - :synopsis: Location of Haddoc CSS file. - - The CSS file that should be used to style the generated - documentation (overriding haddock's default.) - - The command line variant of this flag is ``--css`` (for the - ``haddock`` subcommand). - -.. cfg-field:: haddock-hyperlink-source: boolean - :synopsis: Generate hyperlinked source code for documentation - - :default: False - - Generated hyperlinked source code using `HsColour`_, and have - Haddock documentation link to it. - - The command line variant of this flag is ``--hyperlink-source`` (for - the ``haddock`` subcommand). - -.. cfg-field:: haddock-hscolour-css: path - :synopsis: Location of CSS file for HsColour - - The CSS file that should be used to style the generated hyperlinked - source code (from `HsColour`_). - - The command line variant of this flag is ``--hscolour-css`` (for the - ``haddock`` subcommand). - -.. cfg-field:: haddock-contents-location: URL - :synopsis: URL for contents page. - - A baked-in URL to be used as the location for the contents page. - - The command line variant of this flag is ``--contents-location`` - (for the ``haddock`` subcommand). - -.. cfg-field:: haddock-keep-temp-files: boolean - :synopsis: Keep temporary Haddock files. - - Keep temporary files. - - The command line variant of this flag is ``--keep-temp-files`` (for - the ``haddock`` subcommand). - -Advanced global configuration options -------------------------------------- - -.. cfg-field:: write-ghc-environment-files: always, never, or ghc8.4.4+ - --write-ghc-environment-files=policy - :synopsis: Whether a ``.ghc.environment`` should be created after a successful build. - - :default: ``never`` - - Whether a `GHC package environment file `_ - should be created after a successful build. - - Since Cabal 3.0, defaults to ``never``. Before that, defaulted to - creating them only when compiling with GHC 8.4.4 and older (GHC - 8.4.4 `is the first version - `_ that supports - the ``-package-env -`` option that allows ignoring the package - environment files). - - -.. cfg-field:: http-transport: curl, wget, powershell, or plain-http - --http-transport=transport - :synopsis: Transport to use with http(s) requests. - - :default: ``curl`` - - Set a transport to be used when making http(s) requests. - - The command line variant of this field is ``--http-transport=curl``. - -.. cfg-field:: ignore-expiry: boolean - --ignore-expiry - :synopsis: Ignore Hackage expiration dates. - - :default: False - - If ``True``, we will ignore expiry dates on metadata from Hackage. - - In general, you should not set this to ``True`` as it will leave you - vulnerable to stale cache attacks. However, it may be temporarily - useful if the main Hackage server is down, and we need to rely on - mirrors which have not been updated for longer than the expiry - period on the timestamp. - - The command line variant of this field is ``--ignore-expiry``. - -.. cfg-field:: remote-repo-cache: directory - --remote-repo-cache=DIR - :synopsis: Location of packages cache. - - :default: ``~/.cabal/packages`` - - [STRIKEOUT:The location where packages downloaded from remote - repositories will be cached.] Not implemented yet. - - The command line variant of this flag is - ``--remote-repo-cache=DIR``. - -.. cfg-field:: logs-dir: directory - --logs-dir=DIR - :synopsis: Directory to store build logs. - - :default: ``~/.cabal/logs`` - - [STRIKEOUT:The location where build logs for packages are stored.] - Not implemented yet. - - The command line variant of this flag is ``--logs-dir=DIR``. - -.. cfg-field:: build-summary: template filepath - --build-summary=TEMPLATE - :synopsis: Build summaries location. - - :default: ``~/.cabal/logs/build.log`` - - [STRIKEOUT:The file to save build summaries. Valid variables which - can be used in the path are ``$pkgid``, ``$compiler``, ``$os`` and - ``$arch``.] Not implemented yet. - - The command line variant of this flag is - ``--build-summary=TEMPLATE``. - -.. cfg-field:: local-repo: directory - --local-repo=DIR - :deprecated: - - [STRIKEOUT:The location of a local repository.] Deprecated. See - "Legacy repositories." - - The command line variant of this flag is ``--local-repo=DIR``. - -.. cfg-field:: world-file: path - --world-file=FILE - :deprecated: - - [STRIKEOUT:The location of the world file.] Deprecated. - - The command line variant of this flag is ``--world-file=FILE``. - -Undocumented fields: ``root-cmd``, ``symlink-bindir``, ``build-log``, -``remote-build-reporting``, ``report-planned-failure``, ``one-shot``, -``offline``. - -Advanced solver options -^^^^^^^^^^^^^^^^^^^^^^^ - -Most users generally won't need these. - -.. cfg-field:: solver: modular - --solver=modular - :synopsis: Which solver to use. - - This field is reserved to allow the specification of alternative - dependency solvers. At the moment, the only accepted option is - ``modular``. - - The command line variant of this field is ``--solver=modular``. - -.. cfg-field:: max-backjumps: nat - --max-backjumps=N - :synopsis: Maximum number of solver backjumps. - - :default: 4000 - - Maximum number of backjumps (backtracking multiple steps) allowed - while solving. Set -1 to allow unlimited backtracking, and 0 to - disable backtracking completely. - - The command line variant of this field is ``--max-backjumps=4000``. - -.. cfg-field:: reorder-goals: boolean - --reorder-goals - --no-reorder-goals - :synopsis: Allow solver to reorder goals. - - :default: False - - When enabled, the solver will reorder goals according to certain - heuristics. Slows things down on average, but may make backtracking - faster for some packages. It's unlikely to help for small projects, - but for big install plans it may help you find a plan when otherwise - this is not possible. See :issue:`1780` for more commentary. - - The command line variant of this field is ``--(no-)reorder-goals``. - -.. cfg-field:: count-conflicts: boolean - --count-conflicts - --no-count-conflicts - :synopsis: Solver prefers versions with less conflicts. - - :default: True - - Try to speed up solving by preferring goals that are involved in a - lot of conflicts. - - The command line variant of this field is - ``--(no-)count-conflicts``. - -.. cfg-field:: fine-grained-conflicts: boolean - --fine-grained-conflicts - --no-fine-grained-conflicts - :synopsis: Skip a version of a package if it does not resolve any conflicts - encountered in the last version (solver optimization). - - :default: True - - When enabled, the solver will skip a version of a package if it does not - resolve any of the conflicts encountered in the last version of that - package. For example, if ``foo-1.2`` depended on ``bar``, and the solver - couldn't find consistent versions for ``bar``'s dependencies, then the - solver would skip ``foo-1.1`` if it also depended on ``bar``. - - The command line variant of this field is - ``--(no-)fine-grained-conflicts``. - -.. cfg-field:: minimize-conflict-set: boolean - --minimize-conflict-set - --no-minimize-conflict-set - :synopsis: Try to improve the solver error message when there is no - solution. - - :default: False - - When there is no solution, try to improve the solver error message - by finding a minimal conflict set. This option may increase run - time significantly, so it is off by default. - - The command line variant of this field is - ``--(no-)minimize-conflict-set``. - -.. cfg-field:: strong-flags: boolean - --strong-flags - --no-strong-flags - :synopsis: Do not defer flag choices when solving. - - :default: False - - Do not defer flag choices. (TODO: Better documentation.) - - The command line variant of this field is ``--(no-)strong-flags``. - -.. cfg-field:: allow-boot-library-installs: boolean - --allow-boot-library-installs - --no-allow-boot-library-installs - :synopsis: Allow cabal to install or upgrade any package. - - :default: False - - By default, the dependency solver doesn't allow ``base``, - ``ghc-prim``, ``integer-simple``, ``integer-gmp``, and - ``template-haskell`` to be installed or upgraded. This flag - removes the restriction. - - The command line variant of this field is - ``--(no-)allow-boot-library-installs``. - -.. cfg-field:: cabal-lib-version: version - --cabal-lib-version=version - :synopsis: Version of Cabal library used to build package. - - This field selects the version of the Cabal library which should be - used to build packages. This option is intended primarily for - internal development use (e.g., forcing a package to build with a - newer version of Cabal, to test a new version of Cabal.) (TODO: - Specify its semantics more clearly.) - - The command line variant of this field is - ``--cabal-lib-version=1.24.0.1``. - -.. include:: references.inc diff --git a/Cabal/doc/setup-commands.rst b/Cabal/doc/setup-commands.rst new file mode 100644 index 00000000000..f4d24599e80 --- /dev/null +++ b/Cabal/doc/setup-commands.rst @@ -0,0 +1,1422 @@ +Setup.hs Commands +================= + +.. highlight:: console + +The low-level Cabal interface is implemented using ``Setup.hs`` scripts. +You should prefer using higher level interface provided by +nix-style builds. + +:: + + $ runhaskell Setup.hs [command] [option...] + +For the summary of the command syntax, run: + +:: + + $ runhaskell Setup.hs --help + +Building and installing a system package +---------------------------------------- + +:: + + $ runhaskell Setup.hs configure --ghc + $ runhaskell Setup.hs build + $ runhaskell Setup.hs install + +The first line readies the system to build the tool using GHC; for +example, it checks that GHC exists on the system. The second line +performs the actual building, while the last both copies the build +results to some permanent place and registers the package with GHC. + +.. note :: + + Global installing of packages is not recommended. + The :ref:`_nix-style-builds` is the preferred of building and installing + packages. + +Creating a binary package +------------------------- + +When creating binary packages (e.g. for Red Hat or Debian) one needs to +create a tarball that can be sent to another system for unpacking in the +root directory: + +:: + + $ runhaskell Setup.hs configure --prefix=/usr + $ runhaskell Setup.hs build + $ runhaskell Setup.hs copy --destdir=/tmp/mypkg + $ tar -czf mypkg.tar.gz /tmp/mypkg/ + +If the package contains a library, you need two additional steps: + +:: + + $ runhaskell Setup.hs register --gen-script + $ runhaskell Setup.hs unregister --gen-script + +This creates shell scripts ``register.sh`` and ``unregister.sh``, which +must also be sent to the target system. After unpacking there, the +package must be registered by running the ``register.sh`` script. The +``unregister.sh`` script would be used in the uninstall procedure of the +package. Similar steps may be used for creating binary packages for +Windows. + +The following options are understood by all commands: + +.. program:: setup + +.. option:: --help, -h or -? + + List the available options for the command. + +.. option:: --verbose=n or -v n + + Set the verbosity level (0-3). The normal level is 1; a missing *n* + defaults to 2. + + There is also an extended version of this command which can be + used to fine-tune the verbosity of output. It takes the + form ``[silent|normal|verbose|debug]``\ *flags*, where *flags* + is a list of ``+`` flags which toggle various aspects of + output. At the moment, only ``+callsite`` and ``+callstack`` + are supported, which respectively toggle call site and call + stack printing (these are only supported if Cabal + is built with a sufficiently recent GHC.) + +The various commands and the additional options they support are +described below. In the simple build infrastructure, any other options +will be reported as errors. + +.. _setup-configure: + +runhaskell Setup.hs configure +----------------------------- + +.. program:: runhaskell Setup.hs configure + +Prepare to build the package. Typically, this step checks that the +target platform is capable of building the package, and discovers +platform-specific features that are needed during the build. + +The user may also adjust the behaviour of later stages using the options +listed in the following subsections. In the simple build infrastructure, +the values supplied via these options are recorded in a private file +read by later stages. + +If a user-supplied ``configure`` script is run (see the section on +`system-dependent +parameters `__ or +on `complex +packages `__), it is +passed the :option:`--with-hc-pkg`, :option:`--prefix`, :option:`--bindir`, +:option:`--libdir`, :option:`--dynlibdir`, :option:`--datadir`, :option:`--libexecdir` and +:option:`--sysconfdir` options. In addition the value of the +:option:`--with-compiler` option is passed in a :option:`--with-hc-pkg` option +and all options specified with :option:`--configure-option` are passed on. + +.. note:: + `GNU autoconf places restrictions on paths, including the directory + that the package is built from. + `_ + The errors produced when this happens can be obscure; Cabal attempts to + detect and warn in this situation, but it is not perfect. + +In Cabal 2.0, support for a single positional argument was added to +``runhaskell Setup.hs configure`` This makes Cabal configure the specific component to +be configured. Specified names can be qualified with ``lib:`` or +``exe:`` in case just a name is ambiguous (as would be the case for a +package named ``p`` which has a library and an executable named ``p``.) +This has the following effects: + +- Subsequent invocations of ``cabal build``, ``register``, etc. operate only + on the configured component. + +- Cabal requires all "internal" dependencies (e.g., an executable + depending on a library defined in the same package) must be found in + the set of databases via :option:`--package-db` (and related flags): these + dependencies are assumed to be up-to-date. A dependency can be + explicitly specified using :option:`--dependency` simply by giving the name + of the internal library; e.g., the dependency for an internal library + named ``foo`` is given as + ``--dependency=pkg-internal=pkg-1.0-internal-abcd``. + +- Only the dependencies needed for the requested component are + required. Similarly, when :option:`--exact-configuration` is specified, + it's only necessary to specify :option:`--dependency` for the component. + (As mentioned previously, you *must* specify internal dependencies as + well.) + +- Internal ``build-tool-depends`` and ``build-tools`` dependencies are expected + to be in the ``PATH`` upon subsequent invocations of ``setup``. + +Full details can be found in the `Componentized Cabal +proposal `__. + +Programs used for building +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The following options govern the programs used to process the source +files of a package: + +.. option:: --ghc or -g, --jhc, --lhc, --uhc + + Specify which Haskell implementation to use to build the package. At + most one of these flags may be given. If none is given, the + implementation under which the setup script was compiled or + interpreted is used. + +.. option:: --with-compiler=path or -w *path* + + Specify the path to a particular compiler. If given, this must match + the implementation selected above. The default is to search for the + usual name of the selected implementation. + + This flag also sets the default value of the :option:`--with-hc-pkg` + option to the package tool for this compiler. Check the output of + ``runhaskell Setup.hs configure -v`` to ensure that it finds the right package + tool (or use :option:`--with-hc-pkg` explicitly). + +.. option:: --with-hc-pkg=path + + Specify the path to the package tool, e.g. ``ghc-pkg``. The package + tool must be compatible with the compiler specified by + :option:`--with-compiler`. If this option is omitted, the default value is + determined from the compiler selected. + +.. option:: --with-prog=path + + Specify the path to the program *prog*. Any program known to Cabal + can be used in place of *prog*. It can either be a fully path or the + name of a program that can be found on the program search path. For + example: ``--with-ghc=ghc-6.6.1`` or + ``--with-cpphs=/usr/local/bin/cpphs``. The full list of accepted + programs is not enumerated in this user guide. Rather, run + ``cabal install --help`` to view the list. + +.. option:: --prog-options=options + + Specify additional options to the program *prog*. Any program known + to Cabal can be used in place of *prog*. For example: + ``--alex-options="--template=mytemplatedir/"``. The *options* is + split into program options based on spaces. Any options containing + embedded spaced need to be quoted, for example + ``--foo-options='--bar="C:\Program File\Bar"'``. As an alternative + that takes only one option at a time but avoids the need to quote, + use :option:`--prog-option` instead. + +.. option:: --prog-option=option + + Specify a single additional option to the program *prog*. For + passing an option that contain embedded spaces, such as a file name + with embedded spaces, using this rather than :option:`--prog-options` + means you do not need an additional level of quoting. Of course if you + are using a command shell you may still need to quote, for example + ``--foo-options="--bar=C:\Program File\Bar"``. + +All of the options passed with either :option:`--prog-options` +or :option:`--prog-option` are passed in the order they were +specified on the configure command line. + +Installation paths +^^^^^^^^^^^^^^^^^^ + +The following options govern the location of installed files from a +package: + +.. option:: --prefix=dir + + The root of the installation. For example for a global install you + might use ``/usr/local`` on a Unix system, or ``C:\Program Files`` + on a Windows system. The other installation paths are usually + subdirectories of *prefix*, but they don't have to be. + + In the simple build system, *dir* may contain the following path + variables: ``$pkgid``, ``$pkg``, ``$version``, ``$compiler``, + ``$os``, ``$arch``, ``$abi``, ``$abitag`` + +.. option:: --bindir=dir + + Executables that the user might invoke are installed here. + + In the simple build system, *dir* may contain the following path + variables: ``$prefix``, ``$pkgid``, ``$pkg``, ``$version``, + ``$compiler``, ``$os``, ``$arch``, ``$abi``, ``$abitag`` + +.. option:: --libdir=dir + + Object-code libraries are installed here. + + In the simple build system, *dir* may contain the following path + variables: ``$prefix``, ``$bindir``, ``$pkgid``, ``$pkg``, + ``$version``, ``$compiler``, ``$os``, ``$arch``, ``$abi``, + ``$abitag`` + +.. option:: --dynlibdir=dir + + Dynamic libraries are installed here. + + By default, this is set to `$libdir/$abi`, which is usually not equal to + `$libdir/$libsubdir`. + + In the simple build system, *dir* may contain the following path + variables: ``$prefix``, ``$bindir``, ``$libdir``, ``$pkgid``, ``$pkg``, + ``$version``, ``$compiler``, ``$os``, ``$arch``, ``$abi``, + ``$abitag`` + +.. option:: --libexecdir=dir + + Executables that are not expected to be invoked directly by the user + are installed here. + + In the simple build system, *dir* may contain the following path + variables: ``$prefix``, ``$bindir``, ``$libdir``, ``$libsubdir``, + ``$pkgid``, ``$pkg``, ``$version``, ``$compiler``, ``$os``, + ``$arch``, ``$abi``, ``$abitag`` + +.. option:: --datadir=dir + + Architecture-independent data files are installed here. + + In the simple build system, *dir* may contain the following path + variables: ``$prefix``, ``$bindir``, ``$libdir``, ``$libsubdir``, + ``$pkgid``, ``$pkg``, ``$version``, ``$compiler``, ``$os``, + ``$arch``, ``$abi``, ``$abitag`` + +.. option:: --sysconfdir=dir + + Installation directory for the configuration files. + + In the simple build system, *dir* may contain the following path + variables: ``$prefix``, ``$bindir``, ``$libdir``, ``$libsubdir``, + ``$pkgid``, ``$pkg``, ``$version``, ``$compiler``, ``$os``, + ``$arch``, ``$abi``, ``$abitag`` + +In addition the simple build system supports the following installation +path options: + +.. option:: --libsubdir=dir + + A subdirectory of *libdir* in which libraries are actually installed. For + example, in the simple build system on Unix, the default *libdir* is + ``/usr/local/lib``, and *libsubdir* contains the compiler ABI and package + identifier, + e.g. ``x86_64-linux-ghc-8.0.2/mypkg-0.1.0-IxQNmCA7qrSEQNkoHSF7A``, so + libraries would be installed in + ``/usr/local/lib/x86_64-linux-ghc-8.0.2/mypkg-0.1.0-IxQNmCA7qrSEQNkoHSF7A/``. + + *dir* may contain the following path variables: ``$pkgid``, + ``$pkg``, ``$version``, ``$compiler``, ``$os``, ``$arch``, ``$abi``, + ``$abitag`` + +.. option:: --libexecsubdir=dir + + A subdirectory of *libexecdir* in which private executables are + installed. For example, in the simple build system on Unix, the default + *libexecdir* is ``/usr/local/libexec``, and *libsubdir* is + ``x86_64-linux-ghc-8.0.2/mypkg-0.1.0``, so private executables would be + installed in ``/usr/local/libexec/x86_64-linux-ghc-8.0.2/mypkg-0.1.0/`` + + *dir* may contain the following path variables: ``$pkgid``, + ``$pkg``, ``$version``, ``$compiler``, ``$os``, ``$arch``, ``$abi``, + ``$abitag`` + +.. option:: --datasubdir=dir + + A subdirectory of *datadir* in which data files are actually + installed. + + *dir* may contain the following path variables: ``$pkgid``, + ``$pkg``, ``$version``, ``$compiler``, ``$os``, ``$arch``, ``$abi``, + ``$abitag`` + +.. option:: --docdir=dir + + Documentation files are installed relative to this directory. + + *dir* may contain the following path variables: ``$prefix``, + ``$bindir``, ``$libdir``, ``$libsubdir``, ``$datadir``, + ``$datasubdir``, ``$pkgid``, ``$pkg``, ``$version``, ``$compiler``, + ``$os``, ``$arch``, ``$abi``, ``$abitag`` + +.. option:: --htmldir=dir + + HTML documentation files are installed relative to this directory. + + *dir* may contain the following path variables: ``$prefix``, + ``$bindir``, ``$libdir``, ``$libsubdir``, ``$datadir``, + ``$datasubdir``, ``$docdir``, ``$pkgid``, ``$pkg``, ``$version``, + ``$compiler``, ``$os``, ``$arch``, ``$abi``, ``$abitag`` + +.. option:: --program-prefix=prefix + + Prepend *prefix* to installed program names. + + *prefix* may contain the following path variables: ``$pkgid``, + ``$pkg``, ``$version``, ``$compiler``, ``$os``, ``$arch``, ``$abi``, + ``$abitag`` + +.. option:: --program-suffix=suffix + + Append *suffix* to installed program names. The most obvious use for + this is to append the program's version number to make it possible + to install several versions of a program at once: + ``--program-suffix='$version'``. + + *suffix* may contain the following path variables: ``$pkgid``, + ``$pkg``, ``$version``, ``$compiler``, ``$os``, ``$arch``, ``$abi``, + ``$abitag`` + +Path variables in the simple build system +""""""""""""""""""""""""""""""""""""""""" + +For the simple build system, there are a number of variables that can be +used when specifying installation paths. The defaults are also specified +in terms of these variables. A number of the variables are actually for +other paths, like ``$prefix``. This allows paths to be specified +relative to each other rather than as absolute paths, which is important +for building relocatable packages (see `prefix +independence <#prefix-independence>`__). + +$prefix + The path variable that stands for the root of the installation. For + an installation to be relocatable, all other installation paths must + be relative to the ``$prefix`` variable. +$bindir + The path variable that expands to the path given by the :option:`--bindir` + configure option (or the default). +$libdir + As above but for :option:`--libdir` +$libsubdir + As above but for :option:`--libsubdir` +$dynlibdir + As above but for :option:`--dynlibdir` +$datadir + As above but for :option:`--datadir` +$datasubdir + As above but for :option:`--datasubdir` +$docdir + As above but for :option:`--docdir` +$pkgid + The name and version of the package, e.g. ``mypkg-0.2`` +$pkg + The name of the package, e.g. ``mypkg`` +$version + The version of the package, e.g. ``0.2`` +$compiler + The compiler being used to build the package, e.g. ``ghc-6.6.1`` +$os + The operating system of the computer being used to build the + package, e.g. ``linux``, ``windows``, ``osx``, ``freebsd`` or + ``solaris`` +$arch + The architecture of the computer being used to build the package, + e.g. ``i386``, ``x86_64``, ``ppc`` or ``sparc`` +$abitag + An optional tag that a compiler can use for telling incompatible + ABI's on the same architecture apart. GHCJS encodes the underlying + GHC version in the ABI tag. +$abi + A shortcut for getting a path that completely identifies the + platform in terms of binary compatibility. Expands to the same value + as ``$arch-$os-compiler-$abitag`` if the compiler uses an abi tag, + ``$arch-$os-$compiler`` if it doesn't. + +Paths in the simple build system +"""""""""""""""""""""""""""""""" + +For the simple build system, the following defaults apply: + +.. list-table:: Default installation paths + + * - Option + - Unix Default + - Windows Default + * - :option:`--prefix` (global) + - ``/usr/local`` + - ``%PROGRAMFILES%\Haskell`` + * - :option:`--prefix` (per-user) + - ``$HOME/.cabal`` + - ``%APPDATA%\cabal`` + * - :option:`--bindir` + - ``$prefix/bin`` + - ``$prefix\bin`` + * - :option:`--libdir` + - ``$prefix/lib`` + - ``$prefix`` + * - :option:`--libsubdir` (others) + - ``$pkgid/$compiler`` + - ``$pkgid\$compiler`` + * - :option:`--dynlibdir` + - ``$libdir/$abi`` + - ``$libdir\$abi`` + * - :option:`--libexecdir` + - ``$prefix/libexec`` + - ``$prefix\$pkgid`` + * - :option:`--datadir` (executable) + - ``$prefix/share`` + - ``$prefix`` + * - :option:`--datadir` (library) + - ``$prefix/share`` + - ``%PROGRAMFILES%\Haskell`` + * - :option:`--datasubdir` + - ``$pkgid`` + - ``$pkgid`` + * - :option:`--docdir` + - ``$datadir/doc/$pkgid`` + - ``$prefix\doc\$pkgid`` + * - :option:`--sysconfdir` + - ``$prefix/etc`` + - ``$prefix\etc`` + * - :option:`--htmldir` + - ``$docdir/html`` + - ``$docdir\html`` + * - :option:`--program-prefix` + - (empty) + - (empty) + * - :option:`--program-suffix` + - (empty) + - (empty) + +Prefix-independence +""""""""""""""""""" + +On Windows it is possible to obtain the pathname of the running program. +This means that we can construct an installable executable package that +is independent of its absolute install location. The executable can find +its auxiliary files by finding its own path and knowing the location of +the other files relative to ``$bindir``. Prefix-independence is +particularly useful: it means the user can choose the install location +(i.e. the value of ``$prefix``) at install-time, rather than having to +bake the path into the binary when it is built. + +In order to achieve this, we require that for an executable on Windows, +all of ``$bindir``, ``$libdir``, ``$dynlibdir``, ``$datadir`` and ``$libexecdir`` begin +with ``$prefix``. If this is not the case then the compiled executable +will have baked-in all absolute paths. + +The application need do nothing special to achieve prefix-independence. +If it finds any files using ``getDataFileName`` and the `other functions +provided for the +purpose `__, +the files will be accessed relative to the location of the current +executable. + +A library cannot (currently) be prefix-independent, because it will be +linked into an executable whose file system location bears no relation +to the library package. + +Controlling Flag Assignments +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Flag assignments (see the `resolution of conditions and +flags `__) +can be controlled with the following command line options. + +.. option:: -f flagname or -f -flagname + + Force the specified flag to ``true`` or ``false`` (if preceded with + a ``-``). Later specifications for the same flags will override + earlier, i.e., specifying ``-fdebug -f-debug`` is equivalent to + ``-f-debug`` + +.. option:: --flags=flagspecs + + Same as ``-f``, but allows specifying multiple flag assignments at + once. The parameter is a space-separated list of flag names (to + force a flag to ``true``), optionally preceded by a ``-`` (to force + a flag to ``false``). For example, + ``--flags="debug -feature1 feature2"`` is equivalent to + ``-fdebug -f-feature1 -ffeature2``. + +Building Test Suites +^^^^^^^^^^^^^^^^^^^^ + +.. option:: --enable-tests + + Build the test suites defined in the package description file during + the ``build`` stage. Check for dependencies required by the test + suites. If the package is configured with this option, it will be + possible to run the test suites with the ``test`` command after the + package is built. + +.. option:: --disable-tests + + (default) Do not build any test suites during the ``build`` stage. + Do not check for dependencies required only by the test suites. It + will not be possible to invoke the ``test`` command without + reconfiguring the package. + +.. option:: --enable-coverage + + Build libraries and executables (including test suites) with Haskell + Program Coverage enabled. Running the test suites will automatically + generate coverage reports with HPC. + +.. option:: --disable-coverage + + (default) Do not enable Haskell Program Coverage. + +Miscellaneous options +^^^^^^^^^^^^^^^^^^^^^ + +.. option:: --user + + Does a per-user installation. This changes the `default installation + prefix <#paths-in-the-simple-build-system>`__. It also allow + dependencies to be satisfied by the user's package database, in + addition to the global database. This also implies a default of + ``--user`` for any subsequent ``install`` command, as packages + registered in the global database should not depend on packages + registered in a user's database. + +.. option:: --global + + (default) Does a global installation. In this case package + dependencies must be satisfied by the global package database. All + packages in the user's package database will be ignored. Typically + the final installation step will require administrative privileges. + +.. option:: --package-db=db + + Allows package dependencies to be satisfied from this additional + package database *db* in addition to the global package database. + All packages in the user's package database will be ignored. The + interpretation of *db* is implementation-specific. Typically it will + be a file or directory. Not all implementations support arbitrary + package databases. + + This pushes an extra db onto the db stack. The :option:`--global` and + :option:`--user` mode switches add the respective [Global] and [Global, + User] dbs to the initial stack. There is a compiler-implementation + constraint that the global db must appear first in the stack, and if + the user one appears at all, it must appear immediately after the + global db. + + To reset the stack, use ``--package-db=clear``. + +.. option:: --ipid=ipid + + Specifies the *installed package identifier* of the package to be + built; this identifier is passed on to GHC and serves as the basis + for linker symbols and the ``id`` field in a ``ghc-pkg`` + registration. When a package has multiple components, the actual + component identifiers are derived off of this identifier (e.g., an + internal library ``foo`` from package ``p-0.1-abcd`` will get the + identifier ``p-0.1-abcd-foo``. + +.. option:: --cid=cid + + Specifies the *component identifier* of the component being built; + this is only valid if you are configuring a single component. + +.. option:: --default-user-config=file + + Allows a "default" ``cabal.config`` freeze file to be passed in + manually. This file will only be used if one does not exist in the + project directory already. Typically, this can be set from the + global cabal ``config`` file so as to provide a default set of + partial constraints to be used by projects, providing a way for + users to peg themselves to stable package collections. + +.. option:: --enable-optimization[=n] or -O [n] + + (default) Build with optimization flags (if available). This is + appropriate for production use, taking more time to build faster + libraries and programs. + + The optional *n* value is the optimisation level. Some compilers + support multiple optimisation levels. The range is 0 to 2. Level 0 + is equivalent to :option:`--disable-optimization`, level 1 is the + default if no *n* parameter is given. Level 2 is higher optimisation + if the compiler supports it. Level 2 is likely to lead to longer + compile times and bigger generated code. + + When optimizations are enabled, Cabal passes ``-O2`` to the C compiler. + +.. option:: --disable-optimization + + Build without optimization. This is suited for development: building + will be quicker, but the resulting library or programs will be + slower. + +.. option:: --enable-profiling + + Build libraries and executables with profiling enabled (for + compilers that support profiling as a separate mode). For this to + work, all libraries used by this package must also have been built + with profiling support. For libraries this involves building an + additional instance of the library in addition to the normal + non-profiling instance. For executables it changes the single + executable to be built in profiling mode. + + This flag covers both libraries and executables, but can be + overridden by the :option:`--enable-library-profiling` flag. + + See also the :option:`--profiling-detail` flag below. + +.. option:: --disable-profiling + + (default) Do not enable profiling in generated libraries and + executables. + +.. option:: --enable-library-profiling or -p + + As with :option:`--enable-profiling` above, but it applies only for + libraries. So this generates an additional profiling instance of the + library in addition to the normal non-profiling instance. + + The :option:`--enable-profiling` flag controls the profiling mode for both + libraries and executables, but if different modes are desired for + libraries versus executables then use :option:`--enable-library-profiling` + as well. + +.. option:: --disable-library-profiling + + (default) Do not generate an additional profiling version of the library. + +.. option:: --profiling-detail[=level] + + Some compilers that support profiling, notably GHC, can allocate + costs to different parts of the program and there are different + levels of granularity or detail with which this can be done. In + particular for GHC this concept is called "cost centers", and GHC + can automatically add cost centers, and can do so in different ways. + + This flag covers both libraries and executables, but can be + overridden by the :option:`--library-profiling-detail` flag. + + Currently this setting is ignored for compilers other than GHC. The + levels that cabal currently supports are: + + default + For GHC this uses ``exported-functions`` for libraries and + ``toplevel-functions`` for executables. + none + No costs will be assigned to any code within this component. + exported-functions + Costs will be assigned at the granularity of all top level + functions exported from each module. In GHC specifically, this + is for non-inline functions. + toplevel-functions + Costs will be assigned at the granularity of all top level + functions in each module, whether they are exported from the + module or not. In GHC specifically, this is for non-inline + functions. + all-functions + Costs will be assigned at the granularity of all functions in + each module, whether top level or local. In GHC specifically, + this is for non-inline toplevel or where-bound functions or + values. + + This flag is new in Cabal-1.24. Prior versions used the equivalent + of ``none`` above. + +.. option:: --library-profiling-detail[=level] + + As with :option:`--profiling-detail` above, but it applies only for + libraries. + + The level for both libraries and executables is set by the + :option:`--profiling-detail` flag, but if different levels are desired + for libraries versus executables then use + :option:`--library-profiling-detail` as well. + +.. option:: --enable-library-vanilla + + (default) Build ordinary libraries (as opposed to profiling + libraries). This is independent of the + :option:`--enable-library-profiling` option. If you enable both, you get + both. + +.. option:: --disable-library-vanilla + + Do not build ordinary libraries. This is useful in conjunction with + :option:`--enable-library-profiling` to build only profiling libraries, + rather than profiling and ordinary libraries. + +.. option:: --enable-library-for-ghci + + (default) Build libraries suitable for use with GHCi. + +.. option:: --disable-library-for-ghci + + Not all platforms support GHCi and indeed on some platforms, trying + to build GHCi libs fails. In such cases this flag can be used as a + workaround. + +.. option:: --enable-split-objs + + Use the GHC ``-split-objs`` feature when building the library. This + reduces the final size of the executables that use the library by + allowing them to link with only the bits that they use rather than + the entire library. The downside is that building the library takes + longer and uses considerably more memory. + +.. option:: --disable-split-objs + + (default) Do not use the GHC ``-split-objs`` feature. This makes + building the library quicker but the final executables that use the + library will be larger. + +.. option:: --enable-executable-stripping + + (default) When installing binary executable programs, run the + ``strip`` program on the binary. This can considerably reduce the + size of the executable binary file. It does this by removing + debugging information and symbols. While such extra information is + useful for debugging C programs with traditional debuggers it is + rarely helpful for debugging binaries produced by Haskell compilers. + + Not all Haskell implementations generate native binaries. For such + implementations this option has no effect. + +.. option:: --disable-executable-stripping + + Do not strip binary executables during installation. You might want + to use this option if you need to debug a program using gdb, for + example if you want to debug the C parts of a program containing + both Haskell and C code. Another reason is if your are building a + package for a system which has a policy of managing the stripping + itself (such as some Linux distributions). + +.. option:: --enable-shared + + Build shared library. This implies a separate compiler run to + generate position independent code as required on most platforms. + +.. option:: --disable-shared + + (default) Do not build shared library. + +.. option:: --enable-static + + Build a static library. This passes ``-staticlib`` to GHC (available + for iOS, and with 8.4 more platforms). The result is an archive ``.a`` + containing all dependent haskell libararies combined. + +.. option:: --disable-static + + (default) Do not build a static library. + +.. option:: --enable-executable-dynamic + + Link dependent Haskell libraries into executables dynamically. + The executable's library dependencies must have been + built as shared objects. This implies :option:`--enable-shared` + unless :option:`--disable-shared` is explicitly specified. + +.. option:: --disable-executable-dynamic + + (default) Link dependent Haskell libraries into executables statically. + Non-Haskell (C) libraries are still linked dynamically, including libc, + so the result is still not a fully static executable + unless :option:`--enable-executable-static` is given. + +.. option:: --enable-executable-static + + Build fully static executables. + This link all dependent libraries into executables statically, + including libc. + +.. option:: --disable-executable-static + + (default) Do not build fully static executables. + +.. option:: --configure-option=str + + An extra option to an external ``configure`` script, if one is used + (see the section on `system-dependent + parameters `__). + There can be several of these options. + +.. option:: --extra-include-dirs[=dir] + + An extra directory to search for C header files. You can use this + flag multiple times to get a list of directories. + + You might need to use this flag if you have standard system header + files in a non-standard location that is not mentioned in the + package's ``.cabal`` file. Using this option has the same affect as + appending the directory *dir* to the ``include-dirs`` field in each + library and executable in the package's ``.cabal`` file. The + advantage of course is that you do not have to modify the package at + all. These extra directories will be used while building the package + and for libraries it is also saved in the package registration + information and used when compiling modules that use the library. + +.. option:: --extra-lib-dirs[=dir] + + An extra directory to search for system libraries files. You can use + this flag multiple times to get a list of directories. + +.. option:: --extra-framework-dirs[=dir] + + An extra directory to search for frameworks (OS X only). You can use + this flag multiple times to get a list of directories. + + You might need to use this flag if you have standard system + libraries in a non-standard location that is not mentioned in the + package's ``.cabal`` file. Using this option has the same affect as + appending the directory *dir* to the ``extra-lib-dirs`` field in + each library and executable in the package's ``.cabal`` file. The + advantage of course is that you do not have to modify the package at + all. These extra directories will be used while building the package + and for libraries it is also saved in the package registration + information and used when compiling modules that use the library. + +.. option:: --dependency[=pkgname=ipid] + + Specify that a particular dependency should used for a particular + package name. In particular, it declares that any reference to + *pkgname* in a :pkg-field:`build-depends` should be resolved to + *ipid*. + +.. option:: --exact-configuration + + This changes Cabal to require every dependency be explicitly + specified using :option:`--dependency`, rather than use Cabal's (very + simple) dependency solver. This is useful for programmatic use of + Cabal's API, where you want to error if you didn't specify enough + :option:`--dependency` flags. + +.. option:: --allow-newer[=pkgs], --allow-older[=pkgs] + + Selectively relax upper or lower bounds in dependencies without + editing the package description respectively. + + The following description focuses on upper bounds and the + :option:`--allow-newer` flag, but applies analogously to + :option:`--allow-older` and lower bounds. :option:`--allow-newer` + and :option:`--allow-older` can be used at the same time. + + If you want to install a package A that depends on B >= 1.0 && < + 2.0, but you have the version 2.0 of B installed, you can compile A + against B 2.0 by using ``cabal install --allow-newer=B A``. This + works for the whole package index: if A also depends on C that in + turn depends on B < 2.0, C's dependency on B will be also relaxed. + + Example: + + :: + + $ cd foo + $ cabal configure + Resolving dependencies... + cabal: Could not resolve dependencies: + [...] + $ cabal configure --allow-newer + Resolving dependencies... + Configuring foo... + + Additional examples: + + :: + + # Relax upper bounds in all dependencies. + $ cabal install --allow-newer foo + + # Relax upper bounds only in dependencies on bar, baz and quux. + $ cabal install --allow-newer=bar,baz,quux foo + + # Relax the upper bound on bar and force bar==2.1. + $ cabal install --allow-newer=bar --constraint="bar==2.1" foo + + It's also possible to limit the scope of :option:`--allow-newer` to single + packages with the ``--allow-newer=scope:dep`` syntax. This means + that the dependency on ``dep`` will be relaxed only for the package + ``scope``. + + Example: + + :: + + # Relax upper bound in foo's dependency on base; also relax upper bound in + # every package's dependency on lens. + $ cabal install --allow-newer=foo:base,lens + + # Relax upper bounds in foo's dependency on base and bar's dependency + # on time; also relax the upper bound in the dependency on lens specified by + # any package. + $ cabal install --allow-newer=foo:base,lens --allow-newer=bar:time + + Finally, one can enable :option:`--allow-newer` permanently by setting + ``allow-newer: True`` in the ``~/.cabal/config`` file. Enabling + 'allow-newer' selectively is also supported in the config file + (``allow-newer: foo, bar, baz:base``). + +.. option:: --constraint=constraint + + Restrict solutions involving a package to given version + bounds, flag settings, and other properties. For example, to + consider only install plans that use version 2.1 of ``bar`` + or do not use ``bar`` at all, write: + + :: + + $ cabal install --constraint="bar == 2.1" + + Version bounds have the same syntax as :pkg-field:`build-depends`. + As a special case, the following prevents ``bar`` from being + used at all: + + :: + + # Note: this is just syntax sugar for '> 1 && < 1', and is + # supported by build-depends. + $ cabal install --constraint="bar -none" + + You can also specify flag assignments: + + :: + + # Require bar to be installed with the foo flag turned on and + # the baz flag turned off. + $ cabal install --constraint="bar +foo -baz" + + To specify multiple constraints, you may pass the + ``constraint`` option multiple times. + + There are also some more specialized constraints, which most people + don't generally need: + + :: + + # Require that a version of bar be used that is already installed in + # the global package database. + $ cabal install --constraint="bar installed" + + # Require the local source copy of bar to be used. + # (Note: By default, if we have a local package we will + # automatically use it, so it will generally not be necessary to + # specify this.) + $ cabal install --constraint="bar source" + + # Require that bar have test suites and benchmarks enabled. + $ cabal install --constraint="bar test" --constraint="bar bench" + + By default, constraints only apply to build dependencies + (:pkg-field:`build-depends`), build dependencies of build + dependencies, and so on. Constraints normally do not apply to + dependencies of the ``Setup.hs`` script of any package + (:pkg-field:`setup-depends`) nor do they apply to build tools + (:pkg-field:`build-tool-depends`) or the dependencies of build + tools. To explicitly apply a constraint to a setup or build + tool dependency, you can add a qualifier to the constraint as + follows: + + :: + + # Example use of the 'any' qualifier. This constraint + # applies to package bar anywhere in the dependency graph. + $ cabal install --constraint="any.bar == 1.0" + + :: + + # Example uses of 'setup' qualifiers. + + # This constraint applies to package bar when it is a + # dependency of any Setup.hs script. + $ cabal install --constraint="setup.bar == 1.0" + + # This constraint applies to package bar when it is a + # dependency of the Setup.hs script of package foo. + $ cabal install --constraint="foo:setup.bar == 1.0" + + .. TODO: Uncomment this example once we decide on a syntax for 'exe'. + .. # Example use of the 'exe' (executable build tool) + # qualifier. This constraint applies to package baz when it + # is a dependency of the build tool bar being used to + # build package foo. + $ cabal install --constraint="foo:bar:exe.baz == 1.0" + +.. option:: --preference=preference + + Specify a soft constraint on versions of a package. The solver will + attempt to satisfy these preferences on a "best-effort" basis. + +.. option:: --disable-response-files + + Enable workaround for older versions of programs such as ``ar`` or + ``ld`` that do not support response file arguments (i.e. ``@file`` + arguments). You may want this flag only if you specify custom ar + executable. For system ``ar`` or the one bundled with ``ghc`` on + Windows the ``cabal`` should do the right thing and hence should + normally not require this flag. + +.. _setup-build: + +runhaskell Setup.hs build +------------------------- + +Perform any preprocessing or compilation needed to make this package +ready for installation. + +This command takes the following options: + +.. program:: runhaskell Setup.hs build + +.. option:: --prog-options=options, --prog-option=option + + These are mostly the same as the `options configure + step <#setup-configure>`__. Unlike the options specified at the + configure step, any program options specified at the build step are + not persistent but are used for that invocation only. They options + specified at the build step are in addition not in replacement of + any options specified at the configure step. + +.. _setup-haddock: + +runhaskell Setup.hs haddock +--------------------------- + +.. program:: runhaskell Setup.hs haddock + +Build the documentation for the package using Haddock_. +By default, only the documentation for the exposed modules is generated +(but see the :option:`--executables` and :option:`--internal` flags below). + +This command takes the following options: + +.. option:: --hoogle + + Generate a file ``dist/doc/html/``\ *pkgid*\ ``.txt``, which can be + converted by Hoogle_ into a + database for searching. This is equivalent to running Haddock_ + with the ``--hoogle`` flag. + +.. option:: --html-location=url + + Specify a template for the location of HTML documentation for + prerequisite packages. The substitutions (`see + listing <#paths-in-the-simple-build-system>`__) are applied to the + template to obtain a location for each package, which will be used + by hyperlinks in the generated documentation. For example, the + following command generates links pointing at Hackage_ pages: + + runhaskell Setup.hs haddock + --html-location='http://hackage.haskell.org/packages/archive/$pkg/latest/doc/html' + + Here the argument is quoted to prevent substitution by the shell. If + this option is omitted, the location for each package is obtained + using the package tool (e.g. ``ghc-pkg``). + +.. option:: --executables + + Also run Haddock_ for the modules of all the executable programs. By default + Haddock_ is run only on the exported modules. + +.. option:: --internal + + Run Haddock_ for the all + modules, including unexposed ones, and make + Haddock_ generate documentation + for unexported symbols as well. + +.. option:: --css=path + + The argument *path* denotes a CSS file, which is passed to + Haddock_ and used to set the + style of the generated documentation. This is only needed to + override the default style that + Haddock_ uses. + +.. option:: --hyperlink-source + + Generate Haddock_ documentation integrated with HsColour_ . First, + HsColour_ is run to generate colourised code. Then Haddock_ is run to + generate HTML documentation. Each entity shown in the documentation is + linked to its definition in the colourised code. + +.. option:: --hscolour-css=path + + The argument *path* denotes a CSS file, which is passed to HsColour_ as in + + runhaskell Setup.hs hscolour --css=*path* + +.. _setup-hscolour: + +runhaskell Setup.hs hscolour +---------------------------- + +Produce colourised code in HTML format using HsColour_. Colourised code for +exported modules is put in ``dist/doc/html/``\ *pkgid*\ ``/src``. + +This command takes the following options: + +.. program:: runhaskell Setup.hs hscolour + +.. option:: --executables + + Also run HsColour_ on the sources of all executable programs. Colourised + code is put in ``dist/doc/html/``\ *pkgid*/*executable*\ ``/src``. + +.. option:: --css=path + + Use the given CSS file for the generated HTML files. The CSS file + defines the colours used to colourise code. Note that this copies + the given CSS file to the directory with the generated HTML files + (renamed to ``hscolour.css``) rather than linking to it. + +.. _setup-install: + +runhaskell Setup.hs install +--------------------------- + +.. program:: runhaskell Setup.hs install + +Copy the files into the install locations and (for library packages) +register the package with the compiler, i.e. make the modules it +contains available to programs. + +The `install locations <#installation-paths>`__ are determined by +options to `runhaskell Setup.hs configure`_. + +This command takes the following options: + +.. option:: --global + + Register this package in the system-wide database. (This is the + default, unless the :option:`runhaskell Setup.hs configure --user` option was supplied + to the ``configure`` command.) + +.. option:: --user + + Register this package in the user's local package database. (This is + the default if the :option:`runhaskell Setup.hs configure --user` option was supplied + to the ``configure`` command.) + +.. _setup-copy: + +runhaskell Setup.hs copy +------------------------ + +Copy the files without registering them. This command is mainly of use +to those creating binary packages. + +This command takes the following option: + +.. program:: runhaskell Setup.hs copy + +.. option:: --destdir=path + + Specify the directory under which to place installed files. If this is + not given, then the root directory is assumed. + +.. _setup-register: + +runhaskell Setup.hs register +---------------------------- + +Register this package with the compiler, i.e. make the modules it +contains available to programs. This only makes sense for library +packages. Note that the ``install`` command incorporates this action. +The main use of this separate command is in the post-installation step +for a binary package. + +This command takes the following options: + +.. program:: runhaskell Setup.hs register + +.. option:: --global + + Register this package in the system-wide database. (This is the + default.) + +.. option:: --user + + Register this package in the user's local package database. + +.. option:: --gen-script + + Instead of registering the package, generate a script containing + commands to perform the registration. On Unix, this file is called + ``register.sh``, on Windows, ``register.bat``. This script might be + included in a binary bundle, to be run after the bundle is unpacked + on the target system. + +.. option:: --gen-pkg-config[=path] + + Instead of registering the package, generate a package registration + file (or directory, in some circumstances). This only applies to + compilers that support package registration files which at the + moment is only GHC. The file should be used with the compiler's + mechanism for registering packages. This option is mainly intended + for packaging systems. If possible use the :option:`--gen-script` option + instead since it is more portable across Haskell implementations. + The *path* is optional and can be used to specify a particular + output file to generate. Otherwise, by default the file is the + package name and version with a ``.conf`` extension. + + This option outputs a directory if the package requires multiple + registrations: this can occur if internal/convenience libraries are + used. These configuration file names are sorted so that they can be + registered in order. + +.. option:: --inplace + + Registers the package for use directly from the build tree, without + needing to install it. This can be useful for testing: there's no + need to install the package after modifying it, just recompile and + test. + + This flag does not create a build-tree-local package database. It + still registers the package in one of the user or global databases. + + However, there are some caveats. It only works with GHC (currently). + It only works if your package doesn't depend on having any + supplemental files installed --- plain Haskell libraries should be + fine. + +.. _setup-unregister: + +runhaskell Setup.hs unregister +------------------------------ + +.. program:: runhaskell Setup.hs unregister + +Deregister this package with the compiler. + +This command takes the following options: + +.. option:: --global + + Deregister this package in the system-wide database. (This is the + default.) + +.. option:: --user + + Deregister this package in the user's local package database. + +.. option:: --gen-script + + Instead of deregistering the package, generate a script containing + commands to perform the deregistration. On Unix, this file is called + ``unregister.sh``, on Windows, ``unregister.bat``. This script might + be included in a binary bundle, to be run on the target system. + +.. _setup-clean: + +runhaskell Setup.hs clean +------------------------- + +Remove any local files created during the ``configure``, ``build``, +``haddock``, ``register`` or ``unregister`` steps, and also any files +and directories listed in the :pkg-field:`extra-tmp-files` field. + +This command takes the following options: + +.. program:: runhaskell Setup.hs clean + +.. option:: --save-configure, -s + + Keeps the configuration information so it is not necessary to run + the configure step again before building. + +.. _setup-test: + +runhaskell Setup.hs test +------------------------ + +Run the test suites specified in the package description file. Aside +from the following flags, Cabal accepts the name of one or more test +suites on the command line after ``test``. When supplied, Cabal will run +only the named test suites, otherwise, Cabal will run all test suites in +the package. + +.. program:: runhaskell Setup.hs test + +.. option:: --builddir=dir + + The directory where Cabal puts generated build files (default: + ``dist``). Test logs will be located in the ``test`` subdirectory. + +.. option:: --human-log=path + + The template used to name human-readable test logs; the path is + relative to ``dist/test``. By default, logs are named according to + the template ``$pkgid-$test-suite.log``, so that each test suite + will be logged to its own human-readable log file. Template + variables allowed are: ``$pkgid``, ``$compiler``, ``$os``, + ``$arch``, ``$abi``, ``$abitag``, ``$test-suite``, and ``$result``. + +.. option:: --machine-log=path + + The path to the machine-readable log, relative to ``dist/test``. The + default template is ``$pkgid.log``. Template variables allowed are: + ``$pkgid``, ``$compiler``, ``$os``, ``$arch``, ``$abi``, ``$abitag`` + and ``$result``. + +.. option:: --show-details=filter + + Determines if the results of individual test cases are shown on the + terminal. May be ``always`` (always show), ``never`` (never show), + ``failures`` (show only failed results), or ``streaming`` (show all + results in real time). + +.. option:: --test-options=options + Give extra options to the test executables. + +.. option:: --test-option=option + + Give an extra option to the test executables. There is no need to + quote options containing spaces because a single option is assumed, + so options will not be split on spaces. + +.. option:: --test-wrapper=path + + The wrapper script/application used to setup and tear down the test + execution context. The text executable path and test arguments are + passed as arguments to the wrapper and it is expected that the wrapper + will return the test's return code, as well as a copy of stdout/stderr. + +.. _setup-bench: + +runhaskell Setup.hs bench +------------------------- + +Run the benchmarks specified in the package description file. Aside +from the following flags, Cabal accepts the name of one or more benchmarks +on the command line after ``bench``. When supplied, Cabal will run +only the named benchmarks, otherwise, Cabal will run all benchmarks in +the package. + +.. option:: --benchmark-options=options + Give extra options to the benchmark executables. + +.. option:: --benchmark-option=option + + Give an extra option to the benchmark executables. There is no need to + quote options containing spaces because a single option is assumed, + so options will not be split on spaces. + +.. _setup-sdist: + +runhaskell Setup.hs sdist +------------------------- + +Create a system- and compiler-independent source distribution in a file +*package*-*version*\ ``.tar.gz`` in the ``dist`` subdirectory, for +distribution to package builders. When unpacked, the commands listed in +this section will be available. + +The files placed in this distribution are the package description file, +the setup script, the sources of the modules named in the package +description file, and files named in the ``license-file``, ``main-is``, +``c-sources``, ``asm-sources``, ``cmm-sources``, ``js-sources``, +``data-files``, ``extra-source-files`` and ``extra-doc-files`` fields. + +This command takes the following option: + +.. program:: runhaskell Setup.hs sdist + +.. option:: --snapshot + + Append today's date (in "YYYYMMDD" format) to the version number for + the generated source package. The original package is unaffected. + + +.. include:: references.inc