Support generating HIE files

Adds a `-fenable-ide-info` flag which instructs GHC to generate `.hie`
files (see the wiki page:
https://ghc.haskell.org/trac/ghc/wiki/HIEFiles).

This is a rebased version of Zubin Duggal's (@wz1000) GHC changes for
his GSOC project, as posted here:
https://gist.github.com/wz1000/5ed4ddd0d3e96d6bc75e095cef95363d.

Test Plan: ./validate

Reviewers: bgamari, gershomb, nomeata, alanz, sjakobi

Reviewed By: alanz, sjakobi

Subscribers: alanz, hvr, sjakobi, rwbarton, wz1000, carter

Differential Revision: https://phabricator.haskell.org/D5239

3 files changed, 61 insertions, 0 deletions

diff --git a/docs/users_guide/8.8.1-notes.rst b/docs/users_guide/8.8.1-notes.rst
index ea38029a0a..6e52a63038 100644
--- a/docs/users_guide/8.8.1-notes.rst
+++ b/docs/users_guide/8.8.1-notes.rst
@@ -103,6 +103,10 @@ Runtime system
 - The output filename used for :ref:`eventlog output <rts-eventlog>` can now be
   specified with the :rts-flag:`-ol` flag.
 
+- Add support for generating a new type of output: extended interfaces files.
+  Generation of these files, which sport a ``.hie`` suffix, is enabled via the
+  ``-fwrite-ide-info`` flag. See :ref:`hie-options` for more information.
+
 Template Haskell
 ~~~~~~~~~~~~~~~~
 
diff --git a/docs/users_guide/separate_compilation.rst b/docs/users_guide/separate_compilation.rst
index d17ed2111c..338c438eea 100644
--- a/docs/users_guide/separate_compilation.rst
+++ b/docs/users_guide/separate_compilation.rst
@@ -288,6 +288,14 @@ Redirecting the compilation output(s)
     Redirects all generated interface files into ⟨dir⟩, instead of the
     default.
 
+.. ghc-flag:: -hiedir ⟨dir⟩
+    :shortdesc: set directory for extended interface files
+    :type: dynamic
+    :category:
+
+    Redirects all generated extended interface files into ⟨dir⟩, instead of
+    the default.
+
 .. ghc-flag:: -stubdir ⟨dir⟩
     :shortdesc: redirect FFI stub files
     :type: dynamic
@@ -351,6 +359,12 @@ Redirecting the compilation output(s)
 
     to get the profiled version.
 
+.. ghc-flag:: -hiesuf ⟨suffix⟩
+    :shortdesc: set the suffix to use for extended interface files
+    :type: dynamic
+
+    The ``-hiesuf`` ⟨suffix⟩ will change the ``.hie`` file suffix for
+    extended interface files to whatever you specify.
 
 .. ghc-flag:: -hcsuf ⟨suffix⟩
     :shortdesc: set the suffix to use for intermediate C files
@@ -534,6 +548,46 @@ Other options related to interface files
     where ⟨file⟩ is the name of an interface file, dumps the contents of
     that interface in a human-readable format. See :ref:`modes`.
 
+.. _hie-options:
+
+Options related to extended interface files
+-------------------------------------------
+
+.. index::
+   single: extended interface files, options
+
+GHC builds up a wealth of information about a Haskell source file as it compiles
+it. Extended interface files are a way of persisting some of this information to
+disk so that external tools, such as IDE's, can avoid parsing, typechecking, and
+renaming all over again. These files contain
+
+  * a simplified AST
+
+       * nodes are annotated with source positions and types
+       * identifiers are annotated with scope information
+
+  * the raw bytes of the initial Haskell source
+
+The GHC API exposes functions for reading and writing these files.
+
+.. ghc-flag:: -fwrite-ide-info
+    :shortdesc: Write out extended interface files
+    :type: dynamic
+    :category: extended-interface-files
+
+    Writes out extended interface files alongisde regular enterface files.
+    Just like regular interface files, GHC has a recompilation check to detect
+    out of date or missing extended interface files.
+
+.. ghc-flag:: -fvalidate-ide-info
+    :shortdesc: Perform some sanity checks on the extended interface files
+    :type: dynamic
+    :category: extended-interface-files
+
+    Runs a series of sanity checks and lints on the extended interface files
+    that are being written out. These include testing things properties such as
+    variables not occuring outside of their expected scopes.
+
 .. _recomp:
 
 The recompilation checker
diff --git a/docs/users_guide/using.rst b/docs/users_guide/using.rst
index 553269cc75..420e2d3bfc 100644
--- a/docs/users_guide/using.rst
+++ b/docs/users_guide/using.rst
@@ -203,6 +203,9 @@ the "right thing" to happen to those files.
 ``.hi``
     A Haskell interface file, probably compiler-generated.
 
+``.hie``
+    An extended Haskell interface file, produced by the Haskell compiler.
+
 ``.hc``
     Intermediate C file produced by the Haskell compiler.