diff options
author | Benjamin Maurer <maurer.benjamin@gmail.com> | 2020-09-03 17:44:05 +0200 |
---|---|---|
committer | Marge Bot <ben+marge-bot@smart-cactus.org> | 2020-09-04 22:27:01 -0400 |
commit | 0be8e746b820662a09bf9e406bb7e86da3b548e6 (patch) | |
tree | 693f582beae7c3aca28d1ffb750d9b2c531f8931 | |
parent | 07bdcac38c90e79db9e4327f87c5400630dfe74b (diff) | |
download | haskell-0be8e746b820662a09bf9e406bb7e86da3b548e6.tar.gz |
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
-rw-r--r-- | docs/users_guide/codegens.rst | 1 | ||||
-rw-r--r-- | docs/users_guide/expected-undocumented-flags.txt | 21 | ||||
-rw-r--r-- | docs/users_guide/phases.rst | 13 | ||||
-rw-r--r-- | docs/users_guide/using.rst | 195 |
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`` |