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-prof-shared-options
 391     * Monoidal field
 392     * Available since ``cabal-version: 3.14``.
 393     * Documentation of :pkg-field:`library:ghc-prof-shared-options`
 394
 395     .. math::
 396         {\left\{ \mathop{\mathit{hs\text{-}string}}\mid{{[\mathop{\mathord{``}\mathtt{\ }\mathord{"}}]^c}}^+_{} \right\}}^\ast_{\bullet}
 397
 398 ghc-shared-options
 399     * Monoidal field
 400     * Documentation of :pkg-field:`library:ghc-shared-options`
 401
 402     .. math::
 403         {\left\{ \mathop{\mathit{hs\text{-}string}}\mid{{[\mathop{\mathord{``}\mathtt{\ }\mathord{"}}]^c}}^+_{} \right\}}^\ast_{\bullet}
 404
 405 ghcjs-options
 406     * Monoidal field
 407     * Documentation of :pkg-field:`library:ghcjs-options`
 408
 409     .. math::
 410         {\left\{ \mathop{\mathit{hs\text{-}string}}\mid{{[\mathop{\mathord{``}\mathtt{\ }\mathord{"}}]^c}}^+_{} \right\}}^\ast_{\bullet}
 411
 412 ghcjs-prof-options
 413     * Monoidal field
 414     * Documentation of :pkg-field:`library:ghcjs-prof-options`
 415
 416     .. math::
 417         {\left\{ \mathop{\mathit{hs\text{-}string}}\mid{{[\mathop{\mathord{``}\mathtt{\ }\mathord{"}}]^c}}^+_{} \right\}}^\ast_{\bullet}
 418
 419 ghcjs-prof-shared-options
 420     * Monoidal field
 421     * Available since ``cabal-version: 3.14``.
 422     * Documentation of :pkg-field:`library:ghcjs-prof-shared-options`
 423
 424     .. math::
 425         {\left\{ \mathop{\mathit{hs\text{-}string}}\mid{{[\mathop{\mathord{``}\mathtt{\ }\mathord{"}}]^c}}^+_{} \right\}}^\ast_{\bullet}
 426
 427 ghcjs-shared-options
 428     * Monoidal field
 429     * Documentation of :pkg-field:`library:ghcjs-shared-options`
 430
 431     .. math::
 432         {\left\{ \mathop{\mathit{hs\text{-}string}}\mid{{[\mathop{\mathord{``}\mathtt{\ }\mathord{"}}]^c}}^+_{} \right\}}^\ast_{\bullet}
 433
 434 hs-source-dir
 435     * Monoidal field
 436     * Deprecated since ``cabal-version: 1.2``: Please use 'hs-source-dirs'
 437     * Removed in ``cabal-version: 3.0``: Please use 'hs-source-dirs' field.
 438
 439     .. math::
 440         \mathrm{optcommalist}\left\{ \mathop{\mathit{hs\text{-}string}}\mid{{[\mathop{\mathord{``}\mathtt{\ }\mathord{"}}\mathop{\mathord{``}\mathtt{\text{,}}\mathord{"}}]^c}}^+_{} \right\}
 441
 442 hs-source-dirs
 443     * Monoidal field
 444     * Documentation of :pkg-field:`library:hs-source-dirs`
 445
 446     .. math::
 447         \mathrm{optcommalist}\left\{ \mathop{\mathit{hs\text{-}string}}\mid{{[\mathop{\mathord{``}\mathtt{\ }\mathord{"}}\mathop{\mathord{``}\mathtt{\text{,}}\mathord{"}}]^c}}^+_{} \right\}
 448
 449 hsc2hs-options
 450     * Monoidal field
 451     * Available since ``cabal-version: 3.6``.
 452     * Documentation of :pkg-field:`library:hsc2hs-options`
 453
 454     .. math::
 455         {\left\{ \mathop{\mathit{hs\text{-}string}}\mid{{[\mathop{\mathord{``}\mathtt{\ }\mathord{"}}]^c}}^+_{} \right\}}^\ast_{\bullet}
 456
 457 include-dirs
 458     * Monoidal field
 459     * Documentation of :pkg-field:`library:include-dirs`
 460
 461     .. math::
 462         \mathrm{optcommalist}\left\{ \mathop{\mathit{hs\text{-}string}}\mid{{[\mathop{\mathord{``}\mathtt{\ }\mathord{"}}\mathop{\mathord{``}\mathtt{\text{,}}\mathord{"}}]^c}}^+_{} \right\}
 463
 464 includes
 465     * Monoidal field
 466     * Documentation of :pkg-field:`library:includes`
 467
 468     .. math::
 469         \mathrm{optcommalist}\left\{ \mathop{\mathit{hs\text{-}string}}\mid{{[\mathop{\mathord{``}\mathtt{\ }\mathord{"}}\mathop{\mathord{``}\mathtt{\text{,}}\mathord{"}}]^c}}^+_{} \right\}
 470
 471 install-includes
 472     * Monoidal field
 473     * Documentation of :pkg-field:`library:install-includes`
 474
 475     .. math::
 476         \mathrm{optcommalist}\left\{ \mathop{\mathit{hs\text{-}string}}\mid{{[\mathop{\mathord{``}\mathtt{\ }\mathord{"}}\mathop{\mathord{``}\mathtt{\text{,}}\mathord{"}}]^c}}^+_{} \right\}
 477
 478 js-sources
 479     * Monoidal field
 480     * Documentation of :pkg-field:`library:js-sources`
 481
 482     .. math::
 483         \mathrm{commalist}\left\{ \mathop{\mathit{hs\text{-}string}}\mid{{[\mathop{\mathord{``}\mathtt{\ }\mathord{"}}\mathop{\mathord{``}\mathtt{\text{,}}\mathord{"}}]^c}}^+_{} \right\}
 484
 485 ld-options
 486     * Monoidal field
 487     * Documentation of :pkg-field:`library:ld-options`
 488
 489     .. math::
 490         {\left\{ \mathop{\mathit{hs\text{-}string}}\mid{{[\mathop{\mathord{``}\mathtt{\ }\mathord{"}}]^c}}^+_{} \right\}}^\ast_{\bullet}
 491
 492 mixins
 493     * Monoidal field
 494     * Available since ``cabal-version: 2.0``.
 495     * Documentation of :pkg-field:`library:mixins`
 496
 497     .. math::
 498         \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)
 499
 500 other-extensions
 501     * Monoidal field
 502     * Documentation of :pkg-field:`library:other-extensions`
 503
 504     .. math::
 505         \mathrm{optcommalist}\mathsf{\color{red}{TODO}}
 506
 507 other-languages
 508     * Monoidal field
 509     * Available since ``cabal-version: 1.10``.
 510     * Documentation of :pkg-field:`library:other-languages`
 511
 512     .. math::
 513         \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\}
 514
 515 other-modules
 516     * Monoidal field
 517     * Documentation of :pkg-field:`library:other-modules`
 518
 519     .. math::
 520         \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)
 521
 522 pkgconfig-depends
 523     * Monoidal field
 524     * Documentation of :pkg-field:`library:pkgconfig-depends`
 525
 526     .. math::
 527         \mathrm{commalist}\mathsf{\color{red}{TODO}}
 528
 529 virtual-modules
 530     * Monoidal field
 531     * Available since ``cabal-version: 2.2``.
 532     * Documentation of :pkg-field:`library:virtual-modules`
 533
 534     .. math::
 535         \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)
 536
 537
 538 Package description fields
 539 --------------------------
 540
 541 author
 542     * Free text field
 543     * Documentation of :pkg-field:`author`
 544
 545 bug-reports
 546     * Free text field
 547     * Documentation of :pkg-field:`bug-reports`
 548
 549 build-type
 550     * Optional field
 551     * Documentation of :pkg-field:`build-type`
 552
 553     .. math::
 554         \left\{ \begin{gathered}\mathop{\mathord{``}\mathtt{Simple}\mathord{"}}\\\mathop{\mathord{``}\mathtt{Configure}\mathord{"}}\\\mathop{\mathord{``}\mathtt{Custom}\mathord{"}}\\\mathop{\mathord{``}\mathtt{Hooks}\mathord{"}}\\\mathop{\mathord{``}\mathtt{Make}\mathord{"}}\\\mathop{\mathord{``}\mathtt{Default}\mathord{"}}\end{gathered} \right\}
 555
 556 cabal-version
 557     * Optional field
 558     * Default: ``>=1.0``
 559     * Documentation of :pkg-field:`cabal-version`
 560
 561     .. math::
 562         \mathop{\mathord{``}\mathtt{3\text{.}4}\mathord{"}}
 563
 564 category
 565     * Free text field
 566     * Documentation of :pkg-field:`category`
 567
 568 copyright
 569     * Free text field
 570     * Documentation of :pkg-field:`copyright`
 571
 572 data-dir
 573     * Optional field
 574     * Default: ``.``
 575     * Documentation of :pkg-field:`data-dir`
 576
 577     .. math::
 578         \left\{ \mathop{\mathit{hs\text{-}string}}\mid{{[\mathop{\mathord{``}\mathtt{\ }\mathord{"}}\mathop{\mathord{``}\mathtt{\text{,}}\mathord{"}}]^c}}^+_{} \right\}
 579
 580 data-files
 581     * Monoidal field
 582     * Documentation of :pkg-field:`data-files`
 583
 584     .. math::
 585         \mathrm{commalist}\left\{ \mathop{\mathit{hs\text{-}string}}\mid{{[\mathop{\mathord{``}\mathtt{\ }\mathord{"}}\mathop{\mathord{``}\mathtt{\text{,}}\mathord{"}}]^c}}^+_{} \right\}
 586
 587 description
 588     * Free text field
 589     * Documentation of :pkg-field:`description`
 590
 591 extra-doc-files
 592     * Monoidal field
 593     * Documentation of :pkg-field:`extra-doc-files`
 594
 595     .. math::
 596         \mathrm{commalist}\left\{ \mathop{\mathit{hs\text{-}string}}\mid{{[\mathop{\mathord{``}\mathtt{\ }\mathord{"}}\mathop{\mathord{``}\mathtt{\text{,}}\mathord{"}}]^c}}^+_{} \right\}
 597
 598 extra-files
 599     * Monoidal field
 600     * Available since ``cabal-version: 3.14``.
 601     * Documentation of :pkg-field:`extra-files`
 602
 603     .. math::
 604         \mathrm{commalist}\left\{ \mathop{\mathit{hs\text{-}string}}\mid{{[\mathop{\mathord{``}\mathtt{\ }\mathord{"}}\mathop{\mathord{``}\mathtt{\text{,}}\mathord{"}}]^c}}^+_{} \right\}
 605
 606 extra-source-files
 607     * Monoidal field
 608     * Documentation of :pkg-field:`extra-source-files`
 609
 610     .. math::
 611         \mathrm{commalist}\left\{ \mathop{\mathit{hs\text{-}string}}\mid{{[\mathop{\mathord{``}\mathtt{\ }\mathord{"}}\mathop{\mathord{``}\mathtt{\text{,}}\mathord{"}}]^c}}^+_{} \right\}
 612
 613 extra-tmp-files
 614     * Monoidal field
 615     * Documentation of :pkg-field:`extra-tmp-files`
 616
 617     .. math::
 618         \mathrm{commalist}\left\{ \mathop{\mathit{hs\text{-}string}}\mid{{[\mathop{\mathord{``}\mathtt{\ }\mathord{"}}\mathop{\mathord{``}\mathtt{\text{,}}\mathord{"}}]^c}}^+_{} \right\}
 619
 620 homepage
 621     * Free text field
 622     * Documentation of :pkg-field:`homepage`
 623
 624 license
 625     * Optional field
 626     * Default: ``NONE``
 627     * Documentation of :pkg-field:`license`
 628
 629     .. math::
 630         \mathsf{\color{red}{TODO}}
 631
 632 license-file
 633     * Monoidal field
 634     * Documentation of :pkg-field:`license-file`
 635
 636     .. math::
 637         \left\{ \mathop{\mathit{hs\text{-}string}}\mid{{[\mathop{\mathord{``}\mathtt{\ }\mathord{"}}\mathop{\mathord{``}\mathtt{\text{,}}\mathord{"}}]^c}}^+_{} \right\}
 638
 639 maintainer
 640     * Free text field
 641     * Documentation of :pkg-field:`maintainer`
 642
 643 name
 644     * Required field
 645     * Documentation of :pkg-field:`name`
 646
 647     .. math::
 648         \mathop{\mathit{unqual\text{-}name}}
 649
 650 package-url
 651     * Free text field
 652     * Documentation of :pkg-field:`package-url`
 653
 654 stability
 655     * Free text field
 656     * Documentation of :pkg-field:`stability`
 657
 658 synopsis
 659     * Free text field
 660     * Documentation of :pkg-field:`synopsis`
 661
 662 tested-with
 663     * Monoidal field
 664     * Documentation of :pkg-field:`tested-with`
 665
 666     .. math::
 667         \mathrm{optcommalist}\mathsf{\color{red}{TODO}}
 668
 669 version
 670     * Required field
 671     * Documentation of :pkg-field:`version`
 672
 673     .. math::
 674         {\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{"}}}
 675
 676
 677 Test-suite fields
 678 -----------------
 679
 680 code-generators
 681     * Monoidal field
 682     * Available since ``cabal-version: 3.8``.
 683     * Documentation of :pkg-field:`test-suite:code-generators`
 684
 685     .. math::
 686         \mathrm{commalist}\left\{ \mathop{\mathit{hs\text{-}string}}\mid{{[\mathop{\mathord{``}\mathtt{\ }\mathord{"}}\mathop{\mathord{``}\mathtt{\text{,}}\mathord{"}}]^c}}^+_{} \right\}
 687
 688 main-is
 689     * Optional field
 690     * Documentation of :pkg-field:`test-suite:main-is`
 691
 692     .. math::
 693         \left\{ \mathop{\mathit{hs\text{-}string}}\mid{{[\mathop{\mathord{``}\mathtt{\ }\mathord{"}}\mathop{\mathord{``}\mathtt{\text{,}}\mathord{"}}]^c}}^+_{} \right\}
 694
 695 test-module
 696     * Optional field
 697     * Documentation of :pkg-field:`test-suite:test-module`
 698
 699     .. math::
 700         {\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{"}}}
 701
 702 type
 703     * Optional field
 704     * Documentation of :pkg-field:`test-suite:type`
 705
 706     .. math::
 707         \left\{ \mathop{\mathord{``}\mathtt{exitcode\text{-}stdio\text{-}1\text{.}0}\mathord{"}}\mid\mathop{\mathord{``}\mathtt{detailed\text{-}0\text{.}9}\mathord{"}} \right\}
 708
 709