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