Deprecate -h flag

It is confusing that it defaults to two different things depending on
whether we are in the profiling way or not.

Use -hc if you have a profiling build
Use -hT if you have a normal build

Fixes #19031

6 files changed, 17 insertions, 8 deletions

diff --git a/docs/users_guide/9.2.1-notes.rst b/docs/users_guide/9.2.1-notes.rst
index 6a2cc96128..717da75c33 100644
--- a/docs/users_guide/9.2.1-notes.rst
+++ b/docs/users_guide/9.2.1-notes.rst
@@ -85,6 +85,9 @@ Runtime system
   space lost to fragmentation is no longer counted as live data.
 
 
+- The :rts-flag:`-h` flag has been deprecated, use either :rts-flag:`-hc` or
+  :rts-flag:`-hT` explicitly, as appropiate.
+
 ``ghc-prim`` library
 ~~~~~~~~~~~~~~~~~~~~
 
diff --git a/docs/users_guide/profiling.rst b/docs/users_guide/profiling.rst
index ac1137ac84..62b5615aed 100644
--- a/docs/users_guide/profiling.rst
+++ b/docs/users_guide/profiling.rst
@@ -724,7 +724,7 @@ To generate a heap profile from your program:
 1. Compile the program for profiling (:ref:`prof-compiler-options`).
 
 2. Run it with one of the heap profiling options described below (eg.
-   :rts-flag:`-h` for a basic producer profile). This generates the file
+   :rts-flag:`-hc` for a basic producer profile). This generates the file
    :file:`{prog}.hp`.
 
    If the :ref:`event log <rts-eventlog>` is enabled (with the :rts-flag:`-l ⟨flags⟩`
@@ -769,7 +769,8 @@ following RTS options select which break-down to use:
     .. 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`).
+              equivalent to :rts-flag:`-hT` (see :ref:`rts-profiling`). The :rts-flag:`-h`
+              is deprecated and will be removed in a future release.
 
 .. rts-flag:: -hm
 
diff --git a/rts/RtsFlags.c b/rts/RtsFlags.c
index 95656c3da6..ddd561b29c 100644
--- a/rts/RtsFlags.c
+++ b/rts/RtsFlags.c
@@ -1381,6 +1381,9 @@ error = true;
 #if !defined(PROFILING)
                 switch (rts_argv[arg][2]) {
                   case '\0':
+                    errorBelch("-h is deprecated and will be removed in the next release (9.4),\nuse -hT instead.");
+
+                    FALLTHROUGH;
                   case 'T':
                     OPTION_UNSAFE;
                     RtsFlags.ProfFlags.doHeapProfile = HEAP_BY_CLOSURE_TYPE;
@@ -2133,6 +2136,8 @@ static bool read_heap_profiling_flag(const char *arg)
     bool error = false;
     switch (arg[2]) {
     case '\0':
+      errorBelch("-h is deprecated and will be removed in the next release (9.4),\nuse -hc instead.");
+      FALLTHROUGH;
     case 'C':
     case 'c':
     case 'M':
diff --git a/testsuite/config/ghc b/testsuite/config/ghc
index c54ac6b385..fa2c9d7c7c 100644
--- a/testsuite/config/ghc
+++ b/testsuite/config/ghc
@@ -118,7 +118,7 @@ config.way_flags = {
 
 config.way_rts_flags = {
     'normal'       : [],
-    'normal_h'     : ['-h'], # works without -prof
+    'normal_h'     : ['-hT'], # works without -prof
     'g1'           : ['-G1'],
     'nursery_chunks' : ['-n32k'],
     'debug_numa'   : ['-N2', '--debug-numa=2'],
diff --git a/testsuite/driver/testlib.py b/testsuite/driver/testlib.py
index 87a0bbb23d..1d058c8325 100644
--- a/testsuite/driver/testlib.py
+++ b/testsuite/driver/testlib.py
@@ -606,7 +606,7 @@ def have_thread_sanitizer( ) -> bool:
 # appears to change (up or down) when the underlying profile hasn't
 # really changed. To further minimize this effect we run with a single
 # generation (meaning we get a residency sample on every GC) with a small
-# allocation area (as suggested in #17387). That's what +RTS -h -i0 will do.
+# allocation area (as suggested in #17387). That's what +RTS -hT -i0 will do.
 # If you find that a test is flaky, sampling frequency can be adjusted by
 # shrinking the allocation area (+RTS -A64k, for example).
 #
@@ -614,13 +614,13 @@ def have_thread_sanitizer( ) -> bool:
 # a change in one of these figures, please check whether it is real or
 # not as follows:
 #
-#  * Run the test with old and new compilers, adding +RTS -h -i0.001
+#  * Run the test with old and new compilers, adding +RTS -hT -i0.001
 #    (you don't need to compile anything for profiling or enable profiling
 #    libraries to get a heap profile).
 #  * view the heap profiles, read off the maximum residency.  If it has
 #    really changed, then you know there's an issue.
 
-RESIDENCY_OPTS = '+RTS -A256k -i0 -h -RTS'
+RESIDENCY_OPTS = '+RTS -A256k -i0 -hT -RTS'
 
 # See Note [Measuring residency].
 def collect_runtime_residency(tolerance_pct: float):
@@ -1710,7 +1710,7 @@ def simple_run(name: TestName, way: WayName, prog: str, extra_run_opts: str) ->
                            stderr=read_stderr(name),
                            stdout=read_stdout(name))
 
-    check_hp = '-h' in my_rts_flags and opts.check_hp
+    check_hp = '-hT' in my_rts_flags and opts.check_hp
     check_prof = '-p' in my_rts_flags
 
     # exit_code > 127 probably indicates a crash, so don't try to run hp2ps.
diff --git a/testsuite/tests/hp2ps/Makefile b/testsuite/tests/hp2ps/Makefile
index ec7deb53c3..434ee37951 100644
--- a/testsuite/tests/hp2ps/Makefile
+++ b/testsuite/tests/hp2ps/Makefile
@@ -5,5 +5,5 @@ include $(TOP)/mk/test.mk
 .PHONY: T15904
 T15904:
 	"$(TEST_HC)" $(TEST_HC_OPTS) -rtsopts -main-is "$@" "$@.hs" -o "\"$@\""
-	"./\"$@\"" '{"e": 2.72, "pi": 3.14}' "\\" "" '"' +RTS -h
+	"./\"$@\"" '{"e": 2.72, "pi": 3.14}' "\\" "" '"' +RTS -hT
 	"$(HP2PS_ABS)" "\"$@\".hp"