[commit: ghc] ghc-8.0: Document -dynamic-too (#11488) (acefdeb)

[git at git.haskell.org]

Repository : ssh://git@git.haskell.org/ghc

On branch  : ghc-8.0
Link       : http://ghc.haskell.org/trac/ghc/changeset/acefdeb33d059a0e64e627f5f681e4160e72fb47/ghc

>---------------------------------------------------------------

commit acefdeb33d059a0e64e627f5f681e4160e72fb47
Author: Simon Marlow <marlowsd at gmail.com>
Date:   Mon Feb 15 11:47:12 2016 +0000

    Document -dynamic-too (#11488)
    
    (cherry picked from commit 160765f8331cf92e9a34e9062846a949e7b11b1e)


>---------------------------------------------------------------

acefdeb33d059a0e64e627f5f681e4160e72fb47
 docs/users_guide/phases.rst                        | 14 ++++++++++++++
 utils/mkUserGuidePart/Options/CodeGen.hs           | 10 ++++++++++
 utils/mkUserGuidePart/Options/Linking.hs           | 19 -------------------
 utils/mkUserGuidePart/Options/RedirectingOutput.hs | 12 ++++++++++++
 4 files changed, 36 insertions(+), 19 deletions(-)

diff --git a/docs/users_guide/phases.rst b/docs/users_guide/phases.rst
index e9637fa..ed05add 100644
--- a/docs/users_guide/phases.rst
+++ b/docs/users_guide/phases.rst
@@ -464,6 +464,20 @@ Options affecting code generation
     Note that using this option when linking causes GHC to link against
     shared libraries.
 
+.. ghc-flag:: -dynamic-too
+
+    Generates both dynamic and static object files in a single run of
+    GHC. This option is functionally equivalent to running GHC twice,
+    the second time adding ``-dynamic -osuf dyn_o -hisuf dyn_hi``.
+
+    Although it is equivalent to running GHC twice, using
+    ``-dynamic-too`` is more efficient, because the earlier phases of
+    the compiler up to code generation are performed just once.
+
+    When using ``-dynamic-too``, the options ``-dyno``, ``-dynosuf``,
+    and ``-dynhisuf`` are the counterparts of ``-o``, ``-osuf``, and
+    ``-hisuf`` respectively, but applying to the dynamic compilation.
+
 .. _options-linker:
 
 Options affecting linking
diff --git a/utils/mkUserGuidePart/Options/CodeGen.hs b/utils/mkUserGuidePart/Options/CodeGen.hs
index 9939d9e..0a5d6c1 100644
--- a/utils/mkUserGuidePart/Options/CodeGen.hs
+++ b/utils/mkUserGuidePart/Options/CodeGen.hs
@@ -39,4 +39,14 @@ codegenOptions =
            "output. If ⟨n⟩ is omitted level 2 is assumed."
          , flagType = DynamicFlag
          }
+  , flag { flagName = "-dynamic"
+         , flagDescription = "Build dynamically-linked object files and executables"
+         , flagType = DynamicFlag
+         }
+  , flag { flagName = "-dynamic-too"
+         , flagDescription =
+           "Build dynamic object files *as well as* static object files " ++
+           "during compilation"
+         , flagType = DynamicFlag
+         }
   ]
diff --git a/utils/mkUserGuidePart/Options/Linking.hs b/utils/mkUserGuidePart/Options/Linking.hs
index 2348daa..919cc09 100644
--- a/utils/mkUserGuidePart/Options/Linking.hs
+++ b/utils/mkUserGuidePart/Options/Linking.hs
@@ -21,25 +21,6 @@ linkingOptions =
            "Generate position-independent code (where available)"
          , flagType = DynamicFlag
          }
-  , flag { flagName = "-dynamic"
-         , flagDescription = "Use dynamic Haskell libraries (if available)"
-         , flagType = DynamicFlag
-         }
-  , flag { flagName = "-dynamic-too"
-         , flagDescription =
-           "Build dynamic object files *as well as* static object files " ++
-           "during compilation"
-         , flagType = DynamicFlag
-         }
-  , flag { flagName = "-dyno"
-         , flagDescription =
-           "Set the output path for the *dynamically* linked objects"
-         , flagType = DynamicFlag
-         }
-  , flag { flagName = "-dynosuf"
-         , flagDescription = "Set the output suffix for dynamic object files"
-         , flagType = DynamicFlag
-         }
   , flag { flagName = "-dynload"
          , flagDescription =
            "Selects one of a number of modes for finding shared libraries at runtime."
diff --git a/utils/mkUserGuidePart/Options/RedirectingOutput.hs b/utils/mkUserGuidePart/Options/RedirectingOutput.hs
index 9435e26..62fe99a 100644
--- a/utils/mkUserGuidePart/Options/RedirectingOutput.hs
+++ b/utils/mkUserGuidePart/Options/RedirectingOutput.hs
@@ -44,4 +44,16 @@ redirectingOutputOptions =
          , flagDescription = "set output directory"
          , flagType = DynamicFlag
          }
+  , flag { flagName = "-dyno <filename>"
+         , flagDescription = "Set the output filename for dynamic object files (see ``-dynamic-too``)"
+         , flagType = DynamicFlag
+         }
+  , flag { flagName = "-dynosuf <suffix>"
+         , flagDescription = "Set the object suffix for dynamic object files (see ``-dynamic-too``)"
+         , flagType = DynamicFlag
+         }
+  , flag { flagName = "-dynhisuf <suffix>"
+         , flagDescription = "Set the hi suffix for dynamic object files (see ``-dynamic-too``)"
+         , flagType = DynamicFlag
+         }
   ]