From f6ac490e1358ef66a7a803b244102d1e14719df0 Mon Sep 17 00:00:00 2001 From: Ben Gamari Date: Tue, 25 Jan 2022 18:45:31 -0500 Subject: rts: Clean up RTS flags usage message Align flag descriptions and acknowledge that some flags may not be available unless the user linked with `-rtsopts` (as noted in #20961). Fixes #20961. --- rts/RtsFlags.c | 120 +++++++++++++++++++++++++++++---------------------------- 1 file 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: [+RTS | -RTS ] ... --RTS ", "", -" +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 Sets the maximum stack size (default: 80% of the heap)", -" Egs: -K32k -K512k -K8M", -" -ki Sets the initial thread stack size (default 1k) Egs: -ki4k -ki2m", +" e.g.: -K32k -K512k -K8M", +" -ki Sets the initial thread stack size (default 1k) e.g.: -ki4k -ki2m", " -kc Sets the stack chunk size (default 32k)", " -kb Sets the stack chunk buffer size (default 1k)", "", -" -A Sets the minimum allocation area size (default 4m) Egs: -A20m -A10k", +" -A Sets the minimum allocation area size (default 4m) e.g.: -A20m -A10k", " -AL Sets the amount of large-object memory that can be allocated", " before a GC is triggered (default: the value of -A)", " -F Sets the collecting threshold for old generations as a factor of", @@ -334,8 +336,8 @@ usage_text[] = { " (default 4.0)", " -n Allocation area chunk size (0 = disabled, default: 0)", " -O Sets the minimum size of the old generation (default 1M)", -" -M Sets the maximum heap size (default unlimited) Egs: -M256k -M1G", -" -H Sets the minimum heap size (default 0M) Egs: -H24m -H1G", +" -M Sets the maximum heap size (default unlimited) e.g.: -M256k -M1G", +" -H Sets the minimum heap size (default 0M) e.g.: -H24m -H1G", " -xb 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 Minimum % of heap which must be available (default 3%)", " -G Number of generations (default: 2)", " -c Use in-place compaction instead of copying in the oldest generation", -" when live data is at least % 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 % 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 Perform full GC after idle time (default: 0.3, 0 == off)", +" -I Perform full GC after 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 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= Flush the eventlog at the specified interval.", +" --eventlog-flush-interval=", +" Periodically flush the eventlog at the specified interval.", #endif "", @@ -477,66 +481,66 @@ usage_text[] = { " -N[] Use processors (default: 1, -N alone determines", " the number of processors to use automatically)", " -maxN[] Use up to processors automatically", -" -qg[] Use parallel GC only for generations >= ", -" (default: 0, -qg alone turns off parallel GC)", -" -qb[] Use load-balancing in the parallel GC only for generations >= ", -" (default: 1 for -A < 32M, 0 otherwise;", -" -qb alone turns off load-balancing)", -" -qn Use 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 If a processor has been idle for the last GCs, do not", -" wake it up for a non-load-balancing parallel GC.", -" (0 disables, default: 0)", +" -qg[] Use parallel GC only for generations >= ", +" (default: 0, -qg alone turns off parallel GC)", +" -qb[] Use load-balancing in the parallel GC only for generations >= ", +" (default: 1 for -A < 32M, 0 otherwise;", +" -qb alone turns off load-balancing)", +" -qn Use 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 If a processor has been idle for the last GCs, do not", +" wake it up for a non-load-balancing parallel GC.", +" (0 disables, default: 0)", " --numa[=]", -" Use NUMA, nodes given by (default: off)", +" Use NUMA, nodes given by (default: off)", #if defined(DEBUG) " --debug-numa[=]", -" 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=", -" Install signal handlers (default: yes)", +" Install signal handlers (default: yes)", #if defined(mingw32_HOST_OS) " --install-seh-handlers=", -" 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=", -" 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=", -" 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=", -" 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 Maximum number of outstanding local sparks (default: 4096)", +" -e 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=", -" 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.", "", -- cgit v1.2.1