summaryrefslogtreecommitdiff
path: root/docs/users_guide/phases.rst
diff options
context:
space:
mode:
authorMatthew Pickering <matthewtpickering@gmail.com>2022-10-01 18:16:20 +0100
committerMarge Bot <ben+marge-bot@smart-cactus.org>2022-10-11 12:48:45 -0400
commite058b138fef9f697095f97cb6a52f6ba58c940c5 (patch)
treead00ed929ee6d5fa69825c00d1b8ff3d3dd9ee14 /docs/users_guide/phases.rst
parentfbb887406d27b5271e45392c2c25f8b1ba4cdeae (diff)
downloadhaskell-e058b138fef9f697095f97cb6a52f6ba58c940c5.tar.gz
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
Diffstat (limited to 'docs/users_guide/phases.rst')
-rw-r--r--docs/users_guide/phases.rst46
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