Add `-W(no-)xxx` aliases for `-f(no-)warn-xxx` flags
[ghc.git] / docs / users_guide / separate_compilation.rst
1 .. _separate-compilation:
2
3 Filenames and separate compilation
4 ==================================
5
6 .. index::
7    single: separate compilation
8    single: recompilation checker
9    single: make and recompilation
10
11 This section describes what files GHC expects to find, what files it
12 creates, where these files are stored, and what options affect this
13 behaviour.
14
15 Note that this section is written with hierarchical modules in mind (see
16 :ref:`hierarchical-modules`); hierarchical modules are an extension to
17 Haskell 98 which extends the lexical syntax of module names to include a
18 dot ``.``. Non-hierarchical modules are thus a special case in which none
19 of the module names contain dots.
20
21 Pathname conventions vary from system to system. In particular, the
22 directory separator is "``/``" on Unix systems and "``\``" on
23 Windows systems. In the sections that follow, we shall consistently use
24 "``/``" as the directory separator; substitute this for the
25 appropriate character for your system.
26
27 .. _source-files:
28
29 Haskell source files
30 --------------------
31
32 .. index::
33    single: file names; of source files
34
35 Each Haskell source module should be placed in a file on its own.
36
37 Usually, the file should be named after the module name, replacing dots
38 in the module name by directory separators. For example, on a Unix
39 system, the module ``A.B.C`` should be placed in the file ``A/B/C.hs``,
40 relative to some base directory. If the module is not going to be
41 imported by another module (``Main``, for example), then you are free to
42 use any filename for it.
43
44 .. index::
45    single: Unicode
46    single: UTF-8
47    single: ASCII
48    single: Latin-1
49    single: encodings; of source files
50
51 GHC assumes that source files are ASCII or UTF-8 only, other
52 encoding are not recognised. However, invalid UTF-8 sequences
53 will be ignored in comments, so it is possible to use other encodings
54 such as Latin-1, as long as the non-comment source code is ASCII
55 only.
56
57 .. _output-files:
58
59 Output files
60 ------------
61
62 .. index::
63    single: interface files
64    single: .hi files
65    single: object files
66    single: .o files
67
68 When asked to compile a source file, GHC normally generates two files:
69 an object file, and an interface file.
70
71 The object file, which normally ends in a ``.o`` suffix, contains the
72 compiled code for the module.
73
74 The interface file, which normally ends in a ``.hi`` suffix, contains
75 the information that GHC needs in order to compile further modules that
76 depend on this module. It contains things like the types of exported
77 functions, definitions of data types, and so on. It is stored in a
78 binary format, so don't try to read one; use the ``--show-iface`` option
79 instead (see :ref:`hi-options`).
80
81 You should think of the object file and the interface file as a pair,
82 since the interface file is in a sense a compiler-readable description
83 of the contents of the object file. If the interface file and object
84 file get out of sync for any reason, then the compiler may end up making
85 assumptions about the object file that aren't true; trouble will almost
86 certainly follow. For this reason, we recommend keeping object files and
87 interface files in the same place (GHC does this by default, but it is
88 possible to override the defaults as we'll explain shortly).
89
90 Every module has a *module name* defined in its source code
91 (``module A.B.C where ...``).
92
93 The name of the object file generated by GHC is derived according to the
94 following rules, where ⟨osuf⟩ is the object-file suffix (this can be
95 changed with the ``-osuf`` option).
96
97 -  If there is no ``-odir`` option (the default), then the object
98    filename is derived from the source filename (ignoring the module
99    name) by replacing the suffix with ⟨osuf⟩.
100
101 -  If ``-odir ⟨dir⟩`` has been specified, then the object filename is
102    ⟨dir⟩/⟨mod⟩.⟨osuf⟩, where ⟨mod⟩ is the module name with dots replaced
103    by slashes. GHC will silently create the necessary directory
104    structure underneath ⟨dir⟩, if it does not already exist.
105
106 The name of the interface file is derived using the same rules, except
107 that the suffix is ⟨hisuf⟩ (``.hi`` by default) instead of ⟨osuf⟩, and
108 the relevant options are ``-hidir`` and ``-hisuf`` instead of ``-odir``
109 and ``-osuf`` respectively.
110
111 For example, if GHC compiles the module ``A.B.C`` in the file
112 ``src/A/B/C.hs``, with no ``-odir`` or ``-hidir`` flags, the interface
113 file will be put in ``src/A/B/C.hi`` and the object file in
114 ``src/A/B/C.o``.
115
116 For any module that is imported, GHC requires that the name of the
117 module in the import statement exactly matches the name of the module in
118 the interface file (or source file) found using the strategy specified
119 in :ref:`search-path`. This means that for most modules, the source file
120 name should match the module name.
121
122 However, note that it is reasonable to have a module ``Main`` in a file
123 named ``foo.hs``, but this only works because GHC never needs to search
124 for the interface for module ``Main`` (because it is never imported). It
125 is therefore possible to have several ``Main`` modules in separate
126 source files in the same directory, and GHC will not get confused.
127
128 In batch compilation mode, the name of the object file can also be
129 overridden using the ``-o`` option, and the name of the interface file
130 can be specified directly using the ``-ohi`` option.
131
132 .. _search-path:
133
134 The search path
135 ---------------
136
137 .. index::
138    single: search path
139    single: interface files, finding them
140    single: finding interface files
141
142 In your program, you import a module ``Foo`` by saying ``import Foo``.
143 In ``--make`` mode or GHCi, GHC will look for a source file for ``Foo``
144 and arrange to compile it first. Without ``--make``, GHC will look for
145 the interface file for ``Foo``, which should have been created by an
146 earlier compilation of ``Foo``. GHC uses the same strategy in each of
147 these cases for finding the appropriate file.
148
149 This strategy is as follows: GHC keeps a list of directories called the
150 search path. For each of these directories, it tries appending
151 ``⟨basename⟩.⟨extension⟩`` to the directory, and checks whether the
152 file exists. The value of ⟨basename⟩ is the module name with dots
153 replaced by the directory separator ("``/``" or "``\\"``, depending on the
154 system), and ⟨extension⟩ is a source extension (``hs``, ``lhs``) if we
155 are in ``--make`` mode or GHCi, or ⟨hisuf⟩ otherwise.
156
157 For example, suppose the search path contains directories ``d1``,
158 ``d2``, and ``d3``, and we are in ``--make`` mode looking for the source
159 file for a module ``A.B.C``. GHC will look in ``d1/A/B/C.hs``,
160 ``d1/A/B/C.lhs``, ``d2/A/B/C.hs``, and so on.
161
162 The search path by default contains a single directory: "``.``" (i.e. the
163 current directory). The following options can be used to add to or change the
164 contents of the search path:
165
166 ``-i⟨dir⟩[:⟨dir⟩]*``
167     .. index::
168        single: -idirs; GHC option
169
170     This flag appends a colon-separated list of ``dirs`` to
171     the search path.
172
173 ``-i``
174     resets the search path back to nothing.
175
176 This isn't the whole story: GHC also looks for modules in pre-compiled
177 libraries, known as packages. See the section on packages
178 (:ref:`packages`) for details.
179
180 .. _options-output:
181
182 Redirecting the compilation output(s)
183 -------------------------------------
184
185 .. index::
186    single: output-directing options
187    single: redirecting compilation output
188
189 ``-o ⟨file⟩``
190     .. index::
191        single: -o; GHC option
192
193     GHC's compiled output normally goes into a ``.hc``, ``.o``, etc.,
194     file, depending on the last-run compilation phase. The option
195     ``-o file`` re-directs the output of that last-run phase to ⟨file⟩.
196
197     .. note::
198        This “feature” can be counterintuitive: ``ghc -C -o foo.o foo.hs``
199        will put the intermediate C code in the file ``foo.o``, name
200        notwithstanding!
201
202     This option is most often used when creating an executable file, to
203     set the filename of the executable. For example:
204
205     ::
206
207         ghc -o prog --make Main
208
209     will compile the program starting with module ``Main`` and put the
210     executable in the file ``prog``.
211
212     Note: on Windows, if the result is an executable file, the extension
213     "``.exe``" is added if the specified filename does not already have
214     an extension. Thus
215
216     ::
217
218         ghc -o foo Main.hs
219
220     will compile and link the module ``Main.hs``, and put the resulting
221     executable in ``foo.exe`` (not ``foo``).
222
223     If you use ``ghc --make`` and you don't use the ``-o``, the name GHC
224     will choose for the executable will be based on the name of the file
225     containing the module ``Main``. Note that with GHC the ``Main``
226     module doesn't have to be put in file ``Main.hs``. Thus both
227
228     ::
229
230         ghc --make Prog
231
232     and
233
234     ::
235
236         ghc --make Prog.hs
237
238     will produce ``Prog`` (or ``Prog.exe`` if you are on Windows).
239
240 ``-odir ⟨dir⟩``
241     .. index::
242        single: -odir; GHC option
243
244     Redirects object files to directory ⟨dir⟩. For example:
245
246     ::
247
248         $ ghc -c parse/Foo.hs parse/Bar.hs gurgle/Bumble.hs -odir `uname -m`
249
250     The object files, ``Foo.o``, ``Bar.o``, and ``Bumble.o`` would be
251     put into a subdirectory named after the architecture of the
252     executing machine (``x86``, ``mips``, etc).
253
254     Note that the ``-odir`` option does *not* affect where the interface
255     files are put; use the ``-hidir`` option for that. In the above
256     example, they would still be put in ``parse/Foo.hi``,
257     ``parse/Bar.hi``, and ``gurgle/Bumble.hi``.
258
259 ``-ohi ⟨file⟩``
260     .. index::
261        single: -ohi; GHC option
262
263     The interface output may be directed to another file
264     ``bar2/Wurble.iface`` with the option ``-ohi bar2/Wurble.iface``
265     (not recommended).
266
267     .. warning::
268        If you redirect the interface file somewhere that GHC can't
269        find it, then the recompilation checker may get confused (at the
270        least, you won't get any recompilation avoidance). We recommend
271        using a combination of ``-hidir`` and ``-hisuf`` options instead, if
272        possible.
273
274     To avoid generating an interface at all, you could use this option
275     to redirect the interface into the bit bucket: ``-ohi /dev/null``,
276     for example.
277
278 ``-hidir ⟨dir⟩``
279     .. index::
280        single: -hidir; GHC option
281
282     Redirects all generated interface files into ⟨dir⟩, instead of the
283     default.
284
285 ``-stubdir ⟨dir⟩``
286     .. index::
287        single: -stubdir
288
289     Redirects all generated FFI stub files into ⟨dir⟩. Stub files are
290     generated when the Haskell source contains a ``foreign export`` or
291     ``foreign import "&wrapper"`` declaration (see
292     :ref:`foreign-export-ghc`). The ``-stubdir`` option behaves in
293     exactly the same way as ``-odir`` and ``-hidir`` with respect to
294     hierarchical modules.
295
296 ``-dumpdir ⟨dir⟩``
297     .. index::
298        single: -dumpdir
299
300     Redirects all dump files into ⟨dir⟩. Dump files are generated when
301     ``-ddump-to-file`` is used with other ``-ddump-*`` flags.
302
303 ``-outputdir ⟨dir⟩``
304     .. index::
305        single: -outputdir
306
307     The ``-outputdir`` option is shorthand for the combination of
308     ``-odir``, ``-hidir``, ``-stubdir`` and ``-dumpdir``.
309
310 ``-osuf ⟨suffix⟩; \ ``-hisuf``\ ⟨suffix⟩; \ ``-hcsuf``\ ⟨suffix⟩``
311     .. index::
312        single: -osuf
313
314     .. index::
315        single: -hisuf
316
317     .. index::
318        single: -hcsuf
319
320     The ``-osuf`` ⟨suffix⟩ will change the ``.o`` file suffix for object
321     files to whatever you specify. We use this when compiling libraries,
322     so that objects for the profiling versions of the libraries don't
323     clobber the normal ones.
324
325     Similarly, the ``-hisuf`` ⟨suffix⟩ will change the ``.hi`` file
326     suffix for non-system interface files (see :ref:`hi-options`).
327
328     Finally, the option ``-hcsuf`` ⟨suffix⟩ will change the ``.hc`` file
329     suffix for compiler-generated intermediate C files.
330
331     The ``-hisuf``/``-osuf`` game is particularly useful if you want to
332     compile a program both with and without profiling, in the same
333     directory. You can say:
334
335     ::
336
337         ghc ...
338
339     to get the ordinary version, and
340
341     ::
342
343         ghc ... -osuf prof.o -hisuf prof.hi -prof -auto-all
344
345     to get the profiled version.
346
347 .. _keeping-intermediates:
348
349 Keeping Intermediate Files
350 --------------------------
351
352 .. index::
353    single: intermediate files, saving
354    single: .hc files, saving
355    single: .ll files, saving
356    single: .s files, saving
357
358 The following options are useful for keeping certain intermediate files
359 around, when normally GHC would throw these away after compilation:
360
361 ``-keep-hc-file``
362     .. index::
363        single: -keep-hc-file
364        single: -keep-hc-files
365
366     Keep intermediate ``.hc`` files when doing ``.hs``-to-``.o``
367     compilations via :ref:`C <c-code-gen>` (Note: ``.hc`` files are only
368     generated by :ref:`unregisterised <unreg>` compilers).
369
370 ``-keep-llvm-file``
371     .. index::
372        single: -keep-llvm-file
373        single: -keep-llvm-files
374
375     Keep intermediate ``.ll`` files when doing ``.hs``-to-``.o``
376     compilations via :ref:`LLVM <llvm-code-gen>` (Note: ``.ll`` files
377     aren't generated when using the native code generator, you may need
378     to use ``-fllvm`` to force them to be produced).
379
380 ``-keep-s-file``
381     .. index::
382        single: -keep-s-file
383        single: -keep-s-files
384
385     Keep intermediate ``.s`` files.
386
387 ``-keep-tmp-files``
388     .. index::
389        single: -keep-tmp-files
390        single: temporary files; keeping
391
392     Instructs the GHC driver not to delete any of its temporary files,
393     which it normally keeps in ``/tmp`` (or possibly elsewhere; see
394     :ref:`temp-files`). Running GHC with ``-v`` will show you what
395     temporary files were generated along the way.
396
397 .. _temp-files:
398
399 Redirecting temporary files
400 ---------------------------
401
402 .. index::
403    single: temporary files; redirecting
404
405 ``-tmpdir``
406     .. index::
407        single: -tmpdir
408
409     If you have trouble because of running out of space in ``/tmp`` (or
410     wherever your installation thinks temporary files should go), you
411     may use the ``-tmpdir <dir>``-tmpdir <dir> option option to specify an
412     alternate directory. For example, ``-tmpdir .`` says to put temporary files
413     in the current working directory.
414
415     Alternatively, use your ``TMPDIR`` environment variable.TMPDIR
416     environment variable Set it to the name of the directory where
417     temporary files should be put. GCC and other programs will honour
418     the ``TMPDIR`` variable as well.
419
420     Even better idea: Set the ``DEFAULT_TMPDIR`` make variable when
421     building GHC, and never worry about ``TMPDIR`` again. (see the build
422     documentation).
423
424 .. _hi-options:
425
426 Other options related to interface files
427 ----------------------------------------
428
429 .. index::
430    single: interface files, options
431
432 ``-ddump-hi``
433     .. index::
434        single: -ddump-hi
435
436     Dumps the new interface to standard output.
437
438 ``-ddump-hi-diffs``
439     .. index::
440        single: -ddump-hi-diffs
441
442     The compiler does not overwrite an existing ``.hi`` interface file
443     if the new one is the same as the old one; this is friendly to
444     ``make``. When an interface does change, it is often enlightening to
445     be informed. The ``-ddump-hi-diffs`` option will make GHC report the
446     differences between the old and new ``.hi`` files.
447
448 ``-ddump-minimal-imports``
449     .. index::
450        single: -ddump-minimal-imports
451
452     Dump to the file ``M.imports`` (where ⟨M⟩ is the name of the module
453     being compiled) a "minimal" set of import declarations. The
454     directory where the ``.imports`` files are created can be controlled
455     via the ``-dumpdir`` option.
456
457     You can safely replace all the import declarations in ``M.hs`` with
458     those found in its respective ``.imports`` file. Why would you want
459     to do that? Because the "minimal" imports (a) import everything
460     explicitly, by name, and (b) import nothing that is not required. It
461     can be quite painful to maintain this property by hand, so this flag
462     is intended to reduce the labour.
463
464 ``--show-iface ⟨file⟩``
465     .. index::
466        single: --show-iface
467
468     where ⟨file⟩ is the name of an interface file, dumps the contents of
469     that interface in a human-readable format. See :ref:`modes`.
470
471 .. _recomp:
472
473 The recompilation checker
474 -------------------------
475
476 .. index::
477    single: recompilation checker
478
479 ``-fforce-recomp``
480     .. index::
481        single: -fforce-recomp
482        single: -fno-force-recomp
483
484     Turn off recompilation checking (which is on by default).
485     Recompilation checking normally stops compilation early, leaving an
486     existing ``.o`` file in place, if it can be determined that the
487     module does not need to be recompiled.
488
489 In the olden days, GHC compared the newly-generated ``.hi`` file with
490 the previous version; if they were identical, it left the old one alone
491 and didn't change its modification date. In consequence, importers of a
492 module with an unchanged output ``.hi`` file were not recompiled.
493
494 This doesn't work any more. Suppose module ``C`` imports module ``B``,
495 and ``B`` imports module ``A``. So changes to module ``A`` might require
496 module ``C`` to be recompiled, and hence when ``A.hi`` changes we should
497 check whether ``C`` should be recompiled. However, the dependencies of
498 ``C`` will only list ``B.hi``, not ``A.hi``, and some changes to ``A``
499 (changing the definition of a function that appears in an inlining of a
500 function exported by ``B``, say) may conceivably not change ``B.hi`` one
501 jot. So now…
502
503 GHC calculates a fingerprint (in fact an MD5 hash) of each interface
504 file, and of each declaration within the interface file. It also keeps
505 in every interface file a list of the fingerprints of everything it used
506 when it last compiled the file. If the source file's modification date
507 is earlier than the ``.o`` file's date (i.e. the source hasn't changed
508 since the file was last compiled), and the recompilation checking is on,
509 GHC will be clever. It compares the fingerprints on the things it needs
510 this time with the fingerprints on the things it needed last time
511 (gleaned from the interface file of the module being compiled); if they
512 are all the same it stops compiling early in the process saying
513 “Compilation IS NOT required”. What a beautiful sight!
514
515 You can read about `how all this
516 works <http://ghc.haskell.org/trac/ghc/wiki/Commentary/Compiler/RecompilationAvoidance>`__
517 in the GHC commentary.
518
519 .. _mutual-recursion:
520
521 How to compile mutually recursive modules
522 -----------------------------------------
523
524 .. index::
525    single: module system, recursion
526    single: recursion, between modules
527
528 GHC supports the compilation of mutually recursive modules. This section
529 explains how.
530
531 Every cycle in the module import graph must be broken by a ``hs-boot``
532 file. Suppose that modules ``A.hs`` and ``B.hs`` are Haskell source
533 files, thus:
534
535 ::
536
537     module A where
538         import B( TB(..) )
539
540         newtype TA = MkTA Int
541
542         f :: TB -> TA
543         f (MkTB x) = MkTA x
544
545     module B where
546         import {-# SOURCE #-} A( TA(..) )
547
548         data TB = MkTB !Int
549
550         g :: TA -> TB
551         g (MkTA x) = MkTB x
552
553 ``hs-boot`` files importing, ``hi-boot`` files Here ``A`` imports ``B``,
554 but ``B`` imports ``A`` with a ``{-# SOURCE #-}`` pragma, which breaks
555 the circular dependency. Every loop in the module import graph must be
556 broken by a ``{-# SOURCE #-}`` import; or, equivalently, the module
557 import graph must be acyclic if ``{-# SOURCE #-}`` imports are ignored.
558
559 For every module ``A.hs`` that is ``{-# SOURCE #-}``-imported in this
560 way there must exist a source file ``A.hs-boot``. This file contains an
561 abbreviated version of ``A.hs``, thus:
562
563 ::
564
565     module A where
566         newtype TA = MkTA Int
567
568 To compile these three files, issue the following commands:
569
570 ::
571
572       ghc -c A.hs-boot    -- Produces A.hi-boot, A.o-boot
573       ghc -c B.hs         -- Consumes A.hi-boot, produces B.hi, B.o
574       ghc -c A.hs         -- Consumes B.hi, produces A.hi, A.o
575       ghc -o foo A.o B.o  -- Linking the program
576
577 There are several points to note here:
578
579 -  The file ``A.hs-boot`` is a programmer-written source file. It must
580    live in the same directory as its parent source file ``A.hs``.
581    Currently, if you use a literate source file ``A.lhs`` you must also
582    use a literate boot file, ``A.lhs-boot``; and vice versa.
583
584 -  A ``hs-boot`` file is compiled by GHC, just like a ``hs`` file:
585
586    ::
587
588          ghc -c A.hs-boot
589
590    When a hs-boot file ``A.hs-boot`` is compiled, it is checked for
591    scope and type errors. When its parent module ``A.hs`` is compiled,
592    the two are compared, and an error is reported if the two are
593    inconsistent.
594
595 -  Just as compiling ``A.hs`` produces an interface file ``A.hi``, and
596    an object file ``A.o``, so compiling ``A.hs-boot`` produces an
597    interface file ``A.hi-boot``, and an pseudo-object file ``A.o-boot``:
598
599    -  The pseudo-object file ``A.o-boot`` is empty (don't link it!), but
600       it is very useful when using a Makefile, to record when the
601       ``A.hi-boot`` was last brought up to date (see :ref:`using-make`).
602
603    -  The ``hi-boot`` generated by compiling a ``hs-boot`` file is in
604       the same machine-generated binary format as any other
605       GHC-generated interface file (e.g. ``B.hi``). You can display its
606       contents with ``ghc --show-iface``. If you specify a directory for
607       interface files, the ``-ohidir`` flag, then that affects ``hi-boot`` files
608       too.
609
610 -  If hs-boot files are considered distinct from their parent source
611    files, and if a ``{-# SOURCE #-}`` import is considered to refer to
612    the hs-boot file, then the module import graph must have no cycles.
613    The command ``ghc -M`` will report an error if a cycle is found.
614
615 -  A module ``M`` that is ``{-# SOURCE #-}``\-imported in a program will
616    usually also be ordinarily imported elsewhere. If not, ``ghc --make``
617    automatically adds ``M`` to the set of modules it tries to compile
618    and link, to ensure that ``M``\'s implementation is included in the
619    final program.
620
621 A hs-boot file need only contain the bare minimum of information needed
622 to get the bootstrapping process started. For example, it doesn't need
623 to contain declarations for *everything* that module ``A`` exports, only
624 the things required by the module(s) that import ``A`` recursively.
625
626 A hs-boot file is written in a subset of Haskell:
627
628 -  The module header (including the export list), and import statements,
629    are exactly as in Haskell, and so are the scoping rules. Hence, to
630    mention a non-Prelude type or class, you must import it.
631
632 -  There must be no value declarations, but there can be type signatures
633    for values. For example:
634
635    ::
636
637         double :: Int -> Int
638
639 -  Fixity declarations are exactly as in Haskell.
640
641 -  Vanilla type synonym declarations are exactly as in Haskell.
642
643 -  Open type and data family declarations are exactly as in Haskell.
644
645 -  A closed type family may optionally omit its equations, as in the
646    following example:
647
648    ::
649
650         type family ClosedFam a where ..
651
652    The ``..`` is meant literally -- you should write two dots in your
653    file. Note that the ``where`` clause is still necessary to
654    distinguish closed families from open ones. If you give any equations
655    of a closed family, you must give all of them, in the same order as
656    they appear in the accompanying Haskell file.
657
658 -  A data type declaration can either be given in full, exactly as in
659    Haskell, or it can be given abstractly, by omitting the '=' sign and
660    everything that follows. For example:
661
662    ::
663
664         data T a b
665
666    In a *source* program this would declare TA to have no constructors
667    (a GHC extension: see :ref:`nullary-types`), but in an hi-boot file
668    it means "I don't know or care what the constructors are". This is
669    the most common form of data type declaration, because it's easy to
670    get right. You *can* also write out the constructors but, if you do
671    so, you must write it out precisely as in its real definition.
672
673    If you do not write out the constructors, you may need to give a kind
674    annotation (:ref:`kinding`), to tell GHC the kind of the type
675    variable, if it is not "\*". (In source files, this is worked out
676    from the way the type variable is used in the constructors.) For
677    example:
678
679    ::
680
681         data R (x :: * -> *) y
682
683    You cannot use ``deriving`` on a data type declaration; write an
684    ``instance`` declaration instead.
685
686 -  Class declarations is exactly as in Haskell, except that you may not
687    put default method declarations. You can also omit all the
688    superclasses and class methods entirely; but you must either omit
689    them all or put them all in.
690
691 -  You can include instance declarations just as in Haskell; but omit
692    the "where" part.
693
694 -  The default role for abstract datatype parameters is now
695    representational. (An abstract datatype is one with no constructors
696    listed.) To get another role, use a role annotation. (See
697    :ref:`roles`.)
698
699 .. _module-signatures:
700
701 Module signatures
702 -----------------
703
704 GHC supports the specification of module signatures, which both
705 implementations and users can typecheck against separately. This
706 functionality should be considered experimental for now; some details,
707 especially for type classes and type families, may change. This system
708 was originally described in `Backpack: Retrofitting Haskell with
709 Interfaces <http://plv.mpi-sws.org/backpack/>`__. Signature files are
710 somewhat similar to ``hs-boot`` files, but have the ``hsig`` extension
711 and behave slightly differently.
712
713 Suppose that I have modules ``String.hs`` and ``A.hs``, thus:
714
715 ::
716
717     module Text where
718         data Text = Text String
719
720         empty :: Text
721         empty = Text ""
722
723         toString :: Text -> String
724         toString (Text s) = s
725
726     module A where
727         import Text
728         z = toString empty
729
730 Presently, module ``A`` depends explicitly on a concrete implementation
731 of ``Text``. What if we wanted to a signature ``Text``, so we could vary
732 the implementation with other possibilities (e.g. packed UTF-8 encoded
733 bytestrings)? To do this, we can write a signature ``TextSig.hsig``, and
734 modify ``A`` to include the signature instead:
735
736 ::
737
738     module TextSig where
739         data Text
740         empty :: Text
741         toString :: Text -> String
742
743     module A where
744         import TextSig
745         z = toString empty
746
747 To compile these two files, we need to specify what module we would like
748 to use to implement the signature. This can be done by compiling the
749 implementation, and then using the ``-sig-of`` flag to specify the
750 implementation backing a signature:
751
752 ::
753
754     ghc -c Text.hs
755     ghc -c TextSig.hsig -sig-of "TextSig is main:Text"
756     ghc -c A.hs
757
758 To specify multiple signatures, use a comma-separated list. The
759 ``-sig-of`` parameter is required to specify the backing implementations
760 of all home modules, even in one-shot compilation mode. At the moment,
761 you must specify the full module name (unit ID, colon, and then
762 module name), although in the future we may support more user-friendly
763 syntax.
764
765 To just type-check an interface file, no ``-sig-of`` is necessary;
766 instead, just pass the options ``-fno-code -fwrite-interface``. ``hsig``
767 files will generate normal interface files which other files can also
768 use to type-check against. However, at the moment, we always assume that
769 an entity defined in a signature is a unique identifier (even though we
770 may happen to know it is type equal with another identifier). In the
771 future, we will support passing shaping information to the compiler in
772 order to let it know about these type equalities.
773
774 Just like ``hs-boot`` files, when an ``hsig`` file is compiled it is
775 checked for type consistency against the backing implementation.
776 Signature files are also written in a subset of Haskell essentially
777 identical to that of ``hs-boot`` files.
778
779 There is one important gotcha with the current implementation:
780 currently, instances from backing implementations will "leak" code that
781 uses signatures, and explicit instance declarations in signatures are
782 forbidden. This behavior will be subject to change.
783
784 .. _using-make:
785
786 Using ``make``
787 --------------
788
789 .. index::
790    single: make; building programs with
791
792 It is reasonably straightforward to set up a ``Makefile`` to use with
793 GHC, assuming you name your source files the same as your modules. Thus:
794
795 ::
796
797     HC      = ghc
798     HC_OPTS = -cpp $(EXTRA_HC_OPTS)
799
800     SRCS = Main.lhs Foo.lhs Bar.lhs
801     OBJS = Main.o   Foo.o   Bar.o
802
803     .SUFFIXES : .o .hs .hi .lhs .hc .s
804
805     cool_pgm : $(OBJS)
806             rm -f $@
807             $(HC) -o $@ $(HC_OPTS) $(OBJS)
808
809     # Standard suffix rules
810     .o.hi:
811             @:
812
813     .lhs.o:
814             $(HC) -c $< $(HC_OPTS)
815
816     .hs.o:
817             $(HC) -c $< $(HC_OPTS)
818
819     .o-boot.hi-boot:
820             @:
821
822     .lhs-boot.o-boot:
823             $(HC) -c $< $(HC_OPTS)
824
825     .hs-boot.o-boot:
826             $(HC) -c $< $(HC_OPTS)
827
828     # Inter-module dependencies
829     Foo.o Foo.hc Foo.s    : Baz.hi          # Foo imports Baz
830     Main.o Main.hc Main.s : Foo.hi Baz.hi   # Main imports Foo and Baz
831
832 .. note::
833     Sophisticated ``make`` variants may achieve some of the above more
834     elegantly. Notably, ``gmake``\'s pattern rules let you write the more
835     comprehensible:
836
837     ::
838
839         %.o : %.lhs
840                 $(HC) -c $< $(HC_OPTS)
841
842     What we've shown should work with any ``make``.
843
844 Note the cheesy ``.o.hi`` rule: It records the dependency of the
845 interface (``.hi``) file on the source. The rule says a ``.hi`` file can
846 be made from a ``.o`` file by doing…nothing. Which is true.
847
848 Note that the suffix rules are all repeated twice, once for normal
849 Haskell source files, and once for ``hs-boot`` files (see
850 :ref:`mutual-recursion`).
851
852 Note also the inter-module dependencies at the end of the Makefile,
853 which take the form
854
855 ::
856
857     Foo.o Foo.hc Foo.s    : Baz.hi          # Foo imports Baz
858
859 They tell ``make`` that if any of ``Foo.o``, ``Foo.hc`` or ``Foo.s``
860 have an earlier modification date than ``Baz.hi``, then the out-of-date
861 file must be brought up to date. To bring it up to date, ``make`` looks
862 for a rule to do so; one of the preceding suffix rules does the job
863 nicely. These dependencies can be generated automatically by ``ghc``;
864 see :ref:`makefile-dependencies`
865
866 .. _makefile-dependencies:
867
868 Dependency generation
869 ---------------------
870
871 .. index::
872    single: dependencies in Makefiles
873    single: Makefile dependencies
874
875 Putting inter-dependencies of the form ``Foo.o : Bar.hi`` into your
876 ``Makefile`` by hand is rather error-prone. Don't worry, GHC has support
877 for automatically generating the required dependencies. Add the
878 following to your ``Makefile``:
879
880 ::
881
882     depend :
883             ghc -M $(HC_OPTS) $(SRCS)
884
885 Now, before you start compiling, and any time you change the ``imports``
886 in your program, do ``make depend`` before you do ``make cool_pgm``. The command
887 ``ghc -M`` will append the needed dependencies to your ``Makefile``.
888
889 In general, ``ghc -M Foo`` does the following. For each module ``M`` in
890 the set ``Foo`` plus all its imports (transitively), it adds to the
891 Makefile:
892
893 -  A line recording the dependence of the object file on the source
894    file.
895
896    ::
897
898        M.o : M.hs
899
900    (or ``M.lhs`` if that is the filename you used).
901
902 -  For each import declaration ``import X`` in ``M``, a line recording
903    the dependence of ``M`` on ``X``:
904
905    ::
906
907        M.o : X.hi
908
909 -  For each import declaration ``import {-# SOURCE #-} X`` in ``M``, a
910    line recording the dependence of ``M`` on ``X``:
911
912    ::
913
914        M.o : X.hi-boot
915
916    (See :ref:`mutual-recursion` for details of ``hi-boot`` style
917    interface files.)
918
919 If ``M`` imports multiple modules, then there will be multiple lines
920 with ``M.o`` as the target.
921
922 There is no need to list all of the source files as arguments to the
923 ``ghc -M`` command; ``ghc`` traces the dependencies, just like
924 ``ghc --make`` (a new feature in GHC 6.4).
925
926 Note that ``ghc -M`` needs to find a *source file* for each module in
927 the dependency graph, so that it can parse the import declarations and
928 follow dependencies. Any pre-compiled modules without source files must
929 therefore belong to a package [1]_.
930
931 By default, ``ghc -M`` generates all the dependencies, and then
932 concatenates them onto the end of ``makefile`` (or ``Makefile`` if
933 ``makefile`` doesn't exist) bracketed by the lines
934 "``# DO NOT DELETE: Beginning of Haskell dependencies``" and
935 "``# DO NOT DELETE: End of Haskell dependencies``". If these lines
936 already exist in the ``makefile``, then the old dependencies are deleted
937 first.
938
939 Don't forget to use the same ``-package`` options on the ``ghc -M``
940 command line as you would when compiling; this enables the dependency
941 generator to locate any imported modules that come from packages. The
942 package modules won't be included in the dependencies generated, though
943 (but see the ``-include-pkg-deps`` option below).
944
945 The dependency generation phase of GHC can take some additional options,
946 which you may find useful. The options which affect dependency
947 generation are:
948
949 ``-ddump-mod-cycles``
950     Display a list of the cycles in the module graph. This is useful
951     when trying to eliminate such cycles.
952
953 ``-v2``
954     Print a full list of the module dependencies to stdout. (This is the
955     standard verbosity flag, so the list will also be displayed with
956     ``-v3`` and ``-v4``; :ref:`options-help`.)
957
958 ``-dep-makefile ⟨file⟩``
959     Use ⟨file⟩ as the makefile, rather than ``makefile`` or
960     ``Makefile``. If ⟨file⟩ doesn't exist, ``mkdependHS`` creates it. We
961     often use ``-dep-makefile .depend`` to put the dependencies in
962     ``.depend`` and then ``include`` the file ``.depend`` into
963     ``Makefile``.
964
965 ``-dep-suffix <suf>``
966     Make extra dependencies that declare that files with suffix
967     ``.<suf>_<osuf>`` depend on interface files with suffix
968     ``.<suf>_hi``, or (for ``{-# SOURCE #-}`` imports) on ``.hi-boot``.
969     Multiple ``-dep-suffix`` flags are permitted. For example,
970     ``-dep-suffix a -dep-suffix b`` will make dependencies for ``.hs``
971     on ``.hi``, ``.a_hs`` on ``.a_hi``, and ``.b_hs`` on ``.b_hi``.
972     (Useful in conjunction with NoFib "ways".)
973
974 ``--exclude-module=<file>``
975     Regard ``<file>`` as "stable"; i.e., exclude it from having
976     dependencies on it.
977
978 ``-include-pkg-deps``
979     Regard modules imported from packages as unstable, i.e., generate
980     dependencies on any imported package modules (including ``Prelude``,
981     and all other standard Haskell libraries). Dependencies are not
982     traced recursively into packages; dependencies are only generated
983     for home-package modules on external-package modules directly
984     imported by the home package module. This option is normally only
985     used by the various system libraries.
986
987 .. _orphan-modules:
988
989 Orphan modules and instance declarations
990 ----------------------------------------
991
992 Haskell specifies that when compiling module ``M``, any instance declaration
993 in any module "below" ``M`` is visible. (Module ``A`` is "below" ``M`` if ``A`` is
994 imported directly by ``M``, or if ``A`` is below a module that ``M`` imports
995 directly.) In principle, GHC must therefore read the interface files of
996 every module below ``M``, just in case they contain an instance declaration
997 that matters to ``M``. This would be a disaster in practice, so GHC tries to
998 be clever.
999
1000 In particular, if an instance declaration is in the same module as the
1001 definition of any type or class mentioned in the *head* of the instance
1002 declaration (the part after the "``=>``"; see :ref:`instance-rules`), then GHC
1003 has to visit that interface file anyway. Example:
1004
1005 ::
1006
1007       module A where
1008         instance C a => D (T a) where ...
1009         data T a = ...
1010
1011 The instance declaration is only relevant if the type ``T`` is in use, and
1012 if so, GHC will have visited ``A``\'s interface file to find ``T``\'s definition.
1013
1014 The only problem comes when a module contains an instance declaration
1015 and GHC has no other reason for visiting the module. Example:
1016
1017 ::
1018
1019       module Orphan where
1020         instance C a => D (T a) where ...
1021         class C a where ...
1022
1023 Here, neither ``D`` nor ``T`` is declared in module ``Orphan``. We call such modules
1024 “orphan modules”. GHC identifies orphan modules, and visits the
1025 interface file of every orphan module below the module being compiled.
1026 This is usually wasted work, but there is no avoiding it. You should
1027 therefore do your best to have as few orphan modules as possible.
1028
1029 Functional dependencies complicate matters. Suppose we have:
1030
1031 ::
1032
1033       module B where
1034         instance E T Int where ...
1035         data T = ...
1036
1037 Is this an orphan module? Apparently not, because ``T`` is declared in
1038 the same module. But suppose class ``E`` had a functional dependency:
1039
1040 ::
1041
1042       module Lib where
1043         class E x y | y -> x where ...
1044
1045 Then in some importing module ``M``, the constraint ``(E a Int)`` should be
1046 "improved" by setting ``a = T``, *even though there is no explicit
1047 mention* of ``T`` in ``M``.
1048
1049 These considerations lead to the following definition of an orphan
1050 module:
1051
1052 -  An *orphan module* orphan module contains at least one *orphan
1053    instance* or at least one *orphan rule*.
1054
1055 -  An instance declaration in a module ``M`` is an *orphan instance* if
1056    orphan instance
1057
1058    -  The class of the instance declaration is not declared in ``M``, and
1059
1060    -  *Either* the class has no functional dependencies, and none of the
1061       type constructors in the instance head is declared in ``M``; *or*
1062       there is a functional dependency for which none of the type
1063       constructors mentioned in the *non-determined* part of the
1064       instance head is defined in ``M``.
1065
1066    Only the instance head counts. In the example above, it is not good
1067    enough for ``C``\'s declaration to be in module ``A``; it must be the
1068    declaration of ``D`` or ``T``.
1069
1070 -  A rewrite rule in a module ``M`` is an *orphan rule* orphan rule if none
1071    of the variables, type constructors, or classes that are free in the
1072    left hand side of the rule are declared in ``M``.
1073
1074 If you use the flag ``-Worphans``, GHC will warn you if you are
1075 creating an orphan module. Like any warning, you can switch the warning
1076 off with ``-Wno-orphans``, and ``-Werror`` will make the
1077 compilation fail if the warning is issued.
1078
1079 You can identify an orphan module by looking in its interface file,
1080 ``M.hi``, using the ``--show-iface`` :ref:`mode <modes>`. If there is a
1081 ``[orphan module]`` on the first line, GHC considers it an orphan
1082 module.
1083
1084 .. [1]
1085    This is a change in behaviour relative to 6.2 and earlier.