doc/buildinfo-fields-reference.rst

   1 .. _buildinfo-field-reference:
   2
   3 Field Syntax Reference
   4 ======================
   5
   6 Notation
   7 ---------------
   8
   9 Field syntax is described as they are in the latest cabal file format version.
  10
  11 * terminals are enclosed in quotes and type set in typewriter script:
  12
  13   .. math::
  14
  15       \mathord{"}\mathtt{example}\mathord{"}
  16
  17 * non-terminals are type set in italic:
  18
  19   .. math::
  20
  21       \mathit{version\text-range}
  22
  23 * character sets are type set resembling regular expression notation:
  24
  25
  26   .. math::
  27
  28       [ \mathord{"}\mathtt{1}\mathord{"} \cdots \mathord{"}\mathtt{9}\mathord{"} ]
  29
  30   Character set complements have :math:`c` superscript:
  31
  32   .. math::
  33
  34       [ \mathord{"}\mathtt{1}\mathord{"} \cdots \mathord{"}\mathtt{9}\mathord{"} ]^c
  35
  36 * repetition is type set using regular expression inspired notation.
  37   Superscripts tell how many time to repeat:
  38   The generic notation is :math:`\in[n\ldots5]`, however there
  39   are common shorthands:
  40   :math:`\ast` for :math:`\in[0\ldots\infty]` (``many``),
  41   :math:`+` for :math:`\in[1\ldots\infty]` (``some``),
  42   :math:`?` for :math:`\in[0\ldots1]` (``optional``).
  43
  44   Subscripts tell the used separator:
  45
  46   .. math::
  47
  48       \mathit{digit}^+_{\mathord{"}\mathtt{.}\mathord{"}}
  49
  50   Would be ``digit(\.digit)*`` in common regex syntax.
  51
  52 * alternatives are listed in braces separated by vertical bar:
  53
  54   .. math::
  55
  56       \{ \mathit{foo} \mid \mathit{bar} \}
  57
  58   In case of multiple alternatives, the stacked notation is used
  59
  60   .. math::
  61
  62       \left\{\begin{gathered}
  63       \mathit{one} \\
  64       \mathit{two} \\
  65       \mathit{three} \\
  66       \mathit{four} \\
  67       \mathit{five}
  68       \end{gathered}\right\}
  69
  70 * parenthesis are used only for grouping:
  71
  72   .. math::
  73
  74       \left(\mathit{foo} \mid \mathit{bar}\right)^+
  75
  76 * any amount of spaces, and at least single space are type set using
  77   :math:`\circ` and :math:`\bullet` respectively.
  78   They may appear standalone, not only as binary operators.
  79
  80   .. math::
  81
  82       \mathit{module} \bullet \mathord{``}\mathtt{as}\mathord{"} \bullet \mathit{module}
  83
  84 * While notation is heavily regular expression inspired, there
  85   are also fixed points, which allow represent recursive grammars
  86
  87
  88   .. math::
  89
  90       \mathbf{fix}\; \mathit{expr}\; \mathbf{in}\; \mathit{digit}
  91       \mid \mathit{expr} \circ \mathord{``}\mathtt{+}\mathord{"} \circ \mathit{expr}
  92       \mid \mathord{``}\mathtt{(} \mathord{"} \circ \mathit{expr} \circ \mathord{``}\mathtt{)}\mathord{"}
  93
  94 Lists
  95 -----
  96
  97 Many fields in cabal file format are lists. There are three variations:
  98
  99 Space separated
 100     Are used for lists of things with simple grammars, for example :pkg-field:`ghc-options`
 101
 102     .. math::
 103         {\mathop{\mathit{element}}}^\ast_{\bullet}
 104
 105 Comma separated
 106     Are used for lists of things with complicated grammars, for example :pkg-field:`build-depends`
 107     There can be leading or trailing comma (but not both) since ``cabal-version: 2.2``.
 108     Note, the comma cannot exist alone.
 109
 110     .. math::
 111         \mathrm{commalist}(\mathit{element}) =
 112         \left\{ {\mathop{\mathit{element}}}^\ast_{\left(\circ\mathop{\mathord{``}\mathtt{\text{,}}\mathord{"}}\circ\right)}\mid\mathop{\mathord{``}\mathtt{\text{,}}\mathord{"}}\circ{\mathop{\mathit{element}}}^+_{\left(\circ\mathop{\mathord{``}\mathtt{\text{,}}\mathord{"}}\circ\right)}\mid{\mathop{\mathit{element}}}^+_{\left(\circ\mathop{\mathord{``}\mathtt{\text{,}}\mathord{"}}\circ\right)}\circ\mathop{\mathord{``}\mathtt{\text{,}}\mathord{"}} \right\}
 113
 114 Optional comma separated
 115     Surprisingly many fields can have optional comma separator.
 116     Since ``cabal-version: 3.0`` comma usage have to be consistent,
 117     in other words either used everywhere or nowhere.
 118     It's recommended to avoid using comma in these fields,
 119     an example field is :pkg-field:`default-extensions`.
 120
 121     .. math::
 122         \mathrm{optcommalist}(\mathit{element}) =
 123         \left\{ \begin{gathered}{\mathop{\mathit{element}}}^\ast_{\bullet}\\{\mathop{\mathit{element}}}^\ast_{\left(\circ\mathop{\mathord{``}\mathtt{\text{,}}\mathord{"}}\circ\right)}\\\mathop{\mathord{``}\mathtt{\text{,}}\mathord{"}}\circ{\mathop{\mathit{element}}}^+_{\left(\circ\mathop{\mathord{``}\mathtt{\text{,}}\mathord{"}}\circ\right)}\\{\mathop{\mathit{element}}}^+_{\left(\circ\mathop{\mathord{``}\mathtt{\text{,}}\mathord{"}}\circ\right)}\circ\mathop{\mathord{``}\mathtt{\text{,}}\mathord{"}}\end{gathered} \right\}
 124
 125 Non-terminals
 126 -------------
 127
 128 In the syntax definitions below the following non-terminal symbols are used:
 129
 130 hs-string
 131     String as in Haskell; it's recommended to avoid using Haskell-specific escapes.
 132
 133     .. math::
 134         \mathop{\mathord{``}\mathtt{\text{"}}\mathord{"}}{\left\{ {[\mathop{\mathord{``}\mathtt{\text{"}}\mathord{"}}\mathop{\mathord{``}\mathtt{\text{\\}}\mathord{"}}]^c}\mid\left\{ \begin{gathered}\mathop{\mathord{``}\mathtt{\text{\\}\text{&}}\mathord{"}}\\\mathop{\mathord{``}\mathtt{\text{\\}\text{\\}}\mathord{"}}\\\left\{ \mathop{\mathord{``}\mathtt{\text{\\}n}\mathord{"}}\mid\mathop{\mathit{escapes}} \right\}\\\mathop{\mathord{``}\mathtt{\text{\\}}\mathord{"}}[\mathop{\mathord{``}\mathtt{0}\mathord{"}}\cdots\mathop{\mathord{``}\mathtt{9}\mathord{"}}]\\\mathop{\mathord{``}\mathtt{\text{\\}o}\mathord{"}}[\mathop{\mathord{``}\mathtt{0}\mathord{"}}\cdots\mathop{\mathord{``}\mathtt{7}\mathord{"}}]\\\mathop{\mathord{``}\mathtt{\text{\\}x}\mathord{"}}[\mathop{\mathord{``}\mathtt{0}\mathord{"}}\cdots\mathop{\mathord{``}\mathtt{9}\mathord{"}}\mathop{\mathord{``}\mathtt{A}\mathord{"}}\cdots\mathop{\mathord{``}\mathtt{F}\mathord{"}}\mathop{\mathord{``}\mathtt{a}\mathord{"}}\cdots\mathop{\mathord{``}\mathtt{f}\mathord{"}}]\\\left\{ \mathop{\mathord{``}\mathtt{\text{\\}\text{^}\text{@}}\mathord{"}}\mid\mathop{\mathit{control}} \right\}\\\left\{ \mathop{\mathord{``}\mathtt{\text{\\}NUL}\mathord{"}}\mid\mathop{\mathit{ascii}} \right\}\end{gathered} \right\} \right\}}^\ast_{}\mathop{\mathord{``}\mathtt{\text{"}}\mathord{"}}
 135
 136 unqual-name
 137     Unqualified component names are used for package names, component names etc. but not flag names. Unqualified component name consist of components separated by dash, each component is non-empty alphanumeric string, with at least one alphabetic character. In other words, component may not look like a number.
 138
 139     .. math::
 140         {\left({\mathop{\mathit{alpha\text{-}num}}}^\ast_{}\mathop{\mathit{alpha}}{\mathop{\mathit{alpha\text{-}num}}}^\ast_{}\right)}^+_{\mathop{\mathord{``}\mathtt{\text{-}}\mathord{"}}}
 141
 142 module-name
 143     Haskell module name as recognized by Cabal parser.
 144
 145     .. math::
 146         {\left(\mathop{\mathit{upper}}{\left\{ \mathop{\mathit{alpha\text{-}num}}\mid[\mathop{\mathord{``}\mathtt{\text{'}}\mathord{"}}\mathop{\mathord{``}\mathtt{\text{_}}\mathord{"}}] \right\}}^\ast_{}\right)}^+_{\mathop{\mathord{``}\mathtt{\text{.}}\mathord{"}}}
 147
 148 version
 149     Version is to first approximation numbers separated by dots, where leading zero is not allowed and each version digit is consists at most of nine characters.
 150
 151     .. math::
 152         {\left\{ \mathop{\mathord{``}\mathtt{0}\mathord{"}}\mid[\mathop{\mathord{``}\mathtt{1}\mathord{"}}\cdots\mathop{\mathord{``}\mathtt{9}\mathord{"}}]{[\mathop{\mathord{``}\mathtt{0}\mathord{"}}\cdots\mathop{\mathord{``}\mathtt{9}\mathord{"}}]}^{\in [0\ldots8]}_{} \right\}}^+_{\mathop{\mathord{``}\mathtt{\text{.}}\mathord{"}}}
 153
 154 version-range
 155     Version range syntax is recursive. Also note the set syntax added in ``cabal-version: 3.0``, set cannot be empty.
 156
 157     .. math::
 158         \mathbf{fix}\;\mathop{\mathit{version\text{-}range}}\;\mathbf{in}\;\left\{ \begin{gathered}\mathop{\mathord{``}\mathtt{\text{=}\text{=}}\mathord{"}}\circ\mathop{\mathit{version}}\\\mathop{\mathord{``}\mathtt{\text{>}}\mathord{"}}\circ\mathop{\mathit{version}}\\\mathop{\mathord{``}\mathtt{\text{<}}\mathord{"}}\circ\mathop{\mathit{version}}\\\mathop{\mathord{``}\mathtt{\text{<}\text{=}}\mathord{"}}\circ\mathop{\mathit{version}}\\\mathop{\mathord{``}\mathtt{\text{>}\text{=}}\mathord{"}}\circ\mathop{\mathit{version}}\\\mathop{\mathord{``}\mathtt{\text{^}\text{>}\text{=}}\mathord{"}}\circ\mathop{\mathit{version}}\\\mathop{\mathord{``}\mathtt{\text{=}\text{=}}\mathord{"}}\circ{\left\{ \mathop{\mathord{``}\mathtt{0}\mathord{"}}\mid[\mathop{\mathord{``}\mathtt{1}\mathord{"}}\cdots\mathop{\mathord{``}\mathtt{9}\mathord{"}}]{[\mathop{\mathord{``}\mathtt{0}\mathord{"}}\cdots\mathop{\mathord{``}\mathtt{9}\mathord{"}}]}^{\in [0\ldots8]}_{} \right\}}^+_{\mathop{\mathord{``}\mathtt{\text{.}}\mathord{"}}}\mathop{\mathord{``}\mathtt{\text{.}\text{*}}\mathord{"}}\\\mathop{\mathit{version\text{-}range}}\circ\mathop{\mathord{``}\mathtt{\text{|}\text{|}}\mathord{"}}\circ\mathop{\mathit{version\text{-}range}}\\\mathop{\mathit{version\text{-}range}}\circ\mathop{\mathord{``}\mathtt{\text{&}\text{&}}\mathord{"}}\circ\mathop{\mathit{version\text{-}range}}\\\mathop{\mathord{``}\mathtt{\text{(}}\mathord{"}}\circ\mathop{\mathit{version\text{-}range}}\circ\mathop{\mathord{``}\mathtt{\text{)}}\mathord{"}}\\\mathop{\mathord{``}\mathtt{\text{=}\text{=}}\mathord{"}}\circ\mathop{\mathord{``}\mathtt{\{}\mathord{"}}\circ{\mathop{\mathit{version}}}^+_{\left(\circ\mathop{\mathord{``}\mathtt{\text{,}}\mathord{"}}\circ\right)}\circ\mathop{\mathord{``}\mathtt{\}}\mathord{"}}\\\mathop{\mathord{``}\mathtt{\text{^}\text{>}\text{=}}\mathord{"}}\circ\mathop{\mathord{``}\mathtt{\{}\mathord{"}}\circ{\mathop{\mathit{version}}}^+_{\left(\circ\mathop{\mathord{``}\mathtt{\text{,}}\mathord{"}}\circ\right)}\circ\mathop{\mathord{``}\mathtt{\}}\mathord{"}}\end{gathered} \right\}
 159
 160
 161 Build info fields
 162 -----------------
 163
 164 asm-options
 165     * Monoidal field
 166     * Available since ``cabal-version: 3.0``.
 167     * Documentation of :pkg-field:`library:asm-options`
 168
 169     .. math::
 170         {\left\{ \mathop{\mathit{hs\text{-}string}}\mid{{[\mathop{\mathord{``}\mathtt{\ }\mathord{"}}]^c}}^+_{} \right\}}^\ast_{\bullet}
 171
 172 asm-sources
 173     * Monoidal field
 174     * Available since ``cabal-version: 3.0``.
 175     * Documentation of :pkg-field:`library:asm-sources`
 176
 177     .. math::
 178         \mathrm{commalist}\left\{ \mathop{\mathit{hs\text{-}string}}\mid{{[\mathop{\mathord{``}\mathtt{\ }\mathord{"}}\mathop{\mathord{``}\mathtt{\text{,}}\mathord{"}}]^c}}^+_{} \right\}
 179
 180 autogen-includes
 181     * Monoidal field
 182     * Available since ``cabal-version: 3.0``.
 183     * Documentation of :pkg-field:`library:autogen-includes`
 184
 185     .. math::
 186         \mathrm{optcommalist}\left\{ \mathop{\mathit{hs\text{-}string}}\mid{{[\mathop{\mathord{``}\mathtt{\ }\mathord{"}}\mathop{\mathord{``}\mathtt{\text{,}}\mathord{"}}]^c}}^+_{} \right\}
 187
 188 autogen-modules
 189     * Monoidal field
 190     * Available since ``cabal-version: 2.0``.
 191     * Documentation of :pkg-field:`library:autogen-modules`
 192
 193     .. math::
 194         \mathrm{commalist}\left({\left(\mathop{\mathit{upper}}{\left\{ \mathop{\mathit{alpha\text{-}num}}\mid[\mathop{\mathord{``}\mathtt{\text{'}}\mathord{"}}\mathop{\mathord{``}\mathtt{\text{_}}\mathord{"}}] \right\}}^\ast_{}\right)}^+_{\mathop{\mathord{``}\mathtt{\text{.}}\mathord{"}}}\right)
 195
 196 build-depends
 197     * Monoidal field
 198     * Documentation of :pkg-field:`library:build-depends`
 199
 200     .. math::
 201         \mathrm{commalist}\left(\mathop{\mathit{pkg\text{-}name}}{\left(\mathop{\mathord{``}\mathtt{\text{:}}\mathord{"}}\left\{ \mathop{\mathit{unqual\text{-}name}}\mid\mathop{\mathord{``}\mathtt{\{}\mathord{"}}\circ{\mathop{\mathit{unqual\text{-}name}}}^+_{\left(\circ\mathop{\mathord{``}\mathtt{\text{,}}\mathord{"}}\circ\right)}\circ\mathop{\mathord{``}\mathtt{\}}\mathord{"}} \right\}\right)}^?{\left(\circ\mathop{\mathit{version\text{-}range}}\right)}^?\right)
 202
 203 build-tool-depends
 204     * Monoidal field
 205     * Documentation of :pkg-field:`library:build-tool-depends`
 206
 207     .. math::
 208         \mathrm{commalist}\mathsf{\color{red}{TODO}}
 209
 210 build-tools
 211     * Monoidal field
 212     * Deprecated since ``cabal-version: 2.0``: Please use 'build-tool-depends' field
 213     * Removed in ``cabal-version: 3.0``: Please use 'build-tool-depends' field.
 214
 215     .. math::
 216         \mathrm{commalist}\mathsf{\color{red}{TODO}}
 217
 218 buildable
 219     * Boolean field
 220     * Default: ``True``
 221     * Documentation of :pkg-field:`library:buildable`
 222
 223     .. math::
 224         \left\{ \mathop{\mathord{``}\mathtt{True}\mathord{"}}\mid\mathop{\mathord{``}\mathtt{False}\mathord{"}} \right\}
 225
 226 c-sources
 227     * Monoidal field
 228     * Documentation of :pkg-field:`library:c-sources`
 229
 230     .. math::
 231         \mathrm{commalist}\left\{ \mathop{\mathit{hs\text{-}string}}\mid{{[\mathop{\mathord{``}\mathtt{\ }\mathord{"}}\mathop{\mathord{``}\mathtt{\text{,}}\mathord{"}}]^c}}^+_{} \right\}
 232
 233 cc-options
 234     * Monoidal field
 235     * Documentation of :pkg-field:`library:cc-options`
 236
 237     .. math::
 238         {\left\{ \mathop{\mathit{hs\text{-}string}}\mid{{[\mathop{\mathord{``}\mathtt{\ }\mathord{"}}]^c}}^+_{} \right\}}^\ast_{\bullet}
 239
 240 cmm-options
 241     * Monoidal field
 242     * Available since ``cabal-version: 3.0``.
 243     * Documentation of :pkg-field:`library:cmm-options`
 244
 245     .. math::
 246         {\left\{ \mathop{\mathit{hs\text{-}string}}\mid{{[\mathop{\mathord{``}\mathtt{\ }\mathord{"}}]^c}}^+_{} \right\}}^\ast_{\bullet}
 247
 248 cmm-sources
 249     * Monoidal field
 250     * Available since ``cabal-version: 3.0``.
 251     * Documentation of :pkg-field:`library:cmm-sources`
 252
 253     .. math::
 254         \mathrm{commalist}\left\{ \mathop{\mathit{hs\text{-}string}}\mid{{[\mathop{\mathord{``}\mathtt{\ }\mathord{"}}\mathop{\mathord{``}\mathtt{\text{,}}\mathord{"}}]^c}}^+_{} \right\}
 255
 256 cpp-options
 257     * Monoidal field
 258     * Documentation of :pkg-field:`library:cpp-options`
 259
 260     .. math::
 261         {\left\{ \mathop{\mathit{hs\text{-}string}}\mid{{[\mathop{\mathord{``}\mathtt{\ }\mathord{"}}]^c}}^+_{} \right\}}^\ast_{\bullet}
 262
 263 cxx-options
 264     * Monoidal field
 265     * Available since ``cabal-version: 2.2``.
 266     * Documentation of :pkg-field:`library:cxx-options`
 267
 268     .. math::
 269         {\left\{ \mathop{\mathit{hs\text{-}string}}\mid{{[\mathop{\mathord{``}\mathtt{\ }\mathord{"}}]^c}}^+_{} \right\}}^\ast_{\bullet}
 270
 271 cxx-sources
 272     * Monoidal field
 273     * Available since ``cabal-version: 2.2``.
 274     * Documentation of :pkg-field:`library:cxx-sources`
 275
 276     .. math::
 277         \mathrm{commalist}\left\{ \mathop{\mathit{hs\text{-}string}}\mid{{[\mathop{\mathord{``}\mathtt{\ }\mathord{"}}\mathop{\mathord{``}\mathtt{\text{,}}\mathord{"}}]^c}}^+_{} \right\}
 278
 279 default-extensions
 280     * Monoidal field
 281     * Available since ``cabal-version: 1.10``.
 282     * Documentation of :pkg-field:`library:default-extensions`
 283
 284     .. math::
 285         \mathrm{optcommalist}\mathsf{\color{red}{TODO}}
 286
 287 default-language
 288     * Optional field
 289     * Available since ``cabal-version: 1.10``.
 290     * Documentation of :pkg-field:`library:default-language`
 291
 292     .. math::
 293         \left\{ \begin{gathered}\mathop{\mathord{``}\mathtt{GHC2024}\mathord{"}}\\\mathop{\mathord{``}\mathtt{GHC2021}\mathord{"}}\\\mathop{\mathord{``}\mathtt{Haskell2010}\mathord{"}}\\\mathop{\mathord{``}\mathtt{Haskell98}\mathord{"}}\end{gathered} \right\}
 294
 295 extensions
 296     * Monoidal field
 297     * Deprecated since ``cabal-version: 1.12``: Please use 'default-extensions' or 'other-extensions' fields.
 298     * Removed in ``cabal-version: 3.0``: Please use 'default-extensions' or 'other-extensions' fields.
 299
 300     .. math::
 301         \mathrm{optcommalist}\mathsf{\color{red}{TODO}}
 302
 303 extra-bundled-libraries
 304     * Monoidal field
 305     * Documentation of :pkg-field:`library:extra-bundled-libraries`
 306
 307     .. math::
 308         \mathrm{commalist}\left\{ \mathop{\mathit{hs\text{-}string}}\mid{{[\mathop{\mathord{``}\mathtt{\ }\mathord{"}}\mathop{\mathord{``}\mathtt{\text{,}}\mathord{"}}]^c}}^+_{} \right\}
 309
 310 extra-dynamic-library-flavours
 311     * Monoidal field
 312     * Available since ``cabal-version: 3.0``.
 313     * Documentation of :pkg-field:`library:extra-dynamic-library-flavours`
 314
 315     .. math::
 316         \mathrm{commalist}\left\{ \mathop{\mathit{hs\text{-}string}}\mid{{[\mathop{\mathord{``}\mathtt{\ }\mathord{"}}\mathop{\mathord{``}\mathtt{\text{,}}\mathord{"}}]^c}}^+_{} \right\}
 317
 318 extra-framework-dirs
 319     * Monoidal field
 320     * Documentation of :pkg-field:`library:extra-framework-dirs`
 321
 322     .. math::
 323         \mathrm{optcommalist}\left\{ \mathop{\mathit{hs\text{-}string}}\mid{{[\mathop{\mathord{``}\mathtt{\ }\mathord{"}}\mathop{\mathord{``}\mathtt{\text{,}}\mathord{"}}]^c}}^+_{} \right\}
 324
 325 extra-ghci-libraries
 326     * Monoidal field
 327     * Documentation of :pkg-field:`library:extra-ghci-libraries`
 328
 329     .. math::
 330         \mathrm{commalist}\left\{ \mathop{\mathit{hs\text{-}string}}\mid{{[\mathop{\mathord{``}\mathtt{\ }\mathord{"}}\mathop{\mathord{``}\mathtt{\text{,}}\mathord{"}}]^c}}^+_{} \right\}
 331
 332 extra-lib-dirs
 333     * Monoidal field
 334     * Documentation of :pkg-field:`library:extra-lib-dirs`
 335
 336     .. math::
 337         \mathrm{optcommalist}\left\{ \mathop{\mathit{hs\text{-}string}}\mid{{[\mathop{\mathord{``}\mathtt{\ }\mathord{"}}\mathop{\mathord{``}\mathtt{\text{,}}\mathord{"}}]^c}}^+_{} \right\}
 338
 339 extra-lib-dirs-static
 340     * Monoidal field
 341     * Available since ``cabal-version: 3.8``.
 342     * Documentation of :pkg-field:`library:extra-lib-dirs-static`
 343
 344     .. math::
 345         \mathrm{optcommalist}\left\{ \mathop{\mathit{hs\text{-}string}}\mid{{[\mathop{\mathord{``}\mathtt{\ }\mathord{"}}\mathop{\mathord{``}\mathtt{\text{,}}\mathord{"}}]^c}}^+_{} \right\}
 346
 347 extra-libraries
 348     * Monoidal field
 349     * Documentation of :pkg-field:`library:extra-libraries`
 350
 351     .. math::
 352         \mathrm{commalist}\left\{ \mathop{\mathit{hs\text{-}string}}\mid{{[\mathop{\mathord{``}\mathtt{\ }\mathord{"}}\mathop{\mathord{``}\mathtt{\text{,}}\mathord{"}}]^c}}^+_{} \right\}
 353
 354 extra-libraries-static
 355     * Monoidal field
 356     * Available since ``cabal-version: 3.8``.
 357     * Documentation of :pkg-field:`library:extra-libraries-static`
 358
 359     .. math::
 360         \mathrm{commalist}\left\{ \mathop{\mathit{hs\text{-}string}}\mid{{[\mathop{\mathord{``}\mathtt{\ }\mathord{"}}\mathop{\mathord{``}\mathtt{\text{,}}\mathord{"}}]^c}}^+_{} \right\}
 361
 362 extra-library-flavours
 363     * Monoidal field
 364     * Documentation of :pkg-field:`library:extra-library-flavours`
 365
 366     .. math::
 367         \mathrm{commalist}\left\{ \mathop{\mathit{hs\text{-}string}}\mid{{[\mathop{\mathord{``}\mathtt{\ }\mathord{"}}\mathop{\mathord{``}\mathtt{\text{,}}\mathord{"}}]^c}}^+_{} \right\}
 368
 369 frameworks
 370     * Monoidal field
 371     * Documentation of :pkg-field:`library:frameworks`
 372
 373     .. math::
 374         \mathrm{optcommalist}\left\{ \mathop{\mathit{hs\text{-}string}}\mid{{[\mathop{\mathord{``}\mathtt{\ }\mathord{"}}\mathop{\mathord{``}\mathtt{\text{,}}\mathord{"}}]^c}}^+_{} \right\}
 375
 376 ghc-options
 377     * Monoidal field
 378     * Documentation of :pkg-field:`library:ghc-options`
 379
 380     .. math::
 381         {\left\{ \mathop{\mathit{hs\text{-}string}}\mid{{[\mathop{\mathord{``}\mathtt{\ }\mathord{"}}]^c}}^+_{} \right\}}^\ast_{\bullet}
 382
 383 ghc-prof-options
 384     * Monoidal field
 385     * Documentation of :pkg-field:`library:ghc-prof-options`
 386
 387     .. math::
 388         {\left\{ \mathop{\mathit{hs\text{-}string}}\mid{{[\mathop{\mathord{``}\mathtt{\ }\mathord{"}}]^c}}^+_{} \right\}}^\ast_{\bullet}
 389
 390 ghc-shared-options
 391     * Monoidal field
 392     * Documentation of :pkg-field:`library:ghc-shared-options`
 393
 394     .. math::
 395         {\left\{ \mathop{\mathit{hs\text{-}string}}\mid{{[\mathop{\mathord{``}\mathtt{\ }\mathord{"}}]^c}}^+_{} \right\}}^\ast_{\bullet}
 396
 397 ghcjs-options
 398     * Monoidal field
 399     * Documentation of :pkg-field:`library:ghcjs-options`
 400
 401     .. math::
 402         {\left\{ \mathop{\mathit{hs\text{-}string}}\mid{{[\mathop{\mathord{``}\mathtt{\ }\mathord{"}}]^c}}^+_{} \right\}}^\ast_{\bullet}
 403
 404 ghcjs-prof-options
 405     * Monoidal field
 406     * Documentation of :pkg-field:`library:ghcjs-prof-options`
 407
 408     .. math::
 409         {\left\{ \mathop{\mathit{hs\text{-}string}}\mid{{[\mathop{\mathord{``}\mathtt{\ }\mathord{"}}]^c}}^+_{} \right\}}^\ast_{\bullet}
 410
 411 ghcjs-shared-options
 412     * Monoidal field
 413     * Documentation of :pkg-field:`library:ghcjs-shared-options`
 414
 415     .. math::
 416         {\left\{ \mathop{\mathit{hs\text{-}string}}\mid{{[\mathop{\mathord{``}\mathtt{\ }\mathord{"}}]^c}}^+_{} \right\}}^\ast_{\bullet}
 417
 418 hs-source-dir
 419     * Monoidal field
 420     * Deprecated since ``cabal-version: 1.2``: Please use 'hs-source-dirs'
 421     * Removed in ``cabal-version: 3.0``: Please use 'hs-source-dirs' field.
 422
 423     .. math::
 424         \mathrm{optcommalist}\left\{ \mathop{\mathit{hs\text{-}string}}\mid{{[\mathop{\mathord{``}\mathtt{\ }\mathord{"}}\mathop{\mathord{``}\mathtt{\text{,}}\mathord{"}}]^c}}^+_{} \right\}
 425
 426 hs-source-dirs
 427     * Monoidal field
 428     * Documentation of :pkg-field:`library:hs-source-dirs`
 429
 430     .. math::
 431         \mathrm{optcommalist}\left\{ \mathop{\mathit{hs\text{-}string}}\mid{{[\mathop{\mathord{``}\mathtt{\ }\mathord{"}}\mathop{\mathord{``}\mathtt{\text{,}}\mathord{"}}]^c}}^+_{} \right\}
 432
 433 hsc2hs-options
 434     * Monoidal field
 435     * Available since ``cabal-version: 3.6``.
 436     * Documentation of :pkg-field:`library:hsc2hs-options`
 437
 438     .. math::
 439         {\left\{ \mathop{\mathit{hs\text{-}string}}\mid{{[\mathop{\mathord{``}\mathtt{\ }\mathord{"}}]^c}}^+_{} \right\}}^\ast_{\bullet}
 440
 441 include-dirs
 442     * Monoidal field
 443     * Documentation of :pkg-field:`library:include-dirs`
 444
 445     .. math::
 446         \mathrm{optcommalist}\left\{ \mathop{\mathit{hs\text{-}string}}\mid{{[\mathop{\mathord{``}\mathtt{\ }\mathord{"}}\mathop{\mathord{``}\mathtt{\text{,}}\mathord{"}}]^c}}^+_{} \right\}
 447
 448 includes
 449     * Monoidal field
 450     * Documentation of :pkg-field:`library:includes`
 451
 452     .. math::
 453         \mathrm{optcommalist}\left\{ \mathop{\mathit{hs\text{-}string}}\mid{{[\mathop{\mathord{``}\mathtt{\ }\mathord{"}}\mathop{\mathord{``}\mathtt{\text{,}}\mathord{"}}]^c}}^+_{} \right\}
 454
 455 install-includes
 456     * Monoidal field
 457     * Documentation of :pkg-field:`library:install-includes`
 458
 459     .. math::
 460         \mathrm{optcommalist}\left\{ \mathop{\mathit{hs\text{-}string}}\mid{{[\mathop{\mathord{``}\mathtt{\ }\mathord{"}}\mathop{\mathord{``}\mathtt{\text{,}}\mathord{"}}]^c}}^+_{} \right\}
 461
 462 js-sources
 463     * Monoidal field
 464     * Documentation of :pkg-field:`library:js-sources`
 465
 466     .. math::
 467         \mathrm{commalist}\left\{ \mathop{\mathit{hs\text{-}string}}\mid{{[\mathop{\mathord{``}\mathtt{\ }\mathord{"}}\mathop{\mathord{``}\mathtt{\text{,}}\mathord{"}}]^c}}^+_{} \right\}
 468
 469 ld-options
 470     * Monoidal field
 471     * Documentation of :pkg-field:`library:ld-options`
 472
 473     .. math::
 474         {\left\{ \mathop{\mathit{hs\text{-}string}}\mid{{[\mathop{\mathord{``}\mathtt{\ }\mathord{"}}]^c}}^+_{} \right\}}^\ast_{\bullet}
 475
 476 mixins
 477     * Monoidal field
 478     * Available since ``cabal-version: 2.0``.
 479     * Documentation of :pkg-field:`library:mixins`
 480
 481     .. math::
 482         \mathrm{commalist}\left(\mathop{\mathit{package\text{-}name}}{\left(\mathop{\mathord{``}\mathtt{\text{:}}\mathord{"}}\mathop{\mathit{library\text{-}name}}\right)}^?{\left(\bullet\left\{ \mid\mathop{\mathord{``}\mathtt{hiding}\mathord{"}}\circ\mathop{\mathord{``}\mathtt{\text{(}}\mathord{"}}\circ{\mathop{\mathit{module\text{-}name}}}^\ast_{\left(\circ\mathop{\mathord{``}\mathtt{\text{,}}\mathord{"}}\circ\right)}\circ\mathop{\mathord{``}\mathtt{\text{)}}\mathord{"}}\mid\mathop{\mathord{``}\mathtt{\text{(}}\mathord{"}}\circ{\left(\mathop{\mathit{module\text{-}name}}{\left(\bullet\mathop{\mathord{``}\mathtt{as}\mathord{"}}\bullet\mathop{\mathit{module\text{-}name}}\right)}^?\right)}^\ast_{\left(\circ\mathop{\mathord{``}\mathtt{\text{,}}\mathord{"}}\circ\right)}\circ\mathop{\mathord{``}\mathtt{\text{)}}\mathord{"}} \right\}{\left(\circ\mathop{\mathord{``}\mathtt{requires}\mathord{"}}\bullet\left\{ \mid\mathop{\mathord{``}\mathtt{hiding}\mathord{"}}\circ\mathop{\mathord{``}\mathtt{\text{(}}\mathord{"}}\circ{\mathop{\mathit{module\text{-}name}}}^\ast_{\left(\circ\mathop{\mathord{``}\mathtt{\text{,}}\mathord{"}}\circ\right)}\circ\mathop{\mathord{``}\mathtt{\text{)}}\mathord{"}}\mid\mathop{\mathord{``}\mathtt{\text{(}}\mathord{"}}\circ{\left(\mathop{\mathit{module\text{-}name}}{\left(\bullet\mathop{\mathord{``}\mathtt{as}\mathord{"}}\bullet\mathop{\mathit{module\text{-}name}}\right)}^?\right)}^\ast_{\left(\circ\mathop{\mathord{``}\mathtt{\text{,}}\mathord{"}}\circ\right)}\circ\mathop{\mathord{``}\mathtt{\text{)}}\mathord{"}} \right\}\right)}^?\right)}^?\right)
 483
 484 other-extensions
 485     * Monoidal field
 486     * Documentation of :pkg-field:`library:other-extensions`
 487
 488     .. math::
 489         \mathrm{optcommalist}\mathsf{\color{red}{TODO}}
 490
 491 other-languages
 492     * Monoidal field
 493     * Available since ``cabal-version: 1.10``.
 494     * Documentation of :pkg-field:`library:other-languages`
 495
 496     .. math::
 497         \mathrm{optcommalist}\left\{ \begin{gathered}\mathop{\mathord{``}\mathtt{GHC2024}\mathord{"}}\\\mathop{\mathord{``}\mathtt{GHC2021}\mathord{"}}\\\mathop{\mathord{``}\mathtt{Haskell2010}\mathord{"}}\\\mathop{\mathord{``}\mathtt{Haskell98}\mathord{"}}\end{gathered} \right\}
 498
 499 other-modules
 500     * Monoidal field
 501     * Documentation of :pkg-field:`library:other-modules`
 502
 503     .. math::
 504         \mathrm{commalist}\left({\left(\mathop{\mathit{upper}}{\left\{ \mathop{\mathit{alpha\text{-}num}}\mid[\mathop{\mathord{``}\mathtt{\text{'}}\mathord{"}}\mathop{\mathord{``}\mathtt{\text{_}}\mathord{"}}] \right\}}^\ast_{}\right)}^+_{\mathop{\mathord{``}\mathtt{\text{.}}\mathord{"}}}\right)
 505
 506 pkgconfig-depends
 507     * Monoidal field
 508     * Documentation of :pkg-field:`library:pkgconfig-depends`
 509
 510     .. math::
 511         \mathrm{commalist}\mathsf{\color{red}{TODO}}
 512
 513 virtual-modules
 514     * Monoidal field
 515     * Available since ``cabal-version: 2.2``.
 516     * Documentation of :pkg-field:`library:virtual-modules`
 517
 518     .. math::
 519         \mathrm{commalist}\left({\left(\mathop{\mathit{upper}}{\left\{ \mathop{\mathit{alpha\text{-}num}}\mid[\mathop{\mathord{``}\mathtt{\text{'}}\mathord{"}}\mathop{\mathord{``}\mathtt{\text{_}}\mathord{"}}] \right\}}^\ast_{}\right)}^+_{\mathop{\mathord{``}\mathtt{\text{.}}\mathord{"}}}\right)
 520
 521
 522 Package description fields
 523 --------------------------
 524
 525 author
 526     * Free text field
 527     * Documentation of :pkg-field:`author`
 528
 529 bug-reports
 530     * Free text field
 531     * Documentation of :pkg-field:`bug-reports`
 532
 533 build-type
 534     * Optional field
 535     * Documentation of :pkg-field:`build-type`
 536
 537     .. math::
 538         \left\{ \begin{gathered}\mathop{\mathord{``}\mathtt{Simple}\mathord{"}}\\\mathop{\mathord{``}\mathtt{Configure}\mathord{"}}\\\mathop{\mathord{``}\mathtt{Custom}\mathord{"}}\\\mathop{\mathord{``}\mathtt{Make}\mathord{"}}\\\mathop{\mathord{``}\mathtt{Default}\mathord{"}}\end{gathered} \right\}
 539
 540 cabal-version
 541     * Optional field
 542     * Default: ``>=1.0``
 543     * Documentation of :pkg-field:`cabal-version`
 544
 545     .. math::
 546         \mathop{\mathord{``}\mathtt{3\text{.}4}\mathord{"}}
 547
 548 category
 549     * Free text field
 550     * Documentation of :pkg-field:`category`
 551
 552 copyright
 553     * Free text field
 554     * Documentation of :pkg-field:`copyright`
 555
 556 data-dir
 557     * Optional field
 558     * Default: ``.``
 559     * Documentation of :pkg-field:`data-dir`
 560
 561     .. math::
 562         \left\{ \mathop{\mathit{hs\text{-}string}}\mid{{[\mathop{\mathord{``}\mathtt{\ }\mathord{"}}\mathop{\mathord{``}\mathtt{\text{,}}\mathord{"}}]^c}}^+_{} \right\}
 563
 564 data-files
 565     * Monoidal field
 566     * Documentation of :pkg-field:`data-files`
 567
 568     .. math::
 569         \mathrm{commalist}\left\{ \mathop{\mathit{hs\text{-}string}}\mid{{[\mathop{\mathord{``}\mathtt{\ }\mathord{"}}\mathop{\mathord{``}\mathtt{\text{,}}\mathord{"}}]^c}}^+_{} \right\}
 570
 571 description
 572     * Free text field
 573     * Documentation of :pkg-field:`description`
 574
 575 extra-doc-files
 576     * Monoidal field
 577     * Documentation of :pkg-field:`extra-doc-files`
 578
 579     .. math::
 580         \mathrm{commalist}\left\{ \mathop{\mathit{hs\text{-}string}}\mid{{[\mathop{\mathord{``}\mathtt{\ }\mathord{"}}\mathop{\mathord{``}\mathtt{\text{,}}\mathord{"}}]^c}}^+_{} \right\}
 581
 582 extra-source-files
 583     * Monoidal field
 584     * Documentation of :pkg-field:`extra-source-files`
 585
 586     .. math::
 587         \mathrm{commalist}\left\{ \mathop{\mathit{hs\text{-}string}}\mid{{[\mathop{\mathord{``}\mathtt{\ }\mathord{"}}\mathop{\mathord{``}\mathtt{\text{,}}\mathord{"}}]^c}}^+_{} \right\}
 588
 589 extra-tmp-files
 590     * Monoidal field
 591     * Documentation of :pkg-field:`extra-tmp-files`
 592
 593     .. math::
 594         \mathrm{commalist}\left\{ \mathop{\mathit{hs\text{-}string}}\mid{{[\mathop{\mathord{``}\mathtt{\ }\mathord{"}}\mathop{\mathord{``}\mathtt{\text{,}}\mathord{"}}]^c}}^+_{} \right\}
 595
 596 homepage
 597     * Free text field
 598     * Documentation of :pkg-field:`homepage`
 599
 600 license
 601     * Optional field
 602     * Default: ``NONE``
 603     * Documentation of :pkg-field:`license`
 604
 605     .. math::
 606         \mathsf{\color{red}{TODO}}
 607
 608 license-file
 609     * Monoidal field
 610     * Documentation of :pkg-field:`license-file`
 611
 612     .. math::
 613         \left\{ \mathop{\mathit{hs\text{-}string}}\mid{{[\mathop{\mathord{``}\mathtt{\ }\mathord{"}}\mathop{\mathord{``}\mathtt{\text{,}}\mathord{"}}]^c}}^+_{} \right\}
 614
 615 maintainer
 616     * Free text field
 617     * Documentation of :pkg-field:`maintainer`
 618
 619 name
 620     * Required field
 621     * Documentation of :pkg-field:`name`
 622
 623     .. math::
 624         \mathop{\mathit{unqual\text{-}name}}
 625
 626 package-url
 627     * Free text field
 628     * Documentation of :pkg-field:`package-url`
 629
 630 stability
 631     * Free text field
 632     * Documentation of :pkg-field:`stability`
 633
 634 synopsis
 635     * Free text field
 636     * Documentation of :pkg-field:`synopsis`
 637
 638 tested-with
 639     * Monoidal field
 640     * Documentation of :pkg-field:`tested-with`
 641
 642     .. math::
 643         \mathrm{optcommalist}\mathsf{\color{red}{TODO}}
 644
 645 version
 646     * Required field
 647     * Documentation of :pkg-field:`version`
 648
 649     .. math::
 650         {\left\{ \mathop{\mathord{``}\mathtt{0}\mathord{"}}\mid[\mathop{\mathord{``}\mathtt{1}\mathord{"}}\cdots\mathop{\mathord{``}\mathtt{9}\mathord{"}}]{[\mathop{\mathord{``}\mathtt{0}\mathord{"}}\cdots\mathop{\mathord{``}\mathtt{9}\mathord{"}}]}^{\in [0\ldots8]}_{} \right\}}^+_{\mathop{\mathord{``}\mathtt{\text{.}}\mathord{"}}}
 651
 652
 653 Test-suite fields
 654 -----------------
 655
 656 code-generators
 657     * Monoidal field
 658     * Available since ``cabal-version: 3.8``.
 659     * Documentation of :pkg-field:`test-suite:code-generators`
 660
 661     .. math::
 662         \mathrm{commalist}\left\{ \mathop{\mathit{hs\text{-}string}}\mid{{[\mathop{\mathord{``}\mathtt{\ }\mathord{"}}\mathop{\mathord{``}\mathtt{\text{,}}\mathord{"}}]^c}}^+_{} \right\}
 663
 664 main-is
 665     * Optional field
 666     * Documentation of :pkg-field:`test-suite:main-is`
 667
 668     .. math::
 669         \left\{ \mathop{\mathit{hs\text{-}string}}\mid{{[\mathop{\mathord{``}\mathtt{\ }\mathord{"}}\mathop{\mathord{``}\mathtt{\text{,}}\mathord{"}}]^c}}^+_{} \right\}
 670
 671 test-module
 672     * Optional field
 673     * Documentation of :pkg-field:`test-suite:test-module`
 674
 675     .. math::
 676         {\left(\mathop{\mathit{upper}}{\left\{ \mathop{\mathit{alpha\text{-}num}}\mid[\mathop{\mathord{``}\mathtt{\text{'}}\mathord{"}}\mathop{\mathord{``}\mathtt{\text{_}}\mathord{"}}] \right\}}^\ast_{}\right)}^+_{\mathop{\mathord{``}\mathtt{\text{.}}\mathord{"}}}
 677
 678 type
 679     * Optional field
 680     * Documentation of :pkg-field:`test-suite:type`
 681
 682     .. math::
 683         \left\{ \mathop{\mathord{``}\mathtt{exitcode\text{-}stdio\text{-}1\text{.}0}\mathord{"}}\mid\mathop{\mathord{``}\mathtt{detailed\text{-}0\text{.}9}\mathord{"}} \right\}
 684
 685