[Git][ghc/ghc][wip/ghc-fat-interface] Docs updates

[Matthew Pickering (@mpickering)]

Matthew Pickering pushed to branch wip/ghc-fat-interface at Glasgow Haskell Compiler / GHC


Commits:
91498f0b by Matthew Pickering at 2022-08-12T13:38:25+01:00
Docs updates

- - - - -


1 changed file:

- docs/users_guide/phases.rst


Changes:

=====================================
docs/users_guide/phases.rst
=====================================
@@ -625,6 +625,11 @@ Options affecting code generation
     Omit code generation (and all later phases) altogether. This is
     useful if you're only interested in type checking code.
 
+    If a module contains a Template Haskell splice then in ``--make`` mode, code
+    generation will be automatically turned on for all dependencies. By default
+    object files are generated but if ghc-flag:`-fprefer-byte-code` is enable then
+    byte-code will be generated instead.
+
 .. ghc-flag:: -fwrite-interface
     :shortdesc: Always write interface files
     :type: dynamic
@@ -637,12 +642,16 @@ Options affecting code generation
     compiling dependencies.
 
 .. ghc-flag:: -fwrite-fat-interface
-    :shortdesc: Always write fat interface files
+    :shortdesc: Write a fat interface file
     :type: dynamic
     :category: codegen
 
     A fat interface file is one which contains all the bindings for a module. From
-    a fat interface file we can restart code generation to produce byte code.
+    a fat interface file we can restart code generation to produce byte-code.
+
+    The definition of bindings which are included in a fat interface file
+    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
@@ -652,7 +661,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. Therefore this flag disables :ghc-flag:`-fbyte-code-and-object-code`.
+    to byte-code. Therefore this flag disables :ghc-flag:`-fbyte-code-and-object-code`.
 
 .. ghc-flag:: -fbyte-code
     :shortdesc: Generate byte-code
@@ -665,20 +674,18 @@ Options affecting code generation
     reversing the effect of :ghc-flag:`-fobject-code`.
 
 .. ghc-flag:: -fbyte-code-and-object-code
-    :shortdesc: Generate object code and bytecode
+    :shortdesc: Generate object code and byte-code
     :type: dynamic
     :category: codegen
 
-    Generate object code and byte code. This is useful with the flags
+    Generate object code and byte-code. This is useful with the flags
     :ghc-flag:`-fprefer-byte-code` and :ghc-flag:`-fwrite-fat-interface`.
 
+    This flag implies :ghc-flag:`-fwrite-fat-interface`.
+
     :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
@@ -772,16 +779,20 @@ Options affecting code generation
 
 
 .. ghc-flag:: -fprefer-byte-code
-    :shortdesc: Use bytecode if it is available to run TH splices
+    :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
+    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-fat-interface` which
-    allows byte code to be generated from an interface file.
+    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:



View it on GitLab: https://gitlab.haskell.org/ghc/ghc/-/commit/91498f0b50fc29c9bb69d324df6964c8da821d94

-- 
View it on GitLab: https://gitlab.haskell.org/ghc/ghc/-/commit/91498f0b50fc29c9bb69d324df6964c8da821d94
You're receiving this email because of your account on gitlab.haskell.org.


-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.haskell.org/pipermail/ghc-commits/attachments/20220812/20ef4586/attachment-0001.html>