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

1 files changed, 195 insertions, 0 deletions

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``