Document profiling flags, warning flags, and no-pie

4 files changed, 133 insertions, 46 deletions

diff --git a/docs/users_guide/expected-undocumented-flags.txt b/docs/users_guide/expected-undocumented-flags.txt
index 68dcd2d1df..38d12ada42 100644
--- a/docs/users_guide/expected-undocumented-flags.txt
+++ b/docs/users_guide/expected-undocumented-flags.txt
@@ -3,16 +3,8 @@
 --backpack
 --show-packages
 -Onot
--Wall-missed-specializations
 -Walternative-layout-rule-transitional
--Wauto-orphans
--Wdefault
 -Wderiving-typeable
--Wextra
--Wmissed-specializations
--Wmissing-space-after-bang
--Wnot
--Wprepositive-qualified-module
 -XAlternativeLayoutRule
 -XAlternativeLayoutRuleTransitional
 -XAutoDeriveTypeable
@@ -31,9 +23,6 @@
 -XRelaxedLayout
 -XRelaxedPolyRec
 -XTraditionalRecordSyntax
--auto
--auto-all
--caf-all
 -copy-libs-when-linking
 -dannot-lint
 -dasm-lint
@@ -108,13 +97,9 @@
 -keep-hi-file
 -keep-o-file
 -n
--no-auto
--no-auto-all
--no-caf-all
 -no-keep-hi-file
 -no-keep-o-file
 -no-link
--no-pie
 -no-recomp
 -no-rtsopts
 -no-user-package-conf
diff --git a/docs/users_guide/phases.rst b/docs/users_guide/phases.rst
index b21ebf9529..74b7bd0f40 100644
--- a/docs/users_guide/phases.rst
+++ b/docs/users_guide/phases.rst
@@ -1226,6 +1226,7 @@ for example).
 .. ghc-flag:: -pie
     :shortdesc: Instruct the linker to produce a position-independent executable.
     :type: dynamic
+    :reverse: -no-pie
     :category: linking
 
     :since: 8.2.2
@@ -1247,6 +1248,15 @@ for example).
     Also, you may need to use the :ghc-flag:`-rdynamic` flag to ensure that
     that symbols are not dropped from your PIE objects.
 
+.. ghc-flag:: -no-pie
+    :shortdesc: Don't instruct the linker to produce a position-independent executable.
+    :type: dynamic
+    :reverse: -pie
+    :category: linking
+
+    If required, the C compiler will still produce a PIE. Otherwise, this is the default.
+    Refer to -pie for more information about PIEs.
+
 .. ghc-flag:: -fkeep-cafs
     :shortdesc: Do not garbage-collect CAFs (top-level expressions) at runtime
     :type: dynamic
diff --git a/docs/users_guide/profiling.rst b/docs/users_guide/profiling.rst
index 9c628dc833..e7b1b7e455 100644
--- a/docs/users_guide/profiling.rst
+++ b/docs/users_guide/profiling.rst
@@ -427,6 +427,43 @@ for all modules in a program.
     interested in the entry counts (for example, if you only intend to
     do heap profiling).
 
+
+.. ghc-flag:: -auto-all
+    :shortdesc: *(deprecated)* Alias for :ghc-flag:`-fprof-auto`
+    :type: dynamic
+
+    Deprecated alias for :ghc-flag:`-fprof-auto`
+
+.. ghc-flag:: -auto
+    :shortdesc: *(deprecated)* Alias for :ghc-flag:`-fprof-auto-exported`
+    :type: dynamic
+
+    Deprecated alias for :ghc-flag:`-fprof-auto-exported`
+    
+.. ghc-flag:: -caf-all
+    :shortdesc: *(deprecated)* Alias for :ghc-flag:`-fprof-cafs`
+    :type: dynamic
+
+    Deprecated alias for :ghc-flag:`-fprof-cafs`
+
+.. ghc-flag:: -no-auto-all
+    :shortdesc: *(deprecated)* Alias for :ghc-flag:`-fno-prof-auto`
+    :type: dynamic
+
+    Deprecated alias for :ghc-flag:`-fno-prof-auto`
+
+.. ghc-flag:: -no-auto
+    :shortdesc: *(deprecated)* Alias for :ghc-flag:`-fno-prof-auto`
+    :type: dynamic
+
+    Deprecated alias for :ghc-flag:`-fno-prof-auto`
+
+.. ghc-flag:: -no-caf-all
+    :shortdesc: *(deprecated)* Alias for :ghc-flag:`-fno-prof-cafs`
+    :type: dynamic
+
+    Deprecated alias for :ghc-flag:`-fno-prof-cafs`
+
 .. _prof-time-options:
 
 Time and allocation profiling
