Documented the as of yet undocumented '--print-*' GHC flags,

as well as `-split-objs`, since that is related to
`--print-object-splitting-supported`.
See #18641

4 files changed, 209 insertions, 21 deletions

diff --git a/docs/users_guide/codegens.rst b/docs/users_guide/codegens.rst
index 2801518700..1cad4b7659 100644
--- a/docs/users_guide/codegens.rst
+++ b/docs/users_guide/codegens.rst
@@ -124,4 +124,5 @@ to build GHC with the appropriate options set. Consult the GHC Building
 Guide for details.
 
 You can check if your GHC is unregisterised by calling
+``ghc --print-unregisterised`` (see :ghc-flag:`--print-unregisterised`) or
 ``ghc --info`` (see :ghc-flag:`--info`).
diff --git a/docs/users_guide/expected-undocumented-flags.txt b/docs/users_guide/expected-undocumented-flags.txt
index f7000d89f8..1a0c75413c 100644
--- a/docs/users_guide/expected-undocumented-flags.txt
+++ b/docs/users_guide/expected-undocumented-flags.txt
@@ -1,26 +1,6 @@
 -#include
 --abi-hash
 --backpack
---print-booter-version
---print-build-platform
---print-c-compiler-flags
---print-c-compiler-link-flags
---print-debug-on
---print-global-package-db
---print-have-interpreter
---print-have-native-code-generator
---print-host-platform
---print-ld-flags
---print-leading-underscore
---print-object-splitting-supported
---print-project-git-commit-id
---print-project-version
---print-rts-ways
---print-stage
---print-support-smp
---print-tables-next-to-code
---print-target-platform
---print-unregisterised
 --show-packages
 -Onot
 -Wall-missed-specializations
@@ -161,7 +141,6 @@
 -rtsopts=none
 -rtsopts=some
 -smp
--split-objs
 -syslib
 -this-component-id
 -ticky-LNE
diff --git a/docs/users_guide/phases.rst b/docs/users_guide/phases.rst
index 3c94a39733..582b79bc9f 100644
--- a/docs/users_guide/phases.rst
+++ b/docs/users_guide/phases.rst
@@ -675,6 +675,19 @@ Options affecting code generation
     and ``-dynhisuf`` are the counterparts of ``-o``, ``-osuf``, and
     ``-hisuf`` respectively, but applying to the dynamic compilation.
 
+.. ghc-flag:: -split-objs
+    :shortdesc: Split generated object files into smaller files
+    :type: dynamic
+    :category: codegen
+
+    When using this option, the object file is split into many smaller objects.
+    This feature is used when building libraries, so that a program statically
+    linked against the library will pull in less of the library.
+
+    Since this uses platform specific techniques, it may not be available on
+    all target platforms. See the :ghc-flag:`--print-object-splitting-supported`
+    flag to check whether your GHC supports object splitting.
+
 .. _options-linker:
 
 Options affecting linking
diff --git a/docs/users_guide/using.rst b/docs/users_guide/using.rst
index 5b8425fc9e..51228aac7b 100644
--- a/docs/users_guide/using.rst
+++ b/docs/users_guide/using.rst
@@ -420,6 +420,101 @@ The available mode flags are:
 
     Print GHC's numeric version number only.
 
+.. ghc-flag:: --print-booter-version
+    :shortdesc: display bootstrap compiler version
+    :type: mode
+    :category: modes
+
+    Print the numeric version of the GHC binary used to
+    bootstrap the build of this compiler.
+
+.. ghc-flag:: --print-build-platform
+    :shortdesc: display platform on which GHC was built
+    :type: mode
+    :category: modes
+
+    Print the target string of the build platform, on which GHC was built,
+    as generated by GNU Autotools.
+    The format is ``cpu-manufacturer-operating_system-(kernel)``, e.g.,
+    ``x86_64-unknown-linux``.
+
+.. ghc-flag:: --print-c-compiler-flags
+    :shortdesc: C compiler flags used to build GHC
+    :type: mode
+    :category: modes
+
+    List the flags passed to the C compiler during GHC build.
+
+.. ghc-flag:: --print-c-compiler-link-flags
+    :shortdesc: C linker flags used to build GHC
+    :type: mode
+    :category: modes
+
+    List the flags passed to the C compiler for the linking step
+    during GHC build.
+
+.. ghc-flag:: --print-debug-on
+    :shortdesc: print whether GHC was built with ``-DDEBUG``
+    :type: mode
+    :category: modes
+
+    Print ``True`` if GHC was built with ``-DDebug`` flag.
+    This enables assertions and extra debug code.
+    The flag can be set in ``GhcStage1HcOpts`` and/or ``GhcStage2HcOpts``
+    and is automatically set for ``devel1`` and ``devel2`` build flavors.
+
+.. ghc-flag:: --print-global-package-db
+    :shortdesc: display GHC's global package database directory
+    :type: mode
+    :category: modes
+
+    Print the path to GHC's global package database directory.
+    A package database stores details about installed packages as a directory
+    containing a file for each package.
+    This flag prints the path to the global database shipped with GHC, and
+    looks something like ``/usr/lib/ghc/package.conf.d`` on Unix.
+    There may be other package databases, e.g., the user package databse.
+    For more details see :ref:`package-databases`.
+
+.. ghc-flag:: --print-have-interpreter
+    :shortdesc: display whether GHC was built with interactive support
+    :type: mode
+    :category: modes
+
+    Print ``YES`` if GHC was compiled to include the interpreter, ``NO`` otherwise.
+    If this GHC does not have the interpreter included, running it in interactive
+    mode (see :ghc-flag:`--interactive`) will throw an error.
+    This only pertains the use of GHC interactively, not any separate GHCi binaries
+    (see :ref:`ghci`).
+
+.. ghc-flag:: --print-have-native-code-generator
+    :shortdesc: display whether target platform has NCG support
+    :type: mode
+    :category: modes
+
+    Print ``YES`` if native code generator supports the target platform,
+    ``NO`` otherwise.
+    (See :ref:`native-code-gen`)
+
+.. ghc-flag:: --print-host-platform
+    :shortdesc: display host platform of GHC
+    :type: mode
+    :category: modes
+
+    Print the target string of the host platform, i.e.,
+    the one on which GHC is supposed to run, as generated by GNU Autotools.
+    The format is ``cpu-manufacturer-operating_system-(kernel)``, e.g.,
+    ``x86_64-unknown-linux``.
+
+.. ghc-flag:: --print-leading-underscore
+    :shortdesc: display use of leading underscores on symbol names
+    :type: mode
+    :category: modes
+
+    Print ``YES`` if GHC was compiled to use symbols with leading underscores
+    in object files, ``NO`` otherwise.
+    This is usually atarget platform dependent.
+
 .. ghc-flag:: --print-libdir
     :shortdesc: display GHC library directory
     :type: mode
