users_guide: Convert mkUserGuidePart generation to a Sphinx extension
[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 Pathname conventions vary from system to system. In particular, the
16 directory separator is "``/``" on Unix systems and "``\``" on
17 Windows systems. In the sections that follow, we shall consistently use
18 "``/``" as the directory separator; substitute this for the
19 appropriate character for your system.
20
21 .. _source-files:
22
23 Haskell source files
24 --------------------
25
26 .. index::
27    single: file names; of source files
28
29 Each Haskell source module should be placed in a file on its own.
30
31 Usually, the file should be named after the module name, replacing dots
32 in the module name by directory separators. For example, on a Unix
33 system, the module ``A.B.C`` should be placed in the file ``A/B/C.hs``,
34 relative to some base directory. If the module is not going to be
35 imported by another module (``Main``, for example), then you are free to
36 use any filename for it.
37
38 .. index::
39    single: Unicode
40    single: UTF-8
41    single: ASCII
42    single: Latin-1
43    single: encodings; of source files
44
45 GHC assumes that source files are ASCII or UTF-8 only, other
46 encoding are not recognised. However, invalid UTF-8 sequences
47 will be ignored in comments, so it is possible to use other encodings
48 such as Latin-1, as long as the non-comment source code is ASCII
49 only.
50
51 .. _output-files:
52
53 Output files
54 ------------
55
56 .. index::
57    single: interface files
58    single: .hi files
59    single: object files
60    single: .o files
61
62 When asked to compile a source file, GHC normally generates two files:
63 an object file, and an interface file.
64
65 The object file, which normally ends in a ``.o`` suffix, contains the
66 compiled code for the module.
67
68 The interface file, which normally ends in a ``.hi`` suffix, contains the
69 information that GHC needs in order to compile further modules that depend on
70 this module. It contains things like the types of exported functions,
71 definitions of data types, and so on. It is stored in a binary format, so don't
72 try to read one; use the :ghc-flag:`--show-iface ⟨file⟩` option instead (see
73 :ref:`hi-options`).
74
75 You should think of the object file and the interface file as a pair,
76 since the interface file is in a sense a compiler-readable description
77 of the contents of the object file. If the interface file and object
78 file get out of sync for any reason, then the compiler may end up making
79 assumptions about the object file that aren't true; trouble will almost
80 certainly follow. For this reason, we recommend keeping object files and
81 interface files in the same place (GHC does this by default, but it is
82 possible to override the defaults as we'll explain shortly).
83
84 Every module has a *module name* defined in its source code
85 (``module A.B.C where ...``).
86
87 The name of the object file generated by GHC is derived according to the
88 following rules, where ⟨osuf⟩ is the object-file suffix (this can be
89 changed with the ``-osuf`` option).
90
91 -  If there is no ``-odir`` option (the default), then the object
92    filename is derived from the source filename (ignoring the module
93    name) by replacing the suffix with ⟨osuf⟩.
94
95 -  If ``-odir ⟨dir⟩`` has been specified, then the object filename is
96    ⟨dir⟩/⟨mod⟩.⟨osuf⟩, where ⟨mod⟩ is the module name with dots replaced
97    by slashes. GHC will silently create the necessary directory
98    structure underneath ⟨dir⟩, if it does not already exist.
99
100 The name of the interface file is derived using the same rules, except that the
101 suffix is ⟨hisuf⟩ (``.hi`` by default) instead of ⟨osuf⟩, and the relevant
102 options are :ghc-flag:`-hidir ⟨dir⟩` and :ghc-flag:`-hisuf ⟨suffix⟩` instead of
103 :ghc-flag:`-odir ⟨dir⟩` and :ghc-flag:`-osuf ⟨suffix⟩` respectively.
104
105 For example, if GHC compiles the module ``A.B.C`` in the file
106 ``src/A/B/C.hs``, with no ``-odir`` or ``-hidir`` flags, the interface
107 file will be put in ``src/A/B/C.hi`` and the object file in
108 ``src/A/B/C.o``.
109
110 For any module that is imported, GHC requires that the name of the
111 module in the import statement exactly matches the name of the module in
112 the interface file (or source file) found using the strategy specified
113 in :ref:`search-path`. This means that for most modules, the source file
114 name should match the module name.
115
116 However, note that it is reasonable to have a module ``Main`` in a file
117 named ``foo.hs``, but this only works because GHC never needs to search
118 for the interface for module ``Main`` (because it is never imported). It
119 is therefore possible to have several ``Main`` modules in separate
120 source files in the same directory, and GHC will not get confused.
121
122 In batch compilation mode, the name of the object file can also be overridden
123 using the :ghc-flag:`-o ⟨file⟩` option, and the name of the interface file can
124 be specified directly using the :ghc-flag:`-ohi ⟨file⟩` option.
125
126 .. _search-path:
127
128 The search path
129 ---------------
130
131 .. index::
132    single: search path
133    single: interface files, finding them
134    single: finding interface files
135
136 In your program, you import a module ``Foo`` by saying ``import Foo``.
137 In :ghc-flag:`--make` mode or GHCi, GHC will look for a source file for ``Foo``
138 and arrange to compile it first. Without :ghc-flag:`--make`, GHC will look for
139 the interface file for ``Foo``, which should have been created by an
140 earlier compilation of ``Foo``. GHC uses the same strategy in each of
141 these cases for finding the appropriate file.
142
143 This strategy is as follows: GHC keeps a list of directories called the
144 search path. For each of these directories, it tries appending
145 ``⟨basename⟩.⟨extension⟩`` to the directory, and checks whether the
146 file exists. The value of ⟨basename⟩ is the module name with dots
147 replaced by the directory separator ("``/``" or "``\\"``, depending on the
148 system), and ⟨extension⟩ is a source extension (``hs``, ``lhs``) if we
149 are in :ghc-flag:`--make` mode or GHCi, or ⟨hisuf⟩ otherwise.
150
151 For example, suppose the search path contains directories ``d1``,
152 ``d2``, and ``d3``, and we are in :ghc-flag:`--make` mode looking for the source
153 file for a module ``A.B.C``. GHC will look in ``d1/A/B/C.hs``,
154 ``d1/A/B/C.lhs``, ``d2/A/B/C.hs``, and so on.
155
156 The search path by default contains a single directory: "``.``" (i.e. the
157 current directory). The following options can be used to add to or change the
158 contents of the search path:
159
160 .. ghc-flag:: -i⟨dir⟩[:⟨dir⟩]*
161     :shortdesc: add ⟨dir⟩, ⟨dir2⟩, etc. to import path
162     :type: dynamic/ ``:set``
163     :category: search-path
164
165     .. index::
166        single: search path; source code
167
168     This flag appends a colon-separated list of ``dirs`` to
169     the search path.
170
171 .. ghc-flag:: -i
172     :shortdesc: Empty the import directory list
173     :type: dynamic/ ``:set``
174     :category: search-path
175
176     resets the search path back to nothing.
177
178 This isn't the whole story: GHC also looks for modules in pre-compiled
179 libraries, known as packages. See the section on packages
180 (:ref:`packages`) for details.
181
182 .. _options-output:
183
184 Redirecting the compilation output(s)
185 -------------------------------------
186
187 .. index::
188    single: output-directing options
189    single: redirecting compilation output
190
191 .. ghc-flag:: -o ⟨file⟩
192     :shortdesc: set output filename
193     :type: dynamic
194     :category:
195
196     GHC's compiled output normally goes into a ``.hc``, ``.o``, etc.,
197     file, depending on the last-run compilation phase. The option
198     ``-o file`` re-directs the output of that last-run phase to ⟨file⟩.
199
200     .. note::
201        This “feature” can be counterintuitive: ``ghc -C -o foo.o foo.hs``
202        will put the intermediate C code in the file ``foo.o``, name
203        notwithstanding!
204
205     This option is most often used when creating an executable file, to
206     set the filename of the executable. For example:
207
208     .. code-block:: none
209
210         ghc -o prog --make Main
211
212     will compile the program starting with module ``Main`` and put the
213     executable in the file ``prog``.
214
215     Note: on Windows, if the result is an executable file, the extension
216     "``.exe``" is added if the specified filename does not already have
217     an extension. Thus
218
219     .. code-block:: none
220
221         ghc -o foo Main.hs
222
223     will compile and link the module ``Main.hs``, and put the resulting
224     executable in ``foo.exe`` (not ``foo``).
225
226     If you use ``ghc --make`` and you don't use the ``-o``, the name GHC
227     will choose for the executable will be based on the name of the file
228     containing the module ``Main``. Note that with GHC the ``Main``
229     module doesn't have to be put in file ``Main.hs``. Thus both
230
231     .. code-block:: none
232
233         ghc --make Prog
234
235     and
236
237     .. code-block:: none
238
239         ghc --make Prog.hs
240
241     will produce ``Prog`` (or ``Prog.exe`` if you are on Windows).
242
243 .. ghc-flag:: -odir ⟨dir⟩
244     :shortdesc: set directory for object files
245     :type: dynamic
246     :category:
247
248     Redirects object files to directory ⟨dir⟩. For example:
249
250     .. code-block:: none
251
252         $ ghc -c parse/Foo.hs parse/Bar.hs gurgle/Bumble.hs -odir `uname -m`
253
254     The object files, ``Foo.o``, ``Bar.o``, and ``Bumble.o`` would be
255     put into a subdirectory named after the architecture of the
256     executing machine (``x86``, ``mips``, etc).
257
258     Note that the ``-odir`` option does *not* affect where the interface
259     files are put; use the ``-hidir`` option for that. In the above
260     example, they would still be put in ``parse/Foo.hi``,
261     ``parse/Bar.hi``, and ``gurgle/Bumble.hi``.
262
263 .. ghc-flag:: -ohi ⟨file⟩
264     :shortdesc: set the filename in which to put the interface
265     :type: dynamic
266     :category:
267
268     The interface output may be directed to another file
269     ``bar2/Wurble.iface`` with the option ``-ohi bar2/Wurble.iface``
270     (not recommended).
271
272     .. warning::
273        If you redirect the interface file somewhere that GHC can't
274        find it, then the recompilation checker may get confused (at the
275        least, you won't get any recompilation avoidance). We recommend
276        using a combination of ``-hidir`` and ``-hisuf`` options instead, if
277        possible.
278
279     To avoid generating an interface at all, you could use this option
280     to redirect the interface into the bit bucket: ``-ohi /dev/null``,
281     for example.
282
283 .. ghc-flag:: -hidir ⟨dir⟩
284     :shortdesc: set directory for interface files
285     :type: dynamic
286     :category:
287
288     Redirects all generated interface files into ⟨dir⟩, instead of the
289     default.
290
291 .. ghc-flag:: -stubdir ⟨dir⟩
292     :shortdesc: redirect FFI stub files
293     :type: dynamic
294     :category:
295
296     Redirects all generated FFI stub files into ⟨dir⟩. Stub files are
297     generated when the Haskell source contains a ``foreign export`` or
298     ``foreign import "&wrapper"`` declaration (see
299     :ref:`foreign-export-ghc`). The ``-stubdir`` option behaves in
300     exactly the same way as ``-odir`` and ``-hidir`` with respect to
301     hierarchical modules.
302
303 .. ghc-flag:: -dumpdir ⟨dir⟩
304     :shortdesc: redirect dump files
305     :type: dynamic
306     :category:
307
308     Redirects all dump files into ⟨dir⟩. Dump files are generated when
309     ``-ddump-to-file`` is used with other ``-ddump-*`` flags.
310
311 .. ghc-flag:: -outputdir ⟨dir⟩
312     :shortdesc: set output directory
313     :type: dynamic
314     :category:
315
316     The ``-outputdir`` option is shorthand for the combination of
317     :ghc-flag:`-odir ⟨dir⟩`, :ghc-flag:`-hidir ⟨dir⟩`, :ghc-flag:`-stubdir
318     ⟨dir⟩` and :ghc-flag:`-dumpdir ⟨dir⟩`.
319
320 .. ghc-flag:: -osuf ⟨suffix⟩
321     :shortdesc: set the output file suffix
322     :type: dynamic
323     :category:
324
325     The ``-osuf`` ⟨suffix⟩ will change the ``.o`` file suffix for object
326     files to whatever you specify. We use this when compiling libraries,
327     so that objects for the profiling versions of the libraries don't
328     clobber the normal ones.
329
330 .. ghc-flag:: -hisuf ⟨suffix⟩
331     :shortdesc: set the suffix to use for interface files
332     :type: dynamic
333     :category:
334
335     Similarly, the ``-hisuf`` ⟨suffix⟩ will change the ``.hi`` file
336     suffix for non-system interface files (see :ref:`hi-options`).
337
338     The ``-hisuf``/``-osuf`` game is particularly useful if you want to
339     compile a program both with and without profiling, in the same
340     directory. You can say:
341
342     .. code-block:: none
343
344         ghc ...
345
346     to get the ordinary version, and
347
348     .. code-block:: none
349
350         ghc ... -osuf prof.o -hisuf prof.hi -prof -fprof-auto
351
352     to get the profiled version.
353
354
355 .. ghc-flag:: -hcsuf ⟨suffix⟩
356     :shortdesc: set the suffix to use for intermediate C files
357     :type: dynamic
358     :category:
359
360     Finally, the option ``-hcsuf`` ⟨suffix⟩ will change the ``.hc`` file
361     suffix for compiler-generated intermediate C files.
362
363 .. _keeping-intermediates:
364
365 Keeping Intermediate Files
366 --------------------------
367
368 .. index::
369    single: intermediate files, saving
370    single: .hc files, saving
371    single: .ll files, saving
372    single: .s files, saving
373
374 The following options are useful for keeping (or not keeping) certain
375 intermediate files around, when normally GHC would throw these away after
376 compilation:
377
378 .. ghc-flag:: -keep-hc-file
379               -keep-hc-files
380     :shortdesc: Retain intermediate ``.hc`` files.
381     :type: dynamic
382     :category: keep-intermediates
383
384     Keep intermediate ``.hc`` files when doing ``.hs``-to-``.o``
385     compilations via :ref:`C <c-code-gen>` (Note: ``.hc`` files are only
386     generated by :ref:`unregisterised <unreg>` compilers).
387
388 .. ghc-flag:: -keep-hi-files
389     :shortdesc: Retain intermediate ``.hi`` files (the default).
390     :type: dynamic
391     :reverse: -no-keep-hi-files
392     :category: keep-intermediates
393
394     .. index::
395        single: temporary files; keeping
396
397     Keep intermediate ``.hi`` files. This is the default. You may use
398     ``-no-keep-hi-files`` if you are not interested in the ``.hi`` files.
399
400 .. ghc-flag:: -keep-llvm-file
401               -keep-llvm-files
402     :shortdesc: Retain intermediate LLVM ``.ll`` files.
403         Implies :ghc-flag:`-fllvm`.
404     :type: dynamic
405     :category: keep-intermediates
406
407     :implies: :ghc-flag:`-fllvm`
408
409     Keep intermediate ``.ll`` files when doing ``.hs``-to-``.o``
410     compilations via :ref:`LLVM <llvm-code-gen>` (Note: ``.ll`` files
411     aren't generated when using the native code generator, you may need
412     to use :ghc-flag:`-fllvm` to force them to be produced).
413
414 .. ghc-flag:: -keep-o-files
415     :shortdesc: Retain intermediate ``.o`` files (the default).
416     :type: dynamic
417     :reverse: -no-keep-o-files
418     :category: keep-intermediates
419
420     .. index::
421        single: temporary files; keeping
422
423     Keep intermediate ``.o`` files. This is the default. You may use
424     ``-no-keep-o-files`` if you are not interested in the ``.o`` files.
425
426 .. ghc-flag:: -keep-s-file
427               -keep-s-files
428     :shortdesc: Retain intermediate ``.s`` files.
429     :type: dynamic
430     :category: keep-intermediates
431
432     Keep intermediate ``.s`` files.
433
434 .. ghc-flag:: -keep-tmp-files
435     :shortdesc: Retain all intermediate temporary files.
436     :type: dynamic
437     :category: keep-intermediates
438
439     .. index::
440        single: temporary files; keeping
441
442     Instructs the GHC driver not to delete any of its temporary files,
443     which it normally keeps in ``/tmp`` (or possibly elsewhere; see
444     :ref:`temp-files`). Running GHC with ``-v`` will show you what
445     temporary files were generated along the way.
446
447 .. _temp-files:
448
449 Redirecting temporary files
450 ---------------------------
451
452 .. index::
453    single: temporary files; redirecting
454
455 .. ghc-flag:: -tmpdir ⟨dir⟩
456     :shortdesc: set the directory for temporary files
457     :type: dynamic
458     :category: temp-files
459
460     If you have trouble because of running out of space in ``/tmp`` (or
461     wherever your installation thinks temporary files should go), you
462     may use the :ghc-flag:`-tmpdir ⟨dir⟩` option option to specify an
463     alternate directory. For example, ``-tmpdir .`` says to put temporary files
464     in the current working directory.
465
466     .. index::
467         single: TMPDIR environment variable
468
469     Alternatively, use your :envvar:`TMPDIR` environment variable. Set it to the
470     name of the directory where temporary files should be put. GCC and other
471     programs will honour the :envvar:`TMPDIR` variable as well.
472
473 .. _hi-options:
474
475 Other options related to interface files
476 ----------------------------------------
477
478 .. index::
479    single: interface files, options
480
481 .. ghc-flag:: -ddump-hi
482     :shortdesc: Dump the new interface to stdout
483     :type: dynamic
484     :category: interface-files
485
486     Dumps the new interface to standard output.
487
488 .. ghc-flag:: -ddump-hi-diffs
489     :shortdesc: Show the differences vs. the old interface
490     :type: dynamic
491     :category: interface-files
492
493     The compiler does not overwrite an existing ``.hi`` interface file
494     if the new one is the same as the old one; this is friendly to
495     :command:`make`. When an interface does change, it is often enlightening to
496     be informed. The :ghc-flag:`-ddump-hi-diffs` option will make GHC report the
497     differences between the old and new ``.hi`` files.
498
499 .. ghc-flag:: -ddump-minimal-imports
500     :shortdesc: Dump a minimal set of imports
501     :type: dynamic
502     :category: interface-files
503
504     Dump to the file :file:`{M}.imports` (where ⟨M⟩ is the name of the module
505     being compiled) a "minimal" set of import declarations. The
506     directory where the ``.imports`` files are created can be controlled
507     via the :ghc-flag:`-dumpdir ⟨dir⟩` option.
508
509     You can safely replace all the import declarations in :file:`{M}.hs` with
510     those found in its respective ``.imports`` file. Why would you want
511     to do that? Because the "minimal" imports (a) import everything
512     explicitly, by name, and (b) import nothing that is not required. It
513     can be quite painful to maintain this property by hand, so this flag
514     is intended to reduce the labour.
515
516 .. ghc-flag:: --show-iface ⟨file⟩
517     :shortdesc: See :ref:`modes`.
518     :type: mode
519     :category: interface-files
520
521     where ⟨file⟩ is the name of an interface file, dumps the contents of
522     that interface in a human-readable format. See :ref:`modes`.
523
524 .. _recomp:
525
526 The recompilation checker
527 -------------------------
528
529 .. index::
530    single: recompilation checker
531
532 .. ghc-flag:: -fforce-recomp
533     :shortdesc: Turn off recompilation checking. This is implied by any
534         ``-ddump-X`` option when compiling a single file
535         (i.e. when using :ghc-flag:`-c`).
536     :type: dynamic
537     :reverse: -fno-force-recomp
538     :category: recompilation
539
540     Turn off recompilation checking (which is on by default).
541     Recompilation checking normally stops compilation early, leaving an
542     existing ``.o`` file in place, if it can be determined that the
543     module does not need to be recompiled.
544
545 In the olden days, GHC compared the newly-generated ``.hi`` file with
546 the previous version; if they were identical, it left the old one alone
547 and didn't change its modification date. In consequence, importers of a
548 module with an unchanged output ``.hi`` file were not recompiled.
549
550 This doesn't work any more. Suppose module ``C`` imports module ``B``,
551 and ``B`` imports module ``A``. So changes to module ``A`` might require
552 module ``C`` to be recompiled, and hence when ``A.hi`` changes we should
553 check whether ``C`` should be recompiled. However, the dependencies of
554 ``C`` will only list ``B.hi``, not ``A.hi``, and some changes to ``A``
555 (changing the definition of a function that appears in an inlining of a
556 function exported by ``B``, say) may conceivably not change ``B.hi`` one
557 jot. So now…
558
559 GHC calculates a fingerprint (in fact an MD5 hash) of each interface
560 file, and of each declaration within the interface file. It also keeps
561 in every interface file a list of the fingerprints of everything it used
562 when it last compiled the file. If the source file's modification date
563 is earlier than the ``.o`` file's date (i.e. the source hasn't changed
564 since the file was last compiled), and the recompilation checking is on,
565 GHC will be clever. It compares the fingerprints on the things it needs
566 this time with the fingerprints on the things it needed last time
567 (gleaned from the interface file of the module being compiled); if they
568 are all the same it stops compiling early in the process saying
569 “Compilation IS NOT required”. What a beautiful sight!
570
571 You can read about `how all this
572 works <http://ghc.haskell.org/trac/ghc/wiki/Commentary/Compiler/RecompilationAvoidance>`__
573 in the GHC commentary.
574
575 .. _mutual-recursion:
576
577 How to compile mutually recursive modules
578 -----------------------------------------
579
580 .. index::
581    single: module system, recursion
582    single: recursion, between modules
583
584 GHC supports the compilation of mutually recursive modules. This section
585 explains how.
586
587 Every cycle in the module import graph must be broken by a ``hs-boot``
588 file. Suppose that modules ``A.hs`` and ``B.hs`` are Haskell source
589 files, thus: ::
590
591     module A where
592         import B( TB(..) )
593
594         newtype TA = MkTA Int
595
596         f :: TB -> TA
597         f (MkTB x) = MkTA x
598
599     module B where
600         import {-# SOURCE #-} A( TA(..) )
601
602         data TB = MkTB !Int
603
604         g :: TA -> TB
605         g (MkTA x) = MkTB x
606
607 .. index::
608    single: ``hs-boot`` files
609    single: importing, ``hi-boot`` files
610
611 Here ``A`` imports ``B``, but ``B`` imports ``A`` with a
612 ``{-# SOURCE #-}`` pragma, which breaks the circular dependency. Every
613 loop in the module import graph must be broken by a ``{-# SOURCE #-}``
614 import; or, equivalently, the module import graph must be acyclic if
615 ``{-# SOURCE #-}`` imports are ignored.
616
617 For every module ``A.hs`` that is ``{-# SOURCE #-}``-imported in this
618 way there must exist a source file ``A.hs-boot``. This file contains an
619 abbreviated version of ``A.hs``, thus: ::
620
621     module A where
622         newtype TA = MkTA Int
623
624 To compile these three files, issue the following commands:
625
626 .. code-block:: none
627
628       ghc -c A.hs-boot    -- Produces A.hi-boot, A.o-boot
629       ghc -c B.hs         -- Consumes A.hi-boot, produces B.hi, B.o
630       ghc -c A.hs         -- Consumes B.hi, produces A.hi, A.o
631       ghc -o foo A.o B.o  -- Linking the program
632
633 There are several points to note here:
634
635 -  The file ``A.hs-boot`` is a programmer-written source file. It must
636    live in the same directory as its parent source file ``A.hs``.
637    Currently, if you use a literate source file ``A.lhs`` you must also
638    use a literate boot file, ``A.lhs-boot``; and vice versa.
639
640 -  A ``hs-boot`` file is compiled by GHC, just like a ``hs`` file:
641
642    .. code-block:: none
643
644          ghc -c A.hs-boot
645
646    When a hs-boot file ``A.hs-boot`` is compiled, it is checked for
647    scope and type errors. When its parent module ``A.hs`` is compiled,
648    the two are compared, and an error is reported if the two are
649    inconsistent.
650
651 -  Just as compiling ``A.hs`` produces an interface file ``A.hi``, and
652    an object file ``A.o``, so compiling ``A.hs-boot`` produces an
653    interface file ``A.hi-boot``, and an pseudo-object file ``A.o-boot``:
654
655    -  The pseudo-object file ``A.o-boot`` is empty (don't link it!), but
656       it is very useful when using a Makefile, to record when the
657       ``A.hi-boot`` was last brought up to date (see :ref:`using-make`).
658
659    -  The ``hi-boot`` generated by compiling a ``hs-boot`` file is in
660       the same machine-generated binary format as any other
661       GHC-generated interface file (e.g. ``B.hi``). You can display its
662       contents with ``ghc --show-iface``. If you specify a directory for
663       interface files, the ``-ohidir`` flag, then that affects ``hi-boot`` files
664       too.
665
666 -  If hs-boot files are considered distinct from their parent source
667    files, and if a ``{-# SOURCE #-}`` import is considered to refer to
668    the hs-boot file, then the module import graph must have no cycles.
669    The command ``ghc -M`` will report an error if a cycle is found.
670
671 -  A module ``M`` that is ``{-# SOURCE #-}``\-imported in a program will
672    usually also be ordinarily imported elsewhere. If not, ``ghc --make``
673    automatically adds ``M`` to the set of modules it tries to compile
674    and link, to ensure that ``M``\'s implementation is included in the
675    final program.
676
677 A hs-boot file need only contain the bare minimum of information needed
678 to get the bootstrapping process started. For example, it doesn't need
679 to contain declarations for *everything* that module ``A`` exports, only
680 the things required by the module(s) that import ``A`` recursively.
681
682 A hs-boot file is written in a subset of Haskell:
683
684 -  The module header (including the export list), and import statements,
685    are exactly as in Haskell, and so are the scoping rules. Hence, to
686    mention a non-Prelude type or class, you must import it.
687
688 -  There must be no value declarations, but there can be type signatures
689    for values. For example: ::
690
691         double :: Int -> Int
692
693 -  Fixity declarations are exactly as in Haskell.
694
695 -  Vanilla type synonym declarations are exactly as in Haskell.
696
697 -  Open type and data family declarations are exactly as in Haskell.
698
699 -  A closed type family may optionally omit its equations, as in the
700    following example: ::
701
702         type family ClosedFam a where ..
703
704    The ``..`` is meant literally -- you should write two dots in your
705    file. Note that the ``where`` clause is still necessary to
706    distinguish closed families from open ones. If you give any equations
707    of a closed family, you must give all of them, in the same order as
708    they appear in the accompanying Haskell file.
709
710 -  A data type declaration can either be given in full, exactly as in
711    Haskell, or it can be given abstractly, by omitting the '=' sign and
712    everything that follows. For example: ::
713
714         data T a b
715
716    In a *source* program this would declare TA to have no constructors
717    (a GHC extension: see :ref:`nullary-types`), but in an hi-boot file
718    it means "I don't know or care what the constructors are". This is
719    the most common form of data type declaration, because it's easy to
720    get right. You *can* also write out the constructors but, if you do
721    so, you must write it out precisely as in its real definition.
722
723    If you do not write out the constructors, you may need to give a kind
724    annotation (:ref:`kinding`), to tell GHC the kind of the type
725    variable, if it is not "\*". (In source files, this is worked out
726    from the way the type variable is used in the constructors.) For
727    example: ::
728
729         data R (x :: * -> *) y
730
731    You cannot use ``deriving`` on a data type declaration; write an
732    ``instance`` declaration instead.
733
734 -  Class declarations is exactly as in Haskell, except that you may not
735    put default method declarations. You can also omit all the
736    superclasses and class methods entirely; but you must either omit
737    them all or put them all in.
738
739 -  You can include instance declarations just as in Haskell; but omit
740    the "where" part.
741
742 -  The default role for abstract datatype parameters is now
743    representational. (An abstract datatype is one with no constructors
744    listed.) To get another role, use a role annotation. (See
745    :ref:`roles`.)
746
747 .. _module-signatures:
748
749 Module signatures
750 -----------------
751
752 .. index::
753      single: signature files; Backpack; hsig files
754
755 GHC 8.2 supports module signatures (``hsig`` files), which allow you to
756 write a signature in place of a module implementation, deferring the
757 choice of implementation until a later point in time.  This feature is
758 not intended to be used without `Cabal
759 <http://www.haskell.org/cabal/>`__; this manual entry will focus
760 on the syntax and semantics of signatures.
761
762 To start with an example, suppose you had a module ``A`` which made use of some
763 string operations.  Using normal module imports, you would only
764 be able to pick a particular implementation of strings::
765
766     module Str where
767         type Str = String
768
769         empty :: Str
770         empty = ""
771
772         toString :: Str -> String
773         toString s = s
774
775     module A where
776         import Text
777         z = toString empty
778
779 By replacing ``Str.hs`` with a signature ``Str.hsig``, ``A`` (and
780 any other modules in this package) are now parametrized by
781 a string implementation::
782
783     signature Str where
784         data Str
785         empty :: Str
786         toString :: Str -> String
787
788 We can typecheck ``A`` against this signature, or we can instantiate
789 ``Str`` with a module that provides the following declarations.  Refer
790 to Cabal's documentation for a more in-depth discussion on how to
791 instantiate signatures.
792
793 Module signatures actually consist of two closely related features:
794
795 - The ability to define an ``hsig`` file, containing type definitions
796   and type signature for values which can be used by modules that
797   import the signature, and must be provided by the eventual
798   implementing module, and
799
800 - The ability to *inherit* required signatures from packages we
801   depend upon, combining the signatures into a single merged
802   signature which reflects the requirements of any locally defined
803   signature, as well as the requirements of our dependencies.
804
805 A signature file is denoted by an ``hsig`` file; every required
806 signature must have an ``hsig`` file (even if it is an empty one),
807 including required signatures inherited from dependencies.  Signatures
808 can be imported using an ordinary ``import Sig`` declaration.
809
810 ``hsig`` files are written in a variant of Haskell similar
811 to ``hs-boot`` files, but with some slight changes:
812
813 - The header of a signature is ``signature A where ...`` (instead
814   of the usual ``module A where ...``).
815
816 - Import statements and scoping rules are exactly as in Haskell.
817   To mention a non-Prelude type or class, you must import it.
818
819 - Unlike regular modules, the defined entities of
820   a signature include not only those written in the local
821   ``hsig`` file, but also those from inherited signatures
822   (as inferred from the :ghc-flag:`-package-id ⟨unit-id⟩` flags).
823   These entities are not considered in scope when typechecking
824   the local ``hsig`` file, but are available for import by
825   any module or signature which imports the signature.  The
826   one exception to this rule is the export list, described
827   below.
828
829   If a declaration occurs in multiple inherited signatures,
830   they will be *merged* together.  For values, we require
831   that the types from both signatures match exactly; however,
832   other declarations may merge in more interesting ways.
833   The merging operation in these cases has the effect of
834   textually replacing all occurrences of the old name with
835   a reference to the new, merged declaration.  For example,
836   if we have the following two signatures::
837
838     signature A where
839         data T
840         f :: T -> T
841
842     signature A where
843         data T = MkT
844         g :: T
845
846   the resulting merged signature would be::
847
848     signature A where
849         data T = MkT
850         f :: T -> T
851         g :: T
852
853 - If no export list is provided for a signature, the exports of
854   a signature are all of its defined entities merged with the
855   exports of all inherited signatures.
856
857   If you want to reexport an entity from a signature, you must
858   also include a ``module SigName`` export, so that all of the
859   entities defined in the signature are exported.  For example,
860   the following module exports both ``f`` and ``Int`` from
861   ``Prelude``::
862
863     signature A(module A, Int) where
864         import Prelude (Int)
865         f :: Int
866
867   Reexports merge with local declarations; thus, the signature above
868   would successfully merge with::
869
870     signature A where
871         data Int
872
873   The only permissible implementation of such a signature is a module
874   which reexports precisely the same entity::
875
876     module A (f, Int) where
877         import Prelude (Int)
878         f = 2 :: Int
879
880   Conversely, any entity requested by a signature can be provided
881   by a reexport from the implementing module.  This is different from
882   ``hs-boot`` files, which require every entity to be defined
883   locally in the implementing module.
884
885 - GHC has experimental support for *signature thinning*, which is used
886   when a signature has an explicit export list without a module export of the
887   signature itself.  In this case, the export list applies to the final export
888   list *after* merging, in particular, you may refer to entities which are not
889   declared in the body of the local ``hsig`` file.
890
891   The semantics in this case is that the set of required entities is defined
892   exclusively by its exports; if an entity is not mentioned in the export list,
893   it is not required.  The motivation behind this feature is to allow a library
894   author to provide an omnibus signature containing the type of every function
895   someone might want to use, while a client thins down the exports to the ones
896   they actually require.  For example, supposing that you have inherited a
897   signature for strings, you might write a local signature of this form, listing
898   only the entities that you need::
899
900     signature Str (Str, empty, append, concat) where
901         -- empty
902
903   A few caveats apply here.  First, it is illegal to export an entity
904   which refers to a locally defined type which itself is not exported
905   (GHC will report an error in this case).  Second, signatures which
906   come from dependencies which expose modules cannot be thinned in this
907   way (after all, the dependency itself may need the entity); these
908   requirements are unconditionally exported.  Finally, any module
909   reexports must refer to modules imported by the local signature
910   (even if an inherited signature exported the module).
911
912   We may change the syntax and semantics of this feature in the future.
913
914 - The declarations and types from signatures of dependencies
915   that will be merged in are not in scope when type checking
916   an ``hsig`` file.  To refer to any such type, you must
917   declare it yourself::
918
919     -- OK, assuming we inherited an A that defines T
920     signature A (T) where
921         -- empty
922
923     -- Not OK
924     signature A (T, f) where
925         f :: T -> T
926
927     -- OK
928     signature A (T, f) where
929         data T
930         f :: T -> T
931
932 - There must be no value declarations, but there can be type signatures
933   for values.  For example, we might define the signature::
934
935         signature A where
936             double :: Int -> Int
937
938   A module implementing ``A`` would have to export the function
939   ``double`` with a type definitionally equal to the signature.
940   Note that this means you can't implement ``double`` using
941   a polymorphic function ``double :: Num a => a -> a``.
942
943   Note that signature matching does check if *fixity* matches, so be
944   sure specify fixity of ordinary identifiers if you intend to use them
945   with backticks.
946
947 - Fixity, type synonym, open type/data family declarations
948   are permitted as in normal Haskell.
949
950 - Closed type family declarations are permitted as in normal
951   Haskell.  They can also be given abstractly, as in the
952   following example::
953
954     type family ClosedFam a where ..
955
956   The ``..`` is meant literally -- you should write two dots in
957   your file.  The ``where`` clause distinguishes closed families
958   from open ones.
959
960 - A data type declaration can either be given in full, exactly
961   as in Haskell, or it can be given abstractly, by omitting the '='
962   sign and everything that follows.  For example: ::
963
964         signature A where
965             data T a b
966
967   Abstract data types can be implemented not only with data
968   declarations, but also newtypes and type synonyms (with the
969   restriction that a type synonym must be fully eta-reduced,
970   e.g., ``type T = ...`` to be accepted.)  For example,
971   the following are all valid implementations of the T above::
972
973         -- Algebraic data type
974         data T a b = MkT a b
975
976         -- Newtype
977         newtype T a b = MkT (a, b)
978
979         -- Type synonym
980         data T2 a b = MkT2 a a b b
981         type T = T2
982
983   Data type declarations merge only with other data type
984   declarations which match exactly, except abstract data,
985   which can merge with ``data``, ``newtype`` or ``type``
986   declarations.  Merges with type synonyms are especially useful:
987   suppose you are using a package of strings which has left the type of
988   characters in the string unspecified::
989
990         signature Str where
991             data Str
992             data Elem
993             head :: Str -> Elem
994
995   If you locally define a signature which specifies
996   ``type Elem = Char``, you can now use ``head`` from the
997   inherited signature as if it returned a ``Char``.
998
999   If you do not write out the constructors, you may need to give a kind to tell
1000   GHC what the kinds of the type variables are, if they are not the default
1001   ``*``.
1002
1003   Roles of type parameters are subject to the subtyping
1004   relation ``phantom < representational < nominal``: for example,
1005   an abstract type with a nominal type parameter can be implemented
1006   using a concrete type with a representational type parameter.
1007   Merging respects this subtyping relation (e.g., ``nominal``
1008   merged with ``representational`` is ``representational``.)
1009   Roles in signatures default to ``nominal``, which gives maximum
1010   flexibility on the implementor's side.  You should only need to
1011   give an explicit role annotation if a client of the signature
1012   would like to coerce the abstract type in a type parameter (in which case you
1013   should specify ``representational`` explicitly.)  Unlike
1014   regular data types, we do *not* assume that abstract
1015   data types are representationally injective: if we have
1016   ``Coercible (T a) (T b)``, and ``T`` has role ``nominal``,
1017   this does not imply that ``a ~ b``.
1018
1019 - A class declarations can either be abstract or concrete.  An
1020   abstract class is one with no superclasses or class methods::
1021
1022     signature A where
1023         class Key k
1024
1025   It can be implemented in any way, with any set of superclasses
1026   and methods; however, modules depending on an abstract class
1027   are not permitted to define instances (as of GHC 8.2, this
1028   restriction is not checked, see :ghc-ticket:`13086`.)
1029   These declarations can be implemented by type synonyms
1030   of kind ``Constraint``; this can be useful if you want to parametrize
1031   over a constraint in functions.  For example, with the
1032   ``ConstraintKinds`` extension, this type synonym is a valid
1033   implementation of the signature above::
1034
1035     module A where
1036         type Key = Eq
1037
1038   A concrete class specifies its superclasses, methods,
1039   default method signatures (but not their implementations)
1040   and a ``MINIMAL`` pragma.  Unlike regular Haskell classes,
1041   you don't have to explicitly declare a default for a method
1042   to make it optional vis-a-vis the ``MINIMAL`` pragma.
1043
1044   When merging class declarations, we require that the superclasses
1045   and methods match exactly; however, ``MINIMAL`` pragmas are logically
1046   ORed together, and a method with a default signature will merge
1047   successfully against one that does not.
1048
1049 - You can include instance declarations as in Haskell; just omit the
1050   "where" part.  An instance declaration need not be implemented directly;
1051   if an instance can be derived based on instances in the environment,
1052   it is considered implemented.  For example, the following signature::
1053
1054     signature A where
1055         data Str
1056         instance Eq Str
1057
1058   is considered implemented by the following module, since there
1059   are instances of ``Eq`` for ``[]`` and ``Char`` which can be combined
1060   to form an instance ``Eq [Char]``::
1061
1062     module A where
1063         type Str = [Char]
1064
1065   Unlike other declarations, for which only the entities declared
1066   in a signature file are brought into scope, instances from the
1067   implementation are always brought into scope, even if they were
1068   not declared in the signature file.  This means that a module may
1069   typecheck against a signature, but not against a matching
1070   implementation.  You can avoid situations like this by never
1071   defining orphan instances inside a package that has signatures.
1072
1073   Instance declarations are only merged if their heads are exactly
1074   the same, so it is possible to get into a situation where GHC
1075   thinks that instances in a signature are overlapping, even if
1076   they are implemented in a non-overlapping way.  If this is
1077   giving you problems give us a shout.
1078
1079 - Any orphan instances which are brought into scope by an import
1080   from a signature are unconditionally considered in scope, even
1081   if the eventual implementing module doesn't actually import the
1082   same orphans.
1083
1084 Known limitations:
1085
1086 - Pattern synonyms are not supported.
1087
1088 - Algebraic data types specified in a signature cannot be implemented using
1089   pattern synonyms.  See :ghc-ticket:`12717`
1090
1091 .. _using-make:
1092
1093 Using ``make``
1094 --------------
1095
1096 .. index::
1097    single: make; building programs with
1098
1099 It is reasonably straightforward to set up a ``Makefile`` to use with
1100 GHC, assuming you name your source files the same as your modules. Thus:
1101
1102 .. code-block:: makefile
1103
1104     HC      = ghc
1105     HC_OPTS = -cpp $(EXTRA_HC_OPTS)
1106
1107     SRCS = Main.lhs Foo.lhs Bar.lhs
1108     OBJS = Main.o   Foo.o   Bar.o
1109
1110     .SUFFIXES : .o .hs .hi .lhs .hc .s
1111
1112     cool_pgm : $(OBJS)
1113             rm -f $@
1114             $(HC) -o $@ $(HC_OPTS) $(OBJS)
1115
1116     # Standard suffix rules
1117     .o.hi:
1118             @:
1119
1120     .lhs.o:
1121             $(HC) -c $< $(HC_OPTS)
1122
1123     .hs.o:
1124             $(HC) -c $< $(HC_OPTS)
1125
1126     .o-boot.hi-boot:
1127             @:
1128
1129     .lhs-boot.o-boot:
1130             $(HC) -c $< $(HC_OPTS)
1131
1132     .hs-boot.o-boot:
1133             $(HC) -c $< $(HC_OPTS)
1134
1135     # Inter-module dependencies
1136     Foo.o Foo.hc Foo.s    : Baz.hi          # Foo imports Baz
1137     Main.o Main.hc Main.s : Foo.hi Baz.hi   # Main imports Foo and Baz
1138
1139 .. note::
1140     Sophisticated :command:`make` variants may achieve some of the above more
1141     elegantly. Notably, :command:`gmake`\'s pattern rules let you write the more
1142     comprehensible:
1143
1144     .. code-block:: make
1145
1146         %.o : %.lhs
1147                 $(HC) -c $< $(HC_OPTS)
1148
1149     What we've shown should work with any ``make``.
1150
1151 Note the cheesy ``.o.hi`` rule: It records the dependency of the
1152 interface (``.hi``) file on the source. The rule says a ``.hi`` file can
1153 be made from a ``.o`` file by doing…nothing. Which is true.
1154
1155 Note that the suffix rules are all repeated twice, once for normal
1156 Haskell source files, and once for ``hs-boot`` files (see
1157 :ref:`mutual-recursion`).
1158
1159 Note also the inter-module dependencies at the end of the Makefile,
1160 which take the form
1161
1162 .. code-block:: make
1163
1164     Foo.o Foo.hc Foo.s    : Baz.hi          # Foo imports Baz
1165
1166 They tell ``make`` that if any of ``Foo.o``, ``Foo.hc`` or ``Foo.s``
1167 have an earlier modification date than ``Baz.hi``, then the out-of-date
1168 file must be brought up to date. To bring it up to date, ``make`` looks
1169 for a rule to do so; one of the preceding suffix rules does the job
1170 nicely. These dependencies can be generated automatically by ``ghc``;
1171 see :ref:`makefile-dependencies`
1172
1173 .. _makefile-dependencies:
1174
1175 Dependency generation
1176 ---------------------
1177
1178 .. index::
1179    single: dependencies in Makefiles
1180    single: Makefile dependencies
1181
1182 Putting inter-dependencies of the form ``Foo.o : Bar.hi`` into your
1183 ``Makefile`` by hand is rather error-prone. Don't worry, GHC has support
1184 for automatically generating the required dependencies. Add the
1185 following to your ``Makefile``:
1186
1187 .. code-block:: make
1188
1189     depend :
1190             ghc -dep-suffix '' -M $(HC_OPTS) $(SRCS)
1191
1192 Now, before you start compiling, and any time you change the ``imports``
1193 in your program, do ``make depend`` before you do ``make cool_pgm``. The command
1194 ``ghc -M`` will append the needed dependencies to your ``Makefile``.
1195
1196 In general, ``ghc -M Foo`` does the following. For each module ``M`` in
1197 the set ``Foo`` plus all its imports (transitively), it adds to the
1198 Makefile:
1199
1200 -  A line recording the dependence of the object file on the source
1201    file.
1202
1203    .. code-block:: make
1204
1205        M.o : M.hs
1206
1207    (or ``M.lhs`` if that is the filename you used).
1208
1209 -  For each import declaration ``import X`` in ``M``, a line recording
1210    the dependence of ``M`` on ``X``:
1211
1212    .. code-block:: make
1213
1214        M.o : X.hi
1215
1216 -  For each import declaration ``import {-# SOURCE #-} X`` in ``M``, a
1217    line recording the dependence of ``M`` on ``X``:
1218
1219    .. code-block:: make
1220
1221        M.o : X.hi-boot
1222
1223    (See :ref:`mutual-recursion` for details of ``hi-boot`` style
1224    interface files.)
1225
1226 If ``M`` imports multiple modules, then there will be multiple lines
1227 with ``M.o`` as the target.
1228
1229 There is no need to list all of the source files as arguments to the
1230 ``ghc -M`` command; ``ghc`` traces the dependencies, just like
1231 ``ghc --make`` (a new feature in GHC 6.4).
1232
1233 Note that ``ghc -M`` needs to find a *source file* for each module in
1234 the dependency graph, so that it can parse the import declarations and
1235 follow dependencies. Any pre-compiled modules without source files must
1236 therefore belong to a package [1]_.
1237
1238 By default, ``ghc -M`` generates all the dependencies, and then
1239 concatenates them onto the end of ``makefile`` (or ``Makefile`` if
1240 ``makefile`` doesn't exist) bracketed by the lines
1241 "``# DO NOT DELETE: Beginning of Haskell dependencies``" and
1242 "``# DO NOT DELETE: End of Haskell dependencies``". If these lines
1243 already exist in the ``makefile``, then the old dependencies are deleted
1244 first.
1245
1246 Don't forget to use the same ``-package`` options on the ``ghc -M``
1247 command line as you would when compiling; this enables the dependency
1248 generator to locate any imported modules that come from packages. The
1249 package modules won't be included in the dependencies generated, though
1250 (but see the ``-include-pkg-deps`` option below).
1251
1252 The dependency generation phase of GHC can take some additional options,
1253 which you may find useful. The options which affect dependency
1254 generation are:
1255
1256 .. ghc-flag:: -ddump-mod-cycles
1257     :shortdesc: Dump module cycles
1258     :type: dynamic
1259     :category:
1260
1261     Display a list of the cycles in the module graph. This is useful
1262     when trying to eliminate such cycles.
1263
1264 .. ghc-flag:: -v2
1265     :noindex:
1266
1267     Print a full list of the module dependencies to stdout. (This is the
1268     standard verbosity flag, so the list will also be displayed with
1269     ``-v3`` and ``-v4``; see :ref:`options-help`.)
1270
1271 .. ghc-flag:: -dep-makefile ⟨file⟩
1272     :shortdesc: Use ⟨file⟩ as the makefile
1273     :type: dynamic
1274     :category:
1275
1276     Use ⟨file⟩ as the makefile, rather than ``makefile`` or
1277     ``Makefile``. If ⟨file⟩ doesn't exist, ``mkdependHS`` creates it. We
1278     often use ``-dep-makefile .depend`` to put the dependencies in
1279     ``.depend`` and then ``include`` the file ``.depend`` into
1280     ``Makefile``.
1281
1282 .. ghc-flag:: -dep-suffix ⟨suffix⟩
1283     :shortdesc: Make dependencies that declare that files with suffix
1284         ``.⟨suf⟩⟨osuf⟩`` depend on interface files with suffix ``.⟨suf⟩hi``
1285     :type: dynamic
1286     :category:
1287
1288     Make dependencies that declare that files with suffix
1289     ``.⟨suf⟩⟨osuf⟩`` depend on interface files with suffix
1290     ``.⟨suf⟩hi``, or (for ``{-# SOURCE #-}`` imports) on ``.hi-boot``.
1291     Multiple ``-dep-suffix`` flags are permitted. For example,
1292     ``-dep-suffix a_ -dep-suffix b_`` will make dependencies for ``.hs``
1293     on ``.hi``, ``.a_hs`` on ``.a_hi``, and ``.b_hs`` on ``.b_hi``.
1294     Note that you must provide at least one suffix; if you do not want a suffix
1295     then pass ``-dep-suffix ''``.
1296
1297 .. ghc-flag:: --exclude-module=⟨file⟩
1298     :shortdesc: Regard ``⟨file⟩`` as "stable"; i.e., exclude it from having
1299         dependencies on it.
1300     :type: dynamic
1301     :category:
1302
1303     Regard ``⟨file⟩`` as "stable"; i.e., exclude it from having
1304     dependencies on it.
1305
1306 .. ghc-flag:: -include-pkg-deps
1307     :shortdesc: Regard modules imported from packages as unstable
1308     :type: dynamic
1309     :category:
1310
1311     Regard modules imported from packages as unstable, i.e., generate
1312     dependencies on any imported package modules (including ``Prelude``,
1313     and all other standard Haskell libraries). Dependencies are not
1314     traced recursively into packages; dependencies are only generated
1315     for home-package modules on external-package modules directly
1316     imported by the home package module. This option is normally only
1317     used by the various system libraries.
1318
1319 .. _orphan-modules:
1320
1321 Orphan modules and instance declarations
1322 ----------------------------------------
1323
1324 Haskell specifies that when compiling module ``M``, any instance declaration
1325 in any module "below" ``M`` is visible. (Module ``A`` is "below" ``M`` if ``A`` is
1326 imported directly by ``M``, or if ``A`` is below a module that ``M`` imports
1327 directly.) In principle, GHC must therefore read the interface files of
1328 every module below ``M``, just in case they contain an instance declaration
1329 that matters to ``M``. This would be a disaster in practice, so GHC tries to
1330 be clever.
1331
1332 In particular, if an instance declaration is in the same module as the
1333 definition of any type or class mentioned in the *head* of the instance
1334 declaration (the part after the "``=>``"; see :ref:`instance-rules`), then GHC
1335 has to visit that interface file anyway. Example: ::
1336
1337       module A where
1338         instance C a => D (T a) where ...
1339         data T a = ...
1340
1341 The instance declaration is only relevant if the type ``T`` is in use, and
1342 if so, GHC will have visited ``A``\'s interface file to find ``T``\'s definition.
1343
1344 The only problem comes when a module contains an instance declaration
1345 and GHC has no other reason for visiting the module. Example: ::
1346
1347       module Orphan where
1348         instance C a => D (T a) where ...
1349         class C a where ...
1350
1351 Here, neither ``D`` nor ``T`` is declared in module ``Orphan``. We call such modules
1352 "orphan modules". GHC identifies orphan modules, and visits the
1353 interface file of every orphan module below the module being compiled.
1354 This is usually wasted work, but there is no avoiding it. You should
1355 therefore do your best to have as few orphan modules as possible.
1356
1357 Functional dependencies complicate matters. Suppose we have: ::
1358
1359       module B where
1360         instance E T Int where ...
1361         data T = ...
1362
1363 Is this an orphan module? Apparently not, because ``T`` is declared in
1364 the same module. But suppose class ``E`` had a functional dependency: ::
1365
1366       module Lib where
1367         class E x y | y -> x where ...
1368
1369 Then in some importing module ``M``, the constraint ``(E a Int)`` should be
1370 "improved" by setting ``a = T``, *even though there is no explicit
1371 mention* of ``T`` in ``M``.
1372
1373 These considerations lead to the following definition of an orphan
1374 module:
1375
1376 -  An *orphan module* orphan module contains at least one *orphan
1377    instance* or at least one *orphan rule*.
1378
1379 -  An instance declaration in a module ``M`` is an *orphan instance* if
1380    orphan instance
1381
1382    -  The class of the instance declaration is not declared in ``M``, and
1383
1384    -  *Either* the class has no functional dependencies, and none of the
1385       type constructors in the instance head is declared in ``M``; *or*
1386       there is a functional dependency for which none of the type
1387       constructors mentioned in the *non-determined* part of the
1388       instance head is defined in ``M``.
1389
1390    Only the instance head counts. In the example above, it is not good
1391    enough for ``C``\'s declaration to be in module ``A``; it must be the
1392    declaration of ``D`` or ``T``.
1393
1394 -  A rewrite rule in a module ``M`` is an *orphan rule* orphan rule if none
1395    of the variables, type constructors, or classes that are free in the
1396    left hand side of the rule are declared in ``M``.
1397
1398 If you use the flag :ghc-flag:`-Worphans`, GHC will warn you if you are
1399 creating an orphan module. Like any warning, you can switch the warning
1400 off with :ghc-flag:`-Wno-orphans <-Worphans>`, and :ghc-flag:`-Werror` will make
1401 the compilation fail if the warning is issued.
1402
1403 You can identify an orphan module by looking in its interface file, ``M.hi``,
1404 using the :ghc-flag:`--show-iface ⟨file⟩` :ref:`mode <modes>`. If there is a
1405 ``[orphan module]`` on the first line, GHC considers it an orphan module.
1406
1407 .. [1]
1408    This is a change in behaviour relative to 6.2 and earlier.