release-notes/cabal-install-3.12.1.0.md

   1 cabal-install 3.12.1.0 changelog and release notes.
   2 ---
   3
   4 ### Significant changes
   5
   6 - Cabal 3.12 support [#9917](https://github.com/haskell/cabal/issues/9917)
   7
   8     This is the first release of `cabal-install` that is fully compatible with `Cabal` 3.12.0.0 as released with GHC 9.10.1. In particular, it means custom setup builds will work with GHC 9.10.
   9
  10 - `cabal-install` has been built against `tar` 0.6.3.0 [#10123](https://github.com/haskell/cabal/pull/10123)
  11
  12     The new release of `tar` has significant performance improvements, making `cabal update` in particular much faster.
  13
  14     For anyone building from the source, we suggest making sure that the version of `tar` in your plan is at least 0.6.3.0. (For example, we bumped the `index-state` in our `cabal.project.release` in the `Cabal` repository.)
  15
  16 - 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)
  17
  18     Executable components now support the inclusion of asm, cmm, and js source
  19     files in a cabal file using the same syntax as is used for these sources
  20     in library components, similar to how c and c++ sources are supported in
  21     both types of components. This syntax was already parsed in cabal files,
  22     but was silently ignored in the build step, so no changes to syntax are
  23     made.
  24
  25 - Add `--project-dir` flag [#7695](https://github.com/haskell/cabal/issues/7695) [#7940](https://github.com/haskell/cabal/issues/7940) [#8454](https://github.com/haskell/cabal/pull/8454)
  26
  27     - Added `--project-dir` flag for specifying the project's root directory
  28     - Deprecated using `--project-file` with an absolute filepath without also using `--project-dir`.
  29
  30 - Support per-component builds when coverage is enabled [#4798](https://github.com/haskell/cabal/issues/4798) [#5213](https://github.com/haskell/cabal/issues/5213) [#6397](https://github.com/haskell/cabal/issues/6397) [#6440](https://github.com/haskell/cabal/issues/6440) [#9464](https://github.com/haskell/cabal/pull/9464)
  31
  32     Cabal now supports per-component builds when coverage is enabled.This enables
  33     coverage for packages with internal libraries (#6440), and enables coverage for
  34     packages that use backpack (#6397), even though we do not get coverage for
  35     instantiations of an indefinite module (it is not clear what it means for HPC
  36     to support backpack, regardless of Cabal).
  37
  38     To achieve this, hpc information (`.mix` files) from a library is now written
  39     into the package database of a library under `extraCompilationArtifacts`.
  40
  41     Cabal configure (via the Setup interface) now accepts --coverage-for=<unit-id>,
  42     a flag which specifies which libraries should be included in the coverage
  43     report for some testsuite.
  44
  45 - Add `cabal path` command [#8879](https://github.com/haskell/cabal/pull/8879) [#9673](https://github.com/haskell/cabal/pull/9673)
  46
  47     The `cabal path` command prints the file system paths used by Cabal.
  48     It is intended for use by tooling that needs to read or modify Cabal
  49     data, such that it does not need to replicate the complicated logic
  50     for respecting `CABAL_DIR`, `CABAL_CONFIG`, etc.
  51
  52     It will obey a `cabal.project` if present.
  53
  54   Additionally, we add support for multiple output formats, such as key-value pairs and json.
  55
  56   The key-value pair output prints a line for each queried key and its respective value:
  57
  58       key1: value2
  59       key2: value2
  60
  61   If only a single key is queried, we print only the value, for example:
  62
  63       value1
  64
  65   The json output format is versioned by the cabal-install version, which is part of the json object.
  66   Thus, all result objects contain at least the key "cabal-install-version".
  67
  68   It also produces information of the compiler that is going to be used in a `cabal build` or `cabal repl` invocation.
  69   To do that, we re-configure the compiler program, and outputs the location, version and compiler flavour.
  70   This is helpful for downstream tools, such as HLS, to figure out the GHC version required to compile a project with, without dependency solving.
  71
  72 - Add support for authentication tokens for uploading to Hackage [#6738](https://github.com/haskell/cabal/issues/6738) [#9058](https://github.com/haskell/cabal/pull/9058)
  73
  74     A new flag `--token` (`-t`) has been created. Token authentication takes
  75     precedence over username and password meaning that, if a token is set,
  76     the username and password flags are ignored.
  77
  78 - Make --(test-)show-details=direct the default [#8942](https://github.com/haskell/cabal/pull/8942)
  79
  80     This option leaves it up to the testing framework to decide what and how to print out,
  81     potentially leading to a prettier output. For example, most of the testing frameworks
  82     use colors, which wouldn't be seen with any other option.
  83
  84     This comes with a tradeoff, though: Cabal will not create a log file with this option.
  85     If you prefer a log file, consider setting `--test-show-details=streaming` (or something
  86     else) manually.
  87
  88 - Die if package list is missing [#8944](https://github.com/haskell/cabal/pull/8944)
  89
  90     If a package list is missing, `cabal` will now die and suggest the user to run
  91     `cabal update` instead of continuing into not being able to find packages coming
  92     from the remote package server.
  93
  94 - Reject index-state younger than cached index file [#8944](https://github.com/haskell/cabal/pull/8944)
  95
  96     Requesting to use an index-state younger than the cached version will now fail,
  97     telling the user to use an index-state older or equal to the cached file, or to
  98     run `cabal update`.
  99
 100     The warning for a non-existing index-state has been also demoted to appear only
 101     on verbose logging.
 102
 103 - Warn early that overwrite policy is needed [#5993](https://github.com/haskell/cabal/issues/5993) [#9268](https://github.com/haskell/cabal/pull/9268)
 104
 105     Waiting for a long build and then seeing the install fail because a flag was
 106     missing is frustrating.With this change we skip the wait and warn early,
 107     before the build, that an overwrite policy flag would be needed for the
 108     install to succeed.
 109
 110 - Make sure Haskell files in explicit source directories take precedence over autogenerated Haskell files [#8689](https://github.com/haskell/cabal/issues/8689) [#8690](https://github.com/haskell/cabal/pull/8690)
 111
 112     - Changed order or directories in GHC invocation so that source
 113     directories explicitly specified in cabal file will be considered
 114     before Cabal’s internal build directory.
 115
 116 - config file: allow more flags in the init section [#8835](https://github.com/haskell/cabal/issues/8835) [#8839](https://github.com/haskell/cabal/pull/8839)
 117
 118     The init section of config file now allows the following fields:
 119
 120 - Fix handling of ETag header for remote packages [#9113](https://github.com/haskell/cabal/issues/9113) [#9116](https://github.com/haskell/cabal/pull/9116)
 121
 122     Remote packages will now be cached regardless of the capitalization of the
 123     "ETag" header. Previously remote packages would not be cached if the header
 124     name did not match exactly. Now they will be cached even if the header's
 125     capitalization is different.
 126
 127 - Clarify the semantics of the `--package-db` flag [#9678](https://github.com/haskell/cabal/issues/9678) [#9683](https://github.com/haskell/cabal/pull/9683)
 128
 129     The `--package-db` flag now only applies to the default
 130     immutable initial package stack rather than also applying to the store
 131     package database.
 132
 133     This fixes an assertion failure which was triggered when using `--package-db` and also
 134     clarifies how it should interact with `--store-dir` and `--dist-dir` flags.
 135
 136 - Add `--semaphore` flag to enable interaction with GHC Job Server protocol [#8557](https://github.com/haskell/cabal/pull/8557)
 137
 138     When cabal-install is passed the `--semaphore` flag it will now act as a job server
 139     according to the GHC Jobserver Protocol.
 140
 141     In particular this means that cabal-install will create a semaphore which it then
 142     passes to `./Setup build` (and hence `ghc`) which can be used by `ghc` in order to
 143     control how much paralellism it uses, coordinating with other simultaneously running
 144     processes.
 145
 146     This feature requires ghc-9.8 in order to use, as this is the first version of GHC
 147     which implements the protocol.
 148
 149 - Add `--ignore` to `cabal check` [#8587](https://github.com/haskell/cabal/issues/8587) [#9442](https://github.com/haskell/cabal/pull/9442)
 150
 151     - `cabal check` now ignores specific warnings with `--ignore`. E.g.
 152       `--ignore=missing-upper-bounds` will not display “Missing upper
 153       bounds” warnings.
 154     - `cabal check` output now prints the warning identifier too
 155       (like `[no-category]`).
 156
 157 - Adds functionality for the --offline flag with the "build" command. [#8676](https://github.com/haskell/cabal/pull/8676)
 158
 159     The --offline flag previously created in #2578 but was only implemented
 160     for the install command even thought the flag didn't throw an error
 161     whenever the build command was run. This PR adds functionality for the
 162     --offline flag with the build command.  Additionally there is a new
 163     PackageTest for the flag using the build command.
 164
 165 - Add warning for running cabal run, cabal test and cabal bench with +RTS flag [#8709](https://github.com/haskell/cabal/pull/8709)
 166
 167     This adds a warning when RTS options are passed to cabal instead of the
 168     binary for the commands 'run', 'bench' and 'test', as most users want to
 169     pass these options to their binary.
 170
 171 - Add support for loading multiple components into one repl session [#8238](https://github.com/haskell/cabal/pull/8238) [#8491](https://github.com/haskell/cabal/pull/8491) [#8726](https://github.com/haskell/cabal/pull/8726)
 172
 173     The `repl` command is extended in order to allow starting a repl session
 174     with multiple local components. When a user specifies a target to the
 175     "repl" command which resolves to multiple local components then `cabal`
 176     will start a repl session which loads them all into a single GHC session
 177     if the multi-repl is enabled.
 178
 179     The multi-repl can be enabled by passing `--enable-multi-repl`, or writing
 180     `multi-repl: True` in your cabal.project file.
 181
 182     The feature is fully explained in [this blog
 183     post](https://well-typed.com/blog/2023/03/cabal-multi-unit/).
 184
 185 - Warn when project configuration options are going to be ignored. [#8949](https://github.com/haskell/cabal/pull/8949)
 186
 187     Some project configuration options can only be specified from the command
 188     line.  If the user specified those options from a project file,
 189     cabal-install would silently ignore them. Now cabal-install will emit a
 190     warning.
 191
 192 - Fix precedence for PATH for `build-tools-depends` [#8972](https://github.com/haskell/cabal/pull/8972)
 193
 194     Fixes a bug introduced in #8506 that caused executables in the path to
 195     take precedence over those specified in `build-tools-depends`.
 196
 197 - Guard `PackageInfo_*` modules behind `cabal-version` ≥ 3.12 [#9331](https://github.com/haskell/cabal/issues/9331) [#9481](https://github.com/haskell/cabal/pull/9481)
 198
 199     `cabal check` now warns whenever `PackageInfo_*` autogen modules are
 200     used with `cabal-version` ≥ 3.12.
 201     Additionally, `cabal configure` will fail if you try to use `PackageInfo_*`
 202     with `cabal-version` < 3.12.
 203
 204 - cabal init now generates cabal versions older than 1.12 with the correct >= syntax [#8206](https://github.com/haskell/cabal/issues/8206) [#8860](https://github.com/haskell/cabal/pull/8860)
 205
 206 - `cabal init`: suggest BSD-3 as default license [#8757](https://github.com/haskell/cabal/issues/8757) [#8764](https://github.com/haskell/cabal/pull/8764)
 207
 208 - Do not ask overwrite permissions on blank project [#9150](https://github.com/haskell/cabal/issues/9150) [#9155](https://github.com/haskell/cabal/pull/9155)
 209
 210 - Shorten solver rejection messages by removing repetition [#4251](https://github.com/haskell/cabal/issues/4251) [#9559](https://github.com/haskell/cabal/issues/9559) [#9560](https://github.com/haskell/cabal/pull/9560)
 211
 212     As before, we show a single rejection as hyphenated package-version.
 213
 214     For multiple rejections, we show a list of versions preceded by package
 215     semicolon, a much shorter rendering of the same information.
 216
 217     ```diff
 218     - [__0] rejecting: pandoc-3.1.8, pandoc-3.1.7, pandoc-3.1.6.2, pandoc-3.1.6.1,
 219     - pandoc-3.1.6, pandoc-3.1.5, pandoc-3.1.4, pandoc-3.1.3, pandoc-3.1.2,
 220     - pandoc-3.1.1, pandoc-3.1, pandoc-3.0.1, pandoc-3.0, pandoc-2.19.2,
 221     - pandoc-2.19.1, pandoc-2.19, pandoc-2.18, pandoc-2.17.1.1, pandoc-2.17.1,
 222     + [__0] rejecting: pandoc; 3.1.8, 3.1.7, 3.1.6.2, 3.1.6.1, 3.1.6, 3.1.5, 3.1.4,
 223     + 3.1.3, 3.1.2, 3.1.1, 3.1, 3.0.1, 3.0, 2.19.2, 2.19.1, 2.19, 2.18, 2.17.1.1,
 224     ```
 225
 226 - Show provenance of project constraints [#9562](https://github.com/haskell/cabal/issues/9562) [#9578](https://github.com/haskell/cabal/pull/9578)
 227
 228   Show imports when the solver rejects a package version due to a project
 229   constraint.  Even though imports are relative to their parent when imported,
 230   their paths are shown relative to the directory of the project in the solver
 231   output.
 232
 233   ```
 234   $ cabal build all --dry-run
 235   ...
 236   [__1] next goal: hashable
 237   [__1] rejecting: hashable-1.4.3.0
 238         (constraint from cabal.project requires ==1.4.2.0)
 239   [__1] rejecting: hashable-1.4.2.0
 240         (constraint from project-stackage/nightly-2023-12-07.config requires ==1.4.3.0)
 241           imported by: cabal.project
 242   ```
 243
 244   Fixes some test failures detecting cycles in imports, when;
 245
 246   - the wrong import was reported as starting the cycle
 247   - a cycle was reported that wasn't actually a cycle
 248
 249 - Adjust BSD-2-Clause and BSD-3-Clause licence text [#9812](https://github.com/haskell/cabal/issues/9812) [#9813](https://github.com/haskell/cabal/pull/9813)
 250
 251   This change matters to BSD-2-Clause and BSD-3-Clause licences. For these two
 252   licences, `cabal init` created a licence file that slightly differed from
 253   wording published at SPDX.  This has been rectified.
 254
 255 - 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)
 256
 257     This allows the use of several **API incompatible builds of the same
 258     version of GHC** without corrupting the cabal store.
 259
 260     This relies on the "Project Unit Id" which is available since GHC 9.8.1,
 261     older versions of GHC do not benefit from this change.
 262
 263 - Add support for `GHC2024` [#9736](https://github.com/haskell/cabal/issues/9736) [#9791](https://github.com/haskell/cabal/pull/9791)
 264
 265   Support for the `GHC2024` language edition, introduced by GHC 9.10, has been
 266   added. It can now be used in the `default-language` and `other-languages`
 267   fields, and will be offered as an option by `cabal init`.
 268
 269 - Add language extension `ExtendedLiterals` [#8992](https://github.com/haskell/cabal/pull/8992)
 270
 271     Adds support for the `ExtendedLiterals` language extension (GHC proposal #451)
 272
 273 - Add language extension `ListTuplePuns` [#8854](https://github.com/haskell/cabal/pull/8854)
 274
 275     Adds support for the `ListTuplePuns` language extension (GHC proposal #475)
 276
 277 - Add language extension `TypeAbstractions` [#9496](https://github.com/haskell/cabal/issues/9496) [#9502](https://github.com/haskell/cabal/pull/9502)
 278
 279 - Label error messages with codes (following GHC, Stack)
 280
 281     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.
 282
 283 - The `--offline` flag applied to `source-repository-package`s [#9641](https://github.com/haskell/cabal/issues/9641) [#9771](https://github.com/haskell/cabal/pull/9771)
 284
 285   The `--offline` flag is already used to block access to Hackage. Now with this PR, this also applies to remote dependency `source-repository-package` in `cabal.project`.
 286
 287 - Fix `--program-suffix` resulting in invalid installation [#8823](https://github.com/haskell/cabal/issues/8823) [#9919](https://github.com/haskell/cabal/issues/9919) [#10056](https://github.com/haskell/cabal/pull/10056)
 288
 289     Formerly, using `--program-suffix` resulted in bad symlinks into the store. This has been corrected.
 290
 291 - Warn on missing `default-language` [#9620](https://github.com/haskell/cabal/issues/9620) [#9766](https://github.com/haskell/cabal/pull/9766)
 292
 293   - To help the adoption of GHC language editions, `cabal check` will now
 294     warn about missing `default-language`.
 295
 296 ### Other changes
 297
 298 - Script cache dir is the base16 hash of the canonical path of the script. [#9459](https://github.com/haskell/cabal/pull/9459)
 299
 300     This fixes sporadic path failures on both Windows and Linux (e.g. [#9334](https://github.com/haskell/cabal/issues/9334)).
 301
 302 - Add `--haddock-output-dir` flag to `cabal haddock`. [#8720](https://github.com/haskell/cabal/issues/8720) [#8788](https://github.com/haskell/cabal/pull/8788)
 303
 304   This flag gives the user full control over the directory where the documentation is placed. It allows both relative and absolute paths.
 305
 306 - Remove useles "Log" log level [#9151](https://github.com/haskell/cabal/issues/9151) [#9346](https://github.com/haskell/cabal/pull/9346)
 307
 308     - Remove "Log" as a log level in favour of "Info".
 309     - Remove "Show" in Severity and replace by "displaySeverity" function
 310
 311 - `cabal init` should not suggest Cabal < 2.0 [#8680](https://github.com/haskell/cabal/issues/8680)
 312
 313     'cabal init' no longer suggests users to set cabal-version to less than
 314     2.0.
 315
 316 - PkgConfig individual calls [#9134](https://github.com/haskell/cabal/pull/9134)
 317
 318     `cabal` invokes `pkg-config` individually for each lib if querying for all
 319     doesn't return the expected result.
 320
 321 - Reimplementing `cabal check` [#7423](https://github.com/haskell/cabal/issues/7423) [#8427](https://github.com/haskell/cabal/pull/8427)
 322
 323   - For `cabal-install` users: `cabal check` do not warn on -O2 or similar
 324     options if under an off-by-default cabal flag.
 325
 326 - `cabal check`: clearly mark Errors [#8908](https://github.com/haskell/cabal/pull/8908)
 327
 328     `cabal check` will now mark errors (which make the program return 1 and
 329     Hackage refuse the package) by prepending them with an "Error: " string in
 330     the output.
 331
 332 - 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)
 333
 334 - Make check comply with Hackage requirements [#8897](https://github.com/haskell/cabal/pull/8897)
 335
 336   - `cabal check` will only return exitcode 1 when the package is not fit
 337     for Hackage. E.g. it will not error anymore when your `synopsis:` is
 338     larger than `description:`, just emit a warning.
 339   - Cabal: Distribution.Client.Check now exports `isHackageDistError`, for
 340     third-party tools to know if a specific error will preclude a package
 341     from being uploaded to Hacakge.
 342
 343 - Also render short options with arguments [#8785](https://github.com/haskell/cabal/issues/8785) [#9043](https://github.com/haskell/cabal/pull/9043)
 344
 345     Show how arguments are used with both short and long forms of options:
 346
 347     ```diff
 348     <-v, --verbose[=n]Control verbosity (n is 0--3, default
 349     >-v[n], --verbose[=n] Control verbosity (n is 0--3, default
 350     <-w, --with-compiler=PATH give the path to a particular compiler
 351     >-w PATH or -wPATH, --with-compiler=PATH
 352     ```
 353
 354 - Remove `--cabal-file` flags from v2 commands [#6880](https://github.com/haskell/cabal/issues/6880) [#7225](https://github.com/haskell/cabal/issues/7225) [#8395](https://github.com/haskell/cabal/issues/8395) [#9123](https://github.com/haskell/cabal/pull/9123)
 355
 356     The `--cabal-file` flag was never meant for public use but only for testing.
 357     To avoid confusing the users any further we removed the flag from v2
 358     commands.
 359
 360 - Avoid a double space in "Executing install plan ..." [#9376](https://github.com/haskell/cabal/pull/9376)
 361
 362     The "Executing·install·plan··serially" and other similar "Executing
 363     install plan··..." outputs no longer contain double spaces.
 364
 365 - Allow whitespace in targets [#8875](https://github.com/haskell/cabal/issues/8875) [#10032](https://github.com/haskell/cabal/pull/10032)
 366
 367   Allow spaces in the final component of target selectors. This resolves an issue
 368   where using absolute paths in selectors can fail if there is whitespace in the
 369   parent directories of the project.
 370
 371 - Renders project configuration provenance as a list of canonical paths [#9971](https://github.com/haskell/cabal/issues/9971) [#9985](https://github.com/haskell/cabal/pull/9985)
 372
 373   Removes interleaved rendering of project imports.
 374
 375 - Abbreviate solver rejection messages with installed versions [#9823](https://github.com/haskell/cabal/issues/9823) [#9824](https://github.com/haskell/cabal/pull/9824)
 376
 377 - solver: Prevent `ghc-internal` from being reinstalled [#10108](https://github.com/haskell/cabal/pull/10108)
 378
 379     GHC 9.10 ships with a new wired-in package, `ghc-internal`, which cannot be reinstalled. This commit prevents cabal-install from attempting it.