@@ -434,6 +529,106 @@ The available mode flags are:
     This is the value of ``$libdir`` in the package
     configuration file (see :ref:`packages`).
 
+.. ghc-flag:: --print-ld-flags
+    :shortdesc: display linker flags used to compile GHC
+    :type: mode
+    :category: modes
+
+    Print linke flags used to compile GHC.
+
+.. ghc-flag:: --print-object-splitting-supported
+    :shortdesc: display whether GHC supports object splitting
+    :type: mode
+    :category: modes
+
+    Print ``YES`` if GHC was compiled with support for splitting generated
+    object files into smaller objects, ``NO`` otherwise.
+    This feature uses platform specific techniques and may not be available on
+    all platforms.
+    See :ghc-flag:`-split-objs` for details.
+
+.. ghc-flag:: --print-project-git-commit-id
+    :shortdesc: display Git commit id GHC is built from
+    :type: mode
+    :category: modes
+
+    Print the Git commit id from which this GHC was built.
+    This can be used to trace the current binary back to a specific
+    revision, which is especially useful during development on GHC itself.
+    It is set by the configure script.
+
+.. ghc-flag:: --print-project-version
+    :shortdesc: display GHC version
+    :type: mode
+    :category: modes
+
+    Print the version set in the configure script during build.
+    This is simply the GHC version.
+
+.. ghc-flag:: --print-rts-ways
+    :shortdesc: display which way RTS was built
+    :type: mode
+    :category: modes
+
+    Packages, like the Runtime System, can be built in a number of ways:
+    - profiling - with profiling support
+    - dynamic - with dynamic linking
+    - logging - RTS event logging
+    - threaded - mulithreaded RTS
+    - debug - RTS with debug information
+
+    Various combinations of these flavours are possible.
+
+.. ghc-flag:: --print-stage
+    :shortdesc: display ``stage`` number of GHC
+    :type: mode
+    :category: modes
+
+    GHC is built using GHC itself and this build happens in stages,
+    which are numbered.
+
+    - Stage 0 is the GHC you have installed.  The "GHC you have installed" is also called "the bootstrap compiler".
+    - Stage 1 is the first GHC we build, using stage 0.  Stage 1 is then used to build the packages.
+    - Stage 2 is the second GHC we build, using stage 1.  This is the one we normally install when you say make install.
+    - Stage 3 is optional, but is sometimes built to test stage 2.
+
+    Stage 1 does not support interactive execution (GHCi) and Template Haskell.
+
+.. ghc-flag:: --print-support-smp
+    :shortdesc: display whether GHC was compiled with SMP support
+    :type: mode
+    :category: modes
+
+    Print ``YES`` if GHC was built with multiporcessor support, ``NO`` otherwise.
+
+.. ghc-flag:: --print-tables-next-to-code
+    :shortdesc: display whether GHC was compiled with ``--enable-tables-next-to-code``
+    :type: mode
+    :category: modes
+
+    Print ``YES`` if GHC was built with the flag ``--enable-tables-next-to-code``, ``NO`` otherwise.
+    This option is on by default, as it generates a more efficient code layout.
+
+.. ghc-flag:: --print-target-platform
+    :shortdesc: display target platform of GHC
+    :type: mode
+    :category: modes
+
+    Print the target string of the target platform, i.e.,
+    the one on which generated binaries will run, as generated by GNU Autotools.
+    The format is ``cpu-manufacturer-operating_system-(kernel)``, e.g.,
+    ``x86_64-unknown-linux``.
+
+.. ghc-flag:: --print-unregisterised
+    :shortdesc: display whether this GHC was built in unregisterised mode
+    :type: mode
+    :category: modes
+
+    Print ``YES`` if this GHC was built in unregisterised mode, ``NO`` otherwise.
+    "Unregisterised" means that GHC will disable most platform-specific tricks
+    and optimisations. Only the LLVM and C code generators will be available.
+    See :ref:`unreg` for more details.
+
 .. _make-mode:
 
 Using ``ghc`` ``--make``