release-notes/Cabal-3.14.0.0.md

   1 Cabal and Cabal-syntax 3.14.0.0 changelog and release notes
   2 ---
   3
   4
   5 ### Significant changes
   6
   7 - Neutral field to add files to sdist [#8817](https://github.com/haskell/cabal/issues/8817) [#10107](https://github.com/haskell/cabal/pull/10107)
   8
   9   Adds the `extra-files` field to the cabal file specification. This is like
  10   the other `extra-*` fields in that it is copied with the `sdist` command,
  11   except there are no other semantics. Compare to:
  12
  13   * `extra-source-files`: Tracked by `cabal build`.
  14
  15   * `extra-doc-files`: Copied by Haddock to the html directory.
  16
  17 ### Other changes
  18
  19 - Include package version when passing `--promised-dependency` flag [#10166](https://github.com/haskell/cabal/issues/10166) [#10248](https://github.com/haskell/cabal/pull/10248)
  20
  21   The `--promised-dependency` flag now expects an argument in the format
  22
  23   ```
  24   NAME-VER[:COMPONENT_NAME]=CID
  25   ```
  26
  27   rather than
  28
  29   ```
  30   NAME[:COMPONENT_NAME]=CID
  31   ```
  32
  33 - Add support for building profiled dynamic way [#4816](https://github.com/haskell/cabal/issues/4816) [#9900](https://github.com/haskell/cabal/pull/9900)
  34
  35   Add support for profiled dynamic way
  36
  37   New options for `cabal.project` and `./Setup` interface:
  38
  39   * `profiling-shared`: Enable building profiling dynamic way
  40   * Passing `--enable-profiling` and `--enable-executable-dynamic` builds
  41     profiled dynamic executables.
  42
  43   Support for using `profiling-shared` is guarded behind a constraint
  44   which ensures you are using `Cabal >= 3.13`.
  45
  46   In the cabal file:
  47
  48   * `ghc-prof-shared-options`, for passing options when building in
  49     profiling dynamic way
  50
  51 - Working directory support for `Cabal` [#9702](https://github.com/haskell/cabal/issues/9702) [#9718](https://github.com/haskell/cabal/pull/9718)
  52
  53   The `Cabal` library is now able to handle a passed-in working directory, instead
  54   of always relying on the current working directory of the parent process.
  55
  56   In order to achieve this, the `SymbolicPath` abstraction was fleshed out, and
  57   all fields of `PackageDescription` that, if relative, should be interpreted
  58   with respect to e.g. the package root, use `SymbolicPath` instead of `FilePath`.
  59
  60   This means that many library functions in `Cabal` take an extra argument of type
  61   `Maybe (SymbolicPath CWD (Dir "Package"))`, which is an optional (relative or
  62   absolute) path to the package root (if relative, relative to the current working
  63   directory). In addition, many functions that used to manipulate `FilePath`s now
  64   manipulate `SymbolicPath`s, require explicit conversion using e.g. `getSymbolicPath`.
  65
  66   To illustrate with file searching, the `Cabal` library defines:
  67
  68   ```haskell
  69   findFileCwd
  70     :: forall dir1 dir2 file
  71      . Verbosity
  72     -> Maybe (SymbolicPath CWD (Dir dir1))
  73
  74     -> [SymbolicPath dir1 (Dir dir2)]
  75
  76     -> RelativePath dir2 File
  77
  78     -> IO (SymbolicPath dir1 File)
  79   ```
  80
  81   See Note [Symbolic paths] in `Distribution.Utils.Path` for further information
  82   on the design of this API.
  83
  84 - Add `MultilineStrings` extension (GHC proposal #637) [#10245](https://github.com/haskell/cabal/pull/10245)
  85
  86 - Add `NamedDefaults` extension (GHC proposal #409) [#9740](https://github.com/haskell/cabal/pull/9740)
  87
  88 - Add `OrPatterns` extension (GHC proposal #958) [#10339](https://github.com/haskell/cabal/pull/10339)
  89
  90
  91 ### Other changes
  92
  93 - Add flag `--ignore-build-tools` [#10128](https://github.com/haskell/cabal/pull/10128)
  94
  95   - Adds flag `--ignore-build-tools` which allows a user to ignore the tool
  96     dependencies declared in `build-tool-depends`. For general use, this flag
  97     should never be needed, but it may be useful for packagers.
  98
  99 - Do not try to build dynamic executables on Windows [#10217](https://github.com/haskell/cabal/pull/10217)
 100
 101   - Cabal will now exit with a descriptive error message instead of attempting to
 102     build a dynamic executable on Windows.
 103
 104 - Always pass `ghc-options` to GHC [#8717](https://github.com/haskell/cabal/pull/8717)
 105
 106   Previously, options set in the package field `ghc-options` would not be passed
 107   to GHC during the link phase for shared objects (where multiple `.o` or
 108   `.dyn_o` files are merged into a single object file). This made it impossible
 109   to use `ghc-options` to use a different linker by setting (for example)
 110   `ghc-options: -optl-fuse-ld=mold -optlm-fuse-ld=mold`; the options would be
 111   dropped in the link phase, falling back to the default linker.
 112
 113   It was possible to work around this by duplicating the `ghc-options` to
 114   `ghc-shared-options`, which _are_ passed in the shared link phase, but that had
 115   the undocumented and unfortunate side-effect of disabling the GHC
 116   `-dynamic-too` flag, effectively doubling compilation times when
 117   `ghc-shared-options` are set.
 118
 119   Now, `ghc-options` are combined with `ghc-shared-options` (to accurately
 120   reflect the documentation on this feature) and the fact that
 121   `ghc-shared-options` disables `-dynamic-too` is documented.
 122
 123 - Introduce `SetupHooks` [#9551](https://github.com/haskell/cabal/pull/9551)
 124
 125   Introduction of a new build type: `Hooks`.
 126   This build type, intended to eventually replace the `Custom` build type, integrates
 127   better with the rest of the ecosystem (`cabal-install`, Haskell Language Server).
 128
 129   The motivation and full design of this new build-type are specified in the
 130   Haskell Foundation Tech Proposal
 131   [Replacing the Cabal Custom build-type](https://github.com/haskellfoundation/tech-proposals/pull/60).
 132
 133   Package authors willing to use this feature should declare `cabal-version: 3.14` and `build-type: Hooks`
 134   in their `.cabal` file, declare a `custom-setup` stanza with a dependency on the
 135   `Cabal-hooks` package, and define a module `SetupHooks` that exports a value
 136   `setupHooks :: SetupHooks`, using the API exported by `Distribution.Simple.SetupHooks`
 137   from the `Cabal-hooks` package. Refer to the Haddock documentation of
 138   `Distribution.Simple.SetupHooks` for example usage.
 139
 140 - Redefine `build-type: Configure` in terms of `Hooks` [#9969](https://github.com/haskell/cabal/pull/9969)
 141
 142   The `build-type: Configure` is now implemented in terms of `build-type: Hooks`
 143   rather than in terms of `build-type: Custom`. This moves the `Configure`
 144   build-type away from the `Custom` issues. Eventually, `build-type: Hooks` will
 145   no longer imply packages are built in legacy-fallback mode. When that
 146   happens, `Configure` will also stop implying `legacy-fallback`.
 147
 148   The observable aspect of this change is `runConfigureScript` now having a
 149   different type, and `autoconfSetupHooks` being exposed by `Distribution.Simple`.
 150   The former is motivated by internal implementation details, while the latter
 151   provides the `SetupHooks` value for the `Configure` build type, which can be
 152   consumed by other `Hooks` clients (e.g. eventually HLS).
 153
 154 - Cabal can issue a number of error messages referencing "Setup configure",
 155   but it simply references "configure" which could mean any of three
 156   things (Setup configure, the package's "configure" script, or "cabal
 157   configure"). This has recently caught out even Cabal devs. Clarify these
 158   messages. [#9476](https://github.com/haskell/cabal/pull/9476)
 159
 160 - Update the SPDX License List to version 3.25
 161
 162   The LicenseId and LicenseExceptionId types are updated to reflect the SPDX
 163   License List version 3.25 (2024-08-19).