Document -dynamic-too (#11488)

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

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
+         }
   ]

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."

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
+         }
   ]