nhc98 runtime options

Programs compiled by nhc98 can be given runtime options independently of any command-line arguments that the program will interpret for itself. Options directed at the runtime system must be enclosed between +RTS and -RTS. Any command-line arguments not enclosed will be made available to the program as the return value of the System.getArgs library call.

Options for system resources.
-Hsize allocate a heap of specified size
-Vsize allocate a stack of specified size
-isize set the profiling interval to size

Memory sizes can be given in bytes or words, and may use symbols for Mega- and kilo-. Both upper and lower case are acceptable. For example, 2mw (2 Megawords), 4KB (4 kilobytes). If no units are specified, the default is bytes. A profiling interval may be given as the number of heap allocations, or in Mega-, kilo-, or milli- seconds. For example, 1Ms (1 Megasecond), 2ms (2 milliseconds), 1M (1 megabyte). If no units are specified, the default is allocations.

 Miscellaneous options.
-sgarbage collect statics
-Bprint progress info at every garbage collection (repeating the flag increases amount of info)
-Iturn on instruction counts (Only if runtime system was compiled with -DINSCOUNT=1)
-Xturn on Xlib debugging
-tturn on time profiling (see below)
Heap profiling options.
-p build a producer heap profile
-c build a construction heap profile
-m build a module heap profile
-r[num] build a retainer heap profile, with a maximum retainer set size of num (default=1).
-b build a biographical heap profile
-l build a lifetime heap profile
-pnames restrict profile to named producers
-cnames restrict profile to named constructions
-mnames restrict profile to named modules
-rnames restrict profile to named retainers
-bname restrict profile to named biographical phase (lag, drag, void, or use)
-lnums restrict profile to numbered lifetimes (min-, -max, or min-max)
-@ count application nodes during profiling
-u print usage during profiling
-1 first run (for biography/lifetime)
-2 second run (for biography/lifetime)

These options are only meaningful if the program has been compiled for heap profiling - otherwise they are ignored. The first occurrence of any of the options pcmrbl determines the primary form of the profile. Subsequent pcmrbl options introduce restrictions on the profile, for instance -p -c: asks for a producer profile restricted to producers of the `:' (list) construction. Restrictions are almost all orthogonal to each other, and you may have as many as you like. Except for biography and lifetime restrictions, the format is of a list of names, separated by commas. (In general, you may need to use quotes around the list to protect special characters from the shell.) The heap profile results are produced in a file named program.hp. Use the hp2graph tool to convert this to a Postscript or FrameMaker picture of the graph.

Time profiling options.
-tturn on time profiling
-tt order results by time consumed per function
-tc order results by number of calls per function
-tm group results by module
-txp give percentage of calls as well as percentage of time consumed
-txs count sub-function entries separately
-t-Module show only the total for all functions in named module
-t+Module show all functions separately in named module
-t+all show all functions separately in all modules
-t-all show only total-per-module for all modules

These options are only meaningful if the program has been compiled for time profiling - otherwise they are ignored. The various single-letter flags can be aggregated together, e.g. -tmt. You can give a list of module names separated by spaces using the shell quoting mechanism e.g. -t"+Prelude -Main +IO". The default is to show all functions written by the user separately, but only show the total for library modules (Prelude, IO, etc.).

The time profile results are produced in a file named program.tp.

The latest updates to these pages are available on the WWW from http://www.haskell.org/nhc98/

18th May 2001
York Functional Programming Group