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 - Installing a library with a Custom setup no longer requires building the executable [#9777](https://github.com/haskell/cabal/issues/9777) [#9650](https://github.com/haskell/cabal/pull/9650) [#10311](https://github.com/haskell/cabal/pull/10311)
  87
  88   For example, if we have `pkg-a.cabal`:
  89
  90   ```
  91   library
  92      build-depends: pkg-b
  93   ```
  94
  95   and `pkg-b.cabal`:
  96
  97   ```
  98   library
  99       exposed-modules: ...
 100
 101   executable pkg-b-exe
 102      main-is: ...
 103   ```
 104
 105
 106   An invocation `cabal build pkg-a` will build `lib:pkg-a` and `lib:pkg-b`, but
 107   not `exe:pkg-b-exe` because it is not needed for building `pkg-a`! Previously the executable would be built unnecessarily.
 108
 109   If the invocation were `cabal build pkg-a exe:pkg-b-exe` then all `lib:pkg-a`, `lib:pkg-b`, and `exe:pkg-b-exe` would be built.
 110
 111   Note: There may be a package whose Custom setup expects the executable to be
 112   built together with the library always. Unfortunately, this is a breaking
 113   change for them. To migrate, packages should no longer assume the executable is
 114   built when only the library is requested (e.g. `cabal install --lib Agda` will
 115   *not* build the `Agda` executable, while `cabal install Agda` will).
 116
 117   Agda is an example of a package which expected in its `Setup.hs` copy hook the
 118   executable to already be built. This was fixed by inspecting the copy arguments
 119   and making sure we only use the executable when it is built, since it is only
 120   needed when the executable too is needed.
 121
 122 - `cabal init` should not suggest Cabal < 2.0 [#8680](https://github.com/haskell/cabal/issues/8680) [#8700](https://github.com/haskell/cabal/pull/8700)
 123
 124     'cabal init' no longer suggests users to set cabal-version to less than
 125     2.0.
 126
 127 - Remove `Distribution.Utils.TempTestDir` module from Cabal library [#9453](https://github.com/haskell/cabal/issues/9453) [#9454](https://github.com/haskell/cabal/pull/9454)
 128
 129     This library was only used by internal tests, and now lives in the
 130     `Cabal-tests` library which is shared across test components.
 131
 132 - PkgConfig individual calls [#9134](https://github.com/haskell/cabal/pull/9134)
 133
 134     `cabal` invokes `pkg-config` individually for each lib if querying for all
 135     doesn't return the expected result.
 136
 137 - Split up `Distribution.Simple.Setup` [#8130](https://github.com/haskell/cabal/pull/8130)
 138
 139   The external interface of 'Distribution.Simple.Setup' has been kept the
 140   same, but internally it has been broken up into smaller modules.  This
 141   improves build times in two ways:
 142
 143     1. GHC is superlinear in the size of files, meaning that splitting up a
 144        large file can reduce overall compile times.
 145     2. Breaking up the module allows dependent modules to refine their imports
 146        to just the parts they require, allowing them to start buildling quicker
 147        when GHC is run in parrallel make mode ('--ghc-options -j').
 148
 149 - Reimplementing `cabal check` [#7423](https://github.com/haskell/cabal/issues/7423) [#8427](https://github.com/haskell/cabal/pull/8427)
 150
 151    - `checkPackage` signature has been simplified,
 152      you do not need to pass a specific configuration of the package, since
 153      we do not flatten `GenericPackageDescription` any more.
 154    - `checkPackageFileNames` has been removed,
 155      use `checkPackageFiles` instead.
 156    - `checkPackageFilesGPD` has been introduced,
 157      a function similar to `checkPackageFiles` that works on
 158      `GenericPackageDescription`. You do not need to use
 159      `flattenPackageDescription` anymore.
 160
 161 - Installation of extra-compilation-artifacts directory [#8662](https://github.com/haskell/cabal/pull/8662)
 162
 163     GHC plugins now can store custom data in the 'extra-compilation-artifacts' directory which gets installed with the package.
 164
 165 - Add option to `./Setup repl` to write repl arguments to file [#8726](https://github.com/haskell/cabal/pull/8726)
 166
 167     The `./Setup repl` command is modified to allow a user to defer starting
 168     the repl and instead instruct the command to write the necessary build
 169     flags to a directiory. The option is called `--repl-multi-file <DIR>`.
 170
 171     This is useful when starting multi-component sessions, as we want to query
 172     Setup.hs for the arguments which are needed to build each component but
 173     not for ./Setup to start the repl itself.
 174
 175 - Add Haiku as a known platform [#9006](https://github.com/haskell/cabal/pull/9006)
 176
 177     Cabal: Distribution now recognises Haiku as a valid platform, and also
 178     implements Haiku's unique directory layout.
 179
 180 - Installation of `.hie` files [#8685](https://github.com/haskell/cabal/issues/8685) [#9019](https://github.com/haskell/cabal/pull/9019)
 181
 182     Hie files generated by GHC are now stored in the
 183     `extra-compilation-artifacts` directory which gets installed with the
 184     package.
 185
 186 - 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)
 187
 188     This allows the use of several **API incompatible builds of the same
 189     version of GHC** without corrupting the cabal store.
 190
 191     This relies on the "Project Unit Id" which is available since GHC 9.8.1,
 192     older versions of GHC do not benefit from this change.
 193
 194 - Fix the platform string for GNU/Hurd [#9434](https://github.com/haskell/cabal/pull/9434)
 195
 196     Depending whom you ask, GNU/Hurd will be labelled "gnu" or "hurd". The
 197     autotools use "gnu", so ghc follows this for installed files, even if the
 198     ghc source code uses OSHurd. We thus need to add the translation between
 199     the two.
 200
 201 - Use linker capability detection to improve linker use [#9443](https://github.com/haskell/cabal/pull/9443)
 202
 203     Previously the GHC version number and platform were used as a proxy for
 204     whether the linker can generate relocatable objects.
 205
 206     Now, the ability of the linker to create relocatable objects is detected.
 207
 208 - Merge globbing implementations [#5349](https://github.com/haskell/cabal/issues/5349) [#9673](https://github.com/haskell/cabal/pull/9673)
 209
 210     The common aspects of the globbing functionality between `Cabal` and
 211     `cabal-install` have been factored out. The only change in the user-facing
 212     API is that we now record when a glob does not match exactly, but matches
 213     a directory with that same name, with the new constructor
 214     `GlobMatchesDirectory` of `GlobResult`.
 215
 216     To illustrate, this change means that when `foo/dir` is a directory, the
 217     glob `*/dir/` matches exactly `foo/dir` (as before), but now `*/dir`
 218     produces `GlobMatchesDirectory` instead of failing.  This allows callers
 219     to decide whether to allow or discard such inexact matches.
 220
 221 - Document `remote-repo-cache` as implemented. [#8737](https://github.com/haskell/cabal/issues/8737) [#8738](https://github.com/haskell/cabal/pull/8738)
 222
 223 - Deduplicate `LD_LIBRARY_PATH` when running tests [#8728](https://github.com/haskell/cabal/pull/8728)
 224
 225 - Add support for a number of architectures:
 226
 227     - RISC-V [#9062](https://github.com/haskell/cabal/pull/9062)
 228     - 64-bit LoongArch [#9215](https://github.com/haskell/cabal/pull/9215)
 229     - 64-bit SPARC as a separate architecture [#9445](https://github.com/haskell/cabal/pull/9445)
 230
 231 - 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)
 232
 233 - Enable using `$ORIGIN` in `RPATH` on GNU/Hurd [#9441](https://github.com/haskell/cabal/pull/9441)
 234
 235
 236 - Make check comply with Hackage requirements [#8897](https://github.com/haskell/cabal/pull/8897)
 237
 238   - `cabal check` will only return exitcode 1 when the package is not fit
 239     for Hackage. E.g. it will not error anymore when your `synopsis:` is
 240     larger than `description:`, just emit a warning.
 241   - Cabal: `Distribution.Client.Check` now exports `isHackageDistError`, for
 242     third-party tools to know if a specific error will preclude a package
 243     from being uploaded to Hacakge.
 244
 245 - Add language extension `ExtendedLiterals` (GHC proposal #451) [#8992](https://github.com/haskell/cabal/pull/8992)
 246
 247 - Warn about inconsistent indentation [#8975](https://github.com/haskell/cabal/pull/8975)
 248
 249     - Make Cabal warn about inconsistent indentation in .cabal files. For
 250       example warn about somewhat common decreasing indentation like in
 251
 252     ```cabal
 253     library
 254     default-language: Haskell2010
 255     build-depends: base
 256     ghc-options: -Wall
 257     ```
 258
 259     The change is `readFields` function.
 260
 261     This is an effect of using `indentOfAtLeast` method/approach: any
 262     indentation greater than current offset is accepted.
 263
 264     That behavior is desirable to parsing multiline field contents, but it is
 265     a bit surprising for fields in sections, which we expect to be aligned.
 266
 267     Such insonsistency seems to be always a mistake, and it's easy to fix once
 268     a machine points it out.
 269
 270 - Add `LexBraces` lexer warning [#8577](https://github.com/haskell/cabal/issues/8577)
 271
 272     `LexBraces` warning is issued when brace delimiting syntax is used.  This
 273     way, using `readFields'`, a low-lever consumer may decide whether braces
 274     were used.
 275
 276     Looking for a brace character in the input is imprecise, as braces can
 277     occur inside field content.
 278
 279     This warning is not propagated to parser warnings, so e.g.
 280     `readGenericPackageDescription` doesn't warn about it.  This is because all
 281     parser warnings prevent uploads to Hackage, and using braces (or not) is
 282     a matter of opinion.
 283
 284 - 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)
 285
 286     Adds constructor `PPC64LE` to type `Arch` to distinguish architecture
 287     powerpc64le from powerpc64. Existing constructor `PPC64` now exclusively
 288     represents powerpc64.
 289
 290 - PkgConfig individual calls [#9134](https://github.com/haskell/cabal/pull/9134)
 291
 292     `cabal` invokes `pkg-config` individually for each lib if querying for all doesn't return the expected result
 293
 294 - Add language extension `ListTuplePuns` (GHC proposal #475) [#8854](https://github.com/haskell/cabal/pull/8854)
 295
 296 - Add `mkVersionIntervals` for creating a `VersionIntervals` from a list [#9034](https://github.com/haskell/cabal/pull/9034)
 297
 298     If external tools want to change the version intervals of dependencies, they
 299     need to be able to create a `VersionRange` from a `[VersionInterval]` list. Adding
 300     the function `mkVersionIntervals` makes this possible again.
 301
 302 - Add language extension `TypeAbstractions` [#9496](https://github.com/haskell/cabal/issues/9496) [#9502](https://github.com/haskell/cabal/pull/9502)
 303
 304 - Update SPDX License List to version `3.23 2024-02-08` [#9818](https://github.com/haskell/cabal/pull/9818)
 305
 306   - LicenseId and LicenseExceptionId now conform to SPDX License List
 307     version 3.23 2024-02-08.