diff --git a/docs/users_guide/using-warnings.rst b/docs/users_guide/using-warnings.rst
index acb9303555..04fb591ca3 100644
--- a/docs/users_guide/using-warnings.rst
+++ b/docs/users_guide/using-warnings.rst
@@ -14,37 +14,43 @@ of warnings.
 To turn off an individual warning ``-W<wflag>``, use ``-Wno-<wflag>``.
 To reverse ``-Werror``, which makes all warnings into errors, use ``-Wwarn``.
 
-By default, you get a standard set of warnings which are
-generally likely to indicate bugs in your program. These are:
-
-.. hlist::
-    :columns: 3
-
-    * :ghc-flag:`-Woverlapping-patterns`
-    * :ghc-flag:`-Wwarnings-deprecations`
-    * :ghc-flag:`-Wdeprecations`
-    * :ghc-flag:`-Wdeprecated-flags`
-    * :ghc-flag:`-Wunrecognised-pragmas`
-    * :ghc-flag:`-Wduplicate-exports`
-    * :ghc-flag:`-Wderiving-defaults`
-    * :ghc-flag:`-Woverflowed-literals`
-    * :ghc-flag:`-Wempty-enumerations`
-    * :ghc-flag:`-Wmissing-fields`
-    * :ghc-flag:`-Wmissing-methods`
-    * :ghc-flag:`-Wwrong-do-bind`
-    * :ghc-flag:`-Wsimplifiable-class-constraints`
-    * :ghc-flag:`-Wtyped-holes`
-    * :ghc-flag:`-Wdeferred-type-errors`
-    * :ghc-flag:`-Wpartial-type-signatures`
-    * :ghc-flag:`-Wunsupported-calling-conventions`
-    * :ghc-flag:`-Wdodgy-foreign-imports`
-    * :ghc-flag:`-Winline-rule-shadowing`
-    * :ghc-flag:`-Wunsupported-llvm-version`
-    * :ghc-flag:`-Wmissed-extra-shared-lib`
-    * :ghc-flag:`-Wtabs`
-    * :ghc-flag:`-Wunrecognised-warning-flags`
-    * :ghc-flag:`-Winaccessible-code`
-    * :ghc-flag:`-Wstar-binder`
+
+.. ghc-flag:: -Wdefault
+    :shortdesc: enable default flags
+    :type: dynamic
+    :category:
+
+    By default, you get a standard set of warnings which are
+    generally likely to indicate bugs in your program. These are:
+
+    .. hlist::
+        :columns: 3
+
+        * :ghc-flag:`-Woverlapping-patterns`
+        * :ghc-flag:`-Wwarnings-deprecations`
+        * :ghc-flag:`-Wdeprecations`
+        * :ghc-flag:`-Wdeprecated-flags`
+        * :ghc-flag:`-Wunrecognised-pragmas`
+        * :ghc-flag:`-Wduplicate-exports`
+        * :ghc-flag:`-Wderiving-defaults`
+        * :ghc-flag:`-Woverflowed-literals`
+        * :ghc-flag:`-Wempty-enumerations`
+        * :ghc-flag:`-Wmissing-fields`
+        * :ghc-flag:`-Wmissing-methods`
+        * :ghc-flag:`-Wwrong-do-bind`
+        * :ghc-flag:`-Wsimplifiable-class-constraints`
+        * :ghc-flag:`-Wtyped-holes`
+        * :ghc-flag:`-Wdeferred-type-errors`
+        * :ghc-flag:`-Wpartial-type-signatures`
+        * :ghc-flag:`-Wunsupported-calling-conventions`
+        * :ghc-flag:`-Wdodgy-foreign-imports`
+        * :ghc-flag:`-Winline-rule-shadowing`
+        * :ghc-flag:`-Wunsupported-llvm-version`
+        * :ghc-flag:`-Wmissed-extra-shared-lib`
+        * :ghc-flag:`-Wtabs`
+        * :ghc-flag:`-Wunrecognised-warning-flags`
+        * :ghc-flag:`-Winaccessible-code`
+        * :ghc-flag:`-Wstar-binder`
 
 The following flags are simple ways to select standard "packages" of warnings:
 
@@ -68,6 +74,13 @@ The following flags are simple ways to select standard "packages" of warnings:
         * :ghc-flag:`-Wdodgy-imports`
         * :ghc-flag:`-Wunbanged-strict-patterns`
 
+.. ghc-flag:: -Wextra
+    :shortdesc: alias for :ghc-flag:`-W`
+    :type: dynamic
+    :reverse: -w
+
+    Alias for :ghc-flag:`-W`
+
 .. ghc-flag:: -Wall
     :shortdesc: enable almost all warnings (details in :ref:`options-sanity`)
     :type: dynamic
@@ -145,6 +158,12 @@ The following flags are simple ways to select standard "packages" of warnings:
     Turns off all warnings, including the standard ones and those that
     :ghc-flag:`-Wall` doesn't enable.
 
+.. ghc-flag:: -Wnot
+    :shortdesc: *(deprecated)* Alias for :ghc-flag:`-w`
+    :type: dynamic
+
+    Deprecated alias for :ghc-flag:`-w`
+
 These options control which warnings are considered fatal and cause compilation
 to abort.
 
@@ -249,6 +268,16 @@ of ``-W(no-)*``.
     This warning can be addressed by either adding an explicit import list or
     using a ``qualified`` import.
 
+.. ghc-flag:: -Wprepositive-qualified-module
+    :shortdesc: Report imports with a leading/prepositive "qualified"
+    :type: dynamic
+    :reverse: -Wno-prepositive-qualified-module
+    :category:
+
+    Normally, imports are qualified prepositively: ``import qualified M``.
+    By using :extension:`ImportQualifiedPost`, the qualified keyword can be used after the module name.
+    Like so: ``import M qualified``. This will warn when the first, prepositive syntax is used.
+
 .. ghc-flag:: -Wtyped-holes
     :shortdesc: Report warnings when :ref:`typed hole <typed-holes>` errors are
         :ref:`deferred until runtime <defer-type-errors>`. See
@@ -400,6 +429,13 @@ of ``-W(no-)*``.
 
     This option is off by default.
 
+.. ghc-flag:: -Wmissed-specializations
+    :shortdesc: alias for :ghc-flag:`-Wmissed-specialisations`
+    :type: dynamic
+    :reverse: -Wno-missed-specializations
+
+    Alias for :ghc-flag:`-Wmissed-specialisations`
+
 .. ghc-flag:: -Wall-missed-specialisations
     :shortdesc: warn when specialisation of any overloaded function fails.
     :type: dynamic
@@ -415,6 +451,13 @@ of ``-W(no-)*``.
 
     This option is off by default.
 
+.. ghc-flag:: -Wall-missed-specializations
+    :shortdesc: alias for :ghc-flag:`-Wall-missed-specialisations`
+    :type: dynamic
+    :reverse: -Wno-all-missed-specializations
+
+    Alias for :ghc-flag:`-Wall-missed-specialisations`
+
 .. ghc-flag:: -Wwarnings-deprecations
     :shortdesc: warn about uses of functions & types that have warnings or
         deprecated pragmas
@@ -1826,6 +1869,18 @@ of ``-W(no-)*``.
     This warning informs you about discarded documentation comments.
     It has no effect when :ghc-flag:`-haddock` is disabled.
 
+.. ghc-flag:: -Wauto-orphans
+    :shortdesc: *(deprecated)* Does nothing
+    :type: dynamic
+
+    Does nothing.
+
+.. ghc-flag:: -Wmissing-space-after-bang
+    :shortdesc: *(deprecated)* Does nothing
+    :type: dynamic
+
+    Does nothing.
+
 If you're feeling really paranoid, the :ghc-flag:`-dcore-lint` option is a good choice.
 It turns on heavyweight intra-pass sanity-checking within GHC. (It checks GHC's
 sanity, not yours.)