release-notes/Cabal-3.12.0.0.md

   1 Cabal and Cabal-syntax 3.12.0.0 changelog and release notes
   2 ---
   3
   4
   5 ### Significant changes
   6
   7 - Add support for asm, cmm, and js sources in executable components [#8639](https://github.com/haskell/cabal/issues/8639) [#9061](https://github.com/haskell/cabal/pull/9061)
   8
   9     Executable components now support the inclusion of asm, cmm, and js source
  10     files in a cabal file using the same syntax as is used for these sources
  11     in library components, similar to how c and c++ sources are supported in
  12     both types of components. This syntax was already parsed in cabal files,
  13     but was silently ignored in the build step, so no changes to syntax are
  14     made.
  15
  16 - Add `--haddock-output-dir` flag to `cabal haddock`. [#8720](https://github.com/haskell/cabal/issues/8720) [#8788](https://github.com/haskell/cabal/pull/8788)
  17
  18     This flag gives the user full control over the directory where the documentation is placed. It allows both relative and absolute paths.
  19
  20 - Add `--semaphore` option to `./Setup build` interface [#8557](https://github.com/haskell/cabal/pull/8557)
  21
  22     When `./Setup build --semaphore <SEM>` is called, `ghc` will be called
  23     with the `-jsem` option. It is the responsibility of the caller of
  24     `./Setup build` to manage the semaphore according to the GHC Jobserver
  25     Protocol.
  26
  27     This low level interface is intended to be called by a high-level tool
  28     such as `cabal-install` which can create and manage the semaphore
  29     appropriately.
  30
  31     The protocol is specified by [GHC Proposal #540](https://github.com/ghc-proposals/ghc-proposals/blob/master/proposals/0540-jsem.rst).
  32
  33 - Add `--promised-dependency` flag to `./Setup configure` interface [#8726](https://github.com/haskell/cabal/pull/8726)
  34
  35     There is a new flag `--promised-dependency`to allow users to configure a
  36     package *without* having previously built the dependency.  Instead, we
  37     promise to the configure phase that we will have built it by the time we
  38     build the package. This allows us to configure all the packages we intend
  39     to load into the repl without building any dependenices which we will load
  40     in the same session, because the promise is satisifed due to loading the
  41     package and its dependency into one multi-session which ensures the
  42     dependency is built before it is needed.
  43
  44     A user of ./Setup configure specifies a promised dependency by using the
  45     "--promised-dependency" flag with a normal dependency specification. For
  46     example:
  47
  48     ```
  49     '--promised-dependency=cabal-install-solver=cabal-install-solver-3.9.0.0-inplace'
  50     ```
  51
  52 - Add `--ignore` to `cabal check` [#8587](https://github.com/haskell/cabal/issues/8587) [#9442](https://github.com/haskell/cabal/pull/9442)
  53
  54     - `Distribution.PackageDescription.Check.Warning` now exports
  55       `filterPackageChecksById`, this can be used by third-party
  56       tools to filter warnings.
  57
  58 - Add support for `GHC2024` [#9736](https://github.com/haskell/cabal/issues/9736) [#9791](https://github.com/haskell/cabal/pull/9791)
  59
  60   Support for the `GHC2024` language edition, introduced by GHC 9.10, has been
  61   added. It can now be used in the `default-language` and `other-languages`
  62   fields, and will be offered as an option by `cabal init`.
  63
  64 - Remove `initialBuildSteps` from `Distribution.Simple.Build` [#9474](https://github.com/haskell/cabal/pull/9474)
  65
  66   Calling `initialBuildSteps` to prepare source files for a package is error
  67   prone, as `initialBuildSteps` only handles things like the paths module
  68   and nothing else.
  69
  70   To mimick `initialBuildSteps` behaviour when there is no custom Setup, you
  71   can call `repl_setupHooks`.
  72
  73   If you are dealing with a custom setup, you have to invoke
  74   `./Setup repl --repl-multi-file`.
  75
  76 - Cabal and Cabal-syntax 3.12 support GHC version 8.4.4 and up.
  77
  78   Support for all previous GHC versions is deprecated.
  79
  80 - Label error messages with codes (following GHC, Stack)
  81
  82     As with GHC and Stack, Cabal and cabal-install now generate warnings and errors prefixed with error codes of the form `[Cabal-xxxxx]`. These will be documented on https://errors.haskell.org, although very few are as yet.
  83
  84 ### Other changes
  85
  86 - `cabal init` should not suggest Cabal < 2.0 [#8680](https://github.com/haskell/cabal/issues/8680) [#8700](https://github.com/haskell/cabal/pull/8700)
  87
  88     'cabal init' no longer suggests users to set cabal-version to less than
  89     2.0.
  90
  91 - Remove `Distribution.Utils.TempTestDir` module from Cabal library [#9453](https://github.com/haskell/cabal/issues/9453) [#9454](https://github.com/haskell/cabal/pull/9454)
  92
  93     This library was only used by internal tests, and now lives in the
  94     `Cabal-tests` library which is shared across test components.
  95
  96 - PkgConfig individual calls [#9134](https://github.com/haskell/cabal/pull/9134)
  97
  98     `cabal` invokes `pkg-config` individually for each lib if querying for all
  99     doesn't return the expected result.
 100
 101 - Split up `Distribution.Simple.Setup` [#8130](https://github.com/haskell/cabal/pull/8130)
 102
 103   The external interface of 'Distribution.Simple.Setup' has been kept the
 104   same, but internally it has been broken up into smaller modules.  This
 105   improves build times in two ways:
 106
 107     1. GHC is superlinear in the size of files, meaning that splitting up a
 108        large file can reduce overall compile times.
 109     2. Breaking up the module allows dependent modules to refine their imports
 110        to just the parts they require, allowing them to start buildling quicker
 111        when GHC is run in parrallel make mode ('--ghc-options -j').
 112
 113 - Reimplementing `cabal check` [#7423](https://github.com/haskell/cabal/issues/7423) [#8427](https://github.com/haskell/cabal/pull/8427)
 114
 115    - `checkPackage` signature has been simplified,
 116      you do not need to pass a specific configuration of the package, since
 117      we do not flatten `GenericPackageDescription` any more.
 118    - `checkPackageFileNames` has been removed,
 119      use `checkPackageFiles` instead.
 120    - `checkPackageFilesGPD` has been introduced,
 121      a function similar to `checkPackageFiles` that works on
 122      `GenericPackageDescription`. You do not need to use
 123      `flattenPackageDescription` anymore.
 124
 125 - Installation of extra-compilation-artifacts directory [#8662](https://github.com/haskell/cabal/pull/8662)
 126
 127     GHC plugins now can store custom data in the 'extra-compilation-artifacts' directory which gets installed with the package.
 128
 129 - Add option to `./Setup repl` to write repl arguments to file [#8726](https://github.com/haskell/cabal/pull/8726)
 130
 131     The `./Setup repl` command is modified to allow a user to defer starting
 132     the repl and instead instruct the command to write the necessary build
 133     flags to a directiory. The option is called `--repl-multi-file <DIR>`.
 134
 135     This is useful when starting multi-component sessions, as we want to query
 136     Setup.hs for the arguments which are needed to build each component but
 137     not for ./Setup to start the repl itself.
 138
 139 - Add Haiku as a known platform [#9006](https://github.com/haskell/cabal/pull/9006)
 140
 141     Cabal: Distribution now recognises Haiku as a valid platform, and also
 142     implements Haiku's unique directory layout.
 143
 144 - Installation of `.hie` files [#8685](https://github.com/haskell/cabal/issues/8685) [#9019](https://github.com/haskell/cabal/pull/9019)
 145
 146     Hie files generated by GHC are now stored in the
 147     `extra-compilation-artifacts` directory which gets installed with the
 148     package.
 149
 150 - Include the GHC "Project Unit Id" in the cabal store path [#8114](https://github.com/haskell/cabal/issues/8114) [#9326](https://github.com/haskell/cabal/pull/9326)
 151
 152     This allows the use of several **API incompatible builds of the same
 153     version of GHC** without corrupting the cabal store.
 154
 155     This relies on the "Project Unit Id" which is available since GHC 9.8.1,
 156     older versions of GHC do not benefit from this change.
 157
 158 - Fix the platform string for GNU/Hurd [#9434](https://github.com/haskell/cabal/pull/9434)
 159
 160     Depending whom you ask, GNU/Hurd will be labelled "gnu" or "hurd". The
 161     autotools use "gnu", so ghc follows this for installed files, even if the
 162     ghc source code uses OSHurd. We thus need to add the translation between
 163     the two.
 164
 165 - Use linker capability detection to improve linker use [#9443](https://github.com/haskell/cabal/pull/9443)
 166
 167     Previously the GHC version number and platform were used as a proxy for
 168     whether the linker can generate relocatable objects.
 169
 170     Now, the ability of the linker to create relocatable objects is detected.
 171
 172 - Merge globbing implementations [#5349](https://github.com/haskell/cabal/issues/5349) [#9673](https://github.com/haskell/cabal/pull/9673)
 173
 174     The common aspects of the globbing functionality between `Cabal` and
 175     `cabal-install` have been factored out. The only change in the user-facing
 176     API is that we now record when a glob does not match exactly, but matches
 177     a directory with that same name, with the new constructor
 178     `GlobMatchesDirectory` of `GlobResult`.
 179
 180     To illustrate, this change means that when `foo/dir` is a directory, the
 181     glob `*/dir/` matches exactly `foo/dir` (as before), but now `*/dir`
 182     produces `GlobMatchesDirectory` instead of failing.  This allows callers
 183     to decide whether to allow or discard such inexact matches.
 184
 185 - Document `remote-repo-cache` as implemented. [#8737](https://github.com/haskell/cabal/issues/8737) [#8738](https://github.com/haskell/cabal/pull/8738)
 186
 187 - Deduplicate `LD_LIBRARY_PATH` when running tests [#8728](https://github.com/haskell/cabal/pull/8728)
 188
 189 - Add support for a number of architectures:
 190
 191     - RISC-V [#9062](https://github.com/haskell/cabal/pull/9062)
 192     - 64-bit LoongArch [#9215](https://github.com/haskell/cabal/pull/9215)
 193     - 64-bit SPARC as a separate architecture [#9445](https://github.com/haskell/cabal/pull/9445)
 194
 195 - Don't report `index.html` file as created, if not created by Haddock [#5120](https://github.com/haskell/cabal/issues/5120) [#9332](https://github.com/haskell/cabal/pull/9332)
 196
 197 - Enable using `$ORIGIN` in `RPATH` on GNU/Hurd [#9441](https://github.com/haskell/cabal/pull/9441)
 198
 199
 200 - Make check comply with Hackage requirements [#8897](https://github.com/haskell/cabal/pull/8897)
 201
 202   - `cabal check` will only return exitcode 1 when the package is not fit
 203     for Hackage. E.g. it will not error anymore when your `synopsis:` is
 204     larger than `description:`, just emit a warning.
 205   - Cabal: `Distribution.Client.Check` now exports `isHackageDistError`, for
 206     third-party tools to know if a specific error will preclude a package
 207     from being uploaded to Hacakge.
 208
 209 - Add language extension `ExtendedLiterals` (GHC proposal #451) [#8992](https://github.com/haskell/cabal/pull/8992)
 210
 211 - Warn about inconsistent indentation [#8975](https://github.com/haskell/cabal/pull/8975)
 212
 213     - Make Cabal warn about inconsistent indentation in .cabal files. For
 214       example warn about somewhat common decreasing indentation like in
 215
 216     ```cabal
 217     library
 218     default-language: Haskell2010
 219     build-depends: base
 220     ghc-options: -Wall
 221     ```
 222
 223     The change is `readFields` function.
 224
 225     This is an effect of using `indentOfAtLeast` method/approach: any
 226     indentation greater than current offset is accepted.
 227
 228     That behavior is desirable to parsing multiline field contents, but it is
 229     a bit surprising for fields in sections, which we expect to be aligned.
 230
 231     Such insonsistency seems to be always a mistake, and it's easy to fix once
 232     a machine points it out.
 233
 234 - Add `LexBraces` lexer warning [#8577](https://github.com/haskell/cabal/issues/8577)
 235
 236     `LexBraces` warning is issued when brace delimiting syntax is used.  This
 237     way, using `readFields'`, a low-lever consumer may decide whether braces
 238     were used.
 239
 240     Looking for a brace character in the input is imprecise, as braces can
 241     occur inside field content.
 242
 243     This warning is not propagated to parser warnings, so e.g.
 244     `readGenericPackageDescription` doesn't warn about it.  This is because all
 245     parser warnings prevent uploads to Hackage, and using braces (or not) is
 246     a matter of opinion.
 247
 248 - Distinguish `powerpc64le`, by adding `PPC64LE` constructor to type `Arch` [#9534](https://github.com/haskell/cabal/issues/9534) [#9535](https://github.com/haskell/cabal/pull/9535)
 249
 250     Adds constructor `PPC64LE` to type `Arch` to distinguish architecture
 251     powerpc64le from powerpc64. Existing constructor `PPC64` now exclusively
 252     represents powerpc64.
 253
 254 - PkgConfig individual calls [#9134](https://github.com/haskell/cabal/pull/9134)
 255
 256     `cabal` invokes `pkg-config` individually for each lib if querying for all doesn't return the expected result
 257
 258 - Add language extension `ListTuplePuns` (GHC proposal #475) [#8854](https://github.com/haskell/cabal/pull/8854)
 259
 260 - Add `mkVersionIntervals` for creating a `VersionIntervals` from a list [#9034](https://github.com/haskell/cabal/pull/9034)
 261
 262     If external tools want to change the version intervals of dependencies, they
 263     need to be able to create a `VersionRange` from a `[VersionInterval]` list. Adding
 264     the function `mkVersionIntervals` makes this possible again.
 265
 266 - Add language extension `TypeAbstractions` [#9496](https://github.com/haskell/cabal/issues/9496) [#9502](https://github.com/haskell/cabal/pull/9502)
 267
 268 - Update SPDX License List to version `3.23 2024-02-08` [#9818](https://github.com/haskell/cabal/pull/9818)
 269
 270   - LicenseId and LicenseExceptionId now conform to SPDX License List
 271     version 3.23 2024-02-08.