Document the meaning of -i, -hidir, and -odir

Summary

Recently, I discovered that -hidir clears any attempt to tell to ghc were to find interface files with -i. There seems to be various behaviors that arise in different combinations of these flags as discussed in this thread when using the batch mode as enabled with -c.

None of these behaviors is documented in the user's guide. The most concrete pieces we have are the definition of the search path, and the documentation of -hidir and -odir.

Some things to note

The documentation says the search path is used to search for source files and interface files. However, it can be readily verified that -i is also used to search for object files.

The documentation of -hidir <dir> only says that it makes ghc output and look for interface files in <dir>. But -hidir also has the effect of stopping the search of interface files on any folders specified with -i.

Similar issues happen with object files when using -odir.

Ideal outcome

The documentation should explain accurately how ghc behaves in the presence of these flags. And ideally, there would be a way to control where ghc looks for interface and object files independently of where output files are placed.

Environment

• GHC version used: 9.2.1 and 8.10.4

Optional:

• Operating System: nixos
• System Architecture: x86_64