doc: behaviour of +RTS -h depends on profiling
authorBen Price <ben@brprice.uk>
Tue, 15 Jan 2019 12:38:44 +0000 (12:38 +0000)
committerBen Gamari <ben@smart-cactus.org>
Wed, 16 Jan 2019 19:17:20 +0000 (14:17 -0500)
The rts option `-h` behaves as `-hT` when compiled without profiling,
and `-hc` when compiled with profiling. Add a note to the user's guide
highlighting this inconsistency.

docs/users_guide/profiling.rst
docs/users_guide/runtime_control.rst

index def3596..c1379f3 100644 (file)
@@ -697,6 +697,11 @@ following RTS options select which break-down to use:
     *Requires :ghc-flag:`-prof`.* Breaks down the graph by the cost-centre stack
     which produced the data.
 
+    .. note:: The meaning of the shortened :rts-flag:`-h` is dependent on whether
+              your program was compiled for profiling. When compiled for profiling,
+              :rts-flag:`-h` is equivalent to :rts-flag:`-hc`, but otherwise is
+              equivalent to :rts-flag:`-hT` (see :ref:`rts-profiling`).
+
 .. rts-flag:: -hm
 
     *Requires :ghc-flag:`-prof`.* Break down the live heap by the module
index 7526b06..a5c2f14 100644 (file)
@@ -984,6 +984,10 @@ executables:
     ``THUNK``). To get a more detailed profile, use the full profiling support
     (:ref:`profiling`). Can be shortened to :rts-flag:`-h`.
 
+    .. note:: The meaning of the shortened :rts-flag:`-h` is dependent on whether
+              your program was compiled for profiling.
+              (See :ref:`rts-options-heap-prof` for details.)
+
 .. rts-flag:: -L ⟨n⟩
 
     :default: 25 characters