Cabal library: allow setting the logging handle

[sheaf]

Template Α: This PR modifies behaviour or interface.

The goal of this patch is to allow the logging handle to be set when calling Cabal library functions, without having to spawn a separate process and redirect handles. This allows Cabal library functions to be called in a concurrent setting without spawning separate processes.

To achieve this, this PR modifies Verbosity as follows:

1. The old Verbosity datatype becomes VerbosityFlags. This is what gets passed in the command-line interface, e.g. when running a Setup executable.
2. The new Verbosity datatype contains VerbosityFlags together with VerbosityHandles, which specify where to redirect stdout/stderr.

Crucially, this allows us to get rid of the

  isJust (useLoggingHandle options)

condition in getSetupMethod, which forced us to use the cabal-install "act as setup" mechanism instead of directly calling Cabal library functions.

Several additional changes have been made in relation to the VerbosityFlags data type (which, recall, is what Verbosity used to be):

1. The Ord instance of VerbosityFlags has been removed.
   Comparing verbosity levels is now done through the Ord instance on VerbosityLevel, via verbosityLevel :: Verbosity -> VerbosityLevel.
2. The Eq instance of VerbosityFlags now takes into account all the fields, and not only the verbosity level.
3. The Enum and Bounded instances of VerbosityFlags have been removed.
   Users are again encouraged to go through VerbosityLevel instead.

In addition, the modifyVerbosity function has been removed. It allowed arbitrarily changing the verbosity level, which is undesirable in general (e.g. in practice one wants the "silent" verbosity level to remain "silent").
There was only one use site, which was rewritten to use the new makeVerbose function which increases the "normal" verbosity level to "verbose" and leaves other verbosity levels unchanged.

---

• Patches conform to the coding conventions.
• Any changes that could be relevant to users have been recorded in the changelog.
  • Is the change significant? If so, remember to add significance: significant in the changelog file.
• The documentation has been updated, if necessary.
• Manual QA notes have been included.
• Tests have been added. (Ask for help if you don’t know how to write them! Ask for an exemption if tests are too complex for too little coverage!)

[mpickering]

It does occur to me, that the next step after this PR is to use a proper logging framework (ie. a contravariant logger) within the Cabal library.

That would be even more general than the VerbosityHandles approach in this MR.

[geekosaur]

The problem with using a logging framework is bootstrapping.

[mpickering]

The problem with using a logging framework is bootstrapping.

It seems that you could add a single-file implementation of a logging library which Cabal could use if it was desired. Perhaps not ideal, but also not the end of the world.

[sheaf]

I have added a changelog entry under pr-11077, which goes over the user-facing changes and gives some advice about migrating.

[sheaf]

Current TODOs:

• Rebase.
• Add a test (I was working on one but found it a bit difficult to write a good test without Directly call in-library functions to build packages #9871).
• Update the Cabal-hooks API to pass logging handles as a separate argument, so that custom SetupHooks scripts can do the right thing even without setting the working directory of the process.