rts: Clean up RTS flags usage messagewip/T20961

Align flag descriptions and acknowledge that some flags may not be
available unless the user linked with `-rtsopts` (as noted in #20961).

Fixes #20961.

1 files changed, 62 insertions, 58 deletions

diff --git a/rts/RtsFlags.c b/rts/RtsFlags.c
index 11399e3103..c200dcde5d 100644
--- a/rts/RtsFlags.c
+++ b/rts/RtsFlags.c
@@ -298,15 +298,17 @@ usage_text[] = {
 "",
 "Usage: <prog> <args> [+RTS <rtsopts> | -RTS <args>] ... --RTS <args>",
 "",
-"   +RTS    Indicates run time system options follow",
-"   -RTS    Indicates program arguments follow",
-"  --RTS    Indicates that ALL subsequent arguments will be given to the",
-"           program (including any of these RTS flags)",
+"   +RTS     Indicates run time system options follow",
+"   -RTS     Indicates program arguments follow",
+"  --RTS     Indicates that ALL subsequent arguments will be given to the",
+"            program (including any of these RTS flags)",
 "",
-"The following run time system options are available:",
+"The following run time system options may be available (note that some",
+"of these may not be usable unless this program was linked with the -rtsopts",
+"flag):",
 "",
-"  -?       Prints this message and exits; the program is not executed",
-"  --info   Print information about the RTS used by this program",
+"  -?        Prints this message and exits; the program is not executed",
+"  --info    Print information about the RTS used by this program",
 "",
 "  --nonmoving-gc",
 "            Selects the non-moving mark-and-sweep garbage collector to",
@@ -315,12 +317,12 @@ usage_text[] = {
 "            Selects the copying garbage collector to manage all generations.",
 "",
 "  -K<size>  Sets the maximum stack size (default: 80% of the heap)",
-"            Egs: -K32k -K512k -K8M",
-"  -ki<size> Sets the initial thread stack size (default 1k)  Egs: -ki4k -ki2m",
+"            e.g.: -K32k -K512k -K8M",
+"  -ki<size> Sets the initial thread stack size (default 1k)  e.g.: -ki4k -ki2m",
 "  -kc<size> Sets the stack chunk size (default 32k)",
 "  -kb<size> Sets the stack chunk buffer size (default 1k)",
 "",
-"  -A<size>  Sets the minimum allocation area size (default 4m) Egs: -A20m -A10k",
+"  -A<size>  Sets the minimum allocation area size (default 4m) e.g.: -A20m -A10k",
 "  -AL<size> Sets the amount of large-object memory that can be allocated",
 "            before a GC is triggered (default: the value of -A)",
 "  -F<n>     Sets the collecting threshold for old generations as a factor of",
@@ -334,8 +336,8 @@ usage_text[] = {
 "            (default 4.0)",
 "  -n<size>  Allocation area chunk size (0 = disabled, default: 0)",
 "  -O<size>  Sets the minimum size of the old generation (default 1M)",
-"  -M<size>  Sets the maximum heap size (default unlimited)  Egs: -M256k -M1G",
-"  -H<size>  Sets the minimum heap size (default 0M)   Egs: -H24m  -H1G",
+"  -M<size>  Sets the maximum heap size (default unlimited)  e.g.: -M256k -M1G",
+"  -H<size>  Sets the minimum heap size (default 0M)   e.g.: -H24m  -H1G",
 "  -xb<addr> Sets the address from which a suitable start for the heap memory",
 "            will be searched from. This is useful if the default address",
 "            clashes with some third-party library.",
@@ -343,13 +345,13 @@ usage_text[] = {
 "  -m<n>     Minimum % of heap which must be available (default 3%)",
 "  -G<n>     Number of generations (default: 2)",
 "  -c<n>     Use in-place compaction instead of copying in the oldest generation",
-"           when live data is at least <n>% of the maximum heap size set with",
-"           -M (default: 30%)",
-"  -c       Use in-place compaction for all oldest generation collections",
-"           (the default is to use copying)",
-"  -w       Use mark-region for the oldest generation (experimental)",
+"            when live data is at least <n>% of the maximum heap size set with",
+"            -M (default: 30%)",
+"  -c        Use in-place compaction for all oldest generation collections",
+"            (the default is to use copying)",
+"  -w        Use mark-region for the oldest generation (experimental)",
 #if defined(THREADED_RTS)
-"  -I<sec>  Perform full GC after <sec> idle time (default: 0.3, 0 == off)",
+"  -I<sec>   Perform full GC after <sec> idle time (default: 0.3, 0 == off)",
 #endif
 "",
 "  -T         Collect GC statistics (useful for in-program statistics access)",
@@ -401,9 +403,10 @@ usage_text[] = {
 #endif /* PROFILING */
 
 "  -i<sec>  Time between heap profile samples (seconds, default: 0.1)",
-"  --no-automatic-heap-samples  Do not start the heap profile interval timer on start-up,",
-"                               Rather, the application will be responsible for triggering",
-"                               heap profiler samples."
+"  --no-automatic-heap-samples",
+"           Do not start the heap profile interval timer on start-up,",
+"           Rather, the application will be responsible for triggering",
+"           heap profiler samples."
 
 #if defined(TRACING)
 "",
@@ -428,7 +431,8 @@ usage_text[] = {
 #  endif
 "               -x    disable an event class, for any flag above",
 "             the initial enabled event classes are 'sgpu'",
-" --eventlog-flush-interval=<secs> Flush the eventlog at the specified interval.",
+" --eventlog-flush-interval=<secs>",
+"             Periodically flush the eventlog at the specified interval.",
 #endif
 
 "",
@@ -477,66 +481,66 @@ usage_text[] = {
 "  -N[<n>]    Use <n> processors (default: 1, -N alone determines",
 "             the number of processors to use automatically)",
 "  -maxN[<n>] Use up to <n> processors automatically",
-"  -qg[<n>]  Use parallel GC only for generations >= <n>",
-"            (default: 0, -qg alone turns off parallel GC)",
-"  -qb[<n>]  Use load-balancing in the parallel GC only for generations >= <n>",
-"            (default: 1 for -A < 32M, 0 otherwise;",
-"             -qb alone turns off load-balancing)",
-"  -qn<n>    Use <n> threads for parallel GC (defaults to value of -N)",
-"  -qa       Use the OS to set thread affinity (experimental)",
-"  -qm       Don't automatically migrate threads between CPUs",
-"  -qi<n>    If a processor has been idle for the last <n> GCs, do not",
-"            wake it up for a non-load-balancing parallel GC.",
-"            (0 disables,  default: 0)",
+"  -qg[<n>]   Use parallel GC only for generations >= <n>",
+"             (default: 0, -qg alone turns off parallel GC)",
+"  -qb[<n>]   Use load-balancing in the parallel GC only for generations >= <n>",
+"             (default: 1 for -A < 32M, 0 otherwise;",
+"              -qb alone turns off load-balancing)",
+"  -qn<n>     Use <n> threads for parallel GC (defaults to value of -N)",
+"  -qa        Use the OS to set thread affinity (experimental)",
+"  -qm        Don't automatically migrate threads between CPUs",
+"  -qi<n>     If a processor has been idle for the last <n> GCs, do not",
+"             wake it up for a non-load-balancing parallel GC.",
+"             (0 disables,  default: 0)",
 "  --numa[=<node_mask>]",
-"            Use NUMA, nodes given by <node_mask> (default: off)",
+"             Use NUMA, nodes given by <node_mask> (default: off)",
 #if defined(DEBUG)
 "  --debug-numa[=<num_nodes>]",
-"            Pretend NUMA: like --numa, but without the system calls.",
-"            Can be used on non-NUMA systems for debugging.",
+"             Pretend NUMA: like --numa, but without the system calls.",
+"             Can be used on non-NUMA systems for debugging.",
 "",
 #endif
 #endif
 "  --install-signal-handlers=<yes|no>",
-"            Install signal handlers (default: yes)",
+"             Install signal handlers (default: yes)",
 #if defined(mingw32_HOST_OS)
 "  --install-seh-handlers=<yes|no>",
-"            Install exception handlers (default: yes)",
+"             Install exception handlers (default: yes)",
 "  --generate-crash-dumps",
-"            Generate Windows crash dumps, requires exception handlers",
-"            to be installed. Implies --install-signal-handlers=yes.",
-"            (default: no)",
+"             Generate Windows crash dumps, requires exception handlers",
+"             to be installed. Implies --install-signal-handlers=yes.",
+"             (default: no)",
 "  --generate-stack-traces=<yes|no>",
-"            Generate a stack trace when your application encounters a",
-"            fatal error. When symbols are available an attempt will be",
-"            made to resolve addresses to names. (default: yes)",
+"             Generate a stack trace when your application encounters a",
+"             fatal error. When symbols are available an attempt will be",
+"             made to resolve addresses to names. (default: yes)",
 #endif
 "  --io-manager=<native|posix>",
-"            The I/O manager subsystem to use. (default: posix)",
+"             The I/O manager subsystem to use. (default: posix)",
 #if defined(THREADED_RTS)
 #if defined(mingw32_HOST_OS)
 "  --io-manager-threads=<num>",
-"            The number of worker threads to use in the native I/O manager to",
-"            handle completion events. (default: num cores)",
+"             The number of worker threads to use in the native I/O manager to",
+"             handle completion events. (default: num cores)",
 #endif
-"  -e<n>     Maximum number of outstanding local sparks (default: 4096)",
+"  -e<n>      Maximum number of outstanding local sparks (default: 4096)",
 #endif
 #if defined(x86_64_HOST_ARCH)
 #if !DEFAULT_LINKER_ALWAYS_PIC
-"  -xp       Assume that all object files were compiled with -fPIC",
-"            -fexternal-dynamic-refs and load them anywhere in the address",
-"            space",
+"  -xp        Assume that all object files were compiled with -fPIC",
+"             -fexternal-dynamic-refs and load them anywhere in the address",
+"             space",
 #endif
-"  -xm       Base address to mmap memory in the GHCi linker",
-"            (hex; must be <80000000)",
+"  -xm        Base address to mmap memory in the GHCi linker",
+"             (hex; must be <80000000)",
 #endif
-"  -xq       The allocation limit given to a thread after it receives",
-"            an AllocationLimitExceeded exception. (default: 100k)",
+"  -xq        The allocation limit given to a thread after it receives",
+"             an AllocationLimitExceeded exception. (default: 100k)",
 "",
 "  -Mgrace=<n>",
-"            The amount of allocation after the program receives a",
-"            HeapOverflow exception before the exception is thrown again, if",
-"            the program is still exceeding the heap limit.",
+"             The amount of allocation after the program receives a",
+"             HeapOverflow exception before the exception is thrown again, if",
+"             the program is still exceeding the heap limit.",
 "",
 "RTS options may also be specified using the GHCRTS environment variable.",
 "",