674b8f73acc62896221fa1b14516f7d8a72d87ea
[ghc.git] / docs / users_guide / runtime_control.rst
1 .. _runtime-control:
2
3 Running a compiled program
4 ==========================
5
6 .. index::
7    single: runtime control of Haskell programs
8    single: running, compiled program
9    single: RTS options
10
11 To make an executable program, the GHC system compiles your code and
12 then links it with a non-trivial runtime system (RTS), which handles
13 storage management, thread scheduling, profiling, and so on.
14
15 The RTS has a lot of options to control its behaviour. For example, you
16 can change the context-switch interval, the default size of the heap,
17 and enable heap profiling. These options can be passed to the runtime
18 system in a variety of different ways; the next section
19 (:ref:`setting-rts-options`) describes the various methods, and the
20 following sections describe the RTS options themselves.
21
22 .. _setting-rts-options:
23
24 Setting RTS options
25 -------------------
26
27 .. index::
28    single: RTS options, setting
29
30 There are four ways to set RTS options:
31
32 -  on the command line between ``+RTS ... -RTS``, when running the
33    program (:ref:`rts-opts-cmdline`)
34
35 -  at compile-time, using :ghc-flag:`-with-rtsopts=⟨opts⟩`
36    (:ref:`rts-opts-compile-time`)
37
38 -  with the environment variable :envvar:`GHCRTS`
39    (:ref:`rts-options-environment`)
40
41 -  by overriding "hooks" in the runtime system (:ref:`rts-hooks`)
42
43 .. _rts-opts-cmdline:
44
45 Setting RTS options on the command line
46 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
47
48 .. index::
49    single: +RTS
50    single: -RTS
51    single: --RTS
52
53 If you set the :ghc-flag:`-rtsopts[=⟨none|some|all⟩]` flag appropriately when
54 linking (see :ref:`options-linker`), you can give RTS options on the command
55 line when running your program.
56
57 When your Haskell program starts up, the RTS extracts command-line
58 arguments bracketed between ``+RTS`` and ``-RTS`` as its own. For example:
59
60 .. code-block:: none
61
62     $ ghc prog.hs -rtsopts
63     [1 of 1] Compiling Main             ( prog.hs, prog.o )
64     Linking prog ...
65     $ ./prog -f +RTS -H32m -S -RTS -h foo bar
66
67 The RTS will snaffle ``-H32m -S`` for itself, and the remaining
68 arguments ``-f -h foo bar`` will be available to your program if/when it
69 calls ``System.Environment.getArgs``.
70
71 No ``-RTS`` option is required if the runtime-system options extend to
72 the end of the command line, as in this example:
73
74 .. code-block:: none
75
76     % hls -ltr /usr/etc +RTS -A5m
77
78 If you absolutely positively want all the rest of the options in a
79 command line to go to the program (and not the RTS), use a
80 ``--RTS``.
81
82 As always, for RTS options that take ⟨size⟩s: If the last character of
83 ⟨size⟩ is a K or k, multiply by 1000; if an M or m, by 1,000,000; if a G
84 or G, by 1,000,000,000. (And any wraparound in the counters is *your*
85 fault!)
86
87 Giving a ``+RTS -?`` RTS option option will print out the RTS
88 options actually available in your program (which vary, depending on how
89 you compiled).
90
91 .. note::
92     Since GHC is itself compiled by GHC, you can change RTS options in
93     the compiler using the normal ``+RTS ... -RTS`` combination. For instance, to set
94     the maximum heap size for a compilation to 128M, you would add
95     ``+RTS -M128m -RTS`` to the command line.
96
97 .. _rts-opts-compile-time:
98
99 Setting RTS options at compile time
100 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
101
102 GHC lets you change the default RTS options for a program at compile
103 time, using the ``-with-rtsopts`` flag (:ref:`options-linker`). A common
104 use for this is to give your program a default heap and/or stack size
105 that is greater than the default. For example, to set ``-H128m -K64m``,
106 link with ``-with-rtsopts="-H128m -K64m"``.
107
108 .. _rts-options-environment:
109
110 Setting RTS options with the ``GHCRTS`` environment variable
111 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
112
113 .. index::
114    single: RTS options; from the environment
115    single: environment variable; for setting RTS options
116    single: GHCRTS environment variable
117
118 .. envvar:: GHCRTS
119
120     If the ``-rtsopts`` flag is set to something other than ``none`` or ``ignoreAll``
121     when linking, RTS options are also taken from the environment variable
122     :envvar:`GHCRTS`. For example, to set the maximum heap size to 2G
123     for all GHC-compiled programs (using an ``sh``\-like shell):
124
125     .. code-block:: sh
126
127         GHCRTS='-M2G'
128         export GHCRTS
129
130     RTS options taken from the :envvar:`GHCRTS` environment variable can be
131     overridden by options given on the command line.
132
133 .. tip::
134     Setting something like ``GHCRTS=-M2G`` in your environment is a
135     handy way to avoid Haskell programs growing beyond the real memory in
136     your machine, which is easy to do by accident and can cause the machine
137     to slow to a crawl until the OS decides to kill the process (and you
138     hope it kills the right one).
139
140 .. _rts-hooks:
141
142 "Hooks" to change RTS behaviour
143 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
144
145 .. index::
146    single: hooks; RTS
147    single: RTS hooks
148    single: RTS behaviour, changing
149
150 GHC lets you exercise rudimentary control over certain RTS settings for
151 any given program, by compiling in a "hook" that is called by the
152 run-time system. The RTS contains stub definitions for these hooks, but
153 by writing your own version and linking it on the GHC command line, you
154 can override the defaults.
155
156 Owing to the vagaries of DLL linking, these hooks don't work under
157 Windows when the program is built dynamically.
158
159 Runtime events
160 ##############
161
162 You can change the messages printed when the runtime system "blows up,"
163 e.g., on stack overflow. The hooks for these are as follows:
164
165 .. c:function:: void OutOfHeapHook (unsigned long, unsigned long)
166
167     The heap-overflow message.
168
169 .. c:function:: void StackOverflowHook (long int)
170
171     The stack-overflow message.
172
173 .. c:function:: void MallocFailHook (long int)
174
175     The message printed if ``malloc`` fails.
176
177 Event log output
178 ################
179
180 Furthermore GHC lets you specify the way event log data (see :rts-flag:`-l`) is
181 written through a custom :c:type:`EventLogWriter`:
182
183 .. c:type:: EventLogWriter
184
185     A sink of event-log data.
186
187     .. c:member:: void initEventLogWriter(void)
188
189         Initializes your :c:type:`EventLogWriter`. This is optional.
190
191     .. c:member:: bool writeEventLog(void *eventlog, size_t eventlog_size)
192
193         Hands buffered event log data to your event log writer.
194         Required for a custom :c:type:`EventLogWriter`.
195
196     .. c:member:: void flushEventLog(void)
197
198         Flush buffers (if any) of your custom :c:type:`EventLogWriter`. This can
199         be ``NULL``.
200
201     .. c:member:: void stopEventLogWriter(void)
202
203         Called when event logging is about to stop. This can be ``NULL``.
204
205 .. _rts-options-misc:
206
207 Miscellaneous RTS options
208 -------------------------
209
210 .. rts-flag:: --install-signal-handlers=⟨yes|no⟩
211
212     If yes (the default), the RTS installs signal handlers to catch
213     things like :kbd:`Ctrl-C`. This option is primarily useful for when you are
214     using the Haskell code as a DLL, and want to set your own signal
215     handlers.
216
217     Note that even with ``--install-signal-handlers=no``, the RTS
218     interval timer signal is still enabled. The timer signal is either
219     SIGVTALRM or SIGALRM, depending on the RTS configuration and OS
220     capabilities. To disable the timer signal, use the ``-V0`` RTS
221     option (see :rts-flag:`-V ⟨secs⟩`).
222
223 .. rts-flag:: --install-seh-handlers=⟨yes|no⟩
224
225     If yes (the default), the RTS on Windows installs exception handlers to
226     catch unhandled exceptions using the Windows exception handling mechanism.
227     This option is primarily useful for when you are using the Haskell code as a
228     DLL, and don't want the RTS to ungracefully terminate your application on
229     erros such as segfaults.
230
231 .. rts-flag:: --generate-crash-dumps
232
233     If yes (the default), the RTS on Windows will generate a core dump on
234     any crash. These dumps can be inspected using debuggers such as WinDBG.
235     The dumps record all code, registers and threading information at the time
236     of the crash. Note that this implies `--install-seh-handlers=yes`.
237
238 .. rts-flag:: --generate-stack-traces=<yes|no>
239
240     If yes (the default), the RTS on Windows will generate a stack trace on
241     crashes if exception handling are enabled. In order to get more information
242     in compiled executables, C code or DLLs symbols need to be available.
243
244
245 .. rts-flag:: -xp
246
247     On 64-bit machines, the runtime linker usually needs to map object code
248     into the low 2Gb of the address space, due to the x86_64 small memory model
249     where most symbol references are 32 bits. The problem is that this 2Gb of
250     address space can fill up, especially if you're loading a very large number
251     of object files into GHCi.
252
253     This flag offers a workaround, albeit a slightly convoluted one. To be able
254     to load an object file outside of the low 2Gb, the object code needs to be
255     compiled with ``-fPIC -fexternal-dynamic-refs``. When the ``+RTS -xp`` flag
256     is passed, the linker will assume that all object files were compiled with
257     ``-fPIC -fexternal-dynamic-refs`` and load them anywhere in the address
258     space. It's up to you to arrange that the object files you load (including
259     all packages) were compiled in the right way. If this is not the case for
260     an object, the linker will probably fail with an error message when the
261     problem is detected.
262
263     On some platforms where PIC is always the case, e.g. x86_64 MacOS X, this
264     flag is enabled by default.
265
266 .. rts-flag:: -xm ⟨address⟩
267
268     .. index::
269        single: -xm; RTS option
270
271     .. warning::
272
273         This option is for working around memory allocation
274         problems only. Do not use unless GHCi fails with a message like
275         “\ ``failed to mmap() memory below 2Gb``\ ”. Consider recompiling
276         the objects with ``-fPIC -fexternal-dynamic-refs`` and using the
277         ``-xp`` flag instead. If you need to use this option to get GHCi
278         working on your machine, please file a bug.
279
280     On 64-bit machines, the RTS needs to allocate memory in the low 2Gb
281     of the address space. Support for this across different operating
282     systems is patchy, and sometimes fails. This option is there to give
283     the RTS a hint about where it should be able to allocate memory in
284     the low 2Gb of the address space. For example,
285     ``+RTS -xm20000000 -RTS`` would hint that the RTS should allocate
286     starting at the 0.5Gb mark. The default is to use the OS's built-in
287     support for allocating memory in the low 2Gb if available (e.g.
288     ``mmap`` with ``MAP_32BIT`` on Linux), or otherwise ``-xm40000000``.
289
290 .. rts-flag:: -xq ⟨size⟩
291
292     :default: 100k
293
294     This option relates to allocation limits; for more about this see
295     :base-ref:`GHC.Conc.enableAllocationLimit`.
296     When a thread hits its allocation limit, the RTS throws an exception
297     to the thread, and the thread gets an additional quota of allocation
298     before the exception is raised again, the idea being so that the
299     thread can execute its exception handlers. The ``-xq`` controls the
300     size of this additional quota.
301
302 .. _rts-options-gc:
303
304 RTS options to control the garbage collector
305 --------------------------------------------
306
307 .. index::
308    single: garbage collector; options
309    single: RTS options; garbage collection
310
311 There are several options to give you precise control over garbage
312 collection. Hopefully, you won't need any of these in normal operation,
313 but there are several things that can be tweaked for maximum
314 performance.
315
316 .. rts-flag:: -A ⟨size⟩
317
318     :default: 1MB
319
320     .. index::
321        single: allocation area, size
322
323     Set the allocation area size used by the garbage
324     collector. The allocation area (actually generation 0 step 0) is
325     fixed and is never resized (unless you use :rts-flag:`-H [⟨size⟩]`, below).
326
327     Increasing the allocation area size may or may not give better
328     performance (a bigger allocation area means worse cache behaviour
329     but fewer garbage collections and less promotion).
330
331     With only 1 generation (e.g. ``-G1``, see :rts-flag:`-G ⟨generations⟩`) the
332     ``-A`` option specifies the minimum allocation area, since the actual size
333     of the allocation area will be resized according to the amount of data in
334     the heap (see :rts-flag:`-F ⟨factor⟩`, below).
335
336 .. rts-flag:: -AL ⟨size⟩
337
338     :default: :rts-flag:`-A <-A ⟨size⟩>` value
339     :since: 8.2.1
340
341     .. index::
342        single: allocation area for large objects, size
343
344     Sets the limit on the total size of "large objects" (objects
345     larger than about 3KB) that can be allocated before a GC is
346     triggered. By default this limit is the same as the :rts-flag:`-A <-A
347     ⟨size⟩>` value.
348
349     Large objects are not allocated from the normal allocation area
350     set by the ``-A`` flag, which is why there is a separate limit for
351     these.  Large objects tend to be much rarer than small objects, so
352     most programs hit the ``-A`` limit before the ``-AL`` limit.  However,
353     the ``-A`` limit is per-capability, whereas the ``-AL`` limit is global,
354     so as ``-N`` gets larger it becomes more likely that we hit the
355     ``-AL`` limit first.  To counteract this, it might be necessary to
356     use a larger ``-AL`` limit when using a large ``-N``.
357
358     To see whether you're making good use of all the memory reseverd
359     for the allocation area (``-A`` times ``-N``), look at the output of
360     ``+RTS -S`` and check whether the amount of memory allocated between
361     GCs is equal to ``-A`` times ``-N``. If not, there are two possible
362     remedies: use ``-n`` to set a nursery chunk size, or use ``-AL`` to
363     increase the limit for large objects.
364
365 .. rts-flag:: -O ⟨size⟩
366
367     :default: 1m
368
369     .. index::
370        single: old generation, size
371
372     Set the minimum size of the old generation. The old generation is collected
373     whenever it grows to this size or the value of the :rts-flag:`-F ⟨factor⟩`
374     option multiplied by the size of the live data at the previous major
375     collection, whichever is larger.
376
377 .. rts-flag:: -n ⟨size⟩
378
379     :default: 4m with :rts-flag:`-A16m <-A ⟨size⟩>` or larger, otherwise 0.
380
381     .. index::
382        single: allocation area, chunk size
383
384     [Example: ``-n4m`` ] When set to a non-zero value, this
385     option divides the allocation area (``-A`` value) into chunks of the
386     specified size. During execution, when a processor exhausts its
387     current chunk, it is given another chunk from the pool until the
388     pool is exhausted, at which point a collection is triggered.
389
390     This option is only useful when running in parallel (``-N2`` or
391     greater). It allows the processor cores to make better use of the
392     available allocation area, even when cores are allocating at
393     different rates. Without ``-n``, each core gets a fixed-size
394     allocation area specified by the ``-A``, and the first core to
395     exhaust its allocation area triggers a GC across all the cores. This
396     can result in a collection happening when the allocation areas of
397     some cores are only partially full, so the purpose of the ``-n`` is
398     to allow cores that are allocating faster to get more of the
399     allocation area. This means less frequent GC, leading a lower GC
400     overhead for the same heap size.
401
402     This is particularly useful in conjunction with larger ``-A``
403     values, for example ``-A64m -n4m`` is a useful combination on larger core
404     counts (8+).
405
406 .. rts-flag:: -c
407
408     .. index::
409        single: garbage collection; compacting
410        single: compacting garbage collection
411
412     Use a compacting algorithm for collecting the oldest generation. By
413     default, the oldest generation is collected using a copying
414     algorithm; this option causes it to be compacted in-place instead.
415     The compaction algorithm is slower than the copying algorithm, but
416     the savings in memory use can be considerable.
417
418     For a given heap size (using the :ghc-flag:`-H ⟨size⟩` option), compaction
419     can in fact reduce the GC cost by allowing fewer GCs to be performed. This
420     is more likely when the ratio of live data to heap size is high, say
421     greater than 30%.
422
423     .. note::
424        Compaction doesn't currently work when a single generation is
425        requested using the ``-G1`` option.
426
427 .. rts-flag:: -c ⟨n⟩
428
429     :default: 30
430
431     Automatically enable compacting collection when the live data exceeds ⟨n⟩%
432     of the maximum heap size (see the :rts-flag:`-M ⟨size⟩` option). Note that
433     the maximum heap size is unlimited by default, so this option has no effect
434     unless the maximum heap size is set with :rts-flag:`-M ⟨size⟩`.
435
436 .. rts-flag:: -F ⟨factor⟩
437
438     :default: 2
439
440     .. index::
441        single: heap size, factor
442
443     This option controls the amount of memory reserved for
444     the older generations (and in the case of a two space collector the
445     size of the allocation area) as a factor of the amount of live data.
446     For example, if there was 2M of live data in the oldest generation
447     when we last collected it, then by default we'll wait until it grows
448     to 4M before collecting it again.
449
450     The default seems to work well here. If you have plenty of memory, it is
451     usually better to use ``-H ⟨size⟩`` (see :rts-flag:`-H [⟨size⟩]`) than to
452     increase :rts-flag:`-F ⟨factor⟩`.
453
454     The :rts-flag:`-F ⟨factor⟩` setting will be automatically reduced by the garbage
455     collector when the maximum heap size (the :rts-flag:`-M ⟨size⟩` setting) is approaching.
456
457 .. rts-flag:: -G ⟨generations⟩
458
459     :default: 2
460
461     .. index::
462        single: generations, number of
463
464     Set the number of generations used by the garbage
465     collector. The default of 2 seems to be good, but the garbage
466     collector can support any number of generations. Anything larger
467     than about 4 is probably not a good idea unless your program runs
468     for a *long* time, because the oldest generation will hardly ever
469     get collected.
470
471     Specifying 1 generation with ``+RTS -G1`` gives you a simple 2-space
472     collector, as you would expect. In a 2-space collector, the :rts-flag:`-A
473     ⟨size⟩` option specifies the *minimum* allocation area size, since the
474     allocation area will grow with the amount of live data in the heap. In a
475     multi-generational collector the allocation area is a fixed size (unless
476     you use the :rts-flag:`-H [⟨size⟩]` option).
477
478 .. rts-flag:: -qg ⟨gen⟩
479
480     :default: 0
481     :since: 6.12.1
482
483     Use parallel GC in generation ⟨gen⟩ and higher. Omitting ⟨gen⟩ turns off the
484     parallel GC completely, reverting to sequential GC.
485
486     The default parallel GC settings are usually suitable for parallel programs
487     (i.e. those using :base-ref:`GHC.Conc.par`, Strategies, or with
488     multiple threads). However, it is sometimes beneficial to enable the
489     parallel GC for a single-threaded sequential program too, especially if the
490     program has a large amount of heap data and GC is a significant fraction of
491     runtime. To use the parallel GC in a sequential program, enable the parallel
492     runtime with a suitable :rts-flag:`-N ⟨x⟩` option, and additionally it might
493     be beneficial to restrict parallel GC to the old generation with ``-qg1``.
494
495 .. rts-flag:: -qb ⟨gen⟩
496
497     :default: 1 for :rts-flag:`-A <-A ⟨size⟩>` < 32M, 0 otherwise
498     :since: 6.12.1
499
500     Use load-balancing in the parallel GC in generation ⟨gen⟩ and higher.
501     Omitting ⟨gen⟩ disables load-balancing entirely.
502
503     Load-balancing shares out the work of GC between the available
504     cores. This is a good idea when the heap is large and we need to
505     parallelise the GC work, however it is also pessimal for the short
506     young-generation collections in a parallel program, because it can
507     harm locality by moving data from the cache of the CPU where is it
508     being used to the cache of another CPU. Hence the default is to do
509     load-balancing only in the old-generation. In fact, for a parallel
510     program it is sometimes beneficial to disable load-balancing
511     entirely with ``-qb``.
512
513 .. rts-flag:: -qn ⟨x⟩
514
515     :default: the value of :rts-flag:`-N <-N ⟨x⟩>` or the number of CPU cores,
516               whichever is smaller.
517     :since: 8.2.1
518
519     .. index::
520        single: GC threads, setting the number of
521
522     By default, all of the capabilities participate in parallel
523     garbage collection.  If we want to use a very large ``-N`` value,
524     however, this can reduce the performance of the GC.  For this
525     reason, the ``-qn`` flag can be used to specify a lower number for
526     the threads that should participate in GC.  During GC, if there
527     are more than this number of workers active, some of them will
528     sleep for the duration of the GC.
529
530     The ``-qn`` flag may be useful when running with a large ``-A`` value
531     (so that GC is infrequent), and a large ``-N`` value (so as to make
532     use of hyperthreaded cores, for example).  For example, on a
533     24-core machine with 2 hyperthreads per core, we might use
534     ``-N48 -qn24 -A128m`` to specify that the mutator should use
535     hyperthreads but the GC should only use real cores.  Note that
536     this configuration would use 6GB for the allocation area.
537
538 .. rts-flag:: -H [⟨size⟩]
539
540     :default: 0
541
542     .. index::
543        single: heap size, suggested
544
545     This option provides a "suggested heap size" for the garbage collector.
546     Think of ``-Hsize`` as a variable :rts-flag:`-A ⟨size⟩` option.  It says: I
547     want to use at least ⟨size⟩ bytes, so use whatever is left over to increase
548     the ``-A`` value.
549
550     This option does not put a *limit* on the heap size: the heap may
551     grow beyond the given size as usual.
552
553     If ⟨size⟩ is omitted, then the garbage collector will take the size
554     of the heap at the previous GC as the ⟨size⟩. This has the effect of
555     allowing for a larger ``-A`` value but without increasing the
556     overall memory requirements of the program. It can be useful when
557     the default small ``-A`` value is suboptimal, as it can be in
558     programs that create large amounts of long-lived data.
559
560 .. rts-flag:: -I ⟨seconds⟩
561
562     :default: 0.3 seconds in the threaded runtime, 0 in the non-threaded runtime
563
564     .. index::
565        single: idle GC
566
567     In the threaded and SMP versions of the RTS (see
568     :ghc-flag:`-threaded`, :ref:`options-linker`), a major GC is automatically
569     performed if the runtime has been idle (no Haskell computation has
570     been running) for a period of time. The amount of idle time which
571     must pass before a GC is performed is set by the ``-I ⟨seconds⟩``
572     option. Specifying ``-I0`` disables the idle GC.
573
574     For an interactive application, it is probably a good idea to use
575     the idle GC, because this will allow finalizers to run and
576     deadlocked threads to be detected in the idle time when no Haskell
577     computation is happening. Also, it will mean that a GC is less
578     likely to happen when the application is busy, and so responsiveness
579     may be improved. However, if the amount of live data in the heap is
580     particularly large, then the idle GC can cause a significant delay,
581     and too small an interval could adversely affect interactive
582     responsiveness.
583
584     This is an experimental feature, please let us know if it causes
585     problems and/or could benefit from further tuning.
586
587 .. rts-flag:: -ki ⟨size⟩
588
589     :default: 1k
590
591     .. index::
592        single: stack, initial size
593
594     Set the initial stack size for new threads.
595
596     Thread stacks (including the main thread's stack) live on the heap.
597     As the stack grows, new stack chunks are added as required; if the
598     stack shrinks again, these extra stack chunks are reclaimed by the
599     garbage collector. The default initial stack size is deliberately
600     small, in order to keep the time and space overhead for thread
601     creation to a minimum, and to make it practical to spawn threads for
602     even tiny pieces of work.
603
604     .. note::
605         This flag used to be simply ``-k``, but was renamed to ``-ki`` in
606         GHC 7.2.1. The old name is still accepted for backwards
607         compatibility, but that may be removed in a future version.
608
609 .. rts-flag:: -kc ⟨size⟩
610
611     :default: 32k
612
613     .. index::
614        single: stack; chunk size
615
616     Set the size of "stack chunks". When a thread's current stack overflows, a
617     new stack chunk is created and added to the thread's stack, until the limit
618     set by :rts-flag:`-K ⟨size⟩` is reached.
619
620     The advantage of smaller stack chunks is that the garbage collector can
621     avoid traversing stack chunks if they are known to be unmodified since the
622     last collection, so reducing the chunk size means that the garbage
623     collector can identify more stack as unmodified, and the GC overhead might
624     be reduced. On the other hand, making stack chunks too small adds some
625     overhead as there will be more overflow/underflow between chunks. The
626     default setting of 32k appears to be a reasonable compromise in most cases.
627
628 .. rts-flag:: -kb ⟨size⟩
629
630     :default: 1k
631
632     .. index::
633        single: stack; chunk buffer size
634
635     Sets the stack chunk buffer size. When a stack chunk
636     overflows and a new stack chunk is created, some of the data from
637     the previous stack chunk is moved into the new chunk, to avoid an
638     immediate underflow and repeated overflow/underflow at the boundary.
639     The amount of stack moved is set by the ``-kb`` option.
640
641     Note that to avoid wasting space, this value should typically be less than
642     10% of the size of a stack chunk (:rts-flag:`-kc ⟨size⟩`), because in a
643     chain of stack chunks, each chunk will have a gap of unused space of this
644     size.
645
646 .. rts-flag:: -K ⟨size⟩
647
648     :default: 80% of physical memory
649
650     .. index::
651        single: stack, maximum size
652
653     Set the maximum stack size for
654     an individual thread to ⟨size⟩ bytes. If the thread attempts to
655     exceed this limit, it will be sent the ``StackOverflow`` exception.
656     The limit can be disabled entirely by specifying a size of zero.
657
658     This option is there mainly to stop the program eating up all the
659     available memory in the machine if it gets into an infinite loop.
660
661 .. rts-flag:: -m ⟨n⟩
662
663     :default: 3%
664
665     .. index::
666        single: heap, minimum free
667
668     Minimum % ⟨n⟩ of heap which must be available for allocation.
669
670 .. rts-flag:: -M ⟨size⟩
671
672     :default: unlimited
673
674     .. index::
675        single: heap size, maximum
676
677     Set the maximum heap size to ⟨size⟩ bytes. The
678     heap normally grows and shrinks according to the memory requirements
679     of the program. The only reason for having this option is to stop
680     the heap growing without bound and filling up all the available swap
681     space, which at the least will result in the program being summarily
682     killed by the operating system.
683
684     The maximum heap size also affects other garbage collection
685     parameters: when the amount of live data in the heap exceeds a
686     certain fraction of the maximum heap size, compacting collection
687     will be automatically enabled for the oldest generation, and the
688     ``-F`` parameter will be reduced in order to avoid exceeding the
689     maximum heap size.
690
691 .. rts-flag:: -Mgrace=⟨size⟩
692
693     :default: 1M
694
695     .. index::
696        single: heap size, grace
697
698     If the program's heap exceeds the value set by :rts-flag:`-M ⟨size⟩`, the
699     RTS throws an exception to the program, and the program gets an
700     additional quota of allocation before the exception is raised
701     again, the idea being so that the program can execute its
702     exception handlers. ``-Mgrace=`` controls the size of this
703     additional quota.
704
705 .. rts-flag:: --numa
706               --numa=<mask>
707
708     .. index::
709        single: NUMA, enabling in the runtime
710
711     Enable NUMA-aware memory allocation in the runtime (only available
712     with ``-threaded``, and only on Linux and Windows currently).
713
714     Background: some systems have a Non-Uniform Memory Architecture,
715     whereby main memory is split into banks which are "local" to
716     specific CPU cores.  Accessing local memory is faster than
717     accessing remote memory.  The OS provides APIs for allocating
718     local memory and binding threads to particular CPU cores, so that
719     we can ensure certain memory accesses are using local memory.
720
721     The ``--numa`` option tells the RTS to tune its memory usage to
722     maximize local memory accesses.  In particular, the RTS will:
723
724        - Determine the number of NUMA nodes (N) by querying the OS.
725        - Manage separate memory pools for each node.
726        - Map capabilities to NUMA nodes.  Capability C is mapped to
727          NUMA node C mod N.
728        - Bind worker threads on a capability to the appropriate node.
729        - Allocate the nursery from node-local memory.
730        - Perform other memory allocation, including in the GC, from
731          node-local memory.
732        - When load-balancing, we prefer to migrate threads to another
733          Capability on the same node.
734
735     The ``--numa`` flag is typically beneficial when a program is
736     using all cores of a large multi-core NUMA system, with a large
737     allocation area (``-A``).  All memory accesses to the allocation
738     area will go to local memory, which can save a significant amount
739     of remote memory access.  A runtime speedup on the order of 10%
740     is typical, but can vary a lot depending on the hardware and the
741     memory behaviour of the program.
742
743     Note that the RTS will not set CPU affinity for bound threads and
744     threads entering Haskell from C/C++, so if your program uses bound
745     threads you should ensure that each bound thread calls the RTS API
746     `rts_setInCallCapability(c,1)` from C/C++ before calling into
747     Haskell.  Otherwise there could be a mismatch between the CPU that
748     the thread is running on and the memory it is using while running
749     Haskell code, which will negate any benefits of ``--numa``.
750
751     If given an explicit <mask>, the <mask> is interpreted as a bitmap
752     that indicates the NUMA nodes on which to run the program.  For
753     example, ``--numa=3`` would run the program on NUMA nodes 0 and 1.
754
755 .. rts-flag:: --long-gc-sync
756               --long-gc-sync=<seconds>
757
758     .. index::
759        single: GC sync time, measuring
760
761     When a GC starts, all the running mutator threads have to stop and
762     synchronise.  The period between when the GC is initiated and all
763     the mutator threads are stopped is called the GC synchronisation
764     phase. If this phase is taking a long time (longer than 1ms is
765     considered long), then it can have a severe impact on overall
766     throughput.
767
768     A long GC sync can be caused by a mutator thread that is inside an
769     ``unsafe`` FFI call, or running in a loop that doesn't allocate
770     memory and so doesn't yield.  To fix the former, make the call
771     ``safe``, and to fix the latter, either avoid calling the code in
772     question or compile it with :ghc-flag:`-fomit-yields`.
773
774     By default, the flag will cause a warning to be emitted to stderr
775     when the sync time exceeds the specified time.  This behaviour can
776     be overriden, however: the ``longGCSync()`` hook is called when
777     the sync time is exceeded during the sync period, and the
778     ``longGCSyncEnd()`` hook at the end. Both of these hooks can be
779     overriden in the ``RtsConfig`` when the runtime is started with
780     ``hs_init_ghc()``. The default implementations of these hooks
781     (``LongGcSync()`` and ``LongGCSyncEnd()`` respectively) print
782     warnings to stderr.
783
784     One way to use this flag is to set a breakpoint on
785     ``LongGCSync()`` in the debugger, and find the thread that is
786     delaying the sync. You probably want to use :ghc-flag:`-g` to
787     provide more info to the debugger.
788
789     The GC sync time, along with other GC stats, are available by
790     calling the ``getRTSStats()`` function from C, or
791     ``GHC.Stats.getRTSStats`` from Haskell.
792
793 .. _rts-options-statistics:
794
795 RTS options to produce runtime statistics
796 -----------------------------------------
797
798 .. rts-flag:: -T
799               -t [⟨file⟩]
800               -s [⟨file⟩]
801               -S [⟨file⟩]
802               --machine-readable
803               --internal-counters
804
805     These options produce runtime-system statistics, such as the amount
806     of time spent executing the program and in the garbage collector,
807     the amount of memory allocated, the maximum size of the heap, and so
808     on. The three variants give different levels of detail: ``-T``
809     collects the data but produces no output ``-t`` produces a single
810     line of output in the same format as GHC's ``-Rghc-timing`` option,
811     ``-s`` produces a more detailed summary at the end of the program,
812     and ``-S`` additionally produces information about each and every
813     garbage collection. Passing ``--internal-counters`` to a threaded
814     runtime will cause a detailed summary to include various internal
815     counts accumulated during the run; note that these are unspecified
816     and may change between releases.
817
818     The output is placed in ⟨file⟩. If ⟨file⟩ is omitted, then the
819     output is sent to ``stderr``.
820
821     If you use the ``-T`` flag then, you should access the statistics
822     using :base-ref:`GHC.Stats.`.
823
824     If you use the ``-t`` flag then, when your program finishes, you
825     will see something like this:
826
827     .. code-block:: none
828
829         <<ghc: 36169392 bytes, 69 GCs, 603392/1065272 avg/max bytes residency (2 samples), 3M in use, 0.00 INIT (0.00 elapsed), 0.02 MUT (0.02 elapsed), 0.07 GC (0.07 elapsed) :ghc>>
830
831     This tells you:
832
833     -  The total number of bytes allocated by the program over the whole
834        run.
835
836     -  The total number of garbage collections performed.
837
838     -  The average and maximum "residency", which is the amount of live
839        data in bytes. The runtime can only determine the amount of live
840        data during a major GC, which is why the number of samples
841        corresponds to the number of major GCs (and is usually relatively
842        small). To get a better picture of the heap profile of your
843        program, use the :rts-flag:`-hT` RTS option (:ref:`rts-profiling`).
844
845     -  The peak memory the RTS has allocated from the OS.
846
847     -  The amount of CPU time and elapsed wall clock time while
848        initialising the runtime system (INIT), running the program
849        itself (MUT, the mutator), and garbage collecting (GC).
850
851     You can also get this in a more future-proof, machine readable
852     format, with ``-t --machine-readable``:
853
854     ::
855
856          [("bytes allocated", "36169392")
857          ,("num_GCs", "69")
858          ,("average_bytes_used", "603392")
859          ,("max_bytes_used", "1065272")
860          ,("num_byte_usage_samples", "2")
861          ,("peak_megabytes_allocated", "3")
862          ,("init_cpu_seconds", "0.00")
863          ,("init_wall_seconds", "0.00")
864          ,("mutator_cpu_seconds", "0.02")
865          ,("mutator_wall_seconds", "0.02")
866          ,("GC_cpu_seconds", "0.07")
867          ,("GC_wall_seconds", "0.07")
868          ]
869
870     If you use the ``-s`` flag then, when your program finishes, you
871     will see something like this (the exact details will vary depending
872     on what sort of RTS you have, e.g. you will only see profiling data
873     if your RTS is compiled for profiling):
874
875     .. code-block:: none
876
877               36,169,392 bytes allocated in the heap
878                4,057,632 bytes copied during GC
879                1,065,272 bytes maximum residency (2 sample(s))
880                   54,312 bytes maximum slop
881                        3 MB total memory in use (0 MB lost due to fragmentation)
882
883           Generation 0:    67 collections,     0 parallel,  0.04s,  0.03s elapsed
884           Generation 1:     2 collections,     0 parallel,  0.03s,  0.04s elapsed
885
886           SPARKS: 359207 (557 converted, 149591 pruned)
887
888           INIT  time    0.00s  (  0.00s elapsed)
889           MUT   time    0.01s  (  0.02s elapsed)
890           GC    time    0.07s  (  0.07s elapsed)
891           EXIT  time    0.00s  (  0.00s elapsed)
892           Total time    0.08s  (  0.09s elapsed)
893
894           %GC time      89.5%  (75.3% elapsed)
895
896           Alloc rate    4,520,608,923 bytes per MUT second
897
898           Productivity  10.5% of total user, 9.1% of total elapsed
899
900     -  The "bytes allocated in the heap" is the total bytes allocated by
901        the program over the whole run.
902
903     -  GHC uses a copying garbage collector by default. "bytes copied
904        during GC" tells you how many bytes it had to copy during garbage
905        collection.
906
907     -  The maximum space actually used by your program is the "bytes
908        maximum residency" figure. This is only checked during major
909        garbage collections, so it is only an approximation; the number
910        of samples tells you how many times it is checked.
911
912     -  The "bytes maximum slop" tells you the most space that is ever
913        wasted due to the way GHC allocates memory in blocks. Slop is
914        memory at the end of a block that was wasted. There's no way to
915        control this; we just like to see how much memory is being lost
916        this way.
917
918     -  The "total memory in use" tells you the peak memory the RTS has
919        allocated from the OS.
920
921     -  Next there is information about the garbage collections done. For
922        each generation it says how many garbage collections were done,
923        how many of those collections were done in parallel, the total
924        CPU time used for garbage collecting that generation, and the
925        total wall clock time elapsed while garbage collecting that
926        generation.
927
928     -  The ``SPARKS`` statistic refers to the use of
929        ``Control.Parallel.par`` and related functionality in the
930        program. Each spark represents a call to ``par``; a spark is
931        "converted" when it is executed in parallel; and a spark is
932        "pruned" when it is found to be already evaluated and is
933        discarded from the pool by the garbage collector. Any remaining
934        sparks are discarded at the end of execution, so "converted" plus
935        "pruned" does not necessarily add up to the total.
936
937     -  Next there is the CPU time and wall clock time elapsed broken
938        down by what the runtime system was doing at the time. INIT is
939        the runtime system initialisation. MUT is the mutator time, i.e.
940        the time spent actually running your code. GC is the time spent
941        doing garbage collection. RP is the time spent doing retainer
942        profiling. PROF is the time spent doing other profiling. EXIT is
943        the runtime system shutdown time. And finally, Total is, of
944        course, the total.
945
946        %GC time tells you what percentage GC is of Total. "Alloc rate"
947        tells you the "bytes allocated in the heap" divided by the MUT
948        CPU time. "Productivity" tells you what percentage of the Total
949        CPU and wall clock elapsed times are spent in the mutator (MUT).
950
951     The ``-S`` flag, as well as giving the same output as the ``-s``
952     flag, prints information about each GC as it happens:
953
954     .. code-block:: none
955
956             Alloc    Copied     Live    GC    GC     TOT     TOT  Page Flts
957             bytes     bytes     bytes  user  elap    user    elap
958            528496     47728    141512  0.01  0.02    0.02    0.02    0    0  (Gen:  1)
959         [...]
960            524944    175944   1726384  0.00  0.00    0.08    0.11    0    0  (Gen:  0)
961
962     For each garbage collection, we print:
963
964     -  How many bytes we allocated this garbage collection.
965
966     -  How many bytes we copied this garbage collection.
967
968     -  How many bytes are currently live.
969
970     -  How long this garbage collection took (CPU time and elapsed wall
971        clock time).
972
973     -  How long the program has been running (CPU time and elapsed wall
974        clock time).
975
976     -  How many page faults occurred this garbage collection.
977
978     -  How many page faults occurred since the end of the last garbage
979        collection.
980
981     -  Which generation is being garbage collected.
982
983 RTS options for concurrency and parallelism
984 -------------------------------------------
985
986 The RTS options related to concurrency are described in
987 :ref:`using-concurrent`, and those for parallelism in
988 :ref:`parallel-options`.
989
990 .. _rts-profiling:
991
992 RTS options for profiling
993 -------------------------
994
995 Most profiling runtime options are only available when you compile your
996 program for profiling (see :ref:`prof-compiler-options`, and
997 :ref:`rts-options-heap-prof` for the runtime options). However, there is
998 one profiling option that is available for ordinary non-profiled
999 executables:
1000
1001 .. rts-flag:: -hT
1002               -h
1003
1004     Generates a basic heap profile, in the file :file:`prog.hp`. To produce the
1005     heap profile graph, use :command:`hp2ps` (see :ref:`hp2ps`). The basic heap
1006     profile is broken down by data constructor, with other types of closures
1007     (functions, thunks, etc.) grouped into broad categories (e.g. ``FUN``,
1008     ``THUNK``). To get a more detailed profile, use the full profiling support
1009     (:ref:`profiling`). Can be shortened to :rts-flag:`-h`.
1010
1011 .. rts-flag:: -L ⟨n⟩
1012
1013     :default: 25 characters
1014
1015     Sets the maximum length of the cost-centre names listed in the heap profile.
1016
1017 .. _rts-eventlog:
1018
1019 Tracing
1020 -------
1021
1022 .. index::
1023    single: tracing
1024    single: events
1025    single: eventlog files
1026
1027 When the program is linked with the :ghc-flag:`-eventlog` option
1028 (:ref:`options-linker`), runtime events can be logged in several ways:
1029
1030 -  In binary format to a file for later analysis by a variety of tools.
1031    One such tool is
1032    `ThreadScope <http://www.haskell.org/haskellwiki/ThreadScope>`__,
1033    which interprets the event log to produce a visual parallel execution
1034    profile of the program.
1035
1036 -  In binary format to customized event log writer. This enables live
1037    analysis of the events while the program is running.
1038
1039 -  As text to standard output, for debugging purposes.
1040
1041 .. rts-flag:: -l ⟨flags⟩
1042
1043     Log events in binary format. Without any ⟨flags⟩ specified, this
1044     logs a default set of events, suitable for use with tools like ThreadScope.
1045
1046     Per default the events are written to :file:`{program}.eventlog` though
1047     the mechanism for writing event log data can be overriden with a custom
1048     `EventLogWriter`.
1049
1050     For some special use cases you may want more control over which
1051     events are included. The ⟨flags⟩ is a sequence of zero or more
1052     characters indicating which classes of events to log. Currently
1053     these the classes of events that can be enabled/disabled:
1054
1055     - ``s`` — scheduler events, including Haskell thread creation and start/stop
1056       events. Enabled by default.
1057
1058     - ``g`` — GC events, including GC start/stop. Enabled by default.
1059
1060     - ``p`` — parallel sparks (sampled). Enabled by default.
1061
1062     - ``f`` — parallel sparks (fully accurate). Disabled by default.
1063
1064     - ``u`` — user events. These are events emitted from Haskell code using
1065       functions such as ``Debug.Trace.traceEvent``. Enabled by default.
1066
1067     You can disable specific classes, or enable/disable all classes at
1068     once:
1069
1070     - ``a`` — enable all event classes listed above
1071     - ``-⟨x⟩`` — disable the given class of events, for any event class listed above
1072     - ``-a`` — disable all classes
1073
1074     For example, ``-l-ag`` would disable all event classes (``-a``) except for
1075     GC events (``g``).
1076
1077     For spark events there are two modes: sampled and fully accurate.
1078     There are various events in the life cycle of each spark, usually
1079     just creating and running, but there are some more exceptional
1080     possibilities. In the sampled mode the number of occurrences of each
1081     kind of spark event is sampled at frequent intervals. In the fully
1082     accurate mode every spark event is logged individually. The latter
1083     has a higher runtime overhead and is not enabled by default.
1084
1085     The format of the log file is described by the header
1086     ``EventLogFormat.h`` that comes with GHC, and it can be parsed in
1087     Haskell using the
1088     `ghc-events <http://hackage.haskell.org/package/ghc-events>`__
1089     library. To dump the contents of a ``.eventlog`` file as text, use
1090     the tool ``ghc-events show`` that comes with the
1091     `ghc-events <http://hackage.haskell.org/package/ghc-events>`__
1092     package.
1093
1094 .. rts-flag:: -v [⟨flags⟩]
1095
1096     Log events as text to standard output, instead of to the
1097     ``.eventlog`` file. The ⟨flags⟩ are the same as for ``-l``, with the
1098     additional option ``t`` which indicates that the each event printed
1099     should be preceded by a timestamp value (in the binary ``.eventlog``
1100     file, all events are automatically associated with a timestamp).
1101
1102 The debugging options ``-Dx`` also generate events which are logged
1103 using the tracing framework. By default those events are dumped as text
1104 to stdout (``-Dx`` implies ``-v``), but they may instead be stored in
1105 the binary eventlog file by using the ``-l`` option.
1106
1107 .. _rts-options-debugging:
1108
1109 RTS options for hackers, debuggers, and over-interested souls
1110 -------------------------------------------------------------
1111
1112 .. index::
1113    single: RTS options, hacking/debugging
1114
1115 These RTS options might be used (a) to avoid a GHC bug, (b) to see
1116 "what's really happening", or (c) because you feel like it. Not
1117 recommended for everyday use!
1118
1119 .. rts-flag:: -B
1120
1121     Sound the bell at the start of each (major) garbage collection.
1122
1123     Oddly enough, people really do use this option! Our pal in Durham
1124     (England), Paul Callaghan, writes: “Some people here use it for a
1125     variety of purposes—honestly!—e.g., confirmation that the
1126     code/machine is doing something, infinite loop detection, gauging
1127     cost of recently added code. Certain people can even tell what stage
1128     [the program] is in by the beep pattern. But the major use is for
1129     annoying others in the same office…”
1130
1131 .. rts-flag:: -D ⟨x⟩
1132
1133     An RTS debugging flag; only available if the program was linked with
1134     the :ghc-flag:`-debug` option. Various values of ⟨x⟩ are provided to enable
1135     debug messages and additional runtime sanity checks in different
1136     subsystems in the RTS, for example ``+RTS -Ds -RTS`` enables debug
1137     messages from the scheduler. Use ``+RTS -?`` to find out which debug
1138     flags are supported.
1139
1140     Debug messages will be sent to the binary event log file instead of
1141     stdout if the :rts-flag:`-l` option is added. This might be useful for
1142     reducing the overhead of debug tracing.
1143
1144 .. rts-flag:: -r ⟨file⟩
1145
1146     .. index::
1147        single: ticky ticky profiling
1148        single: profiling; ticky ticky
1149
1150     Produce "ticky-ticky" statistics at the end of the program run (only
1151     available if the program was linked with :ghc-flag:`-debug`). The ⟨file⟩
1152     business works just like on the :rts-flag:`-S [⟨file⟩]` RTS option, above.
1153
1154     For more information on ticky-ticky profiling, see
1155     :ref:`ticky-ticky`.
1156
1157 .. rts-flag:: -xc
1158
1159     (Only available when the program is compiled for profiling.) When an
1160     exception is raised in the program, this option causes a stack trace
1161     to be dumped to ``stderr``.
1162
1163     This can be particularly useful for debugging: if your program is
1164     complaining about a ``head []`` error and you haven't got a clue
1165     which bit of code is causing it, compiling with
1166     ``-prof -fprof-auto`` (see :ghc-flag:`-prof`) and running with ``+RTS -xc
1167     -RTS`` will tell you exactly the call stack at the point the error was
1168     raised.
1169
1170     The output contains one report for each exception raised in the
1171     program (the program might raise and catch several exceptions during
1172     its execution), where each report looks something like this:
1173
1174     .. code-block:: none
1175
1176         *** Exception raised (reporting due to +RTS -xc), stack trace:
1177           GHC.List.CAF
1178           --> evaluated by: Main.polynomial.table_search,
1179           called from Main.polynomial.theta_index,
1180           called from Main.polynomial,
1181           called from Main.zonal_pressure,
1182           called from Main.make_pressure.p,
1183           called from Main.make_pressure,
1184           called from Main.compute_initial_state.p,
1185           called from Main.compute_initial_state,
1186           called from Main.CAF
1187           ...
1188
1189     The stack trace may often begin with something uninformative like
1190     ``GHC.List.CAF``; this is an artifact of GHC's optimiser, which
1191     lifts out exceptions to the top-level where the profiling system
1192     assigns them to the cost centre "CAF". However, ``+RTS -xc`` doesn't
1193     just print the current stack, it looks deeper and reports the stack
1194     at the time the CAF was evaluated, and it may report further stacks
1195     until a non-CAF stack is found. In the example above, the next stack
1196     (after ``--> evaluated by``) contains plenty of information about
1197     what the program was doing when it evaluated ``head []``.
1198
1199     Implementation details aside, the function names in the stack should
1200     hopefully give you enough clues to track down the bug.
1201
1202     See also the function ``traceStack`` in the module ``Debug.Trace``
1203     for another way to view call stacks.
1204
1205 .. rts-flag:: -Z
1206
1207     Turn *off* "update-frame squeezing" at garbage-collection time.
1208     (There's no particularly good reason to turn it off, except to
1209     ensure the accuracy of certain data collected regarding thunk entry
1210     counts.)
1211
1212 .. _ghc-info:
1213
1214 Getting information about the RTS
1215 ---------------------------------
1216
1217 .. index::
1218    single: RTS
1219
1220 .. rts-flag:: --info
1221
1222     It is possible to ask the RTS to give some information about itself. To
1223     do this, use the :rts-flag:`--info` flag, e.g.
1224
1225     .. code-block:: none
1226
1227         $ ./a.out +RTS --info
1228         [("GHC RTS", "YES")
1229         ,("GHC version", "6.7")
1230         ,("RTS way", "rts_p")
1231         ,("Host platform", "x86_64-unknown-linux")
1232         ,("Host architecture", "x86_64")
1233         ,("Host OS", "linux")
1234         ,("Host vendor", "unknown")
1235         ,("Build platform", "x86_64-unknown-linux")
1236         ,("Build architecture", "x86_64")
1237         ,("Build OS", "linux")
1238         ,("Build vendor", "unknown")
1239         ,("Target platform", "x86_64-unknown-linux")
1240         ,("Target architecture", "x86_64")
1241         ,("Target OS", "linux")
1242         ,("Target vendor", "unknown")
1243         ,("Word size", "64")
1244         ,("Compiler unregisterised", "NO")
1245         ,("Tables next to code", "YES")
1246         ,("Flag -with-rtsopts", "")
1247         ]
1248
1249     The information is formatted such that it can be read as a of type
1250     ``[(String, String)]``. Currently the following fields are present:
1251
1252     ``GHC RTS``
1253         Is this program linked against the GHC RTS? (always "YES").
1254
1255     ``GHC version``
1256         The version of GHC used to compile this program.
1257
1258     ``RTS way``
1259         The variant (“way”) of the runtime. The most common values are
1260         ``rts_v`` (vanilla), ``rts_thr`` (threaded runtime, i.e. linked
1261         using the :ghc-flag:`-threaded` option) and ``rts_p`` (profiling runtime,
1262         i.e. linked using the :ghc-flag:`-prof` option). Other variants include
1263         ``debug`` (linked using :ghc-flag:`-debug`), and ``dyn`` (the RTS is linked
1264         in dynamically, i.e. a shared library, rather than statically linked
1265         into the executable itself). These can be combined, e.g. you might
1266         have ``rts_thr_debug_p``.
1267
1268     ``Target platform``\ ``Target architecture``\ ``Target OS``\ ``Target vendor``
1269         These are the platform the program is compiled to run on.
1270
1271     ``Build platform``\ ``Build architecture``\ ``Build OS``\ ``Build vendor``
1272         These are the platform where the program was built on. (That is, the
1273         target platform of GHC itself.) Ordinarily this is identical to the
1274         target platform. (It could potentially be different if
1275         cross-compiling.)
1276
1277     ``Host platform``\ ``Host architecture``\ ``Host OS``\ ``Host vendor``
1278         These are the platform where GHC itself was compiled. Again, this
1279         would normally be identical to the build and target platforms.
1280
1281     ``Word size``
1282         Either ``"32"`` or ``"64"``, reflecting the word size of the target
1283         platform.
1284
1285     ``Compiler unregistered``
1286         Was this program compiled with an :ref:`"unregistered" <unreg>`
1287         version of GHC? (I.e., a version of GHC that has no
1288         platform-specific optimisations compiled in, usually because this is
1289         a currently unsupported platform.) This value will usually be no,
1290         unless you're using an experimental build of GHC.
1291
1292     ``Tables next to code``
1293         Putting info tables directly next to entry code is a useful
1294         performance optimisation that is not available on all platforms.
1295         This field tells you whether the program has been compiled with this
1296         optimisation. (Usually yes, except on unusual platforms.)
1297
1298     ``Flag -with-rtsopts``
1299         The value of the GHC flag :ghc-flag:`-with-rtsopts=⟨opts⟩` at compile/link time.