mirrored from https://gitlab.haskell.org/ghc/ghc.git
-
Notifications
You must be signed in to change notification settings - Fork 705
/
using.xml
2687 lines (2352 loc) · 108 KB
/
using.xml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<?xml version="1.0" encoding="iso-8859-1"?>
<chapter id="using-ghc">
<title>Using GHC</title>
<indexterm><primary>GHC, using</primary></indexterm>
<indexterm><primary>using GHC</primary></indexterm>
<sect1>
<title>Getting started: compiling programs</title>
<para>
In this chapter you'll find a complete reference to the GHC
command-line syntax, including all 400+ flags. It's a large and
complex system, and there are lots of details, so it can be
quite hard to figure out how to get started. With that in mind,
this introductory section provides a quick introduction to the
basic usage of GHC for compiling a Haskell program, before the
following sections dive into the full syntax.
</para>
<para>
Let's create a Hello World program, and compile and run it.
First, create a file <filename>hello.hs</filename> containing
the Haskell code:
</para>
<programlisting>
main = putStrLn "Hello, World!"
</programlisting>
<para>To compile the program, use GHC like this:</para>
<screen>
$ ghc hello.hs
</screen>
<para>(where <literal>$</literal> represents the prompt: don't
type it). GHC will compile the source
file <filename>hello.hs</filename>, producing
an <firstterm>object
file</firstterm> <filename>hello.o</filename> and
an <firstterm>interface
file</firstterm> <filename>hello.hi</filename>, and then it
will link the object file to the libraries that come with GHC
to produce an executable called <filename>hello</filename> on
Unix/Linux/Mac, or <filename>hello.exe</filename> on
Windows.</para>
<para>
By default GHC will be very quiet about what it is doing, only
printing error messages. If you want to see in more detail
what's going on behind the scenes, add <option>-v</option> to
the command line.
</para>
<para>
Then we can run the program like this:
</para>
<screen>
$ ./hello
Hello World!
</screen>
<para>
If your program contains multiple modules, then you only need to
tell GHC the name of the source file containing
the <filename>Main</filename> module, and GHC will examine
the <literal>import</literal> declarations to find the other
modules that make up the program and find their source files.
This means that, with the exception of
the <literal>Main</literal> module, every source file should be
named after the module name that it contains (with dots replaced
by directory separators). For example, the
module <literal>Data.Person</literal> would be in the
file <filename>Data/Person.hs</filename> on Unix/Linux/Mac,
or <filename>Data\Person.hs</filename> on Windows.
</para>
</sect1>
<sect1>
<title>Options overview</title>
<para>GHC's behaviour is controlled by
<firstterm>options</firstterm>, which for historical reasons are
also sometimes referred to as command-line flags or arguments.
Options can be specified in three ways:</para>
<sect2>
<title>Command-line arguments</title>
<indexterm><primary>structure, command-line</primary></indexterm>
<indexterm><primary>command-line</primary><secondary>arguments</secondary></indexterm>
<indexterm><primary>arguments</primary><secondary>command-line</secondary></indexterm>
<para>An invocation of GHC takes the following form:</para>
<screen>
ghc [argument...]
</screen>
<para>Command-line arguments are either options or file names.</para>
<para>Command-line options begin with <literal>-</literal>.
They may <emphasis>not</emphasis> be grouped:
<option>-vO</option> is different from <option>-v -O</option>.
Options need not precede filenames: e.g., <literal>ghc *.o -o
foo</literal>. All options are processed and then applied to
all files; you cannot, for example, invoke <literal>ghc -c -O1
Foo.hs -O2 Bar.hs</literal> to apply different optimisation
levels to the files <filename>Foo.hs</filename> and
<filename>Bar.hs</filename>.</para>
</sect2>
<sect2 id="source-file-options">
<title>Command line options in source files</title>
<indexterm><primary>source-file options</primary></indexterm>
<para>Sometimes it is useful to make the connection between a
source file and the command-line options it requires quite
tight. For instance, if a Haskell source file deliberately
uses name shadowing, it should be compiled with the
<option>-fno-warn-name-shadowing</option> option. Rather than maintaining
the list of per-file options in a <filename>Makefile</filename>,
it is possible to do this directly in the source file using the
<literal>OPTIONS_GHC</literal> pragma <indexterm><primary>OPTIONS_GHC
pragma</primary></indexterm>:</para>
<programlisting>
{-# OPTIONS_GHC -fno-warn-name-shadowing #-}
module X where
...
</programlisting>
<para><literal>OPTIONS_GHC</literal> is a <emphasis>file-header pragma</emphasis>
(see <xref linkend="pragmas"/>).</para>
<para>Only <emphasis>dynamic</emphasis> flags can be used in an <literal>OPTIONS_GHC</literal> pragma
(see <xref linkend="static-dynamic-flags"/>).</para>
<para>Note that your command shell does not
get to the source file options, they are just included literally
in the array of command-line arguments the compiler
maintains internally, so you'll be desperately disappointed if
you try to glob etc. inside <literal>OPTIONS_GHC</literal>.</para>
<para>NOTE: the contents of OPTIONS_GHC are appended to the
command-line options, so options given in the source file
override those given on the command-line.</para>
<para>It is not recommended to move all the contents of your
Makefiles into your source files, but in some circumstances, the
<literal>OPTIONS_GHC</literal> pragma is the Right Thing. (If you
use <option>-keep-hc-file</option> and have OPTION flags in
your module, the OPTIONS_GHC will get put into the generated .hc
file).</para>
</sect2>
<sect2>
<title>Setting options in GHCi</title>
<para>Options may also be modified from within GHCi, using the
<literal>:set</literal> command. See <xref linkend="ghci-set"/>
for more details.</para>
</sect2>
</sect1>
<sect1 id="static-dynamic-flags">
<title>Static, Dynamic, and Mode options</title>
<indexterm><primary>static</primary><secondary>options</secondary>
</indexterm>
<indexterm><primary>dynamic</primary><secondary>options</secondary>
</indexterm>
<indexterm><primary>mode</primary><secondary>options</secondary>
</indexterm>
<para>Each of GHC's command line options is classified as
<firstterm>static</firstterm>, <firstterm>dynamic</firstterm> or
<firstterm>mode</firstterm>:</para>
<variablelist>
<varlistentry>
<term>Mode flags</term>
<listitem>
<para>For example, <option>––make</option> or <option>-E</option>.
There may only be a single mode flag on the command line. The
available modes are listed in <xref linkend="modes"/>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Dynamic Flags</term>
<listitem>
<para>Most non-mode flags fall into this category. A dynamic flag
may be used on the command line, in a
<literal>OPTIONS_GHC</literal> pragma in a source file, or set
using <literal>:set</literal> in GHCi.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Static Flags</term>
<listitem>
<para>A few flags are "static", which means they can only be used on
the command-line, and remain in force over the entire GHC/GHCi
run.</para>
</listitem>
</varlistentry>
</variablelist>
<para>The flag reference tables (<xref
linkend="flag-reference"/>) lists the status of each flag.</para>
<para>There are a few flags that are static except that they can
also be used with GHCi's <literal>:set</literal> command; these
are listed as “static/<literal>:set</literal>” in the
table.</para>
</sect1>
<sect1 id="file-suffixes">
<title>Meaningful file suffixes</title>
<indexterm><primary>suffixes, file</primary></indexterm>
<indexterm><primary>file suffixes for GHC</primary></indexterm>
<para>File names with “meaningful” suffixes (e.g.,
<filename>.lhs</filename> or <filename>.o</filename>) cause the
“right thing” to happen to those files.</para>
<variablelist>
<varlistentry>
<term><filename>.hs</filename></term>
<listitem>
<para>A Haskell module.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<filename>.lhs</filename>
<indexterm><primary><literal>lhs</literal> suffix</primary></indexterm>
</term>
<listitem>
<para>A “literate Haskell” module.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><filename>.hi</filename></term>
<listitem>
<para>A Haskell interface file, probably
compiler-generated.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><filename>.hc</filename></term>
<listitem>
<para>Intermediate C file produced by the Haskell
compiler.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><filename>.c</filename></term>
<listitem>
<para>A C file not produced by the Haskell
compiler.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><filename>.ll</filename></term>
<listitem>
<para>An llvm-intermediate-language source file, usually
produced by the compiler.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><filename>.bc</filename></term>
<listitem>
<para>An llvm-intermediate-language bitcode file, usually
produced by the compiler.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><filename>.s</filename></term>
<listitem>
<para>An assembly-language source file, usually produced by
the compiler.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><filename>.o</filename></term>
<listitem>
<para>An object file, produced by an assembler.</para>
</listitem>
</varlistentry>
</variablelist>
<para>Files with other suffixes (or without suffixes) are passed
straight to the linker.</para>
</sect1>
<sect1 id="modes">
<title>Modes of operation</title>
<para>
GHC's behaviour is firstly controlled by a mode flag. Only one
of these flags may be given, but it does not necessarily need to
be the first option on the command-line.
</para>
<para>
If no mode flag is present, then GHC will enter make mode
(<xref linkend="make-mode" />) if there are any Haskell source
files given on the command line, or else it will link the
objects named on the command line to produce an executable.
</para>
<para>The available mode flags are:</para>
<variablelist>
<varlistentry>
<term>
<cmdsynopsis><command>ghc --interactive</command>
</cmdsynopsis>
<indexterm><primary>interactive mode</primary></indexterm>
<indexterm><primary>ghci</primary></indexterm>
</term>
<listitem>
<para>Interactive mode, which is also available as
<command>ghci</command>. Interactive mode is described in
more detail in <xref linkend="ghci"/>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<cmdsynopsis><command>ghc ––make</command>
</cmdsynopsis>
<indexterm><primary>make mode</primary></indexterm>
<indexterm><primary><option>––make</option></primary></indexterm>
</term>
<listitem>
<para>In this mode, GHC will build a multi-module Haskell
program automatically, figuring out dependencies for itself.
If you have a straightforward Haskell program, this is
likely to be much easier, and faster, than using
<command>make</command>. Make mode is described in <xref
linkend="make-mode"/>.</para>
<para>
This mode is the default if there are any Haskell
source files mentioned on the command line, and in this case
the <option>––make</option> option can be omitted.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<cmdsynopsis><command>ghc -e</command>
<arg choice='plain'><replaceable>expr</replaceable></arg>
</cmdsynopsis>
<indexterm><primary>eval mode</primary></indexterm>
</term>
<listitem>
<para>Expression-evaluation mode. This is very similar to
interactive mode, except that there is a single expression
to evaluate (<replaceable>expr</replaceable>) which is given
on the command line. See <xref linkend="eval-mode"/> for
more details.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<cmdsynopsis>
<command>ghc -E</command>
<command>ghc -c</command>
<command>ghc -S</command>
<command>ghc -c</command>
</cmdsynopsis>
<indexterm><primary><option>-E</option></primary></indexterm>
<indexterm><primary><option>-C</option></primary></indexterm>
<indexterm><primary><option>-S</option></primary></indexterm>
<indexterm><primary><option>-c</option></primary></indexterm>
</term>
<listitem>
<para>This is the traditional batch-compiler mode, in which
GHC can compile source files one at a time, or link objects
together into an executable. This mode also applies if
there is no other mode flag specified on the command line,
in which case it means that the specified files should be
compiled and then linked to form a program. See <xref
linkend="options-order"/>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<cmdsynopsis>
<command>ghc -M</command>
</cmdsynopsis>
<indexterm><primary>dependency-generation mode</primary></indexterm>
</term>
<listitem>
<para>Dependency-generation mode. In this mode, GHC can be
used to generate dependency information suitable for use in
a <literal>Makefile</literal>. See <xref
linkend="makefile-dependencies"/>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<cmdsynopsis>
<command>ghc --mk-dll</command>
</cmdsynopsis>
<indexterm><primary>DLL-creation mode</primary></indexterm>
</term>
<listitem>
<para>DLL-creation mode (Windows only). See <xref
linkend="win32-dlls-create"/>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<cmdsynopsis>
<command>ghc --help</command> <command>ghc -?</command>
</cmdsynopsis>
<indexterm><primary><option>––help</option></primary></indexterm>
</term>
<listitem>
<para>Cause GHC to spew a long usage message to standard
output and then exit.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<cmdsynopsis>
<command>ghc --show-iface <replaceable>file</replaceable></command>
</cmdsynopsis>
<indexterm><primary><option>––--show-iface</option></primary></indexterm>
</term>
<listitem>
<para>Read the interface in
<replaceable>file</replaceable> and dump it as text to
<literal>stdout</literal>. For example <literal>ghc --show-iface M.hi</literal>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<cmdsynopsis>
<command>ghc --supported-extensions</command>
<command>ghc --supported-languages</command>
</cmdsynopsis>
<indexterm><primary><option>––supported-extensions</option></primary><primary><option>––supported-languages</option></primary></indexterm>
</term>
<listitem>
<para>Print the supported language extensions.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<cmdsynopsis>
<command>ghc --info</command>
</cmdsynopsis>
<indexterm><primary><option>––info</option></primary></indexterm>
</term>
<listitem>
<para>Print information about the compiler.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<cmdsynopsis>
<command>ghc --version</command>
<command>ghc -V</command>
</cmdsynopsis>
<indexterm><primary><option>-V</option></primary></indexterm>
<indexterm><primary><option>––version</option></primary></indexterm>
</term>
<listitem>
<para>Print a one-line string including GHC's version number.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<cmdsynopsis>
<command>ghc --numeric-version</command>
</cmdsynopsis>
<indexterm><primary><option>––numeric-version</option></primary></indexterm>
</term>
<listitem>
<para>Print GHC's numeric version number only.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<cmdsynopsis>
<command>ghc --print-libdir</command>
</cmdsynopsis>
<indexterm><primary><option>––print-libdir</option></primary></indexterm>
</term>
<listitem>
<para>Print the path to GHC's library directory. This is
the top of the directory tree containing GHC's libraries,
interfaces, and include files (usually something like
<literal>/usr/local/lib/ghc-5.04</literal> on Unix). This
is the value of
<literal>$libdir</literal><indexterm><primary><literal>libdir</literal></primary></indexterm>
in the package configuration file
(see <xref linkend="packages"/>).</para>
</listitem>
</varlistentry>
</variablelist>
<sect2 id="make-mode">
<title>Using <command>ghc</command> <option>––make</option></title>
<indexterm><primary><option>––make</option></primary></indexterm>
<indexterm><primary>separate compilation</primary></indexterm>
<para>In this mode, GHC will build a multi-module Haskell program by following
dependencies from one or more root modules (usually just
<literal>Main</literal>). For example, if your
<literal>Main</literal> module is in a file called
<filename>Main.hs</filename>, you could compile and link the
program like this:</para>
<screen>
ghc ––make Main.hs
</screen>
<para>
In fact, GHC enters make mode automatically if there are any
Haskell source files on the command line and no other mode is
specified, so in this case we could just type
</para>
<screen>
ghc Main.hs
</screen>
<para>Any number of source file names or module names may be
specified; GHC will figure out all the modules in the program by
following the imports from these initial modules. It will then
attempt to compile each module which is out of date, and
finally, if there is a <literal>Main</literal> module, the
program will also be linked into an executable.</para>
<para>The main advantages to using <literal>ghc
––make</literal> over traditional
<literal>Makefile</literal>s are:</para>
<itemizedlist>
<listitem>
<para>GHC doesn't have to be restarted for each compilation,
which means it can cache information between compilations.
Compiling a multi-module program with <literal>ghc
––make</literal> can be up to twice as fast as
running <literal>ghc</literal> individually on each source
file.</para>
</listitem>
<listitem>
<para>You don't have to write a <literal>Makefile</literal>.</para>
<indexterm><primary><literal>Makefile</literal>s</primary><secondary>avoiding</secondary></indexterm>
</listitem>
<listitem>
<para>GHC re-calculates the dependencies each time it is
invoked, so the dependencies never get out of sync with the
source.</para>
</listitem>
</itemizedlist>
<para>Any of the command-line options described in the rest of
this chapter can be used with
<option>––make</option>, but note that any options
you give on the command line will apply to all the source files
compiled, so if you want any options to apply to a single source
file only, you'll need to use an <literal>OPTIONS_GHC</literal>
pragma (see <xref linkend="source-file-options"/>).</para>
<para>If the program needs to be linked with additional objects
(say, some auxiliary C code), then the object files can be
given on the command line and GHC will include them when linking
the executable.</para>
<para>Note that GHC can only follow dependencies if it has the
source file available, so if your program includes a module for
which there is no source file, even if you have an object and an
interface file for the module, then GHC will complain. The
exception to this rule is for package modules, which may or may
not have source files.</para>
<para>The source files for the program don't all need to be in
the same directory; the <option>-i</option> option can be used
to add directories to the search path (see <xref
linkend="search-path"/>).</para>
</sect2>
<sect2 id="eval-mode">
<title>Expression evaluation mode</title>
<para>This mode is very similar to interactive mode, except that
there is a single expression to evaluate which is specified on
the command line as an argument to the <option>-e</option>
option:</para>
<screen>
ghc -e <replaceable>expr</replaceable>
</screen>
<para>Haskell source files may be named on the command line, and
they will be loaded exactly as in interactive mode. The
expression is evaluated in the context of the loaded
modules.</para>
<para>For example, to load and run a Haskell program containing
a module <literal>Main</literal>, we might say</para>
<screen>
ghc -e Main.main Main.hs
</screen>
<para>or we can just use this mode to evaluate expressions in
the context of the <literal>Prelude</literal>:</para>
<screen>
$ ghc -e "interact (unlines.map reverse.lines)"
hello
olleh
</screen>
</sect2>
<sect2 id="options-order">
<title>Batch compiler mode</title>
<para>In <emphasis>batch mode</emphasis>, GHC will compile one or more source files
given on the command line.</para>
<para>The first phase to run is determined by each input-file
suffix, and the last phase is determined by a flag. If no
relevant flag is present, then go all the way through to linking.
This table summarises:</para>
<informaltable>
<tgroup cols="4">
<colspec align="left"/>
<colspec align="left"/>
<colspec align="left"/>
<colspec align="left"/>
<thead>
<row>
<entry>Phase of the compilation system</entry>
<entry>Suffix saying “start here”</entry>
<entry>Flag saying “stop after”</entry>
<entry>(suffix of) output file</entry>
</row>
</thead>
<tbody>
<row>
<entry>literate pre-processor</entry>
<entry><literal>.lhs</literal></entry>
<entry>-</entry>
<entry><literal>.hs</literal></entry>
</row>
<row>
<entry>C pre-processor (opt.) </entry>
<entry><literal>.hs</literal> (with
<option>-cpp</option>)</entry>
<entry><option>-E</option></entry>
<entry><literal>.hspp</literal></entry>
</row>
<row>
<entry>Haskell compiler</entry>
<entry><literal>.hs</literal></entry>
<entry><option>-C</option>, <option>-S</option></entry>
<entry><literal>.hc</literal>, <literal>.s</literal></entry>
</row>
<row>
<entry>C compiler (opt.)</entry>
<entry><literal>.hc</literal> or <literal>.c</literal></entry>
<entry><option>-S</option></entry>
<entry><literal>.s</literal></entry>
</row>
<row>
<entry>assembler</entry>
<entry><literal>.s</literal></entry>
<entry><option>-c</option></entry>
<entry><literal>.o</literal></entry>
</row>
<row>
<entry>linker</entry>
<entry><replaceable>other</replaceable></entry>
<entry>-</entry>
<entry><filename>a.out</filename></entry>
</row>
</tbody>
</tgroup>
</informaltable>
<indexterm><primary><option>-C</option></primary></indexterm>
<indexterm><primary><option>-E</option></primary></indexterm>
<indexterm><primary><option>-S</option></primary></indexterm>
<indexterm><primary><option>-c</option></primary></indexterm>
<para>Thus, a common invocation would be: </para>
<screen>
ghc -c Foo.hs
</screen>
<para>to compile the Haskell source file
<filename>Foo.hs</filename> to an object file
<filename>Foo.o</filename>.</para>
<para>Note: What the Haskell compiler proper produces depends on what
backend code generator is used. See <xref linkend="code-generators"/>
for more details.</para>
<para>Note: C pre-processing is optional, the
<option>-cpp</option><indexterm><primary><option>-cpp</option></primary></indexterm>
flag turns it on. See <xref linkend="c-pre-processor"/> for more
details.</para>
<para>Note: The option <option>-E</option><indexterm><primary>-E
option</primary></indexterm> runs just the pre-processing passes
of the compiler, dumping the result in a file.</para>
<sect3 id="overriding-suffixes">
<title>Overriding the default behaviour for a file</title>
<para>As described above, the way in which a file is processed by GHC
depends on its suffix. This behaviour can be overridden using the
<option>-x</option> option:</para>
<variablelist>
<varlistentry>
<term><option>-x</option> <replaceable>suffix</replaceable>
<indexterm><primary><option>-x</option></primary>
</indexterm></term>
<listitem>
<para>Causes all files following this option on the command
line to be processed as if they had the suffix
<replaceable>suffix</replaceable>. For example, to compile a
Haskell module in the file <literal>M.my-hs</literal>,
use <literal>ghc -c -x hs M.my-hs</literal>.</para>
</listitem>
</varlistentry>
</variablelist>
</sect3>
</sect2>
</sect1>
<sect1 id="options-help">
<title>Help and verbosity options</title>
<indexterm><primary>help options</primary></indexterm>
<indexterm><primary>verbosity options</primary></indexterm>
<para>See also the <option>--help</option>, <option>--version</option>, <option>--numeric-version</option>,
and <option>--print-libdir</option> modes in <xref linkend="modes"/>.</para>
<variablelist>
<varlistentry>
<term>
<option>-v</option>
<indexterm><primary><option>-v</option></primary></indexterm>
</term>
<listitem>
<para>The <option>-v</option> option makes GHC
<emphasis>verbose</emphasis>: it reports its version number
and shows (on stderr) exactly how it invokes each phase of
the compilation system. Moreover, it passes the
<option>-v</option> flag to most phases; each reports its
version number (and possibly some other information).</para>
<para>Please, oh please, use the <option>-v</option> option
when reporting bugs! Knowing that you ran the right bits in
the right order is always the first thing we want to
verify.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>-v</option><replaceable>n</replaceable>
<indexterm><primary><option>-v</option></primary></indexterm>
</term>
<listitem>
<para>To provide more control over the compiler's verbosity,
the <option>-v</option> flag takes an optional numeric
argument. Specifying <option>-v</option> on its own is
equivalent to <option>-v3</option>, and the other levels
have the following meanings:</para>
<variablelist>
<varlistentry>
<term><option>-v0</option></term>
<listitem>
<para>Disable all non-essential messages (this is the
default).</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-v1</option></term>
<listitem>
<para>Minimal verbosity: print one line per
compilation (this is the default when
<option>––make</option> or
<option>––interactive</option> is on).</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-v2</option></term>
<listitem>
<para>Print the name of each compilation phase as it
is executed. (equivalent to
<option>-dshow-passes</option>).</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-v3</option></term>
<listitem>
<para>The same as <option>-v2</option>, except that in
addition the full command line (if appropriate) for
each compilation phase is also printed.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-v4</option></term>
<listitem>
<para>The same as <option>-v3</option> except that the
intermediate program representation after each
compilation phase is also printed (excluding
preprocessed and C/assembly files).</para>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-ferror-spans</option>
<indexterm><primary><option>-ferror-spans</option></primary>
</indexterm>
</term>
<listitem>
<para>Causes GHC to emit the full source span of the
syntactic entity relating to an error message. Normally, GHC
emits the source location of the start of the syntactic
entity only.</para>
<para>For example:</para>
<screen>
test.hs:3:6: parse error on input `where'
</screen>
<para>becomes:</para>
<screen>
test296.hs:3:6-10: parse error on input `where'
</screen>
<para>And multi-line spans are possible too:</para>
<screen>
test.hs:(5,4)-(6,7):
Conflicting definitions for `a'
Bound at: test.hs:5:4
test.hs:6:7
In the binding group for: a, b, a
</screen>
<para>Note that line numbers start counting at one, but
column numbers start at zero. This choice was made to
follow existing convention (i.e. this is how Emacs does
it).</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-H</option><replaceable>size</replaceable>
<indexterm><primary><option>-H</option></primary></indexterm>
</term>
<listitem>
<para>Set the minimum size of the heap to
<replaceable>size</replaceable>.
This option is equivalent to
<literal>+RTS -H<replaceable>size</replaceable></literal>,
see <xref linkend="rts-options-gc" />.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-Rghc-timing</option>
<indexterm><primary><option>-Rghc-timing</option></primary></indexterm>
</term>
<listitem>
<para>Prints a one-line summary of timing statistics for the
GHC run. This option is equivalent to
<literal>+RTS -tstderr</literal>, see <xref
linkend="rts-options-gc" />.
</para>
</listitem>
</varlistentry>
</variablelist>
</sect1>
&separate;
<sect1 id="options-sanity">
<title>Warnings and sanity-checking</title>
<indexterm><primary>sanity-checking options</primary></indexterm>
<indexterm><primary>warnings</primary></indexterm>
<para>GHC has a number of options that select which types of
non-fatal error messages, otherwise known as warnings, can be
generated during compilation. By default, you get a standard set
of warnings which are generally likely to indicate bugs in your
program. These are:
<option>-fwarn-overlapping-patterns</option>,
<option>-fwarn-warnings-deprecations</option>,
<option>-fwarn-deprecated-flags</option>,
<option>-fwarn-duplicate-exports</option>,
<option>-fwarn-missing-fields</option>,
<option>-fwarn-missing-methods</option>,
<option>-fwarn-lazy-unlifted-bindings</option>,
<option>-fwarn-wrong-do-bind</option>,
<option>-fwarn-unsupported-calling-conventions</option>, and
<option>-fwarn-dodgy-foreign-imports</option>. The following
flags are
simple ways to select standard “packages” of warnings:
</para>
<variablelist>
<varlistentry>
<term><option>-W</option>:</term>
<listitem>
<indexterm><primary>-W option</primary></indexterm>
<para>Provides the standard warnings plus
<option>-fwarn-incomplete-patterns</option>,
<option>-fwarn-dodgy-exports</option>,
<option>-fwarn-dodgy-imports</option>,
<option>-fwarn-unused-matches</option>,
<option>-fwarn-unused-imports</option>, and
<option>-fwarn-unused-binds</option>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-Wall</option>:</term>
<listitem>
<indexterm><primary><option>-Wall</option></primary></indexterm>
<para>Turns on all warning options that indicate potentially
suspicious code. The warnings that are
<emphasis>not</emphasis> enabled by <option>-Wall</option>
are
<option>-fwarn-tabs</option>,
<option>-fwarn-incomplete-uni-patterns</option>,
<option>-fwarn-incomplete-record-updates</option>,
<option>-fwarn-monomorphism-restriction</option>,
<option>-fwarn-auto-orphans</option>,
<option>-fwarn-implicit-prelude</option>,
<option>-fwarn-missing-local-sigs</option>,
<option>-fwarn-missing-import-lists</option>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-w</option>:</term>