cabal-install and cabal-install-solver 3.10.1.0 changelog and release notes

Release 3.10.1.0 of cabal now sets the --enable-documentation option by default when running cabal haddock (https://github.com/haskell/cabal/issues/7462). If the new default does not fit your workflow, pass an explicit --disable-documentation option or consider (helping to implement) the other workarounds proposed in https://github.com/haskell/cabal/issues/8725.

This version of cabal introduces support for JS cross-compilation (https://github.com/haskell/cabal/pull/8636). We've seen related Windows segfaults on CI, so please kindly report if you can reproduce either cabal or GHC segfaults when cross-compiling for JS or compiling normally but with any files listed in the js-sources field of a .cabal file.

This release of cabal also fixes a lot of bugs in cabal 3.8.1.0 and not all of the fixes are listed here.

Significant changes

• Cabal-3.10.1.0 is used, which brings its own set of changes, many of which are significant. The Cabal and Cabal-syntax changes that touch the cabal-install or cabal-install-solver codebases are pasted here again in full.

• Add support for the XDG Base Directory Specification #680 #7386

  Cabal/cabal-install now uses the XDG Base Directory Specification to store configuration, caches, and the store. Specifically, $XDG_CONFIG_HOME/cabal stores the configuration file, $XDG_CACHE_HOME/cabal stores downloaded packages and similar, and $XDG_STATE_HOME/cabal mainly contains the store of compiled packages. Further, cabal install will put executables in ~/.local/bin by default.

  The dist/dist-newstyle directories are not affected.

  On Windows, these XDG paths are mapped to other (hopefully) appropriate locations. See the Cabal User Guide for information.

  If the CABAL_DIR environment variable is set, the indicated directory will be used to store all Cabal-related files, as in previous versions.

  Backwards compatibility: If ~/.cabal already exists, this will be interpreted as CABAL_DIR=~/.cabal. This means that upgrading on an existing system already using cabal-install should not cause any change in behaviour. An existing system can be migrated by deleting ~/.cabal (possibly copying ~/.cabal/config to ~/.config/cabal/config first).

• Add installDirs (datadir, etc) to v2-build and remove them from v2-install #8556

  • Passes through --prefix, --datadir and other installdir-arguments properly in v2-build, allowing its use in preparing somewhat more relocatable compilation targets (no worse than v1-build).
  • Removes these flags (which never worked) from v2-install

• No global packages auto written to environment files, allow --force-reinstalls #5559 #6165 #8607

  • When v2-install runs on a library, it does not pin global packages in the env file, only those directly necessary for the library.

• Add support for GHC 9.4+ -fprof-late flag #8528

  • This adds the new late-toplevel (and its alias late) profiling-detail option which enables -fprof-late-based automatic cost centre annotations for GHCs that support it (earliest is GHC 9.4.1).

• Added haddock-project command #7669 #8162

  The haddock-project command can be used to build documentation of multiple packages. By passing --local option the directory will be self contained, by passing --hackage links to dependencies will link to hackage. Both --local and --hackage options imply --quickfix, --gen-index, --gen-contents, and --hyperlinked-source.

  Building self contained directory is the default, unless --hackage or --html-location.

  The PR #8162 also fixes the --with-haddock option.

Other changes

• Pretty-print run targets on failure #8189 #8234

  • Targets of the run command are pretty-printed when failing due to multiple targets.
  • Duplicate targets are removed in the output.

• Expose BuildFlags and ClientHaddockFlags #8351 #8353

  Some types are present in public functions in cabal-install, but they are not exported. This PR fix it for BuildFlags and ClientHaddockFlags.

• cabal man handles $PAGER containing arguments now #8405 #8353

  Things like PAGER="less -FX" cabal man work now.

  There's a slight change in the default behavior. We still use less -R as the default, but if the user passes PAGER=less, we won't add -R to that, unlike before. This is reasonable, as the user should be able to set the variable as they see fit.

• Fix issue with "nix" config option #8452 #8522

  Nix option in config file was broken with #8054, this should fix it.

• "Build profile" message now reflects optimization level set in global config #8487 #8488

  Imagine you have optimization: 2 in your ~/.cabal/config, and you call cabal build in a project that doesn't have optimization level explicitly set in its project file. You will still see 'Build profile: -w ghc- -O1'. This is incorrect and was fixed in this patch: now you'll see '-O2'.

• ghc, ghc-boot, ghci packages should be non-upgradable #8489 #8501

  • Changed both Distribution.Client.Dependency's dontUpgradeNonUpgradeablePackages and Distribution.Solver.Modular.Solver's nonInstallable to be in sync.

• Apply command line flags to install packages #8637 #8779

  • Command line flags usually only apply to "local" packages (packages specified in the cabal.project). This change causes the v2-install command to ignore that distinction to better match the expected behavior for packages specified directly in the command.

• Print a warning when assertions are enabled #4377 #8240

  • Now cabal-install executable will print a warning if assertions are enabled

• Implement --prefer-oldest #8261

  • The new flag makes Cabal solver try to find a build plan with the oldest versions possible. This is useful to establish lower bounds.

• Update and sdist now only check for compiler when project file has conditionals #8352 #8550 #8589 #8358 #8627

  • Cabal update and sdist will not require a ghc in path unless the project has conditionals that require it

• Allow offline bootstrapping of cabal-install #8368

  • The bootstrap script for cabal-install now supports fetching the sources of the dependencies in a separate step. One can then copy over the resulting archive and perform offline bootstrapping of cabal-install.

• Pass some haddock flags to dependencies #395 #8104 #8414

  • Pass --haddock-hoogle, --haddock-html, --haddock-internal, --haddock-quickjump, --haddock-hyperlinked-source to all the dependencies if they are specified as command line args

• build pkgconfig db individually when bulk fails #8494 #8496

  • When pkg-config fails to get versions for all packages in bulk, falls back to querying one-by-one.

• improve install target handling logic regarding of project files #8094 #8352 #8498

  • fixes an issue where cabal install pkg-x.y.z fails unless --ignore-project is given
  • fixes an issue where cabal install --ignore-project crashes when a project file is present

• Redownload packages when source hash verification fails #7541 #8500

  • Cabal-install will verify source hashes on cached downloads against the current index, and redownload on mismatch. (Which can occur with e.g. head.hackage)

• cabal init -i should sanitize package name guessed from the directory name #8404 #8561

  If the current directory name has any non-alphanumeric symbols in its name, the symbols will be replaced with a dash. Also, will make sure that the resulting package name starts with a letter.

  This worked for cabal init -n already, and this PR only moves code around so that cabal init -i also benefits from this logic.

• Support js-sources with GHC, not only with GHCJS #8636

  • Take into account js-sources when building library components with GHC
  • Missing support for js-sources in executable components is tracked in #8639

• Fix extra-source-file rebuild tracking when run in a multi-package project #8632 #8634 #8640

  • Fixes an issue where glob expansion of extra-source-files for rebuild tracking purposes was not occurring correctly when run in a multi-package setting (i.e. when the globs needed to be expanded relative to something other than ".").

• No up-front warning that assertions are on for special commands (help, version, numeric-version) #8645 #8647

  • When compiled with ghc option -fno-ignore-assert, cabal-install will issue a generic warning that assertions are on. This warning will no longer be emitted for special modes of operation like cabal --numeric-version, --version and help, and also not if cabal could not parse its command line. Further, the warning now goes to stderr rather than stdout.

• Fix and improve list parser for cabal init arguments #8659 #8663

  Occurrences of 'Flag [a]' seem to behave in an unexpected way. The monoid instance of 'Flag' is right associative and discard the value on the left, but we want to merge the contents of 'Flag'.

  Permits:

  • cabal init -d base -d vector -d containers

  Fixes for all Flag '[a]' the cli parser in cabal init. Adds cli parser tests.

  Adds the feature to specify a comma-separated list of dependencies:

  • cabal init -d base,vector,containers

• Fix resolution of imports by relative paths in cabal.project #8686

  Fix bug where cabal tries to resolve imports by relative paths against the directory cabal executable was invoked in rather than directory of cabal.project file that does the import.

• Fix cabal repl discarding --build-depends #6859 #7081 #8732

  • Fix repl command discarding --build-depends argument when using allow-newer or allow-older.

• Add cabal get --only-package-description #1954 #1977 #5162 #8263

• cabal haddock now implies --enable-documentation #7462 #8259

• Include extra-lib-dirs-static into PackageHash #6935 #7794

• Document cabal check in the user guide #8237

• Add documentation (or stubs) for cabal-install commands: fetch, get, info, init, list, report, unpack, upload, user-config #7884 #7978 #8308 #8309

• Add check for upper bound on any dependency in cabal check #8291 #8339