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:`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:`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:`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:`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:`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:`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:`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:`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:`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:`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:`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:`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:`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:`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:`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:`default-language`
 291
 292     .. math::
 293         \left\{ \mathop{\mathord{``}\mathtt{Haskell98}\mathord{"}}\mid\mathop{\mathord{``}\mathtt{Haskell2010}\mathord{"}} \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:`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:`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:`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:`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:`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     * Documentation of :pkg-field:`extra-lib-dirs-static`
 342
 343     .. math::
 344         \mathrm{optcommalist}\left\{ \mathop{\mathit{hs\text{-}string}}\mid{{[\mathop{\mathord{``}\mathtt{\ }\mathord{"}}\mathop{\mathord{``}\mathtt{\text{,}}\mathord{"}}]^c}}^+_{} \right\}
 345
 346 extra-libraries
 347     * Monoidal field
 348     * Documentation of :pkg-field:`extra-libraries`
 349
 350     .. math::
 351         \mathrm{commalist}\left\{ \mathop{\mathit{hs\text{-}string}}\mid{{[\mathop{\mathord{``}\mathtt{\ }\mathord{"}}\mathop{\mathord{``}\mathtt{\text{,}}\mathord{"}}]^c}}^+_{} \right\}
 352
 353 extra-library-flavours
 354     * Monoidal field
 355     * Documentation of :pkg-field:`extra-library-flavours`
 356
 357     .. math::
 358         \mathrm{commalist}\left\{ \mathop{\mathit{hs\text{-}string}}\mid{{[\mathop{\mathord{``}\mathtt{\ }\mathord{"}}\mathop{\mathord{``}\mathtt{\text{,}}\mathord{"}}]^c}}^+_{} \right\}
 359
 360 extra-libraries
 361     * Monoidal field
 362     * Documentation of :pkg-field:`extra-libraries-static`
 363
 364     .. math::
 365         \mathrm{commalist}\left\{ \mathop{\mathit{hs\text{-}string}}\mid{{[\mathop{\mathord{``}\mathtt{\ }\mathord{"}}\mathop{\mathord{``}\mathtt{\text{,}}\mathord{"}}]^c}}^+_{} \right\}
 366
 367 frameworks
 368     * Monoidal field
 369     * Documentation of :pkg-field:`frameworks`
 370
 371     .. math::
 372         \mathrm{optcommalist}\left\{ \mathop{\mathit{hs\text{-}string}}\mid{{[\mathop{\mathord{``}\mathtt{\ }\mathord{"}}\mathop{\mathord{``}\mathtt{\text{,}}\mathord{"}}]^c}}^+_{} \right\}
 373
 374 ghc-options
 375     * Monoidal field
 376     * Documentation of :pkg-field:`ghc-options`
 377
 378     .. math::
 379         {\left\{ \mathop{\mathit{hs\text{-}string}}\mid{{[\mathop{\mathord{``}\mathtt{\ }\mathord{"}}]^c}}^+_{} \right\}}^\ast_{\bullet}
 380
 381 ghc-prof-options
 382     * Monoidal field
 383     * Documentation of :pkg-field:`ghc-prof-options`
 384
 385     .. math::
 386         {\left\{ \mathop{\mathit{hs\text{-}string}}\mid{{[\mathop{\mathord{``}\mathtt{\ }\mathord{"}}]^c}}^+_{} \right\}}^\ast_{\bullet}
 387
 388 ghc-shared-options
 389     * Monoidal field
 390     * Documentation of :pkg-field:`ghc-shared-options`
 391
 392     .. math::
 393         {\left\{ \mathop{\mathit{hs\text{-}string}}\mid{{[\mathop{\mathord{``}\mathtt{\ }\mathord{"}}]^c}}^+_{} \right\}}^\ast_{\bullet}
 394
 395 ghcjs-options
 396     * Monoidal field
 397     * Documentation of :pkg-field:`ghcjs-options`
 398
 399     .. math::
 400         {\left\{ \mathop{\mathit{hs\text{-}string}}\mid{{[\mathop{\mathord{``}\mathtt{\ }\mathord{"}}]^c}}^+_{} \right\}}^\ast_{\bullet}
 401
 402 ghcjs-prof-options
 403     * Monoidal field
 404     * Documentation of :pkg-field:`ghcjs-prof-options`
 405
 406     .. math::
 407         {\left\{ \mathop{\mathit{hs\text{-}string}}\mid{{[\mathop{\mathord{``}\mathtt{\ }\mathord{"}}]^c}}^+_{} \right\}}^\ast_{\bullet}
 408
 409 ghcjs-shared-options
 410     * Monoidal field
 411     * Documentation of :pkg-field:`ghcjs-shared-options`
 412
 413     .. math::
 414         {\left\{ \mathop{\mathit{hs\text{-}string}}\mid{{[\mathop{\mathord{``}\mathtt{\ }\mathord{"}}]^c}}^+_{} \right\}}^\ast_{\bullet}
 415
 416 hs-source-dir
 417     * Monoidal field
 418     * Deprecated since ``cabal-version: 1.2``: Please use 'hs-source-dirs'
 419     * Removed in ``cabal-version: 3.0``: Please use 'hs-source-dirs' field.
 420
 421     .. math::
 422         \mathrm{optcommalist}\left\{ \mathop{\mathit{hs\text{-}string}}\mid{{[\mathop{\mathord{``}\mathtt{\ }\mathord{"}}\mathop{\mathord{``}\mathtt{\text{,}}\mathord{"}}]^c}}^+_{} \right\}
 423
 424 hs-source-dirs
 425     * Monoidal field
 426     * Documentation of :pkg-field:`hs-source-dirs`
 427
 428     .. math::
 429         \mathrm{optcommalist}\left\{ \mathop{\mathit{hs\text{-}string}}\mid{{[\mathop{\mathord{``}\mathtt{\ }\mathord{"}}\mathop{\mathord{``}\mathtt{\text{,}}\mathord{"}}]^c}}^+_{} \right\}
 430
 431 include-dirs
 432     * Monoidal field
 433     * Documentation of :pkg-field:`include-dirs`
 434
 435     .. math::
 436         \mathrm{optcommalist}\left\{ \mathop{\mathit{hs\text{-}string}}\mid{{[\mathop{\mathord{``}\mathtt{\ }\mathord{"}}\mathop{\mathord{``}\mathtt{\text{,}}\mathord{"}}]^c}}^+_{} \right\}
 437
 438 includes
 439     * Monoidal field
 440     * Documentation of :pkg-field:`includes`
 441
 442     .. math::
 443         \mathrm{optcommalist}\left\{ \mathop{\mathit{hs\text{-}string}}\mid{{[\mathop{\mathord{``}\mathtt{\ }\mathord{"}}\mathop{\mathord{``}\mathtt{\text{,}}\mathord{"}}]^c}}^+_{} \right\}
 444
 445 install-includes
 446     * Monoidal field
 447     * Documentation of :pkg-field:`install-includes`
 448
 449     .. math::
 450         \mathrm{optcommalist}\left\{ \mathop{\mathit{hs\text{-}string}}\mid{{[\mathop{\mathord{``}\mathtt{\ }\mathord{"}}\mathop{\mathord{``}\mathtt{\text{,}}\mathord{"}}]^c}}^+_{} \right\}
 451
 452 js-sources
 453     * Monoidal field
 454     * Documentation of :pkg-field:`js-sources`
 455
 456     .. math::
 457         \mathrm{commalist}\left\{ \mathop{\mathit{hs\text{-}string}}\mid{{[\mathop{\mathord{``}\mathtt{\ }\mathord{"}}\mathop{\mathord{``}\mathtt{\text{,}}\mathord{"}}]^c}}^+_{} \right\}
 458
 459 ld-options
 460     * Monoidal field
 461     * Documentation of :pkg-field:`ld-options`
 462
 463     .. math::
 464         {\left\{ \mathop{\mathit{hs\text{-}string}}\mid{{[\mathop{\mathord{``}\mathtt{\ }\mathord{"}}]^c}}^+_{} \right\}}^\ast_{\bullet}
 465
 466 mixins
 467     * Monoidal field
 468     * Available since ``cabal-version: 2.0``.
 469     * Documentation of :pkg-field:`mixins`
 470
 471     .. math::
 472         \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)
 473
 474 other-extensions
 475     * Monoidal field
 476     * Available since ``cabal-version: 1.10``.
 477     * Documentation of :pkg-field:`other-extensions`
 478
 479     .. math::
 480         \mathrm{optcommalist}\mathsf{\color{red}{TODO}}
 481
 482 other-languages
 483     * Monoidal field
 484     * Available since ``cabal-version: 1.10``.
 485     * Documentation of :pkg-field:`other-languages`
 486
 487     .. math::
 488         \mathrm{optcommalist}\left\{ \mathop{\mathord{``}\mathtt{Haskell98}\mathord{"}}\mid\mathop{\mathord{``}\mathtt{Haskell2010}\mathord{"}} \right\}
 489
 490 other-modules
 491     * Monoidal field
 492     * Documentation of :pkg-field:`other-modules`
 493
 494     .. math::
 495         \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)
 496
 497 pkgconfig-depends
 498     * Monoidal field
 499     * Documentation of :pkg-field:`pkgconfig-depends`
 500
 501     .. math::
 502         \mathrm{commalist}\mathsf{\color{red}{TODO}}
 503
 504 virtual-modules
 505     * Monoidal field
 506     * Available since ``cabal-version: 2.2``.
 507     * Documentation of :pkg-field:`virtual-modules`
 508
 509     .. math::
 510         \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)
 511
 512
 513 Library fields
 514 --------------
 515
 516 visibility
 517     * Optional field
 518     * Documentation of :pkg-field:`library:visibility`
 519
 520     .. math::
 521         \left\{ \mathop{\mathord{``}\mathtt{public}\mathord{"}}\mid\mathop{\mathord{``}\mathtt{private}\mathord{"}} \right\}
 522
 523
 524 Package description fields
 525 --------------------------
 526
 527 author
 528     * Free text field
 529     * Documentation of :pkg-field:`author`
 530
 531 bug-reports
 532     * Free text field
 533     * Documentation of :pkg-field:`bug-reports`
 534
 535 build-type
 536     * Optional field
 537     * Documentation of :pkg-field:`build-type`
 538
 539     .. math::
 540         \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\}
 541
 542 cabal-version
 543     * Optional field
 544     * Default: ``>=1.0``
 545     * Documentation of :pkg-field:`cabal-version`
 546
 547     .. math::
 548         \mathop{\mathord{``}\mathtt{3\text{.}4}\mathord{"}}
 549
 550 category
 551     * Free text field
 552     * Documentation of :pkg-field:`category`
 553
 554 copyright
 555     * Free text field
 556     * Documentation of :pkg-field:`copyright`
 557
 558 data-dir
 559     * Optional field
 560     * Default: ``""``
 561     * Documentation of :pkg-field:`data-dir`
 562
 563     .. math::
 564         \left\{ \mathop{\mathit{hs\text{-}string}}\mid{{[\mathop{\mathord{``}\mathtt{\ }\mathord{"}}\mathop{\mathord{``}\mathtt{\text{,}}\mathord{"}}]^c}}^+_{} \right\}
 565
 566 data-files
 567     * Monoidal field
 568     * Documentation of :pkg-field:`data-files`
 569
 570     .. math::
 571         \mathrm{commalist}\left\{ \mathop{\mathit{hs\text{-}string}}\mid{{[\mathop{\mathord{``}\mathtt{\ }\mathord{"}}\mathop{\mathord{``}\mathtt{\text{,}}\mathord{"}}]^c}}^+_{} \right\}
 572
 573 description
 574     * Free text field
 575     * Documentation of :pkg-field:`description`
 576
 577 extra-doc-files
 578     * Monoidal field
 579     * Documentation of :pkg-field:`extra-doc-files`
 580
 581     .. math::
 582         \mathrm{commalist}\left\{ \mathop{\mathit{hs\text{-}string}}\mid{{[\mathop{\mathord{``}\mathtt{\ }\mathord{"}}\mathop{\mathord{``}\mathtt{\text{,}}\mathord{"}}]^c}}^+_{} \right\}
 583
 584 extra-source-files
 585     * Monoidal field
 586     * Documentation of :pkg-field:`extra-source-files`
 587
 588     .. math::
 589         \mathrm{commalist}\left\{ \mathop{\mathit{hs\text{-}string}}\mid{{[\mathop{\mathord{``}\mathtt{\ }\mathord{"}}\mathop{\mathord{``}\mathtt{\text{,}}\mathord{"}}]^c}}^+_{} \right\}
 590
 591 extra-tmp-files
 592     * Monoidal field
 593     * Documentation of :pkg-field:`extra-tmp-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 homepage
 599     * Free text field
 600     * Documentation of :pkg-field:`homepage`
 601
 602 license
 603     * Optional field
 604     * Default: ``NONE``
 605     * Documentation of :pkg-field:`license`
 606
 607     .. math::
 608         \mathsf{\color{red}{TODO}}
 609
 610 license-file
 611     * Monoidal field
 612     * Documentation of :pkg-field:`license-file`
 613
 614     .. math::
 615         \mathrm{optcommalist}\left\{ \mathop{\mathit{hs\text{-}string}}\mid{{[\mathop{\mathord{``}\mathtt{\ }\mathord{"}}\mathop{\mathord{``}\mathtt{\text{,}}\mathord{"}}]^c}}^+_{} \right\}
 616
 617 maintainer
 618     * Free text field
 619     * Documentation of :pkg-field:`maintainer`
 620
 621 name
 622     * Required field
 623     * Documentation of :pkg-field:`name`
 624
 625     .. math::
 626         \mathop{\mathit{unqual\text{-}name}}
 627
 628 package-url
 629     * Free text field
 630     * Documentation of :pkg-field:`package-url`
 631
 632 stability
 633     * Free text field
 634     * Documentation of :pkg-field:`stability`
 635
 636 synopsis
 637     * Free text field
 638     * Documentation of :pkg-field:`synopsis`
 639
 640 tested-with
 641     * Monoidal field
 642     * Documentation of :pkg-field:`tested-with`
 643
 644     .. math::
 645         \mathrm{optcommalist}\mathsf{\color{red}{TODO}}
 646
 647 version
 648     * Required field
 649     * Documentation of :pkg-field:`version`
 650
 651     .. math::
 652         {\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{"}}}
 653
 654
 655 Test-suite fields
 656 -----------------
 657
 658 main-is
 659     * Optional field
 660     * Documentation of :pkg-field:`test-suite:main-is`
 661
 662     .. math::
 663         \left\{ \mathop{\mathit{hs\text{-}string}}\mid{{[\mathop{\mathord{``}\mathtt{\ }\mathord{"}}\mathop{\mathord{``}\mathtt{\text{,}}\mathord{"}}]^c}}^+_{} \right\}
 664
 665 test-module
 666     * Optional field
 667     * Documentation of :pkg-field:`test-suite:test-module`
 668
 669     .. math::
 670         {\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{"}}}
 671
 672 type
 673     * Optional field
 674     * Documentation of :pkg-field:`test-suite:type`
 675
 676     .. math::
 677         \left\{ \mathop{\mathord{``}\mathtt{exitcode\text{-}stdio\text{-}1\text{.}0}\mathord{"}}\mid\mathop{\mathord{``}\mathtt{detailed\text{-}0\text{.}9}\mathord{"}} \right\}