release-notes/WIP-cabal-install-3.12.x.0.md

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