Interface Files with Core Definitions

This commit adds three new flags

* -fwrite-if-simplified-core: Writes the whole core program into an interface
  file
* -fbyte-code-and-object-code: Generate both byte code and object code
  when compiling a file
* -fprefer-byte-code: Prefer to use byte-code if it's available when
  running TH splices.

The goal for including the core bindings in an interface file is to be able to restart the compiler pipeline
at the point just after simplification and before code generation. Once compilation is
restarted then code can be created for the byte code backend.
This can significantly speed up
start-times for projects in GHCi. HLS already implements its own version of these extended interface
files for this reason.

Preferring to use byte-code means that we can avoid some potentially
expensive code generation steps (see #21700)

* Producing object code is much slower than producing bytecode, and normally you
  need to compile with `-dynamic-too` to produce code in the static and dynamic way, the
  dynamic way just for Template Haskell execution when using a dynamically linked compiler.

* Linking many large object files, which happens once per splice, can be quite
  expensive compared to linking bytecode.

And you can get GHC to compile the necessary byte code so
`-fprefer-byte-code` has access to it by using
`-fbyte-code-and-object-code`.

Fixes #21067

1 files changed, 45 insertions, 1 deletions

diff --git a/docs/users_guide/phases.rst b/docs/users_guide/phases.rst
index 052a24537f..be3ca70bf8 100644
--- a/docs/users_guide/phases.rst
+++ b/docs/users_guide/phases.rst
@@ -636,6 +636,19 @@ Options affecting code generation
     useful if you want to type check over multiple runs of GHC without
     compiling dependencies.
 
+.. ghc-flag:: -fwrite-if-simplfied-core
+    :shortdesc: Write an interface file containing the simplified core of the module.
+    :type: dynamic
+    :category: codegen
+
+    The interface file will contain all the bindings for a module. From
+    this interface file we can restart code generation to produce byte-code.
+
+    The definition of bindings which are included in this
+    depend on the optimisation level. Any definitions which are already included in
+    an interface file (via an unfolding for an exported identifier) are reused.
+
+
 .. ghc-flag:: -fobject-code
     :shortdesc: Generate object code
     :type: dynamic
@@ -643,7 +656,7 @@ Options affecting code generation
 
     Generate object code. This is the default outside of GHCi, and can
     be used with GHCi to cause object code to be generated in preference
-    to bytecode.
+    to byte-code. Therefore this flag disables :ghc-flag:`-fbyte-code-and-object-code`.
 
 .. ghc-flag:: -fbyte-code
     :shortdesc: Generate byte-code
@@ -655,6 +668,19 @@ Options affecting code generation
     interpreter, not saved to disk. This option is only useful for
     reversing the effect of :ghc-flag:`-fobject-code`.
 
+.. ghc-flag:: -fbyte-code-and-object-code
+    :shortdesc: Generate object code and byte-code
+    :type: dynamic
+    :category: codegen
+
+    Generate object code and byte-code. This is useful with the flags
+    :ghc-flag:`-fprefer-byte-code` and :ghc-flag:`-fwrite-if-simplfied-core`.
+
+    This flag implies :ghc-flag:`-fwrite-if-simplfied-core`.
+
+    :ghc-flag:`-fbyte-code` and :ghc-flag:`-fobject-code` disable this flag as
+    they specify that GHC should *only* write object code or byte-code respectively.
+
 .. ghc-flag:: -fPIC
     :shortdesc: Generate position-independent code (where available)
     :type: dynamic
@@ -746,6 +772,24 @@ Options affecting code generation
     suppresses all non-global symbol table entries, resulting in smaller object
     file sizes at the expense of debuggability.
 
+
+.. ghc-flag:: -fprefer-byte-code
+    :shortdesc: Use byte-code if it is available to evaluate TH splices
+    :type: dynamic
+    :category: codegen
+
+    If a home package module has byte-code available then use that instead of
+    and object file (if that's available) to evaluate and run TH splices.
+
+    This is useful with flags such as :ghc-flag:`-fbyte-code-and-object-code`, which
+    tells the compiler to generate byte-code, and :ghc-flag:`-fwrite-if-simplfied-core` which
+    allows byte-code to be generated from an interface file.
+
+    This flag also interacts with :ghc-flag:`-fno-code`, if this flag is enabled
+    then any modules which are required to be compiled for Template Haskell evaluation
+    will generate byte-code rather than object code.
+
+
 .. _options-linker:
 
 Options affecting